@jpillora/take 0.11.0 → 0.12.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jpillora/take",
-  "version": "0.11.0",
+  "version": "0.12.2",
   "description": "A minimal CLI library for building TypeScript-based command-line tools",
   "type": "module",
   "main": "./take.mjs",

package/take.d.mts

@@ -1,4 +1,5 @@
 import { type SpawnOptions as nodeSpawnOptions } from "node:child_process";
+export declare function insertHelp(path: string): void;
 export type Flag = {
     initial: number | string | boolean | Date;
     description: string;

package/take.mjs

@@ -3,10 +3,20 @@
 // IMPORTANT: All code must stay in 1 file.
 // deno-lint-ignore-file no-explicit-any
 import { Buffer } from "node:buffer";
-import { readFile } from "node:fs/promises";
-import { basename } from "node:path";
+import { readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join } from "node:path";
 import { spawn as nodeSpawn, } from "node:child_process";
 import process from "node:process";
+let _insertHelpPath = null;
+export function insertHelp(path) {
+    if (isAbsolute(path)) {
+        _insertHelpPath = path;
+    }
+    else {
+        const scriptDir = dirname(process.argv[1] || ".");
+        _insertHelpPath = join(scriptDir, path);
+    }
+}
 export function newFlags(flags) {
     return flags;
 }
@@ -193,6 +203,64 @@ async function loadEnvFile(path) {
         return false;
     }
 }
+const MARKER_START = "<!-- take:start -->";
+const MARKER_END = "<!-- take:end -->";
+async function _writeInsertHelp(commands) {
+    if (!_insertHelpPath)
+        return;
+    const path = _insertHelpPath;
+    // Build markdown list with flags as sub-bullets
+    const lines = [];
+    for (const cmd of commands) {
+        if (cmd.name === "debug")
+            continue;
+        const desc = cmd.description ? ` - ${cmd.description}` : "";
+        lines.push(`- \`${cmd.name}\`${desc}`);
+        // Add flags as sub-bullets (sorted, matching the CLI --help output, so the
+        // generated markdown is deterministic regardless of flag insertion order)
+        const shorts = new Set();
+        for (const flag of namedFlags(cmd.flags)) {
+            const { name } = flag;
+            const letter = name[0];
+            const shortStr = shorts.has(letter) ? "" : ` \`-${letter}\``;
+            shorts.add(letter);
+            const typeStr = typeof flag.initial === "boolean"
+                ? ""
+                : ` <${typeof flag.initial}>`;
+            const parts = [];
+            if (flag.env)
+                parts.push(`env=${flag.env}`);
+            if (flag.initial)
+                parts.push(`default=${flag.initial}`);
+            const extras = parts.length ? ` (${parts.join(" ")})` : "";
+            lines.push(`  - \`--${name}\`${shortStr}${typeStr} - ${flag.description}${extras}`);
+        }
+    }
+    const content = MARKER_START + "\n" + lines.join("\n") + "\n" + MARKER_END;
+    // Read existing file
+    let fileContent;
+    try {
+        fileContent = await readFile(path, "utf-8");
+    }
+    catch {
+        return; // file doesn't exist, nothing to insert into
+    }
+    // Find markers and replace or append
+    const startIdx = fileContent.indexOf(MARKER_START);
+    const endIdx = fileContent.indexOf(MARKER_END);
+    let newContent;
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        newContent = fileContent.substring(0, startIdx) + content +
+            fileContent.substring(endIdx + MARKER_END.length);
+    }
+    else {
+        const sep = fileContent.endsWith("\n") ? "\n" : "\n\n";
+        newContent = fileContent + sep + content + "\n";
+    }
+    if (newContent !== fileContent) {
+        await writeFile(path, newContent, "utf-8");
+    }
+}
 export async function Register(...commands) {
     // Load .env by default
     await loadEnvFile(".env");
@@ -238,6 +306,7 @@ export async function Register(...commands) {
         }
     }
     commands.sort((a, b) => (a.name < b.name ? -1 : 1));
+    await _writeInsertHelp(commands);
     const joinColumns = (table) => {
         const max = table.reduce((m, { left }) => Math.max(m, left.length), 0);
         return table