ag-toolkit 0.1.4 → 0.3.0

package/dist/git.js

@@ -149,7 +149,7 @@ export class GitOperations {
         const output = await this.git.raw(args);
         const lines = output
             .split("\n")
-            .map((line) => line.replace("*", "").trim());
+            .map((line) => line.replace(/\*/g, "").trim());
         const filtered = lines
             .filter(Boolean)
             .filter((name) => !name.includes(" -> "))

package/dist/lib/arg-parser.d.ts

@@ -1,12 +1,16 @@
-interface FlagConfig {
+type FlagConfig = {
     type: "string" | "boolean";
     shortFlag?: string;
-}
-type FlagsSchema = {
-    [key: string]: FlagConfig;
+    enumValues?: never;
+} | {
+    type: "enum";
+    shortFlag?: string;
+    enumValues?: readonly string[];
 };
+export type FlagsSchema = Record<string, FlagConfig>;
+export declare const defineSchema: <T extends FlagsSchema>(schema: T) => T;
 type Flags<T extends FlagsSchema> = {
-    [K in keyof T]: T[K]["type"] extends "string" ? string | undefined : boolean | undefined;
+    [K in keyof T]: T[K]["type"] extends "string" ? string | undefined : T[K]["type"] extends "boolean" ? boolean | undefined : T[K]["type"] extends "enum" ? T[K]["enumValues"] extends readonly (infer U)[] ? U | undefined : string | undefined : never;
 };
 interface ParsedArgs<T extends FlagsSchema> {
     flags: Flags<T>;

package/dist/lib/arg-parser.js

@@ -1,3 +1,6 @@
+export const defineSchema = (schema) => {
+    return schema;
+};
 export class ArgParser {
     schema;
     helpMessage;
@@ -67,6 +70,17 @@ export class ArgParser {
                         }
                         flags[longFlag] = value;
                     }
+                    else if (flagConfig?.type === "enum") {
+                        const value = argValue ?? remainingArgs.shift();
+                        if (value === undefined) {
+                            throw new Error(`Flag --${String(longFlag)} requires a value.`);
+                        }
+                        if (flagConfig.enumValues &&
+                            !flagConfig.enumValues.includes(value)) {
+                            throw new Error(`Flag --${String(longFlag)} must be one of: ${flagConfig.enumValues.join(", ")}`);
+                        }
+                        flags[longFlag] = value;
+                    }
                 }
                 else {
                     if (argName.startsWith("-")) {

package/dist/tests/arg-parser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/arg-parser.test.js

@@ -0,0 +1,404 @@
+import { describe, expect, test } from "bun:test";
+import { ArgParser, defineSchema } from "../lib/arg-parser.js";
+describe("ArgParser", () => {
+    const schema = defineSchema({
+        verbose: { type: "boolean", shortFlag: "v" },
+        output: { type: "string", shortFlag: "o" },
+        force: { type: "boolean" },
+        configFile: { type: "string" },
+    });
+    describe("help and version flags", () => {
+        test("should return help message when -h is passed", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "Test help message",
+                version: "1.0.0",
+            });
+            const result = parser.parse(["-h"]);
+            expect(result.help).toBe("Test help message");
+        });
+        test("should return help message when --help is passed", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "Test help message",
+                version: "1.0.0",
+            });
+            const result = parser.parse(["--help"]);
+            expect(result.help).toBe("Test help message");
+        });
+        test("should return version when -v is passed (not short flag conflict)", () => {
+            const schemaWithoutVerbose = {
+                output: { type: "string", shortFlag: "o" },
+            };
+            const parser = new ArgParser({
+                schema: schemaWithoutVerbose,
+                helpMessage: "Test help",
+                version: "1.0.0",
+            });
+            const result = parser.parse(["-v"]);
+            expect(result.version).toBe("1.0.0");
+        });
+        test("should return version when --version is passed", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "Test help",
+                version: "1.0.0",
+            });
+            const result = parser.parse(["--version"]);
+            expect(result.version).toBe("1.0.0");
+        });
+    });
+    describe("boolean flags", () => {
+        test("should parse long boolean flags", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse(["--verbose", "--force"]);
+            expect(result.flags.verbose).toBe(true);
+            expect(result.flags.force).toBe(true);
+        });
+        test("should parse short boolean flags", () => {
+            const schemaWithDifferentShortFlag = {
+                ...schema,
+                verbose: { type: "boolean", shortFlag: "V" },
+            };
+            const parser = new ArgParser({
+                schema: schemaWithDifferentShortFlag,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse(["-V"]);
+            expect(result.flags.verbose).toBe(true);
+        });
+        test("should handle camelCase to kebab-case conversion", () => {
+            const parser = new ArgParser({
+                schema: { myLongFlag: { type: "boolean" } },
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse(["--my-long-flag"]);
+            expect(result.flags.myLongFlag).toBe(true);
+        });
+        test("should leave undefined flags as undefined", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse([]);
+            expect(result.flags.verbose).toBeUndefined();
+            expect(result.flags.force).toBeUndefined();
+        });
+    });
+    describe("enum flags", () => {
+        const schemaWithEnum = defineSchema({
+            logLevel: {
+                type: "enum",
+                enumValues: ["debug", "info", "warn", "error"],
+                shortFlag: "l",
+            },
+            environment: {
+                type: "enum",
+                enumValues: ["development", "staging", "production"],
+            },
+        });
+        test("should parse long enum flags with space", () => {
+            const parser = new ArgParser({
+                schema: schemaWithEnum,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse(["--log-level", "info"]);
+            expect(result.flags.logLevel).toBe("info");
+        });
+        test("should parse long enum flags with equals", () => {
+            const parser = new ArgParser({
+                schema: schemaWithEnum,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse(["--log-level=error"]);
+            expect(result.flags.logLevel).toBe("error");
+        });
+        test("should parse short enum flags", () => {
+            const parser = new ArgParser({
+                schema: schemaWithEnum,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse(["-l", "debug"]);
+            expect(result.flags.logLevel).toBe("debug");
+        });
+        test("should parse short enum flags with equals", () => {
+            const parser = new ArgParser({
+                schema: schemaWithEnum,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse(["-l=warn"]);
+            expect(result.flags.logLevel).toBe("warn");
+        });
+        test("should handle camelCase to kebab-case for enum flags", () => {
+            const parser = new ArgParser({
+                schema: schemaWithEnum,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse(["--log-level", "info"]);
+            expect(result.flags.logLevel).toBe("info");
+        });
+        test("should throw error when enum flag has invalid value", () => {
+            const parser = new ArgParser({
+                schema: schemaWithEnum,
+                helpMessage: "",
+                version: "",
+            });
+            expect(() => parser.parse(["--log-level", "invalid"])).toThrow("Flag --logLevel must be one of: debug, info, warn, error");
+        });
+        test("should throw error when enum flag has no value", () => {
+            const parser = new ArgParser({
+                schema: schemaWithEnum,
+                helpMessage: "",
+                version: "",
+            });
+            expect(() => parser.parse(["--log-level"])).toThrow("Flag --logLevel requires a value");
+        });
+        test("should parse multiple enum flags", () => {
+            const parser = new ArgParser({
+                schema: schemaWithEnum,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse([
+                "--log-level",
+                "debug",
+                "--environment",
+                "production",
+            ]);
+            expect(result.flags.logLevel).toBe("debug");
+            expect(result.flags.environment).toBe("production");
+        });
+        test("should leave undefined enum flags as undefined", () => {
+            const parser = new ArgParser({
+                schema: schemaWithEnum,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse([]);
+            expect(result.flags.logLevel).toBeUndefined();
+            expect(result.flags.environment).toBeUndefined();
+        });
+        test("should handle multiple occurrences of same enum flag (last wins)", () => {
+            const parser = new ArgParser({
+                schema: schemaWithEnum,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse([
+                "--log-level",
+                "debug",
+                "--log-level",
+                "error",
+            ]);
+            expect(result.flags.logLevel).toBe("error");
+        });
+    });
+    describe("string flags", () => {
+        test("should parse long string flags with space", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse(["--output", "file.txt"]);
+            expect(result.flags.output).toBe("file.txt");
+        });
+        test("should parse long string flags with equals", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse(["--output=file.txt"]);
+            expect(result.flags.output).toBe("file.txt");
+        });
+        test("should parse short string flags", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse(["-o", "file.txt"]);
+            expect(result.flags.output).toBe("file.txt");
+        });
+        test("should parse short string flags with equals", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse(["-o=file.txt"]);
+            expect(result.flags.output).toBe("file.txt");
+        });
+        test("should handle camelCase to kebab-case for string flags", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse(["--config-file", "config.json"]);
+            expect(result.flags.configFile).toBe("config.json");
+        });
+        test("should throw error when string flag has no value", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            expect(() => parser.parse(["--output"])).toThrow();
+        });
+    });
+    describe("input arguments", () => {
+        test("should collect non-flag arguments as input", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse(["arg1", "arg2", "arg3"]);
+            expect(result.input).toEqual(["arg1", "arg2", "arg3"]);
+        });
+        test("should collect input after flags", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse(["--verbose", "arg1", "arg2"]);
+            expect(result.flags.verbose).toBe(true);
+            expect(result.input).toEqual(["arg1", "arg2"]);
+        });
+        test("should handle -- separator", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse(["--verbose", "--", "--output", "file.txt"]);
+            expect(result.flags.verbose).toBe(true);
+            expect(result.flags.output).toBeUndefined();
+            expect(result.input).toEqual(["--output", "file.txt"]);
+        });
+        test("should collect everything after -- as input", () => {
+            const schemaWithoutConflicts = defineSchema({
+                force: { type: "boolean" },
+            });
+            const parser = new ArgParser({
+                schema: schemaWithoutConflicts,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse(["--", "--force"]);
+            expect(result.input).toEqual(["--force"]);
+        });
+    });
+    describe("mixed arguments", () => {
+        test("should parse mixed flags and input", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse([
+                "--verbose",
+                "--output",
+                "file.txt",
+                "input1",
+                "--force",
+                "input2",
+            ]);
+            expect(result.flags.verbose).toBe(true);
+            expect(result.flags.output).toBe("file.txt");
+            expect(result.flags.force).toBe(true);
+            expect(result.input).toEqual(["input1", "input2"]);
+        });
+        test("should handle multiple flags with equals syntax", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse([
+                "--verbose",
+                "--output=out.txt",
+                "--config-file=config.json",
+            ]);
+            expect(result.flags.verbose).toBe(true);
+            expect(result.flags.output).toBe("out.txt");
+            expect(result.flags.configFile).toBe("config.json");
+        });
+    });
+    describe("error handling", () => {
+        test("should throw error for unknown long flags", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            expect(() => parser.parse(["--unknown"])).toThrow("Unknown option: --unknown");
+        });
+        test("should throw error for unknown short flags", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            expect(() => parser.parse(["-x"])).toThrow("Unknown option: -x");
+        });
+        test("should throw error when string flag requires value", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            expect(() => parser.parse(["--output"])).toThrow("Flag --output requires a value");
+        });
+    });
+    describe("edge cases", () => {
+        test("should handle empty args array", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse([]);
+            expect(result.input).toEqual([]);
+            expect(result.flags.verbose).toBeUndefined();
+        });
+        test("should handle flags with empty string values", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse(["--output="]);
+            expect(result.flags.output).toBe("");
+        });
+        test("should handle multiple occurrences of same flag (last wins)", () => {
+            const parser = new ArgParser({
+                schema,
+                helpMessage: "",
+                version: "",
+            });
+            const result = parser.parse([
+                "--output",
+                "first.txt",
+                "--output",
+                "second.txt",
+            ]);
+            expect(result.flags.output).toBe("second.txt");
+        });
+    });
+});

package/dist/tests/config.test.d.ts

@@ -0,0 +1 @@
+export {};