@jpillora/take 0.10.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jpillora/take",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "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 { SpawnOptions as nodeSpawnOptions } from "node:child_process";
+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;
@@ -35,6 +36,22 @@ export type SpawnOptions = {
     args?: string[];
 } & nodeSpawnOptions;
 export declare function spawn(options: SpawnOptions): Promise<number>;
+export type RunResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+    combined: string;
+    error?: string;
+    success: boolean;
+};
+export type ExecResult = {
+    pid: number;
+    error?: string;
+    wait: () => Promise<RunResult>;
+    kill: (signal: number) => void;
+};
+export declare function exec(options: SpawnOptions): ExecResult;
+export declare function run(options: SpawnOptions): Promise<RunResult>;
 export declare const $: (script: string) => Promise<void>;
 export declare const timer: () => () => string;
 export declare function Register(...commands: NewCommand<any>[]): Promise<void>;

package/take.mjs

@@ -1,10 +1,22 @@
-// Take is a mini-CLI library for building typescript-based command-line tools
-// Works with Deno, Node.js (with type stripping), and Bun
+// Take is a mini-CLI library for building typescript-based command-line tools.
+// Works with Deno, Node.js (with type stripping), and Bun.
+// IMPORTANT: All code must stay in 1 file.
 // deno-lint-ignore-file no-explicit-any
-import { readFile } from "node:fs/promises";
-import { basename } from "node:path";
+import { Buffer } from "node:buffer";
+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;
 }
@@ -51,6 +63,84 @@ export async function spawn(options) {
         });
     });
 }
+export function exec(options) {
+    let code = -1;
+    let error = "";
+    const datas = {
+        out: [],
+        err: [],
+        combined: [],
+    };
+    const result = {
+        get code() {
+            return code;
+        },
+        get stdout() {
+            return Buffer.concat(datas.out).toString();
+        },
+        get stderr() {
+            return Buffer.concat(datas.err).toString();
+        },
+        get combined() {
+            return Buffer.concat(datas.combined).toString();
+        },
+        get error() {
+            return error || undefined;
+        },
+        get success() {
+            return code === 0;
+        },
+    };
+    try {
+        const child = nodeSpawn(options.program, options.args ?? [], options);
+        child.stdout?.on("data", (data) => {
+            const buf = Buffer.from(data);
+            datas.out.push(buf);
+            datas.combined.push(buf);
+        });
+        child.stderr?.on("data", (data) => {
+            const buf = Buffer.from(data);
+            datas.err.push(buf);
+            datas.combined.push(buf);
+        });
+        let resolved = false;
+        const resultPromise = new Promise((resolve) => {
+            const done = (finalCode) => {
+                if (resolved) {
+                    return;
+                }
+                code = finalCode;
+                resolved = true;
+                resolve(result);
+            };
+            child.on("error", (err) => {
+                error = err.message;
+                done(1);
+            });
+            child.on("close", (c) => {
+                done(c ?? 1);
+            });
+        });
+        return {
+            pid: child.pid ?? 0,
+            wait: () => resultPromise,
+            kill: (signal) => child.kill(signal),
+        };
+    }
+    catch (err) {
+        code = 1;
+        error = err instanceof Error ? err.message : String(err);
+        return {
+            pid: 0,
+            error,
+            wait: () => Promise.resolve(result),
+            kill: () => { },
+        };
+    }
+}
+export function run(options) {
+    return exec(options).wait();
+}
 // helper for running bash scripts
 export const $ = async (script) => {
     await spawn({
@@ -113,6 +203,62 @@ 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
+        const shorts = new Set();
+        for (const [name, flag] of Object.entries(cmd.flags)) {
+            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");
@@ -158,6 +304,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
@@ -373,7 +520,12 @@ export async function Register(...commands) {
 }
 export function Command(command) {
     const flagsInitial = Object.fromEntries(Object.entries(command.flags).map(([k, v]) => [k, v.initial]));
-    return { ...command, flagValues: null, input: null, flagsInitial };
+    return {
+        ...command,
+        flagValues: null,
+        input: null,
+        flagsInitial,
+    };
 }
 // deno-lint-ignore no-constant-condition
 if (42 < 7) {