gui4cli 0.0.0 → 0.0.1

package/README.md

@@ -1,5 +1,77 @@
-# ArgUI
+# GUI4CLI
 
 Turn a Node.js CLI script into a simple desktop form — inputs, a Run button, and live output — without rewriting the script.
 
-**This `0.0.0` package reserves the npm name `gui4cli`.** The CLI is not implemented yet. `npx gui4cli` will only print this notice.
+## Setup
+
+### Prerequisites
+
+- Node.js 20+
+- pnpm 9+
+
+### Installation (this repo)
+
+```bash
+pnpm install
+pnpm test
+pnpm exec tsx src/cli.ts fixtures/resize.js --json
+pnpm dev
+```
+
+`pnpm dev` opens the Commander fixture in a desktop window. The first windowd launch may download the NW.js runtime (~200 MB).
+
+If the window flashes and closes, run `pnpm dev` from a normal terminal (not Cursor's JavaScript Debug Terminal). Inspector flags inherited by NW.js will shut the window down.
+
+`--json` prints the detected form and exits (no window). Use that in CI or when you cannot open a GUI.
+
+`--build` writes a reusable project folder (GUI shell + `package.json`). It does not create an `.exe`, and it does not rewrite the original script.
+
+```bash
+pnpm exec tsx src/cli.ts fixtures/resize.js --build
+pnpm exec tsx src/cli.ts fixtures/resize.js --build --out ./my-resize-gui
+```
+
+Then `npx --yes windowd` inside that folder.
+
+### Try a script
+
+```bash
+pnpm exec tsx src/cli.ts path/to/your-script.js
+pnpm exec tsx src/cli.ts . --entry bin/cli.js
+```
+
+Optional overrides: `gui4cli.config.js` or `gui4cli.json` next to the script.
+
+## Project Structure
+
+```
+src/           TypeScript CLI (detect, schema, window, run)
+fixtures/      Commander + yargs sample scripts
+docs/          GENESIS + Phase 1 brief
+CONTEXT_PROMPT.md
+TODO.md
+```
+
+## Features
+
+| Feature | Description |
+| ------- | ----------- |
+| Detect | Static Commander / yargs, then JSDoc, config, `--help` |
+| Instant GUI | One windowd window, no generated repo required |
+| `--build` | Reusable project folder; run later with `npx windowd` |
+| Run | Spawn the original script; stream stdout/stderr; cancel |
+| Last run | Values stored under `~/.gui4cli/lastrun/` |
+
+## Tech Stack
+
+- TypeScript, ESM, pnpm
+- Zod
+- windowd (Node + webview)
+- No database, auth, or LLM
+
+## Documentation
+
+- [docs/PHASE_1_BRIEF.md](docs/PHASE_1_BRIEF.md) — locked architecture
+- [docs/GENESIS.md](docs/GENESIS.md) — product spec
+- [CONTEXT_PROMPT.md](CONTEXT_PROMPT.md) — session handoff
+- [TODO.md](TODO.md) — backlog

package/bin/gui4cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const dist = resolve(root, "dist/cli.js");
+
+if (existsSync(dist)) {
+  await import(pathToFileURL(dist).href);
+} else {
+  const { register } = await import("tsx/esm/api");
+  register();
+  await import(pathToFileURL(resolve(root, "src/cli.ts")).href);
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,86 @@
+import { parseArgs } from "node:util";
+import { detectForm } from "./detect/index.js";
+import { formatUserError, Gui4CliError } from "./errors.js";
+import { defaultBuildDir, writeBuildProject } from "./generate/project.js";
+import { writeWindowApp } from "./generate/window.js";
+import { lastRunPath, loadLastRun } from "./last-run/store.js";
+import { resolveTarget } from "./resolve/target.js";
+import { valuesFromDefaults } from "./run/argv.js";
+import { openWindow } from "./window/open.js";
+const HELP = `GUI4CLI — turn a Node CLI script into a desktop form.
+
+Usage:
+  gui4cli <script-or-folder> [--entry <path>] [--json]
+  gui4cli <script-or-folder> --build [--out <dir>] [--force]
+
+Options:
+  --entry <path>   Use this file as the script (overrides folder bin/main)
+  --json           Print the detected form and exit (no window)
+  --build          Write a reusable project folder and exit (no .exe)
+  --out <dir>      Folder for --build (default: <title>-gui in the current directory)
+  --force          Replace an existing --out folder
+  --help           Show this help
+
+Examples:
+  gui4cli fixtures/resize.js
+  gui4cli fixtures/resize.js --build
+  gui4cli . --entry bin/cli.js
+`;
+export async function main(argv = process.argv.slice(2)) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            entry: { type: "string" },
+            json: { type: "boolean", default: false },
+            build: { type: "boolean", default: false },
+            out: { type: "string" },
+            force: { type: "boolean", default: false },
+            help: { type: "boolean", default: false },
+        },
+    });
+    if (values.help || argv.includes("-h")) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (values.json && values.build) {
+        throw new Gui4CliError("Use either --json or --build, not both.");
+    }
+    const { target, cwd } = await resolveTarget(positionals[0], values.entry, process.cwd());
+    const spec = await detectForm(target, cwd);
+    const last = await loadLastRun(target);
+    const formValues = { ...valuesFromDefaults(spec.fields), ...last };
+    if (values.json) {
+        process.stdout.write(`${JSON.stringify({ spec, values: formValues }, null, 2)}\n`);
+        return 0;
+    }
+    if (values.build) {
+        const outDir = values.out ?? defaultBuildDir(spec.title, process.cwd());
+        const dir = await writeBuildProject({
+            spec,
+            values: formValues,
+            outDir,
+            lastRunPath: lastRunPath(target),
+            force: values.force,
+        });
+        process.stdout.write(`Wrote ${dir}\nRun it with: npx --yes windowd\n`);
+        process.stdout.write(`The original script was not changed: ${spec.target}\n`);
+        return 0;
+    }
+    const dir = await writeWindowApp({
+        spec,
+        values: formValues,
+        nodePath: process.execPath,
+        lastRunPath: lastRunPath(target),
+        platform: process.platform,
+    });
+    process.stderr.write(`Opening ${spec.title} (${spec.fields.length} fields, detected via ${spec.source})…\n`);
+    return openWindow(dir, spec);
+}
+const entry = process.argv[1] ?? "";
+if (entry.endsWith("cli.ts") || entry.endsWith("cli.js") || entry.endsWith("gui4cli.js")) {
+    main().then((code) => process.exit(code), (error) => {
+        process.stderr.write(`${formatUserError(error)}\n`);
+        process.exit(error instanceof Gui4CliError ? 2 : 1);
+    });
+}

package/dist/config/load.d.ts

@@ -0,0 +1,13 @@
+import { type Field } from "../schema/form.js";
+export type Gui4CliConfig = {
+    title?: string;
+    description?: string;
+    entry?: string;
+    cwd?: string;
+    window?: {
+        width?: number;
+        height?: number;
+    };
+    fields?: Field[];
+};
+export declare function loadConfig(target: string, cwd: string): Promise<Gui4CliConfig | null>;

package/dist/config/load.js

@@ -0,0 +1,66 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { z } from "zod";
+import { Gui4CliError } from "../errors.js";
+import { fieldSchema } from "../schema/form.js";
+const configFieldSchema = fieldSchema.partial().extend({
+    name: z.string().min(1),
+    longFlag: z.string().min(1).optional(),
+    label: z.string().min(1).optional(),
+    type: fieldSchema.shape.type.optional(),
+    required: z.boolean().optional(),
+});
+const configSchema = z.object({
+    title: z.string().optional(),
+    description: z.string().optional(),
+    entry: z.string().optional(),
+    cwd: z.string().optional(),
+    window: z
+        .object({
+        width: z.number().int().positive().optional(),
+        height: z.number().int().positive().optional(),
+    })
+        .optional(),
+    fields: z.array(configFieldSchema).optional(),
+});
+export async function loadConfig(target, cwd) {
+    const searchDirs = [dirname(target), cwd];
+    for (const dir of searchDirs) {
+        for (const name of ["gui4cli.config.js", "gui4cli.config.mjs", "gui4cli.json"]) {
+            const path = join(dir, name);
+            if (!existsSync(path))
+                continue;
+            return readConfigFile(path);
+        }
+    }
+    return null;
+}
+async function readConfigFile(path) {
+    try {
+        const raw = path.endsWith(".json")
+            ? JSON.parse(await readFile(path, "utf8"))
+            : (await import(pathToFileURL(path).href)).default;
+        const parsed = configSchema.parse(raw);
+        return {
+            ...parsed,
+            fields: parsed.fields?.map((field) => fieldSchema.parse({
+                name: field.name,
+                longFlag: field.longFlag ?? `--${field.name}`,
+                shortFlag: field.shortFlag,
+                type: field.type ?? "string",
+                label: field.label ?? field.name,
+                help: field.help,
+                required: field.required ?? false,
+                default: field.default,
+                choices: field.choices,
+                positional: field.positional,
+            })),
+        };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Gui4CliError(`The config file at ${path} is not valid.`, detail);
+    }
+}

package/dist/detect/ast.d.ts

@@ -0,0 +1,6 @@
+import ts from "typescript";
+export declare function parseSource(fileName: string, source: string): ts.SourceFile;
+export declare function stringLiteral(node: ts.Expression | undefined): string | undefined;
+export declare function primitiveLiteral(node: ts.Expression | undefined): string | number | boolean | undefined;
+export declare function objectProps(node: ts.Expression | undefined): Map<string, ts.Expression>;
+export declare function walkCalls(sourceFile: ts.SourceFile, visit: (call: ts.CallExpression, method: string) => void): void;

package/dist/detect/ast.js

@@ -0,0 +1,62 @@
+import ts from "typescript";
+export function parseSource(fileName, source) {
+    return ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+}
+export function stringLiteral(node) {
+    if (!node)
+        return undefined;
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+        return node.text;
+    }
+    return undefined;
+}
+export function primitiveLiteral(node) {
+    if (!node)
+        return undefined;
+    const text = stringLiteral(node);
+    if (text !== undefined)
+        return text;
+    if (ts.isNumericLiteral(node))
+        return Number(node.text);
+    if (node.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (node.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    return undefined;
+}
+export function objectProps(node) {
+    const props = new Map();
+    if (!node || !ts.isObjectLiteralExpression(node))
+        return props;
+    for (const prop of node.properties) {
+        if (!ts.isPropertyAssignment(prop))
+            continue;
+        const name = ts.isIdentifier(prop.name)
+            ? prop.name.text
+            : ts.isStringLiteral(prop.name)
+                ? prop.name.text
+                : undefined;
+        if (name)
+            props.set(name, prop.initializer);
+    }
+    return props;
+}
+export function walkCalls(sourceFile, visit) {
+    const calls = [];
+    const walk = (node) => {
+        if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+            calls.push({ call: node, method: node.expression.name.text });
+        }
+        ts.forEachChild(node, walk);
+    };
+    walk(sourceFile);
+    calls.sort((a, b) => methodStart(a.call, sourceFile) - methodStart(b.call, sourceFile));
+    for (const item of calls)
+        visit(item.call, item.method);
+}
+function methodStart(call, sourceFile) {
+    if (ts.isPropertyAccessExpression(call.expression)) {
+        return call.expression.name.getStart(sourceFile);
+    }
+    return call.getStart(sourceFile);
+}

package/dist/detect/commander.d.ts

@@ -0,0 +1,2 @@
+import type { Field } from "../schema/form.js";
+export declare function detectCommander(fileName: string, source: string): Field[];

package/dist/detect/commander.js

@@ -0,0 +1,45 @@
+import { objectProps, parseSource, primitiveLiteral, stringLiteral, walkCalls } from "./ast.js";
+import { fieldFromFlag, parseFlagSpec } from "./flags.js";
+export function detectCommander(fileName, source) {
+    const sf = parseSource(fileName, source);
+    const fields = [];
+    walkCalls(sf, (call, method) => {
+        if (method !== "option" && method !== "requiredOption")
+            return;
+        const spec = stringLiteral(call.arguments[0]);
+        if (!spec)
+            return;
+        const parsed = parseFlagSpec(spec);
+        if (!parsed)
+            return;
+        const help = stringLiteral(call.arguments[1]);
+        let defaultValue = primitiveLiteral(call.arguments[2]);
+        let choices;
+        const obj = objectProps(call.arguments[1]);
+        if (obj.size > 0) {
+            const described = stringLiteral(obj.get("description") ?? obj.get("desc"));
+            defaultValue = primitiveLiteral(obj.get("default")) ?? defaultValue;
+        }
+        fields.push(fieldFromFlag({
+            name: parsed.name,
+            longFlag: parsed.longFlag,
+            shortFlag: parsed.shortFlag,
+            typeHint: parsed.typeHint,
+            help,
+            required: method === "requiredOption",
+            default: defaultValue,
+            choices,
+            boolean: parsed.boolean,
+        }));
+    });
+    return uniqueFields(fields);
+}
+function uniqueFields(fields) {
+    const seen = new Set();
+    return fields.filter((field) => {
+        if (seen.has(field.name))
+            return false;
+        seen.add(field.name);
+        return true;
+    });
+}

package/dist/detect/flags.d.ts

@@ -0,0 +1,25 @@
+import { type Field, type FieldType } from "../schema/form.js";
+export declare function shouldSkipFlag(name: string): boolean;
+export declare function nameFromLongFlag(longFlag: string): string;
+export declare function inferType(hint: string | undefined, help: string | undefined, name: string): FieldType;
+export declare function parseFlagSpec(spec: string): {
+    shortFlag?: string;
+    longFlag: string;
+    name: string;
+    boolean: boolean;
+    typeHint?: string;
+} | null;
+export declare function fieldFromFlag(input: {
+    name: string;
+    longFlag: string;
+    shortFlag?: string;
+    type?: FieldType;
+    typeHint?: string;
+    help?: string;
+    required?: boolean;
+    default?: string | number | boolean;
+    choices?: string[];
+    boolean?: boolean;
+    positional?: boolean;
+}): Field;
+export declare function mergeFields(base: Field[], overlay: Field[]): Field[];

package/dist/detect/flags.js

@@ -0,0 +1,77 @@
+import { labelFromName } from "../schema/form.js";
+const SKIP_FLAGS = new Set(["help", "version", "h", "V", "v"]);
+export function shouldSkipFlag(name) {
+    return SKIP_FLAGS.has(name.replace(/^--?/, ""));
+}
+export function nameFromLongFlag(longFlag) {
+    return longFlag.replace(/^--/, "");
+}
+export function inferType(hint, help, name) {
+    const blob = `${hint ?? ""} ${help ?? ""} ${name}`.toLowerCase();
+    if (/\b(dir|directory|folder)\b/.test(blob))
+        return "directory";
+    if (/\b(file|path|filename)\b/.test(blob))
+        return "file";
+    if (/\b(number|int|integer|float|count|width|height|quality|port)\b/.test(blob)) {
+        return "number";
+    }
+    return "string";
+}
+export function parseFlagSpec(spec) {
+    const parts = spec.split(",").map((part) => part.trim()).filter(Boolean);
+    let shortFlag;
+    let longFlag = "";
+    let typeHint;
+    let boolean = true;
+    for (const part of parts) {
+        const short = part.match(/^(-[A-Za-z0-9])$/);
+        if (short) {
+            shortFlag = short[1];
+            continue;
+        }
+        const long = part.match(/^--([A-Za-z0-9][A-Za-z0-9-]*)(?:\s*[<[]([^>\]]+)[>\]])?/);
+        if (long) {
+            longFlag = `--${long[1]}`;
+            if (long[2]) {
+                boolean = false;
+                typeHint = long[2];
+            }
+        }
+    }
+    if (!longFlag && shortFlag) {
+        longFlag = `--${shortFlag.slice(1)}`;
+    }
+    if (!longFlag)
+        return null;
+    const name = nameFromLongFlag(longFlag);
+    if (shouldSkipFlag(name))
+        return null;
+    return { shortFlag, longFlag, name, boolean, typeHint };
+}
+export function fieldFromFlag(input) {
+    const type = input.boolean
+        ? "boolean"
+        : input.choices && input.choices.length > 0
+            ? "choice"
+            : (input.type ?? inferType(input.typeHint, input.help, input.name));
+    return {
+        name: input.name,
+        longFlag: input.longFlag,
+        shortFlag: input.shortFlag,
+        type,
+        label: labelFromName(input.name),
+        help: input.help,
+        required: Boolean(input.required),
+        default: input.default,
+        choices: input.choices,
+        positional: input.positional,
+    };
+}
+export function mergeFields(base, overlay) {
+    const byName = new Map(base.map((field) => [field.name, field]));
+    for (const field of overlay) {
+        const existing = byName.get(field.name);
+        byName.set(field.name, existing ? { ...existing, ...field } : field);
+    }
+    return [...byName.values()];
+}

package/dist/detect/help.d.ts

@@ -0,0 +1,3 @@
+import type { Field } from "../schema/form.js";
+export declare function parseHelpText(text: string): Field[];
+export declare function collectHelpText(target: string, cwd: string, timeoutMs?: number): Promise<string>;

package/dist/detect/help.js

@@ -0,0 +1,53 @@
+import { spawn } from "node:child_process";
+import { fieldFromFlag, parseFlagSpec } from "./flags.js";
+const HELP_LINE = /^\s*(-\S.*?)\s{2,}(\S.*)?$/;
+export function parseHelpText(text) {
+    const fields = [];
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trimEnd();
+        const match = line.match(HELP_LINE);
+        if (!match)
+            continue;
+        const parsed = parseFlagSpec(match[1] ?? "");
+        if (!parsed)
+            continue;
+        const help = (match[2] ?? "").replace(/\(default:.*\)/i, "").trim() || undefined;
+        fields.push(fieldFromFlag({
+            name: parsed.name,
+            longFlag: parsed.longFlag,
+            shortFlag: parsed.shortFlag,
+            typeHint: parsed.typeHint,
+            help,
+            boolean: parsed.boolean,
+        }));
+    }
+    return fields;
+}
+export async function collectHelpText(target, cwd, timeoutMs = 4000) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [target, "--help"], {
+            cwd,
+            env: { ...process.env, GUI4CLI_DETECT: "1" },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let out = "";
+        const timer = setTimeout(() => {
+            child.kill();
+            reject(new Error("Timed out reading --help"));
+        }, timeoutMs);
+        child.stdout.on("data", (chunk) => {
+            out += chunk.toString("utf8");
+        });
+        child.stderr.on("data", (chunk) => {
+            out += chunk.toString("utf8");
+        });
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on("close", () => {
+            clearTimeout(timer);
+            resolve(out);
+        });
+    });
+}

package/dist/detect/index.d.ts

@@ -0,0 +1,2 @@
+import { type FormSpec } from "../schema/form.js";
+export declare function detectForm(target: string, cwd: string): Promise<FormSpec>;

package/dist/detect/index.js

@@ -0,0 +1,61 @@
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { Gui4CliError } from "../errors.js";
+import { formSpecSchema, labelFromName } from "../schema/form.js";
+import { loadConfig } from "../config/load.js";
+import { detectCommander } from "./commander.js";
+import { collectHelpText, parseHelpText } from "./help.js";
+import { detectJsdoc } from "./jsdoc.js";
+import { detectYargs } from "./yargs.js";
+import { mergeFields } from "./flags.js";
+export async function detectForm(target, cwd) {
+    const source = await readFile(target, "utf8");
+    const config = await loadConfig(target, cwd);
+    const commander = detectCommander(target, source);
+    const yargs = detectYargs(target, source);
+    const jsdoc = detectJsdoc(source);
+    let fields = [];
+    let detectSource = "merged";
+    if (commander.length >= yargs.length && commander.length > 0) {
+        fields = commander;
+        detectSource = "commander";
+    }
+    else if (yargs.length > 0) {
+        fields = yargs;
+        detectSource = "yargs";
+    }
+    else if (jsdoc.length > 0) {
+        fields = jsdoc;
+        detectSource = "jsdoc";
+    }
+    if (fields.length === 0) {
+        try {
+            const help = parseHelpText(await collectHelpText(target, cwd));
+            if (help.length > 0) {
+                fields = help;
+                detectSource = "help";
+            }
+        }
+        catch {
+            // Help can have side effects or hang; config is the escape hatch.
+        }
+    }
+    if (config?.fields) {
+        fields = mergeFields(fields, config.fields);
+        detectSource = fields.length > 0 ? "merged" : "config";
+    }
+    if (fields.length === 0) {
+        throw new Gui4CliError("Couldn't detect arguments for this script.", "Add a gui4cli.config.js next to the script with a fields object, then try again.");
+    }
+    const title = config?.title ?? labelFromName(basename(target).replace(/\.[cm]?[jt]s$/, ""));
+    const spec = formSpecSchema.parse({
+        title,
+        description: config?.description,
+        target,
+        cwd: config?.cwd ?? cwd,
+        source: detectSource,
+        fields,
+        window: config?.window,
+    });
+    return spec;
+}

package/dist/detect/jsdoc.d.ts

@@ -0,0 +1,2 @@
+import type { Field } from "../schema/form.js";
+export declare function detectJsdoc(source: string): Field[];

package/dist/detect/jsdoc.js

@@ -0,0 +1,22 @@
+import { fieldFromFlag, shouldSkipFlag } from "./flags.js";
+const PARAM = /@param\s+(?:\{([^}]+)\}\s+)?(?:\[)?(-{0,2}[\w-]+)(?:\])?\s*-?\s*(.*)/g;
+export function detectJsdoc(source) {
+    const fields = [];
+    for (const match of source.matchAll(PARAM)) {
+        const typeHint = match[1];
+        const rawName = match[2] ?? "";
+        const help = match[3]?.trim() || undefined;
+        const name = rawName.replace(/^--/, "");
+        if (!name || shouldSkipFlag(name))
+            continue;
+        fields.push(fieldFromFlag({
+            name,
+            longFlag: `--${name}`,
+            typeHint,
+            help,
+            required: !match[0].includes("["),
+            boolean: /boolean|flag/i.test(typeHint ?? ""),
+        }));
+    }
+    return fields;
+}

package/dist/detect/yargs.d.ts

@@ -0,0 +1,2 @@
+import type { Field } from "../schema/form.js";
+export declare function detectYargs(fileName: string, source: string): Field[];