@getmonoceros/workbench 1.2.0 → 1.3.0

package/README.md

@@ -17,16 +17,18 @@ das vorab und geben plattform-spezifische Anleitung aus.
 ## Installation
 
 ```sh
-npm install -g @getmonoceros/workbench
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/getmonoceros/workbench/main/install.sh | sh
 ```
 
-Oder über das Install-Skript:
-
-```sh
-curl -fsSL https://raw.githubusercontent.com/getmonoceros/workbench/main/install.sh | sh
+```powershell
+# Windows (PowerShell)
+iwr -useb https://raw.githubusercontent.com/getmonoceros/workbench/main/install.ps1 | iex
 ```
 
-Windows: das passende `install.ps1` über PowerShell.
+Das Skript prüft Docker + Node, installiert das Paket global via
+`npm install -g`, und richtet die Shell-Completion für deine Shell
+ein.
 
 ## Erste Schritte
 

package/dist/bin.js

@@ -203,25 +203,25 @@ function detectHelpRequest(argv, main2) {
   const separatorIdx = argv.indexOf("--");
   if (helpIdx === -1) return null;
   if (separatorIdx !== -1 && separatorIdx < helpIdx) return null;
-  const path14 = [];
+  const path13 = [];
   const tokens = argv.slice(
     0,
     separatorIdx === -1 ? argv.length : separatorIdx
   );
   let cursor = main2;
   const mainName = (main2.meta ?? {}).name ?? "monoceros";
-  path14.push(mainName);
+  path13.push(mainName);
   for (const tok of tokens) {
     if (tok.startsWith("-")) continue;
     const subs = cursor.subCommands ?? {};
     if (tok in subs) {
       cursor = subs[tok];
-      path14.push(tok);
+      path13.push(tok);
       continue;
     }
     break;
   }
-  return { path: path14, cmd: cursor };
+  return { path: path13, cmd: cursor };
 }
 async function maybeRenderHelp(argv, main2) {
   const hit = detectHelpRequest(argv, main2);
@@ -451,6 +451,9 @@ function workbenchCheckoutRoot() {
 function componentsDir(root = workbenchRoot()) {
   return path.join(root, "templates", "components");
 }
+function bundledFeaturesDir(root = workbenchRoot()) {
+  return path.join(root, "features");
+}
 function containerConfigsDir(home = monocerosHome()) {
   return path.join(home, "container-configs");
 }
@@ -466,6 +469,16 @@ function containerDir(name, home = monocerosHome()) {
 function monocerosConfigPath(home = monocerosHome()) {
   return path.join(home, "monoceros-config.yml");
 }
+function prettyPath(p) {
+  const home = os.homedir();
+  if (!home) return p;
+  if (p === home) return "~";
+  const prefix = home.endsWith(path.sep) ? home : home + path.sep;
+  if (p.startsWith(prefix)) {
+    return "~" + path.sep + p.slice(prefix.length);
+  }
+  return p;
+}
 
 // src/create/catalog.ts
 var DEFAULT_BASE_IMAGE = "ghcr.io/getmonoceros/monoceros-runtime:1";
@@ -2312,7 +2325,7 @@ async function runApply(opts) {
     });
   }
   logger.success(
-    `Materialized config '${opts.name}' into ${targetDir}. Starting container\u2026`
+    `Materialized config '${opts.name}' into ${prettyPath(targetDir)}. Starting container\u2026`
   );
   const exitCode = await runContainerCycle(targetDir, {
     hasCompose: needsCompose(createOpts),
@@ -2363,7 +2376,7 @@ function warnOnDeprecatedFeatureRefs(containerFeatures, globalConfig, logger) {
 }
 
 // src/version.ts
-var CLI_VERSION = "1.2.0";
+var CLI_VERSION = "1.3.0";
 
 // src/commands/_dispatch.ts
 import { consola as consola11 } from "consola";
@@ -2615,7 +2628,6 @@ import { consola as consola13 } from "consola";
 
 // src/init/index.ts
 import { existsSync as existsSync7, promises as fs10 } from "fs";
-import path10 from "path";
 import { consola as consola12 } from "consola";
 
 // src/init/components.ts
@@ -2814,11 +2826,10 @@ function generateComposedYml(name, components, lookupManifest) {
   if (merged.features.length > 0) {
     lines.push("features:");
     for (const f of merged.features) {
-      const hints = lookupManifest(f.ref)?.optionHints ?? [];
       renderFeatureBlock(
         lines,
         f,
-        hints,
+        lookupManifest(f.ref),
         /* commented */
         false
       );
@@ -2903,11 +2914,10 @@ function generateDocumentedYml(name, catalog, lookupManifest) {
       for (const f of c.file.contributes.features ?? []) {
         if (renderedRefs.has(f.ref)) continue;
         renderedRefs.add(f.ref);
-        const hints = lookupManifest(f.ref)?.optionHints ?? [];
         renderFeatureBlock(
           lines,
           f,
-          hints,
+          lookupManifest(f.ref),
           /* commented */
           true
         );
@@ -2918,11 +2928,10 @@ function generateDocumentedYml(name, catalog, lookupManifest) {
       for (const f of c.file.contributes.features ?? []) {
         if (renderedRefs.has(f.ref)) continue;
         renderedRefs.add(f.ref);
-        const hints = lookupManifest(f.ref)?.optionHints ?? [];
         renderFeatureBlock(
           lines,
           f,
-          hints,
+          lookupManifest(f.ref),
           /* commented */
           true
         );
@@ -2932,8 +2941,21 @@ function generateDocumentedYml(name, catalog, lookupManifest) {
   }
   return ensureTrailingNewline(lines.join("\n"));
 }
-function renderFeatureBlock(out, feature, optionHints, commented) {
+var COMMENT_WIDTH = 72;
+function renderFeatureBlock(out, feature, summary, commented) {
   const c = commented ? "#   " : "  ";
+  const optionHints = summary?.optionHints ?? [];
+  const optionDescriptions = summary?.optionDescriptions ?? {};
+  const usageNotes = summary?.usageNotes ?? [];
+  for (let i = 0; i < usageNotes.length; i++) {
+    if (i > 0) out.push(`${c}#`);
+    for (const line of wrapToComment(
+      usageNotes[i],
+      COMMENT_WIDTH - c.length
+    )) {
+      out.push(`${c}# ${line}`);
+    }
+  }
   out.push(`${c}- ref: ${feature.ref}`);
   const options = feature.options ?? {};
   const activeOptions = Object.entries(options);
@@ -2948,7 +2970,7 @@ function renderFeatureBlock(out, feature, optionHints, commented) {
         `${c}    # Optional \u2014 override monoceros-config.yml defaults.features:`
       );
       for (const hint of remainingHints) {
-        out.push(`${c}    # ${hint}:`);
+        emitHint(out, hint, optionDescriptions[hint], `${c}    `);
       }
     }
   } else if (remainingHints.length > 0) {
@@ -2957,10 +2979,42 @@ function renderFeatureBlock(out, feature, optionHints, commented) {
     );
     out.push(`${c}  # options:`);
     for (const hint of remainingHints) {
-      out.push(`${c}  #   ${hint}:`);
+      emitHint(out, hint, optionDescriptions[hint], `${c}  #   `);
     }
   }
 }
+function emitHint(out, hint, description, linePrefix) {
+  if (description) {
+    for (const line of wrapToComment(
+      description,
+      COMMENT_WIDTH - linePrefix.length
+    )) {
+      out.push(`${linePrefix}# ${line}`);
+    }
+  }
+  out.push(`${linePrefix}${hint}:`);
+}
+function wrapToComment(text, width) {
+  const words = text.split(/\s+/).filter((w) => w.length > 0);
+  if (words.length === 0) return [""];
+  const usable = Math.max(width, 20);
+  const lines = [];
+  let current = "";
+  for (const w of words) {
+    if (current.length === 0) {
+      current = w;
+      continue;
+    }
+    if (current.length + 1 + w.length <= usable) {
+      current += " " + w;
+    } else {
+      lines.push(current);
+      current = w;
+    }
+  }
+  if (current.length > 0) lines.push(current);
+  return lines;
+}
 function renderScalarValue(value) {
   if (typeof value === "string") {
     return /^[A-Za-z_][A-Za-z0-9._-]*$/.test(value) ? value : JSON.stringify(value);
@@ -2988,28 +3042,50 @@ function ensureTrailingNewline(s) {
 // src/init/manifest.ts
 import { existsSync as existsSync6, readFileSync as readFileSync3 } from "fs";
 import path9 from "path";
-function loadFeatureManifestSummary(ref, checkoutRoot = workbenchCheckoutRoot()) {
-  if (!checkoutRoot) return void 0;
-  const match = matchMonocerosFeature(ref);
-  if (!match) return void 0;
-  const name = match.name;
-  const manifestPath = path9.join(
-    checkoutRoot,
-    "images",
-    "features",
+function resolveManifestPath(name, checkoutRoot) {
+  if (checkoutRoot) {
+    const checkoutPath = path9.join(
+      checkoutRoot,
+      "images",
+      "features",
+      name,
+      "devcontainer-feature.json"
+    );
+    if (existsSync6(checkoutPath)) return checkoutPath;
+  }
+  const bundlePath = path9.join(
+    bundledFeaturesDir(),
     name,
     "devcontainer-feature.json"
   );
-  if (!existsSync6(manifestPath)) return void 0;
+  if (existsSync6(bundlePath)) return bundlePath;
+  return null;
+}
+function loadFeatureManifestSummary(ref, checkoutRoot = workbenchCheckoutRoot()) {
+  const match = matchMonocerosFeature(ref);
+  if (!match) return void 0;
+  const manifestPath = resolveManifestPath(match.name, checkoutRoot);
+  if (!manifestPath) return void 0;
   try {
     const text = readFileSync3(manifestPath, "utf8");
     const parsed = JSON.parse(text);
-    const raw = parsed["x-monoceros"]?.optionHints;
-    if (!Array.isArray(raw)) return { optionHints: [] };
-    const hints = raw.filter(
+    const rawHints = parsed["x-monoceros"]?.optionHints;
+    const optionHints = Array.isArray(rawHints) ? rawHints.filter(
       (x) => typeof x === "string" && x.length > 0
-    );
-    return { optionHints: hints };
+    ) : [];
+    const rawNotes = parsed["x-monoceros"]?.usageNotes;
+    const usageNotes = Array.isArray(rawNotes) ? rawNotes.filter(
+      (x) => typeof x === "string" && x.length > 0
+    ) : [];
+    const optionDescriptions = {};
+    if (parsed.options) {
+      for (const [key, opt] of Object.entries(parsed.options)) {
+        if (opt && typeof opt === "object" && typeof opt.description === "string" && opt.description.length > 0) {
+          optionDescriptions[key] = opt.description;
+        }
+      }
+    }
+    return { optionHints, optionDescriptions, usageNotes };
   } catch {
     return void 0;
   }
@@ -3053,14 +3129,14 @@ async function runInit(opts) {
   await fs10.mkdir(containerConfigsDir(home), { recursive: true });
   await fs10.writeFile(dest, text, "utf8");
   const documented = requested.length === 0;
-  const rel = path10.relative(home, dest) || dest;
+  const displayPath = prettyPath(dest);
   if (documented) {
     logger.success(
-      `Wrote documented default to ${rel}. Un-comment what you need, then \`monoceros apply ${opts.name}\`.`
+      `Wrote documented default to ${displayPath}. Un-comment what you need, then \`monoceros apply ${opts.name}\`.`
     );
   } else {
     logger.success(
-      `Composed ${requested.length} component(s) into ${rel}: ${requested.join(", ")}`
+      `Composed ${requested.length} component(s) into ${displayPath}: ${requested.join(", ")}`
     );
     logger.info(
       `Edit the file if you need to tweak, then \`monoceros apply ${opts.name}\`.`
@@ -3297,7 +3373,7 @@ import { createInterface } from "readline/promises";
 
 // src/remove/index.ts
 import { existsSync as existsSync8, promises as fs11 } from "fs";
-import path11 from "path";
+import path10 from "path";
 import { consola as consola17 } from "consola";
 async function runRemove(opts) {
   const home = opts.monocerosHome ?? monocerosHome();
@@ -3340,19 +3416,17 @@ async function runRemove(opts) {
   let backupPath = null;
   if (!opts.noBackup && (hasYml || hasContainer)) {
     const ts = (opts.now ?? /* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-    backupPath = path11.join(home, "container-backups", `${opts.name}-${ts}`);
+    backupPath = path10.join(home, "container-backups", `${opts.name}-${ts}`);
     await fs11.mkdir(backupPath, { recursive: true });
     if (hasYml) {
-      await fs11.copyFile(ymlPath, path11.join(backupPath, `${opts.name}.yml`));
+      await fs11.copyFile(ymlPath, path10.join(backupPath, `${opts.name}.yml`));
     }
     if (hasContainer) {
-      await fs11.cp(containerPath, path11.join(backupPath, "container"), {
+      await fs11.cp(containerPath, path10.join(backupPath, "container"), {
         recursive: true
       });
     }
-    logger.info(
-      `Backup written to ${path11.relative(home, backupPath) || backupPath}.`
-    );
+    logger.info(`Backup written to ${prettyPath(backupPath)}.`);
   }
   if (hasYml) {
     await fs11.rm(ymlPath, { force: true });
@@ -3443,7 +3517,7 @@ import { consola as consola20 } from "consola";
 
 // src/restore/index.ts
 import { existsSync as existsSync9, promises as fs12 } from "fs";
-import path12 from "path";
+import path11 from "path";
 import { consola as consola19 } from "consola";
 async function runRestore(opts) {
   const home = opts.monocerosHome ?? monocerosHome();
@@ -3451,7 +3525,7 @@ async function runRestore(opts) {
     info: (msg) => consola19.info(msg),
     success: (msg) => consola19.success(msg)
   };
-  const backup = path12.resolve(opts.backupPath);
+  const backup = path11.resolve(opts.backupPath);
   if (!existsSync9(backup)) {
     throw new Error(`Backup not found: ${backup}.`);
   }
@@ -3473,7 +3547,7 @@ async function runRestore(opts) {
   }
   const ymlFile = ymlFiles[0];
   const name = ymlFile.replace(/\.yml$/, "");
-  const containerInBackup = path12.join(backup, "container");
+  const containerInBackup = path11.join(backup, "container");
   const hasContainer = existsSync9(containerInBackup);
   const destYml = containerConfigPath(name, home);
   const destContainer = containerDir(name, home);
@@ -3488,13 +3562,11 @@ async function runRestore(opts) {
     );
   }
   await fs12.mkdir(containerConfigsDir(home), { recursive: true });
-  await fs12.copyFile(path12.join(backup, ymlFile), destYml);
+  await fs12.copyFile(path11.join(backup, ymlFile), destYml);
   if (hasContainer) {
     await fs12.cp(containerInBackup, destContainer, { recursive: true });
   }
-  logger.success(
-    `Restored '${name}' from ${path12.relative(home, backup) || backup}.`
-  );
+  logger.success(`Restored '${name}' from ${prettyPath(backup)}.`);
   logger.info(
     `Run \`monoceros apply ${name}\` to bring the container back up.`
   );
@@ -3703,7 +3775,7 @@ import { consola as consola25 } from "consola";
 
 // src/devcontainer/shell.ts
 import { existsSync as existsSync10 } from "fs";
-import path13 from "path";
+import path12 from "path";
 async function runShell(opts) {
   assertContainerExists(opts.root);
   const spawnFn = opts.spawn ?? spawnDevcontainer;
@@ -3718,7 +3790,7 @@ async function runShell(opts) {
   });
 }
 function assertContainerExists(root) {
-  if (!existsSync10(path13.join(root, ".devcontainer"))) {
+  if (!existsSync10(path12.join(root, ".devcontainer"))) {
     throw new Error(
       `No .devcontainer/ at ${root}. Run \`monoceros apply <name>\` first.`
     );