komplian 0.4.1 → 0.4.4

package/README.md

@@ -4,7 +4,9 @@
 
 1. Install [GitHub CLI](https://cli.github.com) and **git** (one-time per machine).
 2. Browser login: `gh auth login -h github.com -s repo -s read:org -w`
-3. `npx komplian onboard --yes`
+3. `npx komplian onboard --yes` (sin `@versión`: usa `latest` del registry público).
+
+**`npm ERR! ETARGET` / “No matching version”** (también si falló **`postman`**, no solo `onboard`): es el mismo paquete npm. Usa **`npx komplian postman login`** / **`npx komplian postman --yes`** **sin** `@0.4.x`; comprueba `npm config get registry` → `https://registry.npmjs.org/`; `npm cache clean --force`. Detalle: `ONBOARDING.md` en el monorepo.
 
 ### Postman (colección + entornos)
 
@@ -24,11 +26,15 @@ npx komplian postman --yes
 
 Opcional: `export POSTMAN_API_KEY=…` solo para la sesión actual (tiene prioridad sobre el archivo).
 
-El comando llama a `GET https://api.getpostman.com/me` y **solo continúa** si el email de la cuenta es `@komplian.com`. Crea la colección **Komplian API**, los entornos **Komplian — Local Dev** y **Komplian — Production**, y deja copia en `./komplian-postman/*.json`.
+El comando llama a `GET https://api.getpostman.com/me` y **solo continúa** si el email de la cuenta es `@komplian.com`. **Si ya existen** la colección **Komplian API** y los entornos con el mismo nombre en ese workspace, se **actualizan**; si no, se crean.
+
+**Variables de la API Komplian** (`apiKey`, `adminApiKey`, `workspaceId`, …) se rellenan en Postman automáticamente si están en `process.env` o en archivos `.env` (busca `api/.env`, `.env`, etc.; o `KOMPLIAN_DOTENV` / `--dotenv ruta`). Nombres típicos: `API_KEY`, `ADMIN_API_KEY`, `KOMPLIAN_WORKSPACE_ID`. Los JSON exportados en `./komplian-postman/` **no** incluyen secretos (para no commitearlos).
 
 - Solo exportar archivos (sin subir por API): `npx komplian postman --yes --export-only`
 - Otro workspace: `POSTMAN_WORKSPACE_ID=<id>`
-- Ruta alternativa del archivo de clave: `KOMPLIAN_POSTMAN_KEY_FILE`
+- Ruta alternativa del archivo de clave Postman: `KOMPLIAN_POSTMAN_KEY_FILE`
+
+**Seguridad (CLI Postman):** clave en `~/.komplian/` (permisos reforzados por el CLI), prompt sin eco, errores redactados; detalle técnico arriba. **Normativa del equipo:** archivo **`SECURITY.md`** en la raíz del monorepo Komplian (no va en el paquete npm).
 
 No OAuth App registration — `gh` uses GitHub’s built-in flow. **Default workspace:** current working directory (`process.cwd()`), not `~/komplian`. Pass a path as last argument to clone elsewhere.  
 **Dependencies:** repos with `package-lock.json` use **`npm ci`** (does not modify the lockfile, so no spurious git changes). Repos without a lockfile use **`npm install --no-package-lock`** so onboarding does not create a new `package-lock.json`. Yarn / pnpm repos use frozen lock installs when `yarn` / `pnpm` is on PATH. Unless `KOMPLIAN_NPM_AUDIT=1`, npm runs with `--no-audit --no-fund`.

package/komplian-localhost.mjs

@@ -0,0 +1,458 @@
+#!/usr/bin/env node
+/**
+ * Komplian localhost — genera `.env.local` con secretos aleatorios (crypto) y arranca
+ * api, app, web, admin, docs en paralelo (concurrently).
+ *
+ * Seguridad: nada se commitea; secretos solo en disco local (.env*.local / .komplian/).
+ * No imprime valores de claves.
+ *
+ * Uso:
+ *   npx komplian localhost --yes
+ *   npx komplian localhost --yes --minimal          # solo app + web + docs (sin DB real)
+ *   npx komplian localhost --env-only --force       # solo escribir env
+ *
+ * URLs de Neon (opcional, una o tres):
+ *   KOMPLIAN_LOCALHOST_DATABASE_URL                 # misma para app/admin/web/api
+ *   KOMPLIAN_LOCALHOST_APP_DATABASE_URL
+ *   KOMPLIAN_LOCALHOST_ADMIN_DATABASE_URL
+ *   KOMPLIAN_LOCALHOST_WEB_DATABASE_URL
+ * O archivo (gitignored): komplian-localhost.secrets.env o .komplian/localhost-secrets.env
+ */
+
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const c = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  bold: "\x1b[1m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+};
+
+function log(s = "") {
+  console.log(s);
+}
+
+const PLACEHOLDER_DB =
+  "postgresql://127.0.0.1:5432/komplian_localhost_placeholder?sslmode=disable";
+
+function rndHex(n = 32) {
+  return randomBytes(n).toString("hex");
+}
+
+function parseEnvFile(content) {
+  const out = {};
+  for (const line of content.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith("#")) continue;
+    const eq = t.indexOf("=");
+    if (eq === -1) continue;
+    const key = t.slice(0, eq).trim();
+    let val = t.slice(eq + 1).trim();
+    if (
+      (val.startsWith('"') && val.endsWith('"')) ||
+      (val.startsWith("'") && val.endsWith("'"))
+    ) {
+      val = val.slice(1, -1);
+    }
+    out[key] = val;
+  }
+  return out;
+}
+
+function loadSecretsFromDisk(workspaceRoot) {
+  const paths = [
+    join(workspaceRoot, "komplian-localhost.secrets.env"),
+    join(workspaceRoot, ".komplian", "localhost-secrets.env"),
+  ];
+  for (const p of paths) {
+    if (!existsSync(p)) continue;
+    try {
+      return parseEnvFile(readFileSync(p, "utf8"));
+    } catch {
+      /* ignore */
+    }
+  }
+  return {};
+}
+
+function resolveDatabaseUrls(workspaceRoot) {
+  const file = loadSecretsFromDisk(workspaceRoot);
+  const single =
+    process.env.KOMPLIAN_LOCALHOST_DATABASE_URL?.trim() ||
+    file.KOMPLIAN_LOCALHOST_DATABASE_URL?.trim();
+  const app =
+    process.env.KOMPLIAN_LOCALHOST_APP_DATABASE_URL?.trim() ||
+    file.KOMPLIAN_LOCALHOST_APP_DATABASE_URL?.trim() ||
+    single;
+  const admin =
+    process.env.KOMPLIAN_LOCALHOST_ADMIN_DATABASE_URL?.trim() ||
+    file.KOMPLIAN_LOCALHOST_ADMIN_DATABASE_URL?.trim() ||
+    single;
+  const web =
+    process.env.KOMPLIAN_LOCALHOST_WEB_DATABASE_URL?.trim() ||
+    file.KOMPLIAN_LOCALHOST_WEB_DATABASE_URL?.trim() ||
+    single;
+  const hasReal =
+    !!(app && admin && web) &&
+    !String(app).includes("komplian_localhost_placeholder");
+  return { app, admin, web, apiApp: app, apiAdmin: admin, apiWeb: web, hasReal };
+}
+
+function writeAtomic(path, content) {
+  writeFileSync(path, content, { encoding: "utf8", mode: 0o600 });
+  try {
+    if (process.platform !== "win32") chmodSync(path, 0o600);
+  } catch {
+    /* ignore */
+  }
+}
+
+function findWorkspaceRoot(start) {
+  let dir = resolve(start);
+  for (let i = 0; i < 8; i++) {
+    if (
+      existsSync(join(dir, "api", "package.json")) &&
+      existsSync(join(dir, "app", "package.json"))
+    ) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return resolve(start);
+}
+
+function buildShared() {
+  const apiKey = rndHex(32);
+  const adminApiKey = rndHex(32);
+  return {
+    apiKey,
+    adminApiKey,
+    jwtSecret: rndHex(32),
+    encryptionKey: rndHex(32),
+    nextAuthSecret: rndHex(32),
+    csrfSecret: rndHex(32),
+    cronSecret: rndHex(32),
+    internalWebhook: rndHex(32),
+    twoFactorEnc: rndHex(32),
+    hashSecret: rndHex(32),
+    nextAuthAdmin: rndHex(32),
+  };
+}
+
+function header(project) {
+  return `# Generated by komplian localhost — do not commit (${project})
+# Regenerate: npx komplian localhost --yes --force
+
+`;
+}
+
+function writeAppEnv(root, s, db, opts) {
+  const p = join(root, "app", ".env.local");
+  if (existsSync(p) && !opts.force) return { path: p, skipped: true };
+  const useNoDb = opts.minimal || !db.app || db.app.includes("placeholder");
+  const lines = [
+    header("app"),
+    useNoDb ? "DEV_MODE_NO_DB=true" : "DEV_MODE_NO_DB=",
+    "",
+    `DATABASE_URL=${db.app || PLACEHOLDER_DB}`,
+    `NEXTAUTH_URL=http://localhost:3001`,
+    `NEXTAUTH_SECRET=${s.nextAuthSecret}`,
+    `AUTH_SECRET=${s.nextAuthSecret}`,
+    `CSRF_SECRET=${s.csrfSecret}`,
+    "",
+    `NEXT_PUBLIC_APP_URL=http://localhost:3001`,
+    `NEXT_PUBLIC_API_URL=http://localhost:4000`,
+    "",
+    `KOMPLIAN_API_URL=http://localhost:4000`,
+    `KOMPLIAN_API_KEY=${s.apiKey}`,
+    `KOMPLIAN_INTERNAL_WEBHOOK_SECRET=${s.internalWebhook}`,
+    "",
+    `ENCRYPTION_KEY=${s.encryptionKey}`,
+    `TWO_FACTOR_ENCRYPTION_KEY=${s.twoFactorEnc}`,
+    `HASH_SECRET=${s.hashSecret}`,
+    "",
+    "# Optional: OPENAI_API_KEY=  Stripe, Shopify, Google OAuth — ver app/.env.example",
+  ];
+  writeAtomic(p, lines.join("\n"));
+  return { path: p, skipped: false };
+}
+
+function writeApiEnv(root, s, db, opts) {
+  const p = join(root, "api", ".env.local");
+  if (existsSync(p) && !opts.force) return { path: p, skipped: true };
+  const appU = db.apiApp || PLACEHOLDER_DB;
+  const adminU = db.apiAdmin || PLACEHOLDER_DB;
+  const webU = db.apiWeb || PLACEHOLDER_DB;
+  const lines = [
+    header("api"),
+    `APP_DATABASE_URL=${appU}`,
+    `ADMIN_DATABASE_URL=${adminU}`,
+    `WEB_DATABASE_URL=${webU}`,
+    "",
+    `API_KEY=${s.apiKey}`,
+    `ADMIN_API_KEY=${s.adminApiKey}`,
+    `KOMPLIAN_INTERNAL_WEBHOOK_SECRET=${s.internalWebhook}`,
+    `JWT_SECRET=${s.jwtSecret}`,
+    `ENCRYPTION_KEY=${s.encryptionKey}`,
+    "",
+    "# OPENAI_API_KEY=  RESEND_API_KEY=  — ver api/.env.example",
+    "",
+    `CRON_SECRET=${s.cronSecret}`,
+    "",
+    `APP_URL=http://localhost:3001`,
+    `WEB_URL=http://localhost:3003`,
+    `ADMIN_URL=http://localhost:3002`,
+    `API_BASE_URL=http://localhost:4000`,
+    "",
+    `PORT=4000`,
+    `NODE_ENV=development`,
+    `LOG_LEVEL=debug`,
+  ];
+  writeAtomic(p, lines.join("\n"));
+  return { path: p, skipped: false };
+}
+
+function writeWebEnv(root, s, db, opts) {
+  const p = join(root, "web", ".env.local");
+  if (existsSync(p) && !opts.force) return { path: p, skipped: true };
+  const lines = [
+    header("web"),
+    `DATABASE_URL=${db.web || PLACEHOLDER_DB}`,
+    `KOMPLIAN_API_URL=http://localhost:4000`,
+    `KOMPLIAN_API_KEY=${s.apiKey}`,
+    "",
+    "# GMAIL_USER= GMAIL_PASS= — opcional",
+  ];
+  writeAtomic(p, lines.join("\n"));
+  return { path: p, skipped: false };
+}
+
+function writeAdminEnv(root, s, db, opts) {
+  const p = join(root, "admin", ".env.local");
+  if (existsSync(p) && !opts.force) return { path: p, skipped: true };
+  const lines = [
+    header("admin"),
+    `DATABASE_URL=${db.admin || PLACEHOLDER_DB}`,
+    `NEXTAUTH_URL=http://localhost:3002`,
+    `NEXTAUTH_SECRET=${s.nextAuthAdmin}`,
+    `AUTH_SECRET=${s.nextAuthAdmin}`,
+    `API_URL=http://localhost:4000`,
+    `ADMIN_API_KEY=${s.adminApiKey}`,
+  ];
+  writeAtomic(p, lines.join("\n"));
+  return { path: p, skipped: false };
+}
+
+function writeDocsEnv(root, opts) {
+  const p = join(root, "docs", ".env.local");
+  if (existsSync(p) && !opts.force) return { path: p, skipped: true };
+  const lines = [
+    header("docs"),
+    "# Vacío: docs no requiere secretos para next dev local",
+  ];
+  writeAtomic(p, lines.join("\n"));
+  return { path: p, skipped: false };
+}
+
+async function confirmOverwrite(yes) {
+  if (yes) return true;
+  const rl = createInterface({ input, output });
+  const ans = await rl.question(
+    `\n${c.bold}Sobrescribir .env.local existentes? [y/N]${c.reset} `
+  );
+  rl.close();
+  return /^y(es)?$/i.test((ans || "").trim());
+}
+
+function parseLocalhostArgs(argv) {
+  const opts = {
+    yes: false,
+    force: false,
+    envOnly: false,
+    workspace: "",
+    minimal: false,
+    help: false,
+  };
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--yes" || a === "-y") opts.yes = true;
+    else if (a === "--force") opts.force = true;
+    else if (a === "--env-only") opts.envOnly = true;
+    else if (a === "--minimal") opts.minimal = true;
+    else if (a === "-h" || a === "--help") opts.help = true;
+    else if (a === "--workspace" || a === "-w") opts.workspace = argv[++i] || "";
+    else if (a.startsWith("-")) {
+      log(`${c.red}✗${c.reset} Opción desconocida: ${a}`);
+      process.exit(1);
+    } else rest.push(a);
+  }
+  if (rest[0]) opts.workspace = rest[0];
+  return opts;
+}
+
+function usageLocalhost() {
+  log(`Uso: npx komplian localhost [opciones] [carpeta-monorepo]`);
+  log(``);
+  log(`  Genera .env.local por proyecto (secretos aleatorios) y ejecuta npm run dev en paralelo.`);
+  log(`  ${c.dim}Neon: export KOMPLIAN_LOCALHOST_DATABASE_URL=… o komplian-localhost.secrets.env${c.reset}`);
+  log(``);
+  log(`  -y, --yes       Sin confirmación interactiva`);
+  log(`  --force         Sobrescribir .env.local aunque existan`);
+  log(`  --minimal       Solo app + web + docs (omitir api y admin)`);
+  log(`  --env-only      Solo escribir env, no arrancar servidores`);
+  log(`  -w, --workspace Ruta al monorepo (por defecto: cwd)`);
+  log(`  -h, --help`);
+}
+
+function checkNodeModules(root, names) {
+  const missing = [];
+  for (const n of names) {
+    if (!existsSync(join(root, n, "node_modules"))) missing.push(n);
+  }
+  return missing;
+}
+
+export async function runLocalhost(argv) {
+  const opts = parseLocalhostArgs(argv);
+  if (opts.help) {
+    usageLocalhost();
+    return;
+  }
+
+  let workspaceRoot = opts.workspace.trim()
+    ? resolve(opts.workspace.replace(/^~(?=$|[/\\])/, process.env.HOME || ""))
+    : findWorkspaceRoot(process.cwd());
+
+  if (!existsSync(join(workspaceRoot, "api", "package.json"))) {
+    log(`${c.red}✗${c.reset} No parece un monorepo Komplian (falta api/package.json): ${workspaceRoot}`);
+    process.exit(1);
+  }
+
+  const db = resolveDatabaseUrls(workspaceRoot);
+  const dbForWrites = {
+    app: db.app || PLACEHOLDER_DB,
+    admin: db.admin || PLACEHOLDER_DB,
+    web: db.web || PLACEHOLDER_DB,
+    apiApp: db.apiApp || PLACEHOLDER_DB,
+    apiAdmin: db.apiAdmin || PLACEHOLDER_DB,
+    apiWeb: db.apiWeb || PLACEHOLDER_DB,
+  };
+
+  const hasAnyEnv = [
+    "app",
+    "api",
+    "web",
+    "admin",
+    "docs",
+  ].some((name) => existsSync(join(workspaceRoot, name, ".env.local")));
+
+  if (hasAnyEnv && !opts.force) {
+    const ok = await confirmOverwrite(opts.yes);
+    if (!ok) {
+      log(`${c.yellow}○${c.reset} Cancelado. Usa ${c.bold}--force${c.reset} para regenerar.`);
+      return;
+    }
+    opts.force = true;
+  }
+
+  const s = buildShared();
+
+  const written = [];
+  written.push(writeAppEnv(workspaceRoot, s, dbForWrites, opts));
+  if (!opts.minimal) {
+    written.push(writeApiEnv(workspaceRoot, s, dbForWrites, opts));
+    written.push(writeWebEnv(workspaceRoot, s, dbForWrites, opts));
+    written.push(writeAdminEnv(workspaceRoot, s, dbForWrites, opts));
+  } else {
+    written.push(writeWebEnv(workspaceRoot, s, dbForWrites, opts));
+  }
+  written.push(writeDocsEnv(workspaceRoot, opts));
+
+  log("");
+  log(`${c.cyan}━━ .env.local ━━${c.reset} ${c.dim}(permisos 600)${c.reset}`);
+  for (const w of written) {
+    const st = w.skipped ? `${c.dim}sin cambios${c.reset}` : `${c.green}ok${c.reset}`;
+    log(`  ${st} ${w.path}`);
+  }
+
+  if (!db.hasReal && !opts.minimal) {
+    log("");
+    log(`${c.yellow}⚠${c.reset} Sin URLs Neon reales: api/admin/web usarán un placeholder local.`);
+    log(`  ${c.dim}Define KOMPLIAN_LOCALHOST_DATABASE_URL o komplian-localhost.secrets.env${c.reset}`);
+    log(`  ${c.dim}O usa ${c.bold}--minimal${c.reset} para solo app + web + docs.${c.reset}`);
+  }
+
+  if (opts.envOnly) {
+    log("");
+    log(`${c.green}✓${c.reset} Solo entorno. Arranca con: ${c.bold}npx komplian localhost --yes${c.reset}`);
+    return;
+  }
+
+  const services = opts.minimal
+    ? ["app", "web", "docs"]
+    : ["api", "app", "web", "admin", "docs"];
+  const missing = checkNodeModules(workspaceRoot, services);
+  if (missing.length) {
+    log("");
+    log(`${c.red}✗${c.reset} Falta node_modules en: ${missing.join(", ")}`);
+    log(`  ${c.dim}Ejecuta npm install en cada carpeta (o npx komplian onboard --yes --install).${c.reset}`);
+    process.exit(1);
+  }
+
+  const colors = "blue,green,cyan,magenta,yellow";
+  const names = services.join(",");
+  const scripts = services.map((name) => {
+    const dir = join(workspaceRoot, name);
+    if (/[\s"]/.test(dir)) {
+      return `npm run dev --prefix "${dir.replace(/"/g, '\\"')}"`;
+    }
+    return `npm run dev --prefix ${dir}`;
+  });
+
+  log("");
+  log(`${c.cyan}━━ Servicios (${services.length}) ━━${c.reset} ${workspaceRoot}`);
+  log(`${c.dim}Ctrl+C detiene todos.${c.reset}`);
+  log("");
+
+  const child = spawn(
+    process.platform === "win32" ? "npx.cmd" : "npx",
+    ["--yes", "concurrently@9", "-c", colors, "-n", names, ...scripts],
+    {
+      cwd: workspaceRoot,
+      stdio: "inherit",
+      shell: true,
+      env: { ...process.env },
+    }
+  );
+
+  const killAll = () => {
+    try {
+      child.kill("SIGINT");
+    } catch {
+      /* ignore */
+    }
+  };
+  process.on("SIGINT", () => {
+    killAll();
+    process.exit(0);
+  });
+  process.on("SIGTERM", killAll);
+
+  child.on("exit", (code) => {
+    process.exit(code ?? 0);
+  });
+}

package/komplian-onboard.mjs

@@ -394,10 +394,11 @@ function npmInstallEach(workspace) {
 }
 
 function usage() {
-  log(`Uso: komplian onboard [opciones] [carpeta]  |  komplian postman [opciones]`);
+  log(`Uso: komplian onboard [opciones] [carpeta]  |  komplian postman [opciones]  |  komplian localhost [opciones]`);
   log(`  npx komplian onboard --yes`);
   log(`  npx komplian postman login   ${c.dim}(una vez · guarda API key)${c.reset}`);
   log(`  npx komplian postman --yes    ${c.dim}(email @komplian.com)${c.reset}`);
+  log(`  npx komplian localhost --yes  ${c.dim}(env local + api app web admin docs)${c.reset}`);
   log(``);
   log(`  Antes (una vez): gh auth login -h github.com -s repo -s read:org -w`);
   log(`  Requisitos: Node 18+, git, GitHub CLI (gh)`);
@@ -486,6 +487,11 @@ async function main() {
     await runPostman(rawArgv.slice(1));
     return;
   }
+  if (rawArgv[0] === "localhost") {
+    const { runLocalhost } = await import("./komplian-localhost.mjs");
+    await runLocalhost(rawArgv.slice(1));
+    return;
+  }
 
   const configPath = join(__dirname, "komplian-team-repos.json");
   const { argv, fromOnboardSubcommand } = normalizeArgv(rawArgv);

package/komplian-postman.mjs

@@ -5,7 +5,8 @@
  * Requisitos: Node 18+. Primera vez: npx komplian postman login
  *
  * Clave: POSTMAN_API_KEY o ~/.komplian/postman-api-key (npx komplian postman login)
- * Opcional: POSTMAN_WORKSPACE_ID, KOMPLIAN_EMAIL_DOMAIN, KOMPLIAN_POSTMAN_KEY_FILE
+ * Seguridad: no registrar secretos; errores API redactados; login sin eco (TTY); ~/.komplian 700 + key 600.
+ * Opcional: POSTMAN_WORKSPACE_ID, KOMPLIAN_EMAIL_DOMAIN, KOMPLIAN_POSTMAN_KEY_FILE, KOMPLIAN_DEBUG
  */
 
 import {
@@ -36,6 +37,175 @@ function log(s = "") {
   console.log(s);
 }
 
+/** Ruta para logs sin exponer home completo (solo prefijo ~). */
+function formatHomePath(absPath) {
+  const h = homedir();
+  if (absPath.startsWith(h)) return `~${absPath.slice(h.length)}`;
+  return absPath;
+}
+
+function maskEmail(email) {
+  if (!email || typeof email !== "string" || !email.includes("@")) {
+    return "[sin email]";
+  }
+  const [user, domain] = email.split("@");
+  if (!domain) return "[sin email]";
+  const u =
+    user.length <= 1 ? "*" : `${user[0]}${"*".repeat(Math.min(3, user.length - 1))}`;
+  return `${u}@${domain}`;
+}
+
+function looksLikeSecretString(s) {
+  return (
+    typeof s === "string" &&
+    s.length >= 24 &&
+    /^[A-Za-z0-9_\-.+/=]+$/.test(s)
+  );
+}
+
+/** Solo mensajes genéricos; nunca volcar cuerpos crudos de la API (pueden incluir tokens). */
+function safeApiErrorHint(body) {
+  if (body == null || typeof body !== "object") return "";
+  const parts = [];
+  const code = body.error?.name || body.error?.code || body.error?.type;
+  if (typeof code === "string" && code.length < 64 && !looksLikeSecretString(code)) {
+    parts.push(code);
+  }
+  const msg = body.error?.message || body.message;
+  if (
+    typeof msg === "string" &&
+    msg.length > 0 &&
+    msg.length < 160 &&
+    !looksLikeSecretString(msg)
+  ) {
+    parts.push(msg);
+  }
+  return parts.join(" · ").slice(0, 200);
+}
+
+function sanitizeForLog(value, depth = 0) {
+  if (depth > 8) return "[…]";
+  if (value == null) return value;
+  if (typeof value === "string") {
+    if (looksLikeSecretString(value)) return "[redacted]";
+    return value.length > 80 ? `${value.slice(0, 40)}…` : value;
+  }
+  if (typeof value !== "object") return value;
+  if (Array.isArray(value)) {
+    return value.slice(0, 15).map((v) => sanitizeForLog(v, depth + 1));
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    const lower = k.toLowerCase();
+    if (
+      /(password|secret|token|apikey|api_key|authorization|credential|bearer|pmak|pm_)/i.test(
+        k
+      ) ||
+      lower === "value" ||
+      (lower === "key" && depth > 0)
+    ) {
+      out[k] = "[redacted]";
+    } else {
+      out[k] = sanitizeForLog(v, depth + 1);
+    }
+  }
+  return out;
+}
+
+function logApiFailure(context, status, body) {
+  const hint = safeApiErrorHint(body);
+  let extra = "";
+  if (
+    process.env.KOMPLIAN_DEBUG === "1" ||
+    process.env.KOMPLIAN_DEBUG === "true"
+  ) {
+    try {
+      extra = ` ${JSON.stringify(sanitizeForLog(body)).slice(0, 480)}`;
+    } catch {
+      extra = " [debug: no serializable]";
+    }
+  }
+  log(
+    `${c.yellow}○${c.reset} ${context}: HTTP ${status}${hint ? ` — ${hint}` : ""}${extra}`
+  );
+}
+
+function ensureSecureKomplianDir() {
+  const dir = join(homedir(), ".komplian");
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try {
+    chmodSync(dir, 0o700);
+  } catch {
+    /* Windows u otros */
+  }
+  return dir;
+}
+
+/**
+ * Lectura de API key sin eco (TTY). Fallback con aviso si no hay raw mode (p. ej. algunos Windows).
+ */
+async function readPasswordLine(promptText) {
+  const prompt = `${c.cyan}${promptText}${c.reset}`;
+  if (!input.isTTY) {
+    return new Promise((resolve, reject) => {
+      const chunks = [];
+      input.on("data", (d) => chunks.push(d));
+      input.on("end", () => {
+        resolve(Buffer.concat(chunks).toString("utf8").trim());
+      });
+      input.on("error", reject);
+    });
+  }
+  if (typeof input.setRawMode !== "function") {
+    log(
+      `${c.dim}○ Entrada visible (terminal sin modo oculto). No compartas pantalla con la clave.${c.reset}`
+    );
+    const rl = createInterface({ input, output });
+    const line = await rl.question(
+      `${c.cyan}Postman API key${c.reset} (Settings → API keys): `
+    );
+    rl.close();
+    return line.trim();
+  }
+  return new Promise((resolve) => {
+    process.stderr.write(prompt);
+    let buf = "";
+    const cleanup = () => {
+      try {
+        input.setRawMode(false);
+      } catch {
+        /* ignore */
+      }
+      input.removeListener("data", onData);
+    };
+    const onData = (chunk) => {
+      const s = chunk.toString("utf8");
+      for (let i = 0; i < s.length; i++) {
+        const code = s.charCodeAt(i);
+        if (code === 13 || code === 10) {
+          cleanup();
+          process.stderr.write("\n");
+          resolve(buf.trim());
+          return;
+        }
+        if (code === 3) {
+          cleanup();
+          process.exit(130);
+        }
+        if (code === 127 || code === 8) {
+          buf = buf.slice(0, -1);
+          continue;
+        }
+        buf += s[i];
+      }
+    };
+    input.setRawMode(true);
+    input.resume();
+    input.setEncoding("utf8");
+    input.on("data", onData);
+  });
+}
+
 function defaultKeyPath() {
   const override = process.env.KOMPLIAN_POSTMAN_KEY_FILE?.trim();
   if (override) return resolve(override);
@@ -65,11 +235,102 @@ function printMissingKeyHelp() {
   log(``);
   log(`  ${c.dim}O en la sesión actual: export POSTMAN_API_KEY=…${c.reset}`);
   log(
-    `${c.dim}  Archivo manual: ${defaultKeyPath()}${c.reset}`
+    `${c.dim}  Archivo manual: ${formatHomePath(defaultKeyPath())}${c.reset}`
   );
   process.exit(1);
 }
 
+/** Parseo mínimo .env (sin dependencia dotenv). */
+function parseEnvFile(text) {
+  const out = {};
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (!t || t.startsWith("#")) continue;
+    const eq = t.indexOf("=");
+    if (eq < 1) continue;
+    const key = t.slice(0, eq).trim();
+    let val = t.slice(eq + 1).trim();
+    if (
+      (val.startsWith('"') && val.endsWith('"')) ||
+      (val.startsWith("'") && val.endsWith("'"))
+    ) {
+      val = val.slice(1, -1);
+    }
+    out[key] = val;
+  }
+  return out;
+}
+
+function discoverDotenvPaths(cwd, extraPath) {
+  const paths = [];
+  if (extraPath?.trim()) paths.push(resolve(extraPath.trim()));
+  if (process.env.KOMPLIAN_DOTENV?.trim()) {
+    paths.push(resolve(process.env.KOMPLIAN_DOTENV.trim()));
+  }
+  for (const rel of [
+    "api/.env",
+    "../api/.env",
+    ".env",
+    "app/.env",
+    "../app/.env",
+  ]) {
+    paths.push(resolve(cwd, rel));
+  }
+  return [...new Set(paths)];
+}
+
+function loadMergedEnvFiles(cwd, extraDotenv) {
+  const merged = {};
+  for (const p of discoverDotenvPaths(cwd, extraDotenv)) {
+    if (!existsSync(p)) continue;
+    try {
+      Object.assign(merged, parseEnvFile(readFileSync(p, "utf8")));
+    } catch {
+      /* ignore */
+    }
+  }
+  return merged;
+}
+
+/**
+ * Valores para variables de Postman (API Komplian): API_KEY, ADMIN_API_KEY, IDs, etc.
+ * Orden: process.env por cada alias, luego claves en .env fusionados.
+ */
+function loadKomplianSecrets(cwd, extraDotenv) {
+  const file = loadMergedEnvFiles(cwd, extraDotenv);
+  const get = (...keys) => {
+    for (const k of keys) {
+      const e = process.env[k];
+      if (e != null && String(e).trim()) return String(e).trim();
+    }
+    for (const k of keys) {
+      const f = file[k];
+      if (f != null && String(f).trim()) return String(f).trim();
+    }
+    return "";
+  };
+  return {
+    apiKey: get("KOMPLIAN_API_KEY", "API_KEY"),
+    adminApiKey: get("KOMPLIAN_ADMIN_API_KEY", "ADMIN_API_KEY"),
+    workspaceId: get("KOMPLIAN_WORKSPACE_ID", "WORKSPACE_ID"),
+    widgetId: get("KOMPLIAN_WIDGET_ID", "WIDGET_ID"),
+    sessionId: get("KOMPLIAN_SESSION_ID", "SESSION_ID"),
+    leadId: get("KOMPLIAN_LEAD_ID", "LEAD_ID"),
+    flowId: get("KOMPLIAN_FLOW_ID", "FLOW_ID"),
+    sourceId: get("KOMPLIAN_SOURCE_ID", "SOURCE_ID"),
+    documentId: get("KOMPLIAN_DOCUMENT_ID", "DOCUMENT_ID"),
+    queryId: get("KOMPLIAN_QUERY_ID", "QUERY_ID"),
+    userId: get("KOMPLIAN_USER_ID", "USER_ID"),
+    entryId: get("KOMPLIAN_ENTRY_ID", "ENTRY_ID"),
+  };
+}
+
+function summarizeSecretsLoaded(s) {
+  return Object.keys(s).filter(
+    (k) => s[k] != null && String(s[k]).trim() !== ""
+  );
+}
+
 function headers(apiKey) {
   return {
     "X-API-Key": apiKey,
@@ -279,52 +540,50 @@ function buildCollection() {
   };
 }
 
-function buildEnvironments() {
-  const secret = (key) => ({
-    key,
-    value: "",
-    type: "secret",
-    enabled: true,
-  });
-  const plain = (key, value) => ({
-    key,
-    value,
-    type: "default",
-    enabled: true,
-  });
+/**
+ * @param {Record<string, string>} secrets - desde API_KEY / api/.env (no subir a git los JSON locales).
+ */
+function buildEnvironments(secrets = {}) {
+  const pick = (key, fallback = "") => {
+    const v = secrets[key];
+    if (v != null && String(v).trim() !== "") return String(v).trim();
+    return fallback;
+  };
+  const row = (key, def = "") => {
+    const val = pick(key, def);
+    const isSecret = key === "apiKey" || key === "adminApiKey";
+    return {
+      key,
+      value: val,
+      type: isSecret ? "secret" : "default",
+      enabled: true,
+    };
+  };
 
-  const common = [
-    plain("baseUrl", ""),
-    secret("apiKey"),
-    secret("adminApiKey"),
-    plain("workspaceId", ""),
-    plain("widgetId", ""),
-    plain("sessionId", ""),
-    plain("leadId", ""),
-    plain("flowId", ""),
-    plain("sourceId", ""),
-    plain("documentId", ""),
-    plain("queryId", ""),
-    plain("userId", ""),
-    plain("entryId", ""),
+  const rowsForBase = (baseUrl) => [
+    row("baseUrl", baseUrl),
+    row("apiKey"),
+    row("adminApiKey"),
+    row("workspaceId"),
+    row("widgetId"),
+    row("sessionId"),
+    row("leadId"),
+    row("flowId"),
+    row("sourceId"),
+    row("documentId"),
+    row("queryId"),
+    row("userId"),
+    row("entryId"),
   ];
 
   return [
     {
       name: "Komplian — Local Dev",
-      values: common.map((v) =>
-        v.key === "baseUrl"
-          ? { ...v, value: "http://localhost:4000", type: "default" }
-          : { ...v }
-      ),
+      values: rowsForBase("http://localhost:4000"),
     },
     {
       name: "Komplian — Production",
-      values: common.map((v) =>
-        v.key === "baseUrl"
-          ? { ...v, value: "https://api.komplian.com", type: "default" }
-          : { ...v }
-      ),
+      values: rowsForBase("https://api.komplian.com"),
     },
   ];
 }
@@ -358,7 +617,7 @@ async function verifyKomplianEmail(apiKey, domain) {
   }
   if (!emailAllowed(email, domain)) {
     log(
-      `${c.red}✗${c.reset} Este comando solo permite cuentas **@${domain}**. Sesión Postman: ${c.bold}${email}${c.reset}`
+      `${c.red}✗${c.reset} Este comando solo permite cuentas **@${domain}**. Sesión: ${c.bold}${maskEmail(email)}${c.reset}`
     );
     log(
       `${c.dim}  Crea la API key desde una cuenta @${domain} o añade ese email a tu usuario en Postman.${c.reset}`
@@ -366,7 +625,7 @@ async function verifyKomplianEmail(apiKey, domain) {
     process.exit(1);
   }
   log(
-    `${c.green}✓${c.reset} Postman: ${c.bold}${email}${c.reset} (${c.dim}dominio permitido${c.reset})`
+    `${c.green}✓${c.reset} Postman: ${c.bold}${maskEmail(email)}${c.reset} (${c.dim}dominio permitido${c.reset})`
   );
   return email;
 }
@@ -387,13 +646,93 @@ async function createEnvironment(apiKey, workspaceId, env) {
   });
 }
 
+async function listCollections(apiKey, workspaceId) {
+  const q = new URLSearchParams({ workspace: workspaceId });
+  return pmFetch(apiKey, `/collections?${q}`);
+}
+
+async function listEnvironments(apiKey, workspaceId) {
+  const q = new URLSearchParams({ workspace: workspaceId });
+  return pmFetch(apiKey, `/environments?${q}`);
+}
+
+function firstArray(...candidates) {
+  for (const c of candidates) {
+    if (Array.isArray(c)) return c;
+  }
+  return [];
+}
+
+function findCollectionByName(body, name) {
+  const arr = firstArray(
+    body.collections,
+    body.data?.collections,
+    body.data,
+    Array.isArray(body) ? body : null
+  );
+  return arr.find(
+    (c) =>
+      c.name === name ||
+      c.collection?.name === name ||
+      c.info?.name === name
+  );
+}
+
+function findEnvironmentByName(body, name) {
+  const arr = firstArray(
+    body.environments,
+    body.data?.environments,
+    body.data,
+    Array.isArray(body) ? body : null
+  );
+  return arr.find((e) => e.name === name);
+}
+
+async function upsertCollection(apiKey, workspaceId, collection) {
+  const name = collection.info?.name;
+  const list = await listCollections(apiKey, workspaceId);
+  if (!list.ok) {
+    return { ok: false, status: list.status, body: list.body };
+  }
+  const existing = findCollectionByName(list.body, name);
+  if (!existing) {
+    const r = await createCollection(apiKey, workspaceId, collection);
+    return { ...r, op: "create" };
+  }
+  const uid = existing.uid ?? existing.id;
+  const r = await pmFetch(apiKey, `/collections/${uid}`, {
+    method: "PUT",
+    body: JSON.stringify({ collection }),
+  });
+  return { ...r, op: "update" };
+}
+
+async function upsertEnvironment(apiKey, workspaceId, env) {
+  const list = await listEnvironments(apiKey, workspaceId);
+  if (!list.ok) {
+    return { ok: false, status: list.status, body: list.body };
+  }
+  const existing = findEnvironmentByName(list.body, env.name);
+  if (!existing) {
+    const r = await createEnvironment(apiKey, workspaceId, env);
+    return { ...r, op: "create" };
+  }
+  const uid = existing.uid ?? existing.id;
+  const r = await pmFetch(apiKey, `/environments/${uid}`, {
+    method: "PUT",
+    body: JSON.stringify({ environment: env }),
+  });
+  return { ...r, op: "update" };
+}
+
 function parseArgs(argv) {
-  const out = { yes: false, exportOnly: false, outDir: "", help: false };
+  const out = { yes: false, exportOnly: false, outDir: "", help: false, dotenv: "" };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--yes" || a === "-y") out.yes = true;
     else if (a === "--export-only") out.exportOnly = true;
     else if (a === "--out") out.outDir = argv[++i] || "";
+    else if (a === "--dotenv") out.dotenv = argv[++i] || "";
     else if (a === "-h" || a === "--help") out.help = true;
     else if (a.startsWith("-")) {
       log(`${c.red}✗${c.reset} Opción desconocida: ${a}`);
@@ -423,8 +762,10 @@ function usage() {
   log(`  -y, --yes           Sin prompts extra`);
   log(`  --export-only       Solo escribe JSON en disco (no llama a la API de Postman)`);
   log(`  --out <dir>         Carpeta para export (por defecto: ./komplian-postman)`);
+  log(`  --dotenv <ruta>     .env extra (además de api/.env, .env, KOMPLIAN_DOTENV)`);
   log(`  -h, --help`);
   log(``);
+  log(`  Variables Komplian en Postman: API_KEY, ADMIN_API_KEY, WORKSPACE_ID, … (env o .env)`);
   log(`  Opcional: POSTMAN_WORKSPACE_ID, KOMPLIAN_EMAIL_DOMAIN, KOMPLIAN_POSTMAN_KEY_FILE`);
 }
 
@@ -436,25 +777,6 @@ function usageLogin() {
   log(`  Postman → Settings (avatar) → API keys → Generate`);
 }
 
-async function promptApiKey() {
-  if (input.isTTY) {
-    const rl = createInterface({ input, output });
-    const line = await rl.question(
-      `${c.cyan}Pega tu Postman API key${c.reset} (Settings → API keys): `
-    );
-    rl.close();
-    return line.trim();
-  }
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    input.on("data", (d) => chunks.push(d));
-    input.on("end", () => {
-      resolve(Buffer.concat(chunks).toString("utf8").trim());
-    });
-    input.on("error", reject);
-  });
-}
-
 async function runPostmanLogin(argv) {
   const la = parseLoginArgs(argv);
   if (la.help) {
@@ -471,7 +793,9 @@ async function runPostmanLogin(argv) {
   const domain = (process.env.KOMPLIAN_EMAIL_DOMAIN || "komplian.com").trim();
   const keyPath = defaultKeyPath();
 
-  let apiKey = await promptApiKey();
+  let apiKey = await readPasswordLine(
+    "Postman API key (no se muestra al escribir; Settings → API keys): "
+  );
   if (!apiKey) {
     log(`${c.red}✗${c.reset} Clave vacía.`);
     process.exit(1);
@@ -479,7 +803,7 @@ async function runPostmanLogin(argv) {
 
   await verifyKomplianEmail(apiKey, domain);
 
-  mkdirSync(join(homedir(), ".komplian"), { recursive: true });
+  ensureSecureKomplianDir();
   writeFileSync(keyPath, `${apiKey}\n`, { encoding: "utf8", mode: 0o600 });
   try {
     chmodSync(keyPath, 0o600);
@@ -489,7 +813,7 @@ async function runPostmanLogin(argv) {
 
   log("");
   log(
-    `${c.green}✓${c.reset} Guardada en ${c.bold}${keyPath}${c.reset} (solo tu usuario).`
+    `${c.green}✓${c.reset} Guardada en ${c.bold}${formatHomePath(keyPath)}${c.reset} (permiso 600; no subir a git).`
   );
   log(
     `${c.dim}  Siguiente: ${c.reset}${c.cyan}npx komplian postman --yes${c.reset}`
@@ -522,14 +846,29 @@ export async function runPostman(argv) {
     printMissingKeyHelp();
   }
   if (source && source !== "POSTMAN_API_KEY") {
-    log(`${c.dim}→ API key: ${source}${c.reset}`);
+    log(`${c.dim}→ API key Postman desde: ${formatHomePath(source)}${c.reset}`);
   }
 
   const domain = (process.env.KOMPLIAN_EMAIL_DOMAIN || "komplian.com").trim();
   await verifyKomplianEmail(apiKey, domain);
 
   const collection = buildCollection();
-  const envs = buildEnvironments();
+  const cwd = process.cwd();
+  const secrets = loadKomplianSecrets(cwd, args.dotenv);
+  const envsForUpload = buildEnvironments(secrets);
+  const envsForExport = buildEnvironments({});
+
+  const filled = summarizeSecretsLoaded(secrets);
+  if (filled.length) {
+    log(
+      `${c.green}✓${c.reset} Komplian → Postman: ${c.dim}${filled.join(", ")}${c.reset} (process.env / .env)`
+    );
+  } else {
+    log(
+      `${c.dim}○ Sin API_KEY / ADMIN_API_KEY / IDs en env o .env — los entornos en Postman quedarán vacíos en esos campos.${c.reset}`
+    );
+  }
+
   const workspaceId = await pickWorkspaceId(
     apiKey,
     process.env.POSTMAN_WORKSPACE_ID
@@ -547,10 +886,10 @@ export async function runPostman(argv) {
   writeFileSync(collPath, JSON.stringify(collection, null, 2), "utf8");
   log(`${c.green}✓${c.reset} Export: ${c.dim}${collPath}${c.reset}`);
 
-  for (const env of envs) {
+  for (const env of envsForExport) {
     const safe = env.name.replace(/[\\/]/g, "-") + ".postman_environment.json";
     writeFileSync(join(outBase, safe), JSON.stringify({ ...env }, null, 2), "utf8");
-    log(`${c.green}✓${c.reset} Export: ${c.dim}${join(outBase, safe)}${c.reset}`);
+    log(`${c.green}✓${c.reset} Export: ${c.dim}${join(outBase, safe)}${c.reset} ${c.dim}(sin secretos; no commitear)${c.reset}`);
   }
 
   if (args.exportOnly) {
@@ -562,38 +901,40 @@ export async function runPostman(argv) {
   }
 
   log("");
-  log(`${c.cyan}━━ Subiendo a Postman (API) ━━${c.reset}`);
+  log(`${c.cyan}━━ Sincronizar Postman (crear o actualizar) ━━${c.reset}`);
 
-  const cr = await createCollection(apiKey, workspaceId, collection);
+  const cr = await upsertCollection(apiKey, workspaceId, collection);
   if (!cr.ok) {
+    logApiFailure("Colección API", cr.status, cr.body);
     log(
-      `${c.yellow}○${c.reset} Colección API: ${cr.status} — ${JSON.stringify(cr.body).slice(0, 400)}`
-    );
-    log(
-      `${c.dim}  Si el nombre ya existe, borra la colección antigua en Postman o importa el JSON exportado.${c.reset}`
+      `${c.dim}  Revisa permisos del workspace o importa el JSON exportado. Depuración: KOMPLIAN_DEBUG=1 (salida redactada).${c.reset}`
     );
   } else {
+    const verb = cr.op === "update" ? "actualizada" : "creada";
     const uid = cr.body?.collection?.uid || cr.body?.collection?.id || "?";
-    log(`${c.green}✓${c.reset} Colección creada en Postman (${uid})`);
+    log(`${c.green}✓${c.reset} Colección ${verb}: ${c.bold}Komplian API${c.reset} (${uid})`);
   }
 
-  for (const env of envs) {
-    const er = await createEnvironment(apiKey, workspaceId, {
+  for (const env of envsForUpload) {
+    const er = await upsertEnvironment(apiKey, workspaceId, {
       name: env.name,
       values: env.values,
     });
     if (!er.ok) {
+      logApiFailure(`Entorno "${env.name}"`, er.status, er.body);
+    } else {
+      const verb = er.op === "update" ? "actualizado" : "creado";
       log(
-        `${c.yellow}○${c.reset} Entorno "${env.name}": ${er.status} — ${JSON.stringify(er.body).slice(0, 200)}`
+        `${c.green}✓${c.reset} Entorno ${verb}: ${c.bold}${env.name}${c.reset}`
       );
-    } else {
-      log(`${c.green}✓${c.reset} Entorno: ${c.bold}${env.name}${c.reset}`);
     }
   }
 
   log("");
-  log(`${c.green}✓${c.reset} Abre Postman → workspace → revisa ${c.bold}Komplian API${c.reset} y los entornos.`);
-  log(
-    `${c.dim}  Rellena apiKey / adminApiKey / IDs en el entorno (secret).${c.reset}`
-  );
+  log(`${c.green}✓${c.reset} En Postman: elige entorno ${c.dim}(Local Dev / Production)${c.reset} y prueba las peticiones.`);
+  if (!filled.length) {
+    log(
+      `${c.dim}  Para rellenar apiKey: exporta API_KEY o pon api/.env y vuelve a ejecutar este comando.${c.reset}`
+    );
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "komplian",
-  "version": "0.4.1",
+  "version": "0.4.4",
   "description": "Komplian developer workspace: GitHub clone (onboard) + Postman collection/environments (postman). Node 18+.",
   "type": "module",
   "engines": {
@@ -12,6 +12,7 @@
   "files": [
     "komplian-onboard.mjs",
     "komplian-postman.mjs",
+    "komplian-localhost.mjs",
     "komplian-team-repos.json",
     "README.md"
   ],
@@ -19,7 +20,7 @@
     "access": "public"
   },
   "scripts": {
-    "prepublishOnly": "node --check komplian-onboard.mjs && node --check komplian-postman.mjs"
+    "prepublishOnly": "node --check komplian-onboard.mjs && node --check komplian-postman.mjs && node --check komplian-localhost.mjs"
   },
   "keywords": [
     "komplian",