komplian 0.4.0 → 0.4.3

package/README.md

@@ -10,17 +10,29 @@
 
 1. En [Postman](https://postman.com) usa una cuenta con email **`@komplian.com`** (o añade ese email a tu perfil).
 2. Crea una **API key**: Settings → **API keys** → Generate.
-3. En la terminal:
+3. **Una vez por máquina** (guarda la clave en `~/.komplian/postman-api-key`; no hace falta `export` después):
+
+```bash
+npx komplian postman login
+```
+
+4. Cuando quieras sincronizar la colección:
 
 ```bash
-export POSTMAN_API_KEY=pmak-…
 npx komplian postman --yes
 ```
 
-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** (carpetas como en el workspace interno), los entornos **Komplian — Local Dev** y **Komplian — Production** (variables `baseUrl`, `apiKey`, `adminApiKey`, IDs, etc.), y deja copia en `./komplian-postman/*.json` por si hace falta importar a mano.
+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`. **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>` (si no, se usa un workspace por defecto con permiso de escritura)
+- Otro workspace: `POSTMAN_WORKSPACE_ID=<id>`
+- 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-onboard.mjs

@@ -396,7 +396,8 @@ function npmInstallEach(workspace) {
 function usage() {
   log(`Uso: komplian onboard [opciones] [carpeta]  |  komplian postman [opciones]`);
   log(`  npx komplian onboard --yes`);
-  log(`  npx komplian postman --yes   ${c.dim}(POSTMAN_API_KEY + email @komplian.com)${c.reset}`);
+  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(``);
   log(`  Antes (una vez): gh auth login -h github.com -s repo -s read:org -w`);
   log(`  Requisitos: Node 18+, git, GitHub CLI (gh)`);

package/komplian-postman.mjs

@@ -2,17 +2,24 @@
 /**
  * Komplian Postman — API key + email @komplian.com (Postman /me), luego colección + entornos.
  *
- * Requisitos: Node 18+, variable POSTMAN_API_KEY (Postman → Settings → API keys)
+ * Requisitos: Node 18+. Primera vez: npx komplian postman login
  *
- *   export POSTMAN_API_KEY=pmak-...
- *   npx komplian postman --yes
- *
- * Opcional: POSTMAN_WORKSPACE_ID (si no, usa el primer workspace con permiso de escritura)
- * Opcional: KOMPLIAN_EMAIL_DOMAIN=komplian.com (solo para pruebas internas del script)
+ * Clave: POSTMAN_API_KEY o ~/.komplian/postman-api-key (npx komplian postman login)
+ * 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 { writeFileSync, mkdirSync } from "node:fs";
+import {
+  writeFileSync,
+  mkdirSync,
+  readFileSync,
+  existsSync,
+  chmodSync,
+} from "node:fs";
 import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { stdin as input, stdout as output } from "node:process";
+import { createInterface } from "node:readline/promises";
 
 const POSTMAN_API = "https://api.getpostman.com";
 
@@ -30,6 +37,300 @@ 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);
+  return join(homedir(), ".komplian", "postman-api-key");
+}
+
+/**
+ * Orden: POSTMAN_API_KEY → ~/.komplian/postman-api-key (o KOMPLIAN_POSTMAN_KEY_FILE).
+ */
+function resolveApiKey() {
+  const env = process.env.POSTMAN_API_KEY?.trim();
+  if (env) return { key: env, source: "POSTMAN_API_KEY" };
+  const path = defaultKeyPath();
+  if (existsSync(path)) {
+    const k = readFileSync(path, "utf8").trim();
+    if (k) return { key: k, source: path };
+  }
+  return { key: "", source: null };
+}
+
+function printMissingKeyHelp() {
+  log(`${c.red}✗${c.reset} No hay API key de Postman.`);
+  log(``);
+  log(`  ${c.bold}Una vez por máquina:${c.reset}`);
+  log(`    ${c.cyan}npx komplian postman login${c.reset}`);
+  log(`    (pega la clave de Postman → Settings → API keys → Generate)`);
+  log(``);
+  log(`  ${c.dim}O en la sesión actual: export POSTMAN_API_KEY=…${c.reset}`);
+  log(
+    `${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,
@@ -239,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"),
     },
   ];
 }
@@ -305,7 +604,7 @@ async function verifyKomplianEmail(apiKey, domain) {
   const { ok, status, body } = await pmFetch(apiKey, "/me");
   if (!ok) {
     log(
-      `${c.red}✗${c.reset} POSTMAN_API_KEY inválida o sin acceso (${status}).`
+      `${c.red}✗${c.reset} API key de Postman inválida o sin acceso (${status}).`
     );
     process.exit(1);
   }
@@ -318,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}`
@@ -326,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;
 }
@@ -347,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}`);
@@ -363,40 +742,133 @@ function parseArgs(argv) {
   return out;
 }
 
+function parseLoginArgs(argv) {
+  const out = { help: false };
+  for (const a of argv) {
+    if (a === "-h" || a === "--help") out.help = true;
+    else if (a.startsWith("-")) {
+      log(`${c.red}✗${c.reset} Opción desconocida: ${a}`);
+      process.exit(1);
+    }
+  }
+  return out;
+}
+
 function usage() {
-  log(`Uso: komplian postman [opciones]`);
-  log(`  ${c.dim}POSTMAN_API_KEY${c.reset}   Obligatoria (Postman → Settings → API keys)`);
-  log(`  ${c.dim}Dominio email${c.reset}      Solo cuentas @komplian.com (verificado vía GET /me)`);
+  log(`Uso: komplian postman [opciones]  |  komplian postman login`);
+  log(`  Clave: ${c.dim}POSTMAN_API_KEY${c.reset} o archivo ${c.dim}~/.komplian/postman-api-key${c.reset} (véase ${c.cyan}postman login${c.reset})`);
+  log(`  Dominio email: solo @komplian.com (GET /me)`);
   log(``);
-  log(`  -y, --yes           Sin confirmaciones interactivas`);
+  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(`  Opcional: POSTMAN_WORKSPACE_ID, KOMPLIAN_EMAIL_DOMAIN (defecto: komplian.com)`);
+  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`);
+}
+
+function usageLogin() {
+  log(`Uso: komplian postman login`);
+  log(`  Guarda la API key de Postman en ${c.dim}~/.komplian/postman-api-key${c.reset} (permiso 600).`);
+  log(`  Tras esto: ${c.cyan}npx komplian postman --yes${c.reset} sin exportar variables.`);
+  log(``);
+  log(`  Postman → Settings (avatar) → API keys → Generate`);
+}
+
+async function runPostmanLogin(argv) {
+  const la = parseLoginArgs(argv);
+  if (la.help) {
+    usageLogin();
+    return;
+  }
+
+  log(`${c.cyan}━━ Postman login (Komplian) ━━${c.reset}`);
+  log(
+    `${c.dim}Cuenta con email @komplian.com. Genera la clave en Postman → Settings → API keys.${c.reset}`
+  );
+  log("");
+
+  const domain = (process.env.KOMPLIAN_EMAIL_DOMAIN || "komplian.com").trim();
+  const keyPath = defaultKeyPath();
+
+  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);
+  }
+
+  await verifyKomplianEmail(apiKey, domain);
+
+  ensureSecureKomplianDir();
+  writeFileSync(keyPath, `${apiKey}\n`, { encoding: "utf8", mode: 0o600 });
+  try {
+    chmodSync(keyPath, 0o600);
+  } catch {
+    /* Windows puede ignorar chmod */
+  }
+
+  log("");
+  log(
+    `${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}`
+  );
+}
+
+function normalizePostmanArgv(argv) {
+  const a = [...argv];
+  if (a[0] === "login") {
+    return { mode: "login", rest: a.slice(1) };
+  }
+  return { mode: "sync", rest: a };
 }
 
 export async function runPostman(argv) {
-  const args = parseArgs(argv);
+  const { mode, rest } = normalizePostmanArgv(argv);
+  if (mode === "login") {
+    await runPostmanLogin(rest);
+    return;
+  }
+
+  const args = parseArgs(rest);
   if (args.help) {
     usage();
     return;
   }
 
-  const apiKey = process.env.POSTMAN_API_KEY?.trim();
+  const { key: apiKey, source } = resolveApiKey();
   if (!apiKey) {
-    log(`${c.red}✗${c.reset} Falta ${c.bold}POSTMAN_API_KEY${c.reset} en el entorno.`);
-    log(
-      `${c.dim}  Postman → Settings (avatar) → API keys → Generate.${c.reset}`
-    );
-    process.exit(1);
+    printMissingKeyHelp();
+  }
+  if (source && source !== "POSTMAN_API_KEY") {
+    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
@@ -414,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) {
@@ -429,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.0",
+  "version": "0.4.3",
   "description": "Komplian developer workspace: GitHub clone (onboard) + Postman collection/environments (postman). Node 18+.",
   "type": "module",
   "engines": {