orch-mini 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orch-mini",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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

@@ -99,7 +99,12 @@ export function renderInfo(loaded: LoadedStack): string {
     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 tag = c.required ? `${C.red}[required]${C.reset} ` : '';
+      out.push(`  ${tag}${k}${C.dim}${c.reason}${C.reset}`);
+      if (c.description) {
+        // Indenta la descripción debajo, alineada con el nombre del key.
+        out.push(`  ${' '.repeat(maxKey + 2 + (c.required ? 11 : 0))}${C.dim}↳ ${c.description}${C.reset}`);
+      }
     }
   } else {
     out.push('');
@@ -170,31 +175,47 @@ 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, _workDir: string): 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);
-
-      if (v === '') {
-        out.push({ service: svcName, key: k, reason: 'vacío' });
-        continue;
+      const m = meta[k] ?? {};
+
+      let reason: string | null = null;
+      if (v === '') reason = 'vacío';
+      else if (PLACEHOLDER_PATTERNS.some((re) => re.test(v))) {
+        reason = `placeholder: "${truncate(v, 30)}"`;
+      } else if (m.required === true) {
+        // Marcado como required en la metadata, pero ya tiene valor — no es concern.
       }
 
-      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á.
     }
   }
 
-  return out;
+  // Required arriba (los más urgentes), después el resto.
+  return out.sort((a, b) => {
+    if ((b.required ? 1 : 0) - (a.required ? 1 : 0) !== 0) {
+      return (b.required ? 1 : 0) - (a.required ? 1 : 0);
+    }
+    return 0;
+  });
 }
 
 function truncate(s: string, max: number): string {

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(),