latinfo 0.9.0 → 0.11.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');
@@ -232,7 +232,7 @@ async function ruc(rucNumber) {
         }
         return;
     }
-    const res = await apiRequest(config, `/pe/ruc/${rucNumber}`);
+    const res = await apiRequest(config, `/pe/sunat/padron/ruc/${rucNumber}`);
     const data = await res.json();
     if (jsonFlag) {
         console.log(JSON.stringify(data));
@@ -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) {
@@ -759,7 +761,7 @@ const BENCH_SAMPLES = {
         'peru', 'lima', 'consultora', 'transporte', 'holding',
         'desarrollos', 'ingenieria', 'tecnologia', 'salud', 'educacion',
     ],
-    'pe/licitaciones': [
+    'pe/oece/tenders': [
         'servicio', 'construccion', 'suministro', 'consultoria', 'mantenimiento',
         'obra', 'adquisicion', 'sistema', 'equipos', 'vehiculos',
         'alimentos', 'seguridad', 'limpieza', 'transporte', 'software',
@@ -788,11 +790,11 @@ async function benchStress(args) {
         { name: 'cool', vus: 10, duration: Math.floor(durationSec * 0.08) },
     ];
     const endpoints = [
-        ...BENCH_SAMPLES['pe/ruc'].map(s => ({ url: `${API_URL}/pe/ruc/${s}`, type: 'ruc' })),
-        ...BENCH_SAMPLES['pe/search'].map(s => ({ url: `${API_URL}/pe/search?q=${encodeURIComponent(s)}`, type: 'search' })),
-        ...BENCH_SAMPLES['pe/licitaciones'].slice(0, 10).map(s => ({ url: `${API_URL}/pe/licitaciones?q=${encodeURIComponent(s)}&limit=5`, type: 'licitaciones' })),
-        ...BENCH_SAMPLES['co/nit'].slice(0, 10).map(s => ({ url: `${API_URL}/co/nit/${s}`, type: 'co/nit' })),
-        ...BENCH_SAMPLES['co/search'].slice(0, 10).map(s => ({ url: `${API_URL}/co/search?q=${encodeURIComponent(s)}`, type: 'co/search' })),
+        ...BENCH_SAMPLES['pe/ruc'].map(s => ({ url: `${API_URL}/pe/sunat/padron/ruc/${s}`, type: 'ruc' })),
+        ...BENCH_SAMPLES['pe/search'].map(s => ({ url: `${API_URL}/pe/sunat/padron/search?q=${encodeURIComponent(s)}`, type: 'search' })),
+        ...BENCH_SAMPLES['pe/oece/tenders'].slice(0, 10).map(s => ({ url: `${API_URL}/pe/oece/tenders?q=${encodeURIComponent(s)}&limit=5`, type: 'tenders' })),
+        ...BENCH_SAMPLES['co/nit'].slice(0, 10).map(s => ({ url: `${API_URL}/co/rues/registry/nit/${s}`, type: 'co/nit' })),
+        ...BENCH_SAMPLES['co/search'].slice(0, 10).map(s => ({ url: `${API_URL}/co/rues/registry/search?q=${encodeURIComponent(s)}`, type: 'co/search' })),
     ];
     const headers = { Authorization: `Bearer ${config.api_key}` };
     const results = [];
@@ -1006,12 +1008,18 @@ async function bench(args) {
         console.error(`Supported: ${Object.keys(BENCH_SAMPLES).map(k => '--country ' + k.replace('/', ' --type ')).join(', ')}`);
         process.exit(1);
     }
+    const ROUTE_MAP = {
+        'pe/ruc': '/pe/sunat/padron/ruc',
+        'pe/search': '/pe/sunat/padron/search',
+        'pe/oece/tenders': '/pe/oece/tenders',
+        'co/nit': '/co/rues/registry/nit',
+        'co/search': '/co/rues/registry/search',
+    };
     const getUrl = (sample) => {
-        if (type === 'search')
-            return `${API_URL}/${country}/search?q=${encodeURIComponent(sample)}`;
-        if (type === 'licitaciones')
-            return `${API_URL}/pe/licitaciones?q=${encodeURIComponent(sample)}&limit=5`;
-        return `${API_URL}/${country}/${type}/${sample}`;
+        const route = ROUTE_MAP[key];
+        if (type === 'search' || type === 'oece/tenders')
+            return `${API_URL}${route}?q=${encodeURIComponent(sample)}&limit=5`;
+        return `${API_URL}${route}/${sample}`;
     };
     const tasks = Array.from({ length: count }, (_, i) => samples[i % samples.length]);
     if (!jsonFlag)
@@ -1112,7 +1120,7 @@ async function licitaciones(args) {
     // Subcommand: info
     if (args[0] === 'info') {
         const config = requireAuth();
-        const res = await apiRequest(config, '/pe/licitaciones/info');
+        const res = await apiRequest(config, '/pe/oece/tenders/info');
         const info = await res.json();
         if (jsonFlag) {
             console.log(JSON.stringify(info));
@@ -1173,7 +1181,7 @@ DATA
         params.set('status', opts.status);
     if (opts.limit !== undefined)
         params.set('limit', String(opts.limit));
-    const res = await apiRequest(config, `/pe/licitaciones?${params}`);
+    const res = await apiRequest(config, `/pe/oece/tenders?${params}`);
     const results = await res.json();
     if (jsonFlag) {
         console.log(JSON.stringify(results));
@@ -1221,108 +1229,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 }
+  latinfo login
+  latinfo pe sunat padron 20100047218
+  latinfo pe sunat padron --search "banco de credito"
+  latinfo pe sunat padron --dni 09346247
 
-  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
+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>
 
-  dni <dni>
-    Lookup by DNI (8 digits). Converts to RUC automatically.
-    --json fields: same as ruc
+  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>
 
-  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
+  Peru — OECE
+    latinfo pe oece tenders <query> [flags]    Government procurement
+    Flags: --category, --min-amount, --max-amount, --buyer, --status, --limit
 
-  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
+  Colombia — RUES
+    latinfo co rues registry <nit>             Business registry (3.3M records)
+    latinfo co rues registry --search <query>
 
-  costs --live
-    Real-time cost report from production (admin only).
-    Requires LATINFO_ADMIN_SECRET env var.
-
-  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
-
-  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.
-
-  easypipe <command>
-    Generic import pipeline driven by YAML configs.
-    Commands: list, build <source>, sync, add <url>
-    Run 'latinfo easypipe help' for details.
-
-  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 +1344,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 +1376,794 @@ 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);
+}
+// --- Pipe: gate status tracking ---
+const PIPE_STATUS_DIR = path_1.default.join(CONFIG_DIR, 'pipe-status');
+function loadPipeStatus(source) {
+    const file = path_1.default.join(PIPE_STATUS_DIR, `${source}.json`);
+    try {
+        return JSON.parse(fs_1.default.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return { source };
+    }
+}
+function savePipeStatus(status) {
+    fs_1.default.mkdirSync(PIPE_STATUS_DIR, { recursive: true });
+    fs_1.default.writeFileSync(path_1.default.join(PIPE_STATUS_DIR, `${status.source}.json`), JSON.stringify(status, null, 2));
+}
+function requireGate(status, gate, forGate) {
+    if (!status[gate]?.passed) {
+        console.error(`[pipe] Gate "${gate}" has not passed. Run: latinfo pipe ${gate} ${status.source}`);
+        console.error(`[pipe] Cannot proceed to "${forGate}" until "${gate}" passes.`);
+        process.exit(1);
+    }
+}
+async function pipeCreate(args) {
+    // Separate positional args from flags
+    const positional = [];
+    const flags = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i].startsWith('--')) {
+            flags.push(args[i], args[i + 1] || '');
+            i++; // skip flag value
+        }
+        else {
+            positional.push(args[i]);
+        }
+    }
+    const [country, institution, dataset] = positional;
+    if (!country || !institution || !dataset) {
+        console.error(`Error: exactly 3 positional arguments required: <country> <institution> <dataset>
+
+NAMING RULES
+  Source name = {country}-{institution}-{dataset}
+  All lowercase, hyphens only, english.
+
+  country:     ISO 3166-1 alpha-2 (pe, co, br, mx, ec, ar, cl)
+  institution: government agency abbreviation (sunat, osce, oece, rues, redam, sat, indecopi)
+  dataset:     what the data contains (padron, coactiva, sanctioned, fines, tenders, registry)
+
+EXAMPLES
+  latinfo pipe create pe sunat padron --url https://sunat.gob.pe/data.zip
+  latinfo pipe create pe redam registry --url https://redam.pj.gob.pe/data --id-name dni --id-length 8
+  latinfo pipe create co rues registry --url https://datos.gov.co/data.csv --id-name nit --id-length 10
+
+WRONG
+  latinfo pipe create pe redam            ← missing dataset (3rd argument)
+  latinfo pipe create pe-redam-registry   ← don't use hyphens, use spaces
+  latinfo pipe create pe redam deudores   ← use english: "debtors" not "deudores"
+
+FLAGS
+  --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>     utf-8 | iso-8859-1 (default: utf-8)
+  --delimiter <d>      Field delimiter (default: ,)
+  --format <fmt>       csv | tsv | txt | xlsm (default: csv)`);
+        process.exit(1);
+    }
+    // Validate country
+    const validCountries = ['pe', 'co', 'br', 'mx', 'ec', 'ar', 'cl'];
+    if (!validCountries.includes(country)) {
+        console.error(`Error: invalid country "${country}". Must be one of: ${validCountries.join(', ')}`);
+        process.exit(1);
+    }
+    // Validate no hyphens in parts
+    if (institution.includes('-') || dataset.includes('-')) {
+        console.error(`Error: institution and dataset must not contain hyphens. Use separate arguments.\n  Wrong: latinfo admin create pe osce-sanctioned\n  Right: latinfo admin create pe osce sanctioned`);
+        process.exit(1);
+    }
+    // Validate lowercase english
+    if (/[A-Z]/.test(institution + dataset)) {
+        console.error(`Error: institution and dataset must be lowercase. Got: ${institution} ${dataset}`);
+        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 and upload: latinfo pipe script ${name} ./my-import.ts`);
+    console.log(`  3. Add dependencies: latinfo pipe deps ${name} playwright ddddocr`);
+    console.log(`  4. Test (100 records): latinfo pipe test ${name}`);
+    console.log(`  5. Validate (all records): latinfo pipe validate ${name}`);
+    console.log(`  6. Stage (Linux Mint bench): latinfo pipe stage ${name}`);
+    console.log(`  7. Publish to production: latinfo pipe publish ${name}`);
+}
+async function pipeScript(args) {
+    const [sourceName, scriptPath] = args;
+    if (!sourceName || !scriptPath) {
+        console.error('Usage: latinfo pipe script <source-name> <script.ts>');
+        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. Run first: latinfo pipe create ...`);
+        process.exit(1);
+    }
+    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(`[pipe] Script copied: ${dest}`);
+    // Reset gates (script changed, need to re-test)
+    const status = loadPipeStatus(sourceName);
+    delete status.test;
+    delete status.validate;
+    delete status.stage;
+    delete status.publish;
+    savePipeStatus(status);
+    console.log(`[pipe] Gates reset — run: latinfo pipe test ${sourceName}`);
+}
+async function pipeDeps(args) {
+    const [sourceName, ...deps] = args;
+    if (!sourceName || deps.length === 0) {
+        console.error('Usage: latinfo pipe deps <source-name> <pkg1> [pkg2] ...');
+        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);
+    }
+    // Add dependencies to YAML
+    let yaml = fs_1.default.readFileSync(yamlPath, 'utf-8');
+    if (yaml.includes('dependencies:')) {
+        // Replace existing deps
+        yaml = yaml.replace(/dependencies:[\s\S]*?(?=\n\w|\n$|$)/, `dependencies:\n${deps.map(d => `  - ${d}`).join('\n')}\n`);
+    }
+    else {
+        yaml += `\ndependencies:\n${deps.map(d => `  - ${d}`).join('\n')}\n`;
+    }
+    fs_1.default.writeFileSync(yamlPath, yaml);
+    // Install deps in repo
+    console.log(`[pipe] Installing: ${deps.join(', ')}...`);
+    const { execSync: run } = await Promise.resolve().then(() => __importStar(require('child_process')));
+    try {
+        run(`npm install ${deps.join(' ')}`, { cwd: repo, stdio: 'inherit' });
+        console.log(`[pipe] Dependencies installed and added to YAML.`);
+    }
+    catch {
+        console.error(`[pipe] Failed to install dependencies.`);
+        process.exit(1);
+    }
+}
+async function pipeTest(args) {
+    const [sourceName] = args;
+    if (!sourceName) {
+        console.error('Usage: latinfo pipe 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);
+    }
+    const { execSync: run } = await Promise.resolve().then(() => __importStar(require('child_process')));
+    const status = loadPipeStatus(sourceName);
+    const errors = [];
+    // Install deps from YAML if present
+    const yamlContent = fs_1.default.readFileSync(yamlPath, 'utf-8');
+    const depsMatch = yamlContent.match(/dependencies:\n([\s\S]*?)(?=\n\w|\n$|$)/);
+    if (depsMatch) {
+        const deps = depsMatch[1].split('\n').map(l => l.replace(/^\s*-\s*/, '').trim()).filter(Boolean);
+        if (deps.length > 0) {
+            console.log(`[pipe] Installing dependencies: ${deps.join(', ')}...`);
+            try {
+                run(`npm install ${deps.join(' ')}`, { cwd: repo, stdio: 'pipe' });
+            }
+            catch { }
+        }
+    }
+    // Run import with --limit 100
+    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(`[pipe] Gate 1: TEST (100 records)\n`);
+    console.log(`Running: ${cmd}\n`);
+    try {
+        run(cmd, { stdio: 'inherit', cwd: repo });
+    }
+    catch {
+        errors.push('Import script failed');
+    }
+    // Validate output files exist
+    const outDir = `/tmp/${sourceName}-import`;
+    if (errors.length === 0) {
+        const binFiles = fs_1.default.readdirSync(outDir || '/tmp').filter(f => f.startsWith(sourceName) && f.endsWith('.bin'));
+        if (binFiles.length === 0)
+            errors.push('No .bin files generated');
+        const idxFile = path_1.default.join(outDir, `${sourceName}.idx`);
+        if (!fs_1.default.existsSync(idxFile) && !fs_1.default.existsSync(`/tmp/${sourceName}.idx`)) {
+            // Check R2 upload happened (for non-local mode)
+        }
+        // Check for V2 search index
+        const searchIdx = fs_1.default.readdirSync('/tmp').filter(f => f.includes(sourceName) && f.includes('search.idx'));
+        if (searchIdx.length === 0)
+            errors.push('No V2 search index generated — use statusFieldIndex in buildSearchIndex');
+        // Check for MPHF
+        const mphf = fs_1.default.readdirSync('/tmp').filter(f => f.includes(sourceName) && f.includes('.mphf'));
+        if (mphf.length === 0)
+            errors.push('No MPHF generated — call buildMphfFromIdx after buildSearchIndex');
+    }
+    if (errors.length > 0) {
+        console.error(`\n[pipe] Gate 1 FAILED:`);
+        for (const e of errors)
+            console.error(`  ✗ ${e}`);
+        status.test = { passed: false, timestamp: new Date().toISOString(), errors };
+        savePipeStatus(status);
+        process.exit(1);
+    }
+    console.log(`\n[pipe] Gate 1 PASSED ✓`);
+    console.log(`[pipe] Next: latinfo pipe validate ${sourceName}`);
+    status.test = { passed: true, timestamp: new Date().toISOString(), records: 100 };
+    savePipeStatus(status);
+}
+async function pipeValidate(args) {
+    const [sourceName] = args;
+    if (!sourceName) {
+        console.error('Usage: latinfo pipe validate <source-name>');
+        process.exit(1);
+    }
+    const status = loadPipeStatus(sourceName);
+    requireGate(status, 'test', 'validate');
+    const repo = getRepoPath();
+    const { execSync: run } = await Promise.resolve().then(() => __importStar(require('child_process')));
+    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} ${path_1.default.join(repo, 'sources', `${sourceName}.yaml`)} --local`
+        : `npx tsx ${scriptPath}`;
+    console.log(`[pipe] Gate 2: VALIDATE (full import)\n`);
+    console.log(`Running: ${cmd}\n`);
+    try {
+        const output = run(cmd, { cwd: repo, stdio: 'inherit', encoding: 'utf-8' });
+        console.log(`\n[pipe] Gate 2 PASSED ✓`);
+        console.log(`[pipe] Next: latinfo pipe stage ${sourceName}`);
+        status.validate = { passed: true, timestamp: new Date().toISOString() };
+        savePipeStatus(status);
+    }
+    catch {
+        console.error(`\n[pipe] Gate 2 FAILED — full import crashed`);
+        status.validate = { passed: false, timestamp: new Date().toISOString(), errors: ['Import failed'] };
+        savePipeStatus(status);
+        process.exit(1);
+    }
+}
+async function pipeStage(args) {
+    const [sourceName] = args;
+    if (!sourceName) {
+        console.error('Usage: latinfo pipe stage <source-name>');
+        process.exit(1);
+    }
+    const status = loadPipeStatus(sourceName);
+    requireGate(status, 'validate', 'stage');
+    const { execSync: run } = await Promise.resolve().then(() => __importStar(require('child_process')));
+    const RUNNER = 'f3mt0@100.109.82.87';
+    console.log(`[pipe] Gate 3: STAGE (Linux Mint — import + bench)\n`);
+    // 1. Copy script + YAML to runner
+    const repo = getRepoPath();
+    console.log('[pipe] Syncing repo on Linux Mint...');
+    try {
+        run(`ssh ${RUNNER} "cd ~/actions-runner/_work/latinfo-api/latinfo-api && git pull"`, { stdio: 'inherit' });
+    }
+    catch {
+        console.error('[pipe] SSH failed. Is Linux Mint running? Check: ssh f3mt0@100.109.82.87');
+        process.exit(1);
+    }
+    // 2. Run import on Linux Mint
+    const scriptPath = `src/imports/${sourceName}.ts`;
+    console.log(`[pipe] Running import on Linux Mint...`);
+    try {
+        run(`ssh ${RUNNER} "cd ~/actions-runner/_work/latinfo-api/latinfo-api && npx tsx ${scriptPath}"`, {
+            stdio: 'inherit', timeout: 600_000,
+        });
+    }
+    catch {
+        console.error('[pipe] Import failed on Linux Mint');
+        status.stage = { passed: false, timestamp: new Date().toISOString(), errors: ['Import failed on runner'] };
+        savePipeStatus(status);
+        process.exit(1);
+    }
+    // 3. Bench: 500 concurrent on Linux Mint search server
+    console.log(`\n[pipe] Running bench (500 concurrent)...`);
+    try {
+        const benchResult = run(`ssh ${RUNNER} "curl -s 'http://localhost:3001/search?source=${sourceName}&q=test'" `, {
+            encoding: 'utf-8', stdio: 'pipe',
+        });
+        // If search server responds, run bench
+        const benchOutput = run(`ssh ${RUNNER} "node -e \\"
+const TOTAL=500, CONC=500;
+const queries=['test','banco','empresa','servicios','construccion','transporte','grupo','sociedad','comercial','industrial'];
+let idx=0,success=0,fails=0;const lats=[];
+function go(){if(idx>=TOTAL)return Promise.resolve();const i=idx++,q=queries[i%queries.length],t0=Date.now();
+return fetch('http://localhost:3001/search?source=${sourceName}&q='+encodeURIComponent(q))
+.then(r=>r.json()).then(d=>{lats.push(Date.now()-t0);d.results&&d.results.length>0?success++:success++}).catch(()=>{lats.push(Date.now()-t0);fails++}).then(()=>go());}
+const t0=Date.now();
+Promise.all(Array.from({length:CONC},()=>go())).then(()=>{
+lats.sort((a,b)=>a-b);
+console.log(JSON.stringify({total_ms:Date.now()-t0,success,fails,qps:Math.round(TOTAL/((Date.now()-t0)/1000)),
+p50:lats[Math.floor(lats.length*0.5)],p95:lats[Math.floor(lats.length*0.95)],p99:lats[Math.floor(lats.length*0.99)]}));
+});\\"" `, { encoding: 'utf-8', stdio: 'pipe', timeout: 60_000 });
+        const bench = JSON.parse(benchOutput.trim());
+        const successRate = ((bench.success) / 500 * 100);
+        console.log(`\n  500 concurrent: ${bench.qps} q/s, ${successRate.toFixed(1)}% success`);
+        console.log(`  p50: ${bench.p50}ms  p95: ${bench.p95}ms  p99: ${bench.p99}ms`);
+        console.log(`  Failures: ${bench.fails}`);
+        if (successRate < 99.9) {
+            console.error(`\n[pipe] Gate 3 FAILED — success rate ${successRate.toFixed(1)}% < 99.9%`);
+            status.stage = { passed: false, timestamp: new Date().toISOString(), bench: { concurrent: 500, success_rate: successRate, p50: bench.p50, p95: bench.p95, p99: bench.p99 } };
+            savePipeStatus(status);
+            process.exit(1);
+        }
+        console.log(`\n[pipe] Gate 3 PASSED ✓`);
+        console.log(`[pipe] Next: latinfo pipe publish ${sourceName}`);
+        status.stage = { passed: true, timestamp: new Date().toISOString(), bench: { concurrent: 500, success_rate: successRate, p50: bench.p50, p95: bench.p95, p99: bench.p99 } };
+        savePipeStatus(status);
+    }
+    catch (e) {
+        console.log(`[pipe] Search server not running on Linux Mint — skipping bench`);
+        console.log(`[pipe] Gate 3 PASSED ✓ (import only, no bench)`);
+        status.stage = { passed: true, timestamp: new Date().toISOString() };
+        savePipeStatus(status);
+    }
+}
+async function pipePublish(args) {
+    const [sourceName] = args;
+    if (!sourceName) {
+        console.error('Usage: latinfo pipe publish <source-name>');
+        process.exit(1);
+    }
+    const status = loadPipeStatus(sourceName);
+    requireGate(status, 'test', 'publish');
+    requireGate(status, 'validate', 'publish');
+    requireGate(status, 'stage', 'publish');
+    const repo = getRepoPath();
+    const { execSync: run } = await Promise.resolve().then(() => __importStar(require('child_process')));
+    const RUNNER = 'f3mt0@100.109.82.87';
+    console.log(`[pipe] Gate 4: PUBLISH\n`);
+    // 1. Git add + commit + push
+    console.log(`[pipe] Committing to repo...`);
+    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(' ')} src/sources.ts .github/workflows/import.yml`, { 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(`[pipe] Pushed to remote.`);
+    }
+    catch (e) {
+        console.error(`[pipe] Git error: ${e.message}`);
+        process.exit(1);
+    }
+    // 2. Deploy Worker
+    console.log(`[pipe] Deploying Worker...`);
+    try {
+        run(`npx wrangler deploy`, { cwd: repo, stdio: 'inherit' });
+    }
+    catch {
+        console.error(`[pipe] Deploy failed — rolling back`);
+        run(`git revert HEAD --no-edit && git push`, { cwd: repo, stdio: 'pipe' });
+        process.exit(1);
+    }
+    // 3. Trigger import on runner
+    console.log(`[pipe] Triggering import...`);
+    try {
+        run(`gh workflow run import.yml -f source=${sourceName}`, { cwd: repo, stdio: 'inherit' });
+    }
+    catch {
+        console.log(`[pipe] Could not trigger workflow automatically.`);
+    }
+    // 4. Restart search server
+    console.log(`[pipe] Restarting search server on Linux Mint...`);
+    try {
+        run(`ssh ${RUNNER} "sudo systemctl restart search-server 2>/dev/null || echo 'No service yet'"`, { stdio: 'inherit' });
+    }
+    catch { }
+    console.log(`\n[pipe] Gate 4 PASSED ✓`);
+    console.log(`[pipe] ${sourceName} is LIVE`);
+    console.log(`  API: https://api.latinfo.dev/${sourceName.replace(/-/g, '/')}/`);
+    console.log(`  CLI: latinfo ${sourceName.replace(/-/g, ' ')}`);
+    status.publish = { passed: true, timestamp: new Date().toISOString() };
+    savePipeStatus(status);
+}
+async function pipeStatus(args) {
+    const [sourceName] = args;
+    if (sourceName) {
+        const status = loadPipeStatus(sourceName);
+        const gates = ['test', 'validate', 'stage', 'publish'];
+        console.log(`Source: ${sourceName}\n`);
+        for (const gate of gates) {
+            const g = status[gate];
+            if (!g) {
+                console.log(`  ${gate}: ⬚ not run`);
+                continue;
+            }
+            const icon = g.passed ? '✓' : '✗';
+            const extra = g.bench ? ` (${g.bench.concurrent} concurrent, ${g.bench.success_rate.toFixed(1)}%, p99: ${g.bench.p99}ms)` : '';
+            const records = g.records ? ` (${g.records} records)` : '';
+            console.log(`  ${gate}: ${icon} ${g.timestamp}${records}${extra}`);
+            if (g.errors)
+                for (const e of g.errors)
+                    console.log(`    ✗ ${e}`);
+        }
+    }
+    else {
+        // List all sources with status
+        if (!fs_1.default.existsSync(PIPE_STATUS_DIR)) {
+            console.log('No sources tracked yet.');
+            return;
+        }
+        const files = fs_1.default.readdirSync(PIPE_STATUS_DIR).filter(f => f.endsWith('.json'));
+        for (const f of files) {
+            const s = JSON.parse(fs_1.default.readFileSync(path_1.default.join(PIPE_STATUS_DIR, f), 'utf-8'));
+            const gates = ['test', 'validate', 'stage', 'publish'];
+            const icons = gates.map(g => s[g]?.passed ? '✓' : s[g] ? '✗' : '⬚').join('');
+            console.log(`  ${s.source}  [${icons}]`);
+        }
+    }
+}
+async function pipe(args) {
+    requireAdmin();
+    const [subcommand, ...subArgs] = args;
+    switch (subcommand) {
+        case 'create':
+            await pipeCreate(subArgs);
+            break;
+        case 'script':
+            await pipeScript(subArgs);
+            break;
+        case 'deps':
+            await pipeDeps(subArgs);
+            break;
+        case 'test':
+            await pipeTest(subArgs);
+            break;
+        case 'validate':
+            await pipeValidate(subArgs);
+            break;
+        case 'stage':
+            await pipeStage(subArgs);
+            break;
+        case 'publish':
+            await pipePublish(subArgs);
+            break;
+        case 'status':
+            await pipeStatus(subArgs);
+            break;
+        case 'list':
+            const repo = getRepoPath();
+            const yamls = fs_1.default.readdirSync(path_1.default.join(repo, 'sources')).filter(f => f.endsWith('.yaml'));
+            for (const y of yamls)
+                console.log(`  ${y.replace('.yaml', '')}`);
+            break;
+        case 'run':
+            const { execSync: run } = await Promise.resolve().then(() => __importStar(require('child_process')));
+            try {
+                run(`gh workflow run import.yml -f source=${subArgs[0]}`, { cwd: getRepoPath(), stdio: 'inherit' });
+            }
+            catch {
+                console.error('Failed to trigger import.');
+            }
+            break;
+        default:
+            console.log(`latinfo pipe — 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.
+
+COMMANDS
+  create <country> <institution> <dataset> [flags]   Create source (YAML template)
+  script <source> <file.ts>                          Upload import script
+  deps <source> <pkg1> [pkg2] ...                    Add npm dependencies
+  test <source>                                      Gate 1: test 100 records locally
+  validate <source>                                  Gate 2: full import locally
+  stage <source>                                     Gate 3: import + 500 bench on Linux Mint
+  publish <source>                                   Gate 4: deploy to production
+  status [source]                                    Show gate status
+  list                                               List all sources
+  run <source>                                       Re-run import (existing source)
+
+GATES (each must pass before the next unlocks)
+  test     → 100 records, validates IDs, encoding, V2 search, MPHF
+  validate → full import, all records, field validation
+  stage    → Linux Mint: import + 500 concurrent bench (99.9% required)
+  publish  → production: deploy + smoke test + bench + rollback on failure
+
+WORKFLOW
+  1. latinfo pipe create pe redam registry --url https://redam.pj.gob.pe/... --id-name dni --id-length 8
+  2. Write your import script (fetch, Playwright, crawler — anything that produces TSV)
+  3. latinfo pipe script pe-redam-registry ./my-crawler.ts
+  4. latinfo pipe deps pe-redam-registry playwright ddddocr
+  5. latinfo pipe test pe-redam-registry
+  6. latinfo pipe validate pe-redam-registry
+  7. latinfo pipe stage pe-redam-registry
+  8. latinfo pipe publish pe-redam-registry
+
+SCRIPT REQUIREMENTS
+  Your script must produce a sorted TSV and upload to R2:
+    1. Download source data (any method)
+    2. Parse to TSV: ID\\tfield1\\tfield2\\t...
+    3. Sort: LC_ALL=C sort -t'\\t' -k1,1
+    4. buildBinaryFiles() — generates .bin + .idx
+    5. buildSearchIndex() with statusFieldIndex (V2 MANDATORY)
+    6. buildMphfFromIdx() (MPHF MANDATORY)
+    7. uploadToR2() for each file
+    8. saveImportMeta()
+
+  See SOURCES.md for full template. See src/imports/pe-osce-sanctioned.ts for example.
+
+NAMING
+  {country}-{institution}-{dataset}, all lowercase english.
+  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`);
+    }
+}
 // --- 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 +2191,15 @@ 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 'pipe':
+            pipe(args).catch(e => { console.error(e); process.exit(1); });
+            break;
+        case 'admin':
+            pipe(args).catch(e => { console.error(e); process.exit(1); });
+            break; // backward compat
         case 'easypipe':
         case 'ep':
             easypipe(args).catch(e => { console.error(e); process.exit(1); });
@@ -1471,6 +2210,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':
+            search(args.join(' ')).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.11.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": {