latinfo 0.9.0 → 0.10.0

package/dist/index.js

@@ -47,7 +47,7 @@ const local_search_1 = require("./local-search");
 const client_search_1 = require("./client-search");
 const odis_search_1 = require("./odis-search");
 const mphf_search_1 = require("./mphf-search");
-const VERSION = '0.8.1';
+const VERSION = '0.10.0';
 const API_URL = process.env.LATINFO_API_URL || 'https://api.latinfo.dev';
 const GITHUB_CLIENT_ID = process.env.GITHUB_CLIENT_ID || 'Ov23li5fcQaiCsVtaMKK';
 const CONFIG_DIR = path_1.default.join(os_1.default.homedir(), '.latinfo');
@@ -339,7 +339,9 @@ async function search(query) {
     const odisMode = allArgs.includes('--odis');
     const mphfMode = allArgs.includes('--mphf');
     // MPHF: fully autonomous client-side search (zero server for search)
-    if (mphfMode || (!clientMode && !odisMode && (0, mphf_search_1.hasMphfData)(country))) {
+    // Skip auto-detection in demo mode (no config) so demo data path is used
+    const config = loadConfig();
+    if (mphfMode || (config && !clientMode && !odisMode && (0, mphf_search_1.hasMphfData)(country))) {
         const stripped = query.split(' ').filter((w, i, a) => !['--mphf', '--client', '--odis', '--json'].includes(w) &&
             !(i > 0 && ['--country'].includes(a[i - 1])) &&
             !['--country'].includes(w)).join(' ');
@@ -416,7 +418,8 @@ async function search(query) {
         return;
     }
     // Local search: if data exists in ~/.latinfo/data/, search offline
-    if ((0, local_search_1.hasLocalData)(country)) {
+    // Skip in demo mode (no config) so demo data path is used
+    if (config && (0, local_search_1.hasLocalData)(country)) {
         const results = (0, local_search_1.localSearch)(country, query);
         if (jsonFlag) {
             console.log(JSON.stringify(results));
@@ -436,7 +439,6 @@ async function search(query) {
         return;
     }
     // Fallback: API search
-    const config = loadConfig();
     if (!config) {
         const results = (0, demo_data_1.searchDemo)(query);
         if (jsonFlag) {
@@ -1221,108 +1223,65 @@ function help() {
     console.log(`latinfo v${VERSION} — Tax registry API for Latin America
 
 USAGE
-  latinfo <command> [args] [--json]
+  latinfo <country> <institution> <dataset> <id|--search query|--dni id> [--json]
+  latinfo <admin-command> [args]
 
 QUICK START
   npm install -g latinfo
-  latinfo login                      # GitHub OAuth, 30 seconds
-  latinfo ruc 20100047218            # Banco de Crédito del Perú
-  latinfo search "banco de credito"  # search by company name
-  latinfo ruc 20100047218 --json     # JSON output
-
-  Works instantly with ${Object.keys(demo_data_1.DEMO_DATA).length} embedded records (no login needed).
-  Run 'latinfo login' for 18M+ records and DNI lookup.
-
-COMMANDS
-  login
-    GitHub OAuth. Opens browser, stores API key in ~/.latinfo/config.json.
-
-  login --token <github_pat>
-    Login with a GitHub Personal Access Token. No browser needed.
-    Create a PAT at github.com/settings/tokens (scope: read:user).
-
-  logout
-    Remove stored credentials.
-
-  whoami
-    Show authenticated GitHub username.
-    --json: { username, api_key }
-
-  ruc <ruc>
-    Lookup by RUC (11 digits).
-    --json fields: ruc, razon_social, estado, condicion, ubigeo,
-      tipo_via, nombre_via, numero, interior, lote, codigo_zona,
-      tipo_zona, departamento, manzana, kilometro
-
-  dni <dni>
-    Lookup by DNI (8 digits). Converts to RUC automatically.
-    --json fields: same as ruc
-
-  search <query>
-    Search by company name (razón social). Returns ranked results
-    with prefix autocomplete and abbreviation handling (S.A.C., E.I.R.L.).
-    --json fields: array of ruc objects
-
-  costs <users> [avg_req/user/month] [pro_%]
-    Simulate Cloudflare cost vs revenue.
-    Defaults: 1000 req/user, 1% Pro.
-    --json fields: users, pro_users, requests, cf_tier, cf_cost,
-      revenue, margin, safe
+  latinfo login
+  latinfo pe sunat padron 20100047218
+  latinfo pe sunat padron --search "banco de credito"
+  latinfo pe sunat padron --dni 09346247
 
-  costs --live
-    Real-time cost report from production (admin only).
-    Requires LATINFO_ADMIN_SECRET env var.
+DATA SOURCES
+  Peru — SUNAT
+    latinfo pe sunat padron <ruc>              Padrón RUC (18M records)
+    latinfo pe sunat padron --dni <dni>        Lookup by DNI
+    latinfo pe sunat padron --search <query>   Search by name
+    latinfo pe sunat coactiva <ruc>            Tax debt (cobranza coactiva)
+    latinfo pe sunat coactiva --search <query>
 
-  debtors <ruc|name> [--source <source>]
-    Search Peru debtors across SUNAT Coactiva, OSCE Inhabilitados, OSCE Multas.
-    --source: filter by sunat-coactiva, osce-inhabilitado, osce-multa
-    --json fields: ruc, name, source, detail, amount, date_start, date_end, resolution
+  Peru — OSCE
+    latinfo pe osce sanctioned <ruc>           Sanctioned providers
+    latinfo pe osce sanctioned --search <query>
+    latinfo pe osce fines <ruc>                Provider fines
+    latinfo pe osce fines --search <query>
 
-  licitaciones <query> [flags]
-    Search Peru government procurement (OECE/SEACE).
-    Flags: --category, --min-amount, --max-amount, --buyer, --method, --status, --limit
-    Run 'latinfo licitaciones help' for details.
+  Peru — OECE
+    latinfo pe oece tenders <query> [flags]    Government procurement
+    Flags: --category, --min-amount, --max-amount, --buyer, --status, --limit
 
-  easypipe <command>
-    Generic import pipeline driven by YAML configs.
-    Commands: list, build <source>, sync, add <url>
-    Run 'latinfo easypipe help' for details.
+  Colombia — RUES
+    latinfo co rues registry <nit>             Business registry (3.3M records)
+    latinfo co rues registry --search <query>
 
-  bench [--country pe|co] [--type ruc|nit|search|licitaciones] [--count N] [--concurrency N]
-    Stress test the API.
-
-  completion [bash|zsh]
-    Output shell completion script.
-    bash: eval "$(latinfo completion bash)"
-    zsh:  eval "$(latinfo completion zsh)"
-
-  help       Show this help text.
+ADMIN
+  login [--token <github_pat>]    GitHub OAuth or PAT login
+  logout                          Remove credentials
+  whoami                          Show authenticated user
+  imports                         Show import status
+  imports run <source>            Trigger import
+  imports report [days]           Import diagnostics
+  costs <users> [avg_req] [pro_%] Cost simulation
+  costs --live                    Production cost report
+  bench [flags]                   Stress test API
+  easypipe <command>              Generic import pipeline
+  completion [bash|zsh]           Shell completions
+  help                            This help text
 
 FLAGS
-  --json     Output raw JSON. Errors → stderr as { error, message }.
-  --live     Use production data (costs command).
-  --version  Print version and exit.
-
-COUNTRIES
-  pe    Peru (SUNAT padrón) — 18M+ records, updated daily. Active.
-  br, mx, co, ar, cl — in development.
+  --json     Raw JSON output
+  --search   Search by name instead of ID lookup
+  --dni      Lookup by DNI (Peru only)
+  --version  Print version
 
 PRICING
-  Free  100,000 requests/day — no credit card
-  Pro   10M requests/month   — $1/month
-
-LINKS
-  latinfo.dev/docs       API reference
-  latinfo.dev/changelog  Changelog
-  carrera.instatus.com   Status page
+  Free  100,000 requests/day
+  Pro   10M requests/month — $1/month
 
 CONFIG
-  ~/.latinfo/config.json  API key (written by 'latinfo login')
-  LATINFO_API_URL         Override API base URL
-
-EXIT CODES
-  0  Success
-  1  Error`);
+  ~/.latinfo/config.json  API key
+  LATINFO_API_URL         Override API URL`);
 }
 function printLogo() {
     if (!process.stdout.isTTY)
@@ -1379,15 +1338,31 @@ function completion() {
     if (shell === 'zsh') {
         console.log(`#compdef latinfo
 _latinfo() {
-  local -a commands=(login logout whoami plan costs ruc dni search debtors licitaciones lic help)
-  local -a lic_flags=(--category --min-amount --max-amount --buyer --method --status --limit --json)
-  local -a global_flags=(--json --live --version --token)
+  local -a countries=(pe co)
+  local -a admin=(login logout whoami imports plan costs bench easypipe completion help)
+  local -a pe_inst=(sunat osce oece)
+  local -a co_inst=(rues)
+  local -a sunat_ds=(padron coactiva)
+  local -a osce_ds=(sanctioned fines)
+  local -a oece_ds=(tenders)
+  local -a rues_ds=(registry)
+  local -a flags=(--json --search --dni --version)
   if (( CURRENT == 2 )); then
-    _describe 'command' commands
-  elif [[ "\${words[2]}" == "licitaciones" || "\${words[2]}" == "lic" ]]; then
-    _describe 'flag' lic_flags
+    _describe 'command' countries -- admin
+  elif (( CURRENT == 3 )); then
+    case "\${words[2]}" in
+      pe) _describe 'institution' pe_inst;;
+      co) _describe 'institution' co_inst;;
+    esac
+  elif (( CURRENT == 4 )); then
+    case "\${words[3]}" in
+      sunat) _describe 'dataset' sunat_ds;;
+      osce) _describe 'dataset' osce_ds;;
+      oece) _describe 'dataset' oece_ds;;
+      rues) _describe 'dataset' rues_ds;;
+    esac
   else
-    _describe 'flag' global_flags
+    _describe 'flag' flags
   fi
 }
 compdef _latinfo latinfo`);
@@ -1395,26 +1370,444 @@ compdef _latinfo latinfo`);
     else {
         console.log(`_latinfo_completions() {
   local cur="\${COMP_WORDS[COMP_CWORD]}"
-  local prev="\${COMP_WORDS[1]}"
-  if [[ \${COMP_CWORD} -eq 1 ]]; then
-    COMPREPLY=( $(compgen -W "login logout whoami plan costs ruc dni search debtors licitaciones lic help" -- "$cur") )
-  elif [[ "$prev" == "licitaciones" || "$prev" == "lic" ]]; then
-    COMPREPLY=( $(compgen -W "--category --min-amount --max-amount --buyer --method --status --limit --json info help" -- "$cur") )
-  elif [[ "$prev" == "--category" || "$prev" == "-c" ]]; then
-    COMPREPLY=( $(compgen -W "goods services works" -- "$cur") )
-  elif [[ "$prev" == "--status" || "$prev" == "-s" ]]; then
-    COMPREPLY=( $(compgen -W "CONVOCADO CONTRATADO DESIERTO NULO CONSENTIDO" -- "$cur") )
+  local lvl=\${COMP_CWORD}
+  local w1="\${COMP_WORDS[1]}" w2="\${COMP_WORDS[2]}" w3="\${COMP_WORDS[3]}"
+  if [[ \$lvl -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "pe co login logout whoami imports plan costs bench easypipe completion help" -- "$cur") )
+  elif [[ \$lvl -eq 2 ]]; then
+    case "$w1" in
+      pe) COMPREPLY=( $(compgen -W "sunat osce oece" -- "$cur") );;
+      co) COMPREPLY=( $(compgen -W "rues" -- "$cur") );;
+    esac
+  elif [[ \$lvl -eq 3 ]]; then
+    case "$w2" in
+      sunat) COMPREPLY=( $(compgen -W "padron coactiva" -- "$cur") );;
+      osce) COMPREPLY=( $(compgen -W "sanctioned fines" -- "$cur") );;
+      oece) COMPREPLY=( $(compgen -W "tenders" -- "$cur") );;
+      rues) COMPREPLY=( $(compgen -W "registry" -- "$cur") );;
+    esac
+  else
+    COMPREPLY=( $(compgen -W "--json --search --dni" -- "$cur") )
   fi
 }
 complete -F _latinfo_completions latinfo`);
     }
 }
+// --- Generic source query ---
+async function sourceQuery(routePath, datasetArgs) {
+    const searchFlag = datasetArgs.includes('--search');
+    const dniFlag = datasetArgs.includes('--dni');
+    if (searchFlag) {
+        const query = datasetArgs.filter(a => a !== '--search').join(' ');
+        if (!query) {
+            if (jsonFlag)
+                jsonError('invalid_input', 'Search query is required.');
+            console.error('Search query is required.');
+            process.exit(1);
+        }
+        const config = requireAuth();
+        const res = await apiRequest(config, `${routePath}/search?q=${encodeURIComponent(query)}`);
+        const data = await res.json();
+        if (jsonFlag) {
+            console.log(JSON.stringify(data));
+            return;
+        }
+        const results = Array.isArray(data) ? data : [];
+        if (results.length === 0) {
+            console.log('No results found.');
+            return;
+        }
+        for (const r of results) {
+            const fields = Object.values(r);
+            console.log(`  ${fields.slice(0, 3).join('  ')}`);
+        }
+        console.log(`\n${results.length} result(s)`);
+        return;
+    }
+    if (dniFlag) {
+        const dniVal = datasetArgs.find(a => a !== '--dni' && !a.startsWith('--'));
+        if (!dniVal || !/^\d{8}$/.test(dniVal)) {
+            if (jsonFlag)
+                jsonError('invalid_input', 'Invalid DNI. Must be 8 digits.');
+            console.error('Invalid DNI. Must be 8 digits.');
+            process.exit(1);
+        }
+        const config = requireAuth();
+        const res = await apiRequest(config, `${routePath}/dni/${dniVal}`);
+        const data = await res.json();
+        if (jsonFlag) {
+            console.log(JSON.stringify(data));
+            return;
+        }
+        for (const [k, v] of Object.entries(data)) {
+            if (v && v !== '-')
+                console.log(`  ${k}: ${v}`);
+        }
+        return;
+    }
+    // Direct ID lookup
+    const id = datasetArgs.find(a => !a.startsWith('--'));
+    if (!id) {
+        if (jsonFlag)
+            jsonError('invalid_input', 'ID or --search <query> required.');
+        console.error('ID or --search <query> required.');
+        process.exit(1);
+    }
+    const config = loadConfig();
+    // Demo mode for pe/sunat/padron
+    if (!config && routePath === '/pe/sunat/padron' && /^\d{11}$/.test(id)) {
+        const demo = demo_data_1.DEMO_DATA[id];
+        if (demo) {
+            if (jsonFlag) {
+                console.log(JSON.stringify({ ...demo, _demo: true }));
+            }
+            else {
+                for (const [k, v] of Object.entries(demo)) {
+                    if (v && v !== '-')
+                        console.log(`  ${k}: ${v}`);
+                }
+            }
+            process.stderr.write(`Demo data (${Object.keys(demo_data_1.DEMO_DATA).length} records). Run 'latinfo login' for full access.\n`);
+            return;
+        }
+        if (jsonFlag)
+            jsonError('not_found', "Not in demo data. Run 'latinfo login' for full access.");
+        console.error("Not in demo data. Run 'latinfo login' for full access.");
+        process.exit(1);
+    }
+    if (!config) {
+        if (jsonFlag)
+            jsonError('auth_required', "Lookup requires login. Run 'latinfo login'");
+        console.error("Lookup requires login. Run 'latinfo login'");
+        process.exit(1);
+    }
+    // Detect primary ID name from route path
+    const idNames = {
+        '/pe/sunat/padron': 'ruc', '/pe/sunat/coactiva': 'ruc',
+        '/pe/osce/sanctioned': 'ruc', '/pe/osce/fines': 'ruc',
+        '/co/rues/registry': 'nit',
+    };
+    const idName = idNames[routePath] || 'id';
+    const res = await apiRequest(config, `${routePath}/${idName}/${id}`);
+    const data = await res.json();
+    if (jsonFlag) {
+        console.log(JSON.stringify(data));
+        return;
+    }
+    for (const [k, v] of Object.entries(data)) {
+        if (v && v !== '-')
+            console.log(`  ${k}: ${v}`);
+    }
+}
+// --- Admin: source management ---
+function getRepoPath() {
+    const envPath = process.env.LATINFO_REPO_PATH;
+    if (envPath)
+        return envPath;
+    // Try to detect from cwd
+    const candidates = [
+        process.cwd(),
+        path_1.default.join(os_1.default.homedir(), 'Documents/Github/carrerahaus/latinfo-api'),
+        path_1.default.join(os_1.default.homedir(), 'latinfo-api'),
+    ];
+    for (const p of candidates) {
+        if (fs_1.default.existsSync(path_1.default.join(p, 'sources')) && fs_1.default.existsSync(path_1.default.join(p, 'src/imports')))
+            return p;
+    }
+    console.error('Cannot find latinfo-api repo. Set LATINFO_REPO_PATH or run from repo dir.');
+    process.exit(1);
+}
+function requireAdmin() {
+    // 1. Env var
+    if (process.env.LATINFO_ADMIN_SECRET)
+        return process.env.LATINFO_ADMIN_SECRET;
+    // 2. ~/.latinfo/admin.secret
+    const secretFile = path_1.default.join(CONFIG_DIR, 'admin.secret');
+    if (fs_1.default.existsSync(secretFile))
+        return fs_1.default.readFileSync(secretFile, 'utf-8').trim();
+    // 3. .dev.vars in repo
+    try {
+        const repo = getRepoPath();
+        const devVars = path_1.default.join(repo, '.dev.vars');
+        if (fs_1.default.existsSync(devVars)) {
+            const match = fs_1.default.readFileSync(devVars, 'utf-8').match(/ADMIN_SECRET=(.+)/);
+            if (match)
+                return match[1].trim();
+        }
+    }
+    catch { }
+    console.error('Admin access not found. Create ~/.latinfo/admin.secret or set LATINFO_ADMIN_SECRET.');
+    process.exit(1);
+}
+async function adminCreate(args) {
+    const [country, institution, dataset, ...flags] = args;
+    if (!country || !institution || !dataset) {
+        console.error('Usage: latinfo admin create <country> <institution> <dataset> [--url URL] [--id-name ruc] [--id-length 11] [--encoding utf-8] [--delimiter ","]');
+        process.exit(1);
+    }
+    const name = `${country}-${institution}-${dataset}`;
+    const repo = getRepoPath();
+    const yamlPath = path_1.default.join(repo, 'sources', `${name}.yaml`);
+    if (fs_1.default.existsSync(yamlPath)) {
+        console.error(`Source ${name} already exists: ${yamlPath}`);
+        process.exit(1);
+    }
+    const getFlag = (flag) => {
+        const idx = flags.indexOf(flag);
+        return idx !== -1 ? flags[idx + 1] : undefined;
+    };
+    const url = getFlag('--url') || 'https://example.com/data.csv';
+    const idName = getFlag('--id-name') || 'id';
+    const idLength = getFlag('--id-length') || '11';
+    const encoding = getFlag('--encoding') || 'utf-8';
+    const delimiter = getFlag('--delimiter') || ',';
+    const format = getFlag('--format') || 'csv';
+    const yaml = `name: ${name}
+country: ${country}
+institution: ${institution}
+dataset: ${dataset}
+source: ${institution}-${dataset}
+
+url: ${url}
+format: ${format}
+encoding: ${encoding}
+delimiter: "${delimiter}"
+skip_header: true
+
+primary_id:
+  name: ${idName}
+  column: 0
+  length: ${idLength}
+  regex: "^\\\\d{${idLength}}$"
+  prefix_length: 5
+
+alternate_ids: []
+
+fields:
+  - name: name
+    column: 1
+    search: true
+  - name: status
+    column: 2
+
+import: custom
+import_script: src/imports/${name}.ts
+
+schedule: manual
+change_detection: none
+min_rows: 100
+
+smoke_test:
+  id: ""
+  expect_field: name
+`;
+    fs_1.default.writeFileSync(yamlPath, yaml);
+    console.log(`Created: ${yamlPath}`);
+    console.log(`\nNext steps:`);
+    console.log(`  1. Edit ${yamlPath} to match your data source`);
+    console.log(`  2. Write import script: latinfo admin upload-script ${name} ./my-import.ts`);
+    console.log(`  3. Test: latinfo admin test ${name}`);
+    console.log(`  4. Publish: latinfo admin publish ${name}`);
+}
+async function adminUploadScript(args) {
+    const [sourceName, scriptPath] = args;
+    if (!sourceName || !scriptPath) {
+        console.error('Usage: latinfo admin upload-script <source-name> <script-path>');
+        process.exit(1);
+    }
+    const repo = getRepoPath();
+    const dest = path_1.default.join(repo, 'src', 'imports', `${sourceName}.ts`);
+    const src = path_1.default.resolve(scriptPath);
+    if (!fs_1.default.existsSync(src)) {
+        console.error(`Script not found: ${src}`);
+        process.exit(1);
+    }
+    fs_1.default.copyFileSync(src, dest);
+    console.log(`Copied: ${src} → ${dest}`);
+}
+async function adminTest(args) {
+    const [sourceName] = args;
+    if (!sourceName) {
+        console.error('Usage: latinfo admin test <source-name>');
+        process.exit(1);
+    }
+    const repo = getRepoPath();
+    const yamlPath = path_1.default.join(repo, 'sources', `${sourceName}.yaml`);
+    if (!fs_1.default.existsSync(yamlPath)) {
+        console.error(`Source not found: ${yamlPath}`);
+        process.exit(1);
+    }
+    // Check if import script exists
+    const scriptPath = path_1.default.join(repo, 'src', 'imports', `${sourceName}.ts`);
+    const easypipePath = path_1.default.join(repo, 'src', 'imports', 'easypipe.ts');
+    const useEasypipe = !fs_1.default.existsSync(scriptPath);
+    const cmd = useEasypipe
+        ? `npx tsx ${easypipePath} ${yamlPath} --limit 100 --local`
+        : `npx tsx ${scriptPath} --limit 100`;
+    console.log(`Testing ${sourceName}...`);
+    console.log(`Running: ${cmd}\n`);
+    try {
+        const { execSync: run } = await Promise.resolve().then(() => __importStar(require('child_process')));
+        run(cmd, { stdio: 'inherit', cwd: repo });
+        console.log(`\n[test] ${sourceName}: PASSED`);
+    }
+    catch {
+        console.error(`\n[test] ${sourceName}: FAILED`);
+        process.exit(1);
+    }
+}
+async function adminPublish(args) {
+    const [sourceName] = args;
+    if (!sourceName) {
+        console.error('Usage: latinfo admin publish <source-name>');
+        process.exit(1);
+    }
+    const repo = getRepoPath();
+    const yamlPath = path_1.default.join(repo, 'sources', `${sourceName}.yaml`);
+    if (!fs_1.default.existsSync(yamlPath)) {
+        console.error(`Source not found: ${yamlPath}`);
+        process.exit(1);
+    }
+    const { execSync: run } = await Promise.resolve().then(() => __importStar(require('child_process')));
+    // 1. Add source config to sources.ts
+    console.log(`[publish] Adding ${sourceName} to source registry...`);
+    // TODO: auto-generate sources.ts from YAMLs
+    // 2. Git add + commit + push
+    console.log(`[publish] Committing...`);
+    const files = [`sources/${sourceName}.yaml`];
+    const scriptPath = path_1.default.join(repo, 'src', 'imports', `${sourceName}.ts`);
+    if (fs_1.default.existsSync(scriptPath))
+        files.push(`src/imports/${sourceName}.ts`);
+    try {
+        run(`git add ${files.join(' ')}`, { cwd: repo, stdio: 'pipe' });
+        run(`git commit -m "Add data source: ${sourceName}"`, { cwd: repo, stdio: 'pipe' });
+        run(`git push`, { cwd: repo, stdio: 'pipe' });
+        console.log(`[publish] Pushed to remote.`);
+    }
+    catch (e) {
+        console.error(`[publish] Git error: ${e.message}`);
+        process.exit(1);
+    }
+    // 3. Trigger import
+    console.log(`[publish] Triggering import...`);
+    try {
+        run(`gh workflow run import.yml -f source=${sourceName}`, { cwd: repo, stdio: 'inherit' });
+        console.log(`[publish] Import triggered. Check: gh run list --workflow=import.yml`);
+    }
+    catch {
+        console.log(`[publish] Could not trigger workflow. Run manually: latinfo imports run ${sourceName}`);
+    }
+    console.log(`\n[publish] ${sourceName}: PUBLISHED`);
+}
+async function admin(args) {
+    requireAdmin();
+    const [subcommand, ...subArgs] = args;
+    switch (subcommand) {
+        case 'create':
+            await adminCreate(subArgs);
+            break;
+        case 'upload-script':
+            await adminUploadScript(subArgs);
+            break;
+        case 'test':
+            await adminTest(subArgs);
+            break;
+        case 'publish':
+            await adminPublish(subArgs);
+            break;
+        default:
+            console.log(`latinfo admin — data pipeline for public government records
+
+DO NOT use SQLite, Supabase, Postgres, or any other database.
+latinfo handles storage, indexing, full-text search, and API serving automatically.
+Your only job is to download and parse the source data into a TSV file.
+
+WORKFLOW
+  Step 1: Create a source definition
+    latinfo admin create <country> <institution> <dataset> [flags]
+
+    Example:
+      latinfo admin create pe redam debtors \\
+        --url "https://redam.pj.gob.pe/data.csv" \\
+        --id-name dni --id-length 8 --encoding utf-8
+
+    This generates a YAML config in sources/{name}.yaml
+    Edit the YAML to match your data: column indexes, field names, delimiter.
+
+  Step 2: Write and upload your import script
+    latinfo admin upload-script <source-name> <script.ts>
+
+    Your script must:
+      1. Download the source data (HTTP, crawler, API, etc.)
+      2. Parse it into a TSV file: ID\\tfield1\\tfield2\\t...
+      3. Sort by ID: LC_ALL=C sort -t'\\t' -k1,1
+      4. Call buildBinaryFiles() and buildSearchIndex() from ./build-binary and ./build-search-index
+      5. Call uploadToR2() for each output file
+      6. Call saveImportMeta() at the end
+
+    See SOURCES.md in the repo for the full template and common errors.
+    See src/imports/pe-osce-sanctioned.ts for a clean working example.
+
+  Step 3: Test locally
+    latinfo admin test <source-name>
+
+    Runs your import with --limit 100 and validates the output.
+    Must pass before publishing.
+
+  Step 4: Publish to production
+    latinfo admin publish <source-name>
+
+    Commits your YAML + script, pushes to GitHub, triggers the import workflow.
+    After import completes, the data is live at:
+      API:  https://api.latinfo.dev/{country}/{institution}/{dataset}/...
+      CLI:  latinfo {country} {institution} {dataset} <id|--search query>
+
+FLAGS FOR CREATE
+  --url <url>          Source data download URL
+  --id-name <name>     Primary ID field name (default: id)
+  --id-length <n>      Primary ID length in digits (default: 11)
+  --encoding <enc>     Source file encoding: utf-8 | iso-8859-1 (default: utf-8)
+  --delimiter <d>      Field delimiter (default: ,)
+  --format <fmt>       Source format: csv | tsv | txt | xlsm (default: csv)
+
+NAMING CONVENTION
+  Source name: {country}-{institution}-{dataset}
+  Country: ISO 3166-1 alpha-2 lowercase (pe, co, br, mx, ec, ar, cl)
+  Institution: government agency abbreviation, lowercase
+  Dataset: what the data contains, english, lowercase
+
+  Examples: pe-sunat-padron, pe-osce-sanctioned, co-rues-registry
+
+ENVIRONMENT
+  LATINFO_ADMIN_SECRET  Auto-detected from ~/.latinfo/admin.secret or .dev.vars
+  LATINFO_REPO_PATH     Auto-detected from cwd or ~/Documents/Github/carrerahaus/latinfo-api`);
+    }
+}
 // --- Main ---
 const [command, ...args] = rawArgs;
+const COUNTRIES = ['pe', 'co', 'br', 'mx', 'ar', 'cl', 'ec'];
 if (rawArgs.includes('--version') || rawArgs.includes('-v')) {
     version();
 }
+else if (COUNTRIES.includes(command)) {
+    // New structure: latinfo <country> <institution> <dataset> [args]
+    const [institution, dataset, ...datasetArgs] = args;
+    if (!institution || !dataset) {
+        console.error(`Usage: latinfo ${command} <institution> <dataset> <id|--search query|--dni id>`);
+        console.error(`Example: latinfo ${command} sunat padron 20100047218`);
+        process.exit(1);
+    }
+    // Special case: pe oece tenders → licitaciones (custom routes)
+    if (command === 'pe' && institution === 'oece' && dataset === 'tenders') {
+        licitaciones(datasetArgs).catch(e => { console.error(e); process.exit(1); });
+    }
+    else {
+        const routePath = `/${command}/${institution}/${dataset}`;
+        sourceQuery(routePath, datasetArgs).catch(e => { console.error(e); process.exit(1); });
+    }
+}
 else {
+    // Admin commands (flat)
     switch (command) {
         case 'login':
             login(tokenFlag).catch(e => { console.error(e); process.exit(1); });
@@ -1442,25 +1835,12 @@ else {
         case 'costs':
             (liveFlag ? costsLive() : Promise.resolve(costsSimulate(args[0], args[1], args[2]))).catch(e => { console.error(e); process.exit(1); });
             break;
-        case 'ruc':
-            ruc(args[0]).catch(e => { console.error(e); process.exit(1); });
-            break;
-        case 'dni':
-            dni(args[0]).catch(e => { console.error(e); process.exit(1); });
-            break;
-        case 'search':
-            search(args.join(' ')).catch(e => { console.error(e); process.exit(1); });
-            break;
-        case 'debtors':
-            debtors(args).catch(e => { console.error(e); process.exit(1); });
-            break;
-        case 'licitaciones':
-        case 'lic':
-            licitaciones(args).catch(e => { console.error(e); process.exit(1); });
-            break;
         case 'bench':
             bench(args).catch(e => { console.error(e); process.exit(1); });
             break;
+        case 'admin':
+            admin(args).catch(e => { console.error(e); process.exit(1); });
+            break;
         case 'easypipe':
         case 'ep':
             easypipe(args).catch(e => { console.error(e); process.exit(1); });
@@ -1471,6 +1851,23 @@ else {
         case 'help':
             help();
             break;
+        // Backward compat: old flat commands redirect
+        case 'ruc':
+            sourceQuery('/pe/sunat/padron', args).catch(e => { console.error(e); process.exit(1); });
+            break;
+        case 'dni':
+            sourceQuery('/pe/sunat/padron', ['--dni', ...args]).catch(e => { console.error(e); process.exit(1); });
+            break;
+        case 'search':
+            sourceQuery('/pe/sunat/padron', ['--search', ...args]).catch(e => { console.error(e); process.exit(1); });
+            break;
+        case 'debtors':
+            sourceQuery('/pe/sunat/coactiva', args).catch(e => { console.error(e); process.exit(1); });
+            break;
+        case 'licitaciones':
+        case 'lic':
+            licitaciones(args).catch(e => { console.error(e); process.exit(1); });
+            break;
         default:
             printLogo();
             help();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "latinfo",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Tax registry & procurement API for Latin America. Query RUC, DNI, NIT, licitaciones from Peru & Colombia. Offline MPHF search, full OCDS data, updated daily.",
   "homepage": "https://latinfo.dev",
   "repository": {