orch-mini 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orch-mini",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Orquestador declarativo mínimo: un stack.yaml describe la arquitectura, om renderiza docker-compose + nginx + scripts y levanta el stack.",
   "type": "module",
   "engines": {

package/src/info.ts

@@ -3,7 +3,6 @@ import { resolve } from 'node:path';
 import type { LoadedStack } from './parser.js';
 import { hasRepo, type Service, type Stack } from './schema.js';
 
-// Patrones que sugieren "el usuario debería completar esto antes de prod".
 const PLACEHOLDER_PATTERNS = [
   /^changeit-/i,
   /^dev-default-/i,
@@ -13,6 +12,9 @@ const PLACEHOLDER_PATTERNS = [
   /^your-/i,
 ];
 
+const WRAP_WIDTH = 78;
+const DESC_INDENT = '       ';   // 7 espacios — alineado con texto post-marker
+
 const C = supportsColor()
   ? {
       reset: '\x1b[0m',
@@ -22,8 +24,9 @@ const C = supportsColor()
       yellow: '\x1b[33m',
       green: '\x1b[32m',
       red: '\x1b[31m',
+      magenta: '\x1b[35m',
     }
-  : { reset: '', dim: '', bold: '', cyan: '', yellow: '', green: '', red: '' };
+  : { reset: '', dim: '', bold: '', cyan: '', yellow: '', green: '', red: '', magenta: '' };
 
 function supportsColor(): boolean {
   return process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
@@ -37,8 +40,9 @@ export function renderInfo(loaded: LoadedStack): string {
   const gw = stack.gateway;
 
   out.push(
-    header(`${stack.name}`) +
-      `  ${C.dim}${services.length} services${gw ? ` · gateway en :${gw.port}` : ''}${C.reset}`,
+    `${C.bold}${stack.name}${C.reset}  ${C.dim}${services.length} services${
+      gw ? ` · gateway en :${gw.port}` : ''
+    }${C.reset}`,
   );
 
   out.push('');
@@ -73,9 +77,7 @@ export function renderInfo(loaded: LoadedStack): string {
     const sorted = [...gw.routes].sort(
       (a, b) => effectiveLen(b.path) - effectiveLen(a.path),
     );
-    const maxUrl = Math.max(
-      ...sorted.map((r) => urlFor(gw.port, r.path).length),
-    );
+    const maxUrl = Math.max(...sorted.map((r) => urlFor(gw.port, r.path).length));
     for (const route of sorted) {
       const url = urlFor(gw.port, route.path);
       const note = route.strip_prefix ? `  ${C.dim}(strip prefix)${C.reset}` : '';
@@ -86,20 +88,31 @@ export function renderInfo(loaded: LoadedStack): string {
   const debugConfigs = services.filter(([, s]) => s.debug_port !== undefined);
   if (debugConfigs.length > 0) {
     out.push('');
-    out.push(section('Debug (VS Code attach via om vscode)'));
+    out.push(section('Debug') + `  ${C.dim}(om vscode genera launch.json)${C.reset}`);
+    const maxName = Math.max(...debugConfigs.map(([n]) => n.length));
     for (const [name, svc] of debugConfigs) {
-      out.push(`  ${name.padEnd(30)} attach → localhost:${svc.debug_port}`);
+      out.push(
+        `  ${name.padEnd(maxName + 2)}${C.dim}attach →${C.reset} localhost:${svc.debug_port}`,
+      );
     }
   }
 
-  const concerns = collectConcerns(stack, loaded.workDir);
+  const concerns = collectConcerns(stack);
   if (concerns.length > 0) {
     out.push('');
     out.push(`${C.yellow}⚠${C.reset}  ${C.bold}Probablemente quieras tocar${C.reset}`);
-    const maxKey = Math.max(...concerns.map((c) => `${c.service}.${c.key}`.length));
-    for (const c of concerns) {
-      const k = `${c.service}.${c.key}`.padEnd(maxKey + 2);
-      out.push(`  ${k}${C.dim}${c.reason}${C.reset}`);
+    const grouped = groupByService(concerns);
+    for (const [svcName, items] of grouped) {
+      out.push('');
+      out.push(`  ${C.cyan}${svcName}${C.reset}`);
+      for (const c of items) {
+        out.push(`    ${renderConcernLine(c)}`);
+        if (c.description) {
+          for (const line of wrapText(c.description, WRAP_WIDTH - DESC_INDENT.length)) {
+            out.push(`    ${DESC_INDENT}${C.dim}${line}${C.reset}`);
+          }
+        }
+      }
     }
   } else {
     out.push('');
@@ -109,8 +122,45 @@ export function renderInfo(loaded: LoadedStack): string {
   return out.join('\n') + '\n';
 }
 
-function header(text: string): string {
-  return `${C.bold}${text}${C.reset}`;
+function renderConcernLine(c: Concern): string {
+  const marker = c.required
+    ? `${C.red}✗${C.reset}`
+    : c.reason.startsWith('placeholder')
+    ? `${C.yellow}!${C.reset}`
+    : `${C.dim}·${C.reset}`;
+  const tag = c.required ? ` ${C.red}[required]${C.reset}` : '';
+  return `${marker}${tag} ${C.bold}${c.key}${C.reset} ${C.dim}— ${c.reason}${C.reset}`;
+}
+
+function groupByService(concerns: Concern[]): Map<string, Concern[]> {
+  const grouped = new Map<string, Concern[]>();
+  for (const c of concerns) {
+    const list = grouped.get(c.service) ?? [];
+    list.push(c);
+    grouped.set(c.service, list);
+  }
+  // Ordenar items de cada service: required arriba.
+  for (const list of grouped.values()) {
+    list.sort((a, b) => (b.required ? 1 : 0) - (a.required ? 1 : 0));
+  }
+  return grouped;
+}
+
+function wrapText(text: string, width: number): string[] {
+  if (text.length <= width) return [text];
+  const words = text.split(/\s+/);
+  const lines: string[] = [];
+  let current = '';
+  for (const word of words) {
+    if ((current + ' ' + word).trim().length > width) {
+      if (current) lines.push(current);
+      current = word;
+    } else {
+      current = (current + ' ' + word).trim();
+    }
+  }
+  if (current) lines.push(current);
+  return lines;
 }
 
 function section(text: string): string {
@@ -129,11 +179,7 @@ function formatServiceRow(name: string, svc: Service): string {
 }
 
 function shortenRepo(repo: string): string {
-  // github.com/logieinc/foo.git → foo, /local → local
-  return repo
-    .replace(/\.git$/, '')
-    .split(/[/:]/)
-    .pop() ?? repo;
+  return repo.replace(/\.git$/, '').split(/[/:]/).pop() ?? repo;
 }
 
 function urlFor(port: number, path: string): string {
@@ -151,10 +197,7 @@ function collectRepos(stack: Stack): RepoEntry[] {
   const seen = new Map<string, RepoEntry>();
   for (const svc of Object.values(stack.services)) {
     if (!hasRepo(svc)) continue;
-    const slug = svc.repo
-      .replace(/\.git$/, '')
-      .split(/[/:]/)
-      .pop()!;
+    const slug = svc.repo.replace(/\.git$/, '').split(/[/:]/).pop()!;
     if (!seen.has(slug)) seen.set(slug, { slug, ref: svc.ref });
   }
   return [...seen.values()];
@@ -170,27 +213,35 @@ function collectDatabases(stack: Stack): Array<{ service: string; names: string[
   return out;
 }
 
-type Concern = { service: string; key: string; reason: string };
+type Concern = {
+  service: string;
+  key: string;
+  reason: string;
+  description?: string;
+  required?: boolean;
+};
 
-function collectConcerns(stack: Stack, workDir: string): Concern[] {
+function collectConcerns(stack: Stack): Concern[] {
   const out: Concern[] = [];
 
   for (const [svcName, svc] of Object.entries(stack.services)) {
+    const meta = svc.env_meta ?? {};
     for (const [k, vRaw] of Object.entries(svc.env ?? {})) {
       const v = String(vRaw);
+      const m = meta[k] ?? {};
 
-      if (v === '') {
-        out.push({ service: svcName, key: k, reason: 'vacío' });
-        continue;
+      let reason: string | null = null;
+      if (v === '') reason = 'vacío';
+      else if (PLACEHOLDER_PATTERNS.some((re) => re.test(v))) {
+        reason = `placeholder "${truncate(v, 30)}"`;
       }
 
-      if (PLACEHOLDER_PATTERNS.some((re) => re.test(v))) {
-        out.push({ service: svcName, key: k, reason: `placeholder: "${truncate(v, 30)}"` });
-        continue;
+      if (reason !== null) {
+        const concern: Concern = { service: svcName, key: k, reason };
+        if (m.description) concern.description = m.description;
+        if (m.required) concern.required = m.required;
+        out.push(concern);
       }
-
-      // ${file:...} ya fue expandido en el parse — si llegamos acá y no
-      // existe, el parse hubiera tirado error. No re-chequear acá.
     }
   }
 

package/src/parser.ts

@@ -49,7 +49,11 @@ export function loadStack(stackPath?: string): LoadedStack {
   // Expandir ${file:path} antes de validar — paths se resuelven relativo al workDir.
   const expanded = expandFileRefs(doc, workDir);
 
-  const result = stackSchema.safeParse(expanded);
+  // Normalizar el formato mixed de env (string | {value, description, required})
+  // a dos campos planos: env (Record<string,string>) + env_meta (descripciones).
+  const normalized = normalizeEnvMetadata(expanded);
+
+  const result = stackSchema.safeParse(normalized);
   if (!result.success) {
     throw new Error(formatZodError(result.error, absPath));
   }
@@ -74,6 +78,46 @@ function computeWorkspaceRoot(workDir: string): string {
   return workDir;
 }
 
+// Recorre stack.services.*.env y si algún valor es un objeto con shape
+// { value, description?, required? }, splittea: env[k] = String(value),
+// env_meta[k] = { description?, required? }. Los valores que ya son string,
+// number o boolean pasan tal cual.
+function normalizeEnvMetadata(doc: unknown): unknown {
+  if (!isPlainObject(doc)) return doc;
+  const services = isPlainObject(doc.services) ? doc.services : undefined;
+  if (!services) return doc;
+
+  const newServices: Record<string, unknown> = {};
+  for (const [svcName, svc] of Object.entries(services)) {
+    if (!isPlainObject(svc) || !isPlainObject(svc.env)) {
+      newServices[svcName] = svc;
+      continue;
+    }
+    const env: Record<string, unknown> = {};
+    const env_meta: Record<string, { description?: string; required?: boolean }> = {};
+    for (const [k, v] of Object.entries(svc.env)) {
+      if (isPlainObject(v) && ('value' in v || 'description' in v || 'required' in v)) {
+        env[k] = v.value ?? '';
+        const meta: { description?: string; required?: boolean } = {};
+        if (typeof v.description === 'string') meta.description = v.description;
+        if (typeof v.required === 'boolean') meta.required = v.required;
+        if (Object.keys(meta).length > 0) env_meta[k] = meta;
+      } else {
+        env[k] = v;
+      }
+    }
+    const newSvc: Record<string, unknown> = { ...svc, env };
+    if (Object.keys(env_meta).length > 0) newSvc.env_meta = env_meta;
+    newServices[svcName] = newSvc;
+  }
+
+  return { ...doc, services: newServices };
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
 function formatZodError(err: z.ZodError, source: string): string {
   const lines = err.issues.map((issue) => {
     const path = issue.path.length > 0 ? issue.path.join('.') : '(root)';

package/src/schema.ts

@@ -8,6 +8,15 @@ const serviceNameSchema = z
 const envValueSchema = z.union([z.string(), z.number(), z.boolean()]).transform(String);
 const envMapSchema = z.record(z.string(), envValueSchema);
 
+// Metadata opcional por env var: description + required.
+// El parser pre-normaliza el formato mixed (string vs {value,description,required})
+// dejando `env` como Record<string,string> y `env_meta` como esta estructura.
+const envMetaEntrySchema = z.object({
+  description: z.string().optional(),
+  required: z.boolean().optional(),
+});
+const envMetaMapSchema = z.record(z.string(), envMetaEntrySchema);
+
 const routeSchema = z.object({
   path: z.string().min(1),
   service: serviceNameSchema,
@@ -44,6 +53,7 @@ const serviceSchema = z
     port: z.number().int().positive().optional(),
     debug_port: z.number().int().positive().optional(),
     env: envMapSchema.optional(),
+    env_meta: envMetaMapSchema.optional(),
     needs: z.array(serviceNameSchema).optional(),
     expose_host: z.number().int().positive().optional(),
     volumes: z.array(z.string()).optional(),