specli 0.0.11 → 0.0.13

package/dist/cli/runtime/execute.js

@@ -0,0 +1,106 @@
+import { buildRequest } from "./request.js";
+/**
+ * Format an error message with a help hint.
+ */
+function formatError(message, resourceName, actionName) {
+    const helpCmd = resourceName
+        ? `${resourceName} ${actionName} --help`
+        : `${actionName} --help`;
+    return `${message}\n\nRun '${helpCmd}' to see available options.`;
+}
+/**
+ * Execute an action and return the result as data.
+ * This is the core execution function used by both CLI and programmatic API.
+ */
+export async function execute(input) {
+    const { request, curl } = await buildRequest({
+        specId: input.specId,
+        action: input.action,
+        positionalValues: input.positionalValues,
+        flagValues: input.flagValues,
+        globals: input.globals,
+        servers: input.servers,
+        authSchemes: input.authSchemes,
+        embeddedDefaults: input.embeddedDefaults,
+        bodyFlagDefs: input.bodyFlagDefs,
+    });
+    const res = await fetch(request);
+    const contentType = res.headers.get("content-type") ?? "";
+    const text = await res.text();
+    let body = text;
+    if (contentType.includes("json") && text) {
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            // keep as text
+        }
+    }
+    return {
+        ok: res.ok,
+        status: res.status,
+        body,
+        curl,
+    };
+}
+/**
+ * Execute an action and write output to stdout/stderr.
+ * This is the CLI-facing wrapper around execute().
+ */
+export async function executeAction(input) {
+    const actionName = input.action.action;
+    const resourceName = input.resourceName;
+    try {
+        if (input.globals.curl) {
+            const { curl } = await buildRequest({
+                specId: input.specId,
+                action: input.action,
+                positionalValues: input.positionalValues,
+                flagValues: input.flagValues,
+                globals: input.globals,
+                servers: input.servers,
+                authSchemes: input.authSchemes,
+                embeddedDefaults: input.embeddedDefaults,
+                bodyFlagDefs: input.bodyFlagDefs,
+            });
+            process.stdout.write(`${curl}\n`);
+            return;
+        }
+        const result = await execute(input);
+        if (!result.ok) {
+            if (input.globals.json) {
+                process.stdout.write(`${JSON.stringify({ status: result.status, body: result.body })}\n`);
+            }
+            else {
+                process.stderr.write(`HTTP ${result.status}\n`);
+                process.stderr.write(`${typeof result.body === "string" ? result.body : JSON.stringify(result.body, null, 2)}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        if (input.globals.json) {
+            process.stdout.write(`${JSON.stringify(result.body)}\n`);
+            return;
+        }
+        // default (human + agent readable)
+        if (typeof result.body === "string") {
+            process.stdout.write(result.body);
+            if (!result.body.endsWith("\n"))
+                process.stdout.write("\n");
+        }
+        else {
+            process.stdout.write(`${JSON.stringify(result.body, null, 2)}\n`);
+        }
+    }
+    catch (err) {
+        const rawMessage = err instanceof Error ? err.message : String(err);
+        const message = formatError(rawMessage, resourceName, actionName);
+        if (input.globals.json) {
+            process.stdout.write(`${JSON.stringify({ error: rawMessage })}\n`);
+        }
+        else {
+            process.stderr.write(`error: ${message}\n`);
+        }
+        process.exitCode = 1;
+    }
+}

package/dist/{src/cli → cli}/runtime/generated.d.ts

@@ -11,4 +11,3 @@ export type GeneratedCliContext = {
     embeddedDefaults?: EmbeddedDefaults;
 };
 export declare function addGeneratedCommands(program: Command, context: GeneratedCliContext): void;
-//# sourceMappingURL=generated.d.ts.map

package/dist/cli/runtime/generated.js

@@ -0,0 +1,168 @@
+import { Command } from "commander";
+import { generateBodyFlags } from "./body-flags.js";
+import { executeAction } from "./execute.js";
+import { coerceArrayInput, coerceValue } from "./validate/index.js";
+/**
+ * Format help output that is clear for both humans and AI agents.
+ * Groups options into Required, Optional, and Global sections.
+ */
+function formatCustomHelp(cmd, action, operationFlags, bodyFlagDefs) {
+    const lines = [];
+    const cmdName = cmd.name();
+    const parentName = cmd.parent?.name() ?? "";
+    const fullCmd = parentName ? `${parentName} ${cmdName}` : cmdName;
+    // Usage line
+    const positionals = action.positionals.map((p) => `<${p.name}>`).join(" ");
+    const usageSuffix = positionals ? ` ${positionals}` : "";
+    lines.push(`Usage: ${fullCmd}${usageSuffix} [options]`);
+    lines.push("");
+    // Description
+    const desc = action.summary ?? action.description ?? `${action.method} ${action.path}`;
+    lines.push(desc);
+    lines.push("");
+    // Collect all options into categories
+    const requiredOpts = [];
+    const optionalOpts = [];
+    // Format a single option line
+    const formatOpt = (flag, type, desc, required) => {
+        const typeStr = type === "boolean" ? "" : ` <${type}>`;
+        const reqMarker = required ? " (required)" : "";
+        return `  ${flag}${typeStr}${reqMarker}\n      ${desc}`;
+    };
+    // Operation flags (query/header/path params)
+    for (const f of operationFlags) {
+        const type = f.type === "array" ? `${f.itemType ?? "string"}[]` : f.type;
+        const line = formatOpt(f.flag, type, f.description ?? `${f.in} parameter`, f.required);
+        if (f.required) {
+            requiredOpts.push(line);
+        }
+        else {
+            optionalOpts.push(line);
+        }
+    }
+    // Body flags
+    for (const def of bodyFlagDefs) {
+        const line = formatOpt(def.flag, def.type, def.description, def.required);
+        if (def.required) {
+            requiredOpts.push(line);
+        }
+        else {
+            optionalOpts.push(line);
+        }
+    }
+    // Required options section
+    if (requiredOpts.length > 0) {
+        lines.push("Required:");
+        lines.push(...requiredOpts);
+        lines.push("");
+    }
+    // Optional options section
+    if (optionalOpts.length > 0) {
+        lines.push("Options:");
+        lines.push(...optionalOpts);
+        lines.push("");
+    }
+    // Global options (always available)
+    lines.push("Global:");
+    lines.push("  --curl\n      Print curl command instead of executing");
+    lines.push("  --json\n      Output response as JSON");
+    lines.push("  --server <url>\n      Override the API server URL");
+    lines.push("  --bearer-token <token>\n      Provide auth token (or use 'login' command)");
+    lines.push("  -h, --help\n      Show this help message");
+    lines.push("");
+    return lines.join("\n");
+}
+export function addGeneratedCommands(program, context) {
+    for (const resource of context.commands.resources) {
+        const resourceCmd = program
+            .command(resource.resource)
+            .description(`Operations for ${resource.resource}`);
+        for (const action of resource.actions) {
+            const cmd = resourceCmd.command(action.action);
+            cmd.description(action.summary ??
+                action.description ??
+                `${action.method} ${action.path}`);
+            for (const pos of action.positionals) {
+                cmd.argument(`<${pos.name}>`, pos.description);
+            }
+            for (const flag of action.flags) {
+                const opt = flag.flag;
+                const desc = flag.description ?? `${flag.in} parameter`;
+                if (flag.type === "boolean") {
+                    cmd.option(opt, desc);
+                    continue;
+                }
+                const isArray = flag.type === "array";
+                const itemType = flag.itemType ?? "string";
+                const flagType = isArray ? itemType : flag.type;
+                const parser = (raw) => coerceValue(raw, flagType);
+                if (isArray) {
+                    const key = `${opt} <value>`;
+                    cmd.option(key, desc, (value, prev) => {
+                        const next = [...(prev ?? [])];
+                        // Allow `--tags a,b` and `--tags '["a","b"]'` to expand.
+                        const items = coerceArrayInput(value, itemType);
+                        for (const item of items) {
+                            next.push(item);
+                        }
+                        return next;
+                    });
+                    continue;
+                }
+                const key = `${opt} <value>`;
+                if (flag.required)
+                    cmd.requiredOption(key, desc, parser);
+                else
+                    cmd.option(key, desc, parser);
+            }
+            // Collect reserved flags: operation params + --curl
+            const operationFlagSet = new Set(action.flags.map((f) => f.flag));
+            const reservedFlags = new Set([...operationFlagSet, "--curl"]);
+            // Only --curl is a built-in flag (for debugging)
+            if (!operationFlagSet.has("--curl")) {
+                cmd.option("--curl", "Print curl command without sending");
+            }
+            // Track body flag definitions for this action
+            let bodyFlagDefs = [];
+            if (action.requestBody) {
+                // Generate body flags from schema (recursive with dot notation)
+                // Pass reserved flags to avoid conflicts with operation params and --curl
+                bodyFlagDefs = generateBodyFlags(action.requestBodySchema, reservedFlags);
+                for (const def of bodyFlagDefs) {
+                    if (def.type === "boolean") {
+                        cmd.option(def.flag, def.description);
+                    }
+                    else {
+                        cmd.option(`${def.flag} <value>`, def.description);
+                    }
+                }
+            }
+            // Custom help output for better agent/human readability
+            cmd.configureHelp({
+                formatHelp: () => formatCustomHelp(cmd, action, action.flags, bodyFlagDefs),
+            });
+            // Commander passes positional args and then the Command instance as last arg.
+            cmd.action(async (...args) => {
+                const command = args[args.length - 1];
+                const positionalValues = args.slice(0, -1).map((v) => String(v));
+                if (!(command instanceof Command)) {
+                    throw new Error("Unexpected commander action signature");
+                }
+                const globals = command.optsWithGlobals();
+                const local = command.opts();
+                await executeAction({
+                    action,
+                    positionalValues,
+                    flagValues: local,
+                    globals,
+                    servers: context.servers,
+                    authSchemes: context.authSchemes,
+                    specId: context.specId,
+                    embeddedDefaults: context.embeddedDefaults,
+                    bodyFlagDefs,
+                    resourceName: resource.resource,
+                });
+            });
+        }
+    }
+}

package/dist/{src/cli → cli}/runtime/headers.d.ts

@@ -6,4 +6,3 @@ export declare function mergeHeaders(base: Headers, entries: Array<{
     name: string;
     value: string;
 }>): Headers;
-//# sourceMappingURL=headers.d.ts.map

package/dist/cli/runtime/headers.js

@@ -0,0 +1,30 @@
+export function parseHeaderInput(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        throw new Error("Empty header");
+    // Support either "Name: Value" or "Name=Value".
+    const colon = trimmed.indexOf(":");
+    if (colon !== -1) {
+        const name = trimmed.slice(0, colon).trim();
+        const value = trimmed.slice(colon + 1).trim();
+        if (!name)
+            throw new Error("Invalid header name");
+        return { name, value };
+    }
+    const eq = trimmed.indexOf("=");
+    if (eq !== -1) {
+        const name = trimmed.slice(0, eq).trim();
+        const value = trimmed.slice(eq + 1).trim();
+        if (!name)
+            throw new Error("Invalid header name");
+        return { name, value };
+    }
+    throw new Error("Invalid header format. Use 'Name: Value' or 'Name=Value'.");
+}
+export function mergeHeaders(base, entries) {
+    const h = new Headers(base);
+    for (const { name, value } of entries) {
+        h.set(name, value);
+    }
+    return h;
+}

package/dist/{src/cli → cli}/runtime/index.d.ts

@@ -1,4 +1,3 @@
 export * from "./argv.js";
 export * from "./context.js";
 export * from "./generated.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/cli/runtime/index.js

@@ -0,0 +1,3 @@
+export * from "./argv.js";
+export * from "./context.js";
+export * from "./generated.js";

package/dist/{src/cli → cli}/runtime/profile/secrets.d.ts

@@ -22,4 +22,3 @@ export declare function getToken(specId: string, profile: string): Promise<strin
  * In Node.js: returns false (secrets not supported)
  */
 export declare function deleteToken(specId: string, profile: string): Promise<boolean>;
-//# sourceMappingURL=secrets.d.ts.map

package/dist/cli/runtime/profile/secrets.js

@@ -0,0 +1,53 @@
+import { isBun } from "../compat.js";
+const bunLiteral = "bun";
+export function secretServiceForSpec(specId) {
+    return `specli:${specId}`;
+}
+export function tokenSecretKey(specId, profile) {
+    return {
+        service: secretServiceForSpec(specId),
+        name: `profile:${profile}:token`,
+    };
+}
+/**
+ * Store a token securely.
+ * In Bun: uses the native secrets store (system keychain)
+ * In Node.js: secrets are not supported, warns user
+ */
+export async function setToken(specId, profile, token) {
+    if (!isBun) {
+        console.warn("Warning: Secure token storage requires Bun. Token will not be persisted.");
+        console.warn("Use --bearer-token <token> flag instead when running with Node.js.");
+        return;
+    }
+    const { secrets } = await import(bunLiteral);
+    const key = tokenSecretKey(specId, profile);
+    await secrets.set({ service: key.service, name: key.name, value: token });
+}
+/**
+ * Retrieve a stored token.
+ * In Bun: retrieves from the native secrets store
+ * In Node.js: returns null (secrets not supported)
+ */
+export async function getToken(specId, profile) {
+    if (!isBun) {
+        return null;
+    }
+    const { secrets } = await import(bunLiteral);
+    const key = tokenSecretKey(specId, profile);
+    return await secrets.get({ service: key.service, name: key.name });
+}
+/**
+ * Delete a stored token.
+ * In Bun: removes from the native secrets store
+ * In Node.js: returns false (secrets not supported)
+ */
+export async function deleteToken(specId, profile) {
+    if (!isBun) {
+        console.warn("Warning: Secure token storage requires Bun. No token to delete.");
+        return false;
+    }
+    const { secrets } = await import(bunLiteral);
+    const key = tokenSecretKey(specId, profile);
+    return await secrets.delete({ service: key.service, name: key.name });
+}

package/dist/{src/cli → cli}/runtime/profile/store.d.ts

@@ -12,4 +12,3 @@ export declare function writeProfiles(data: ProfilesFile): Promise<void>;
 export declare function getProfile(data: ProfilesFile, name: string | undefined): Profile | undefined;
 export declare function upsertProfile(data: ProfilesFile, profile: Profile): ProfilesFile;
 export declare function removeProfile(data: ProfilesFile, name: string): ProfilesFile;
-//# sourceMappingURL=store.d.ts.map

package/dist/cli/runtime/profile/store.js

@@ -0,0 +1,63 @@
+import { fileExists, mkdirp, parseYamlContent, readFileText, writeFileText, } from "../compat.js";
+function configDir() {
+    // Keep it simple (v1). We can move to env-paths later.
+    const home = process.env.HOME;
+    if (!home)
+        throw new Error("Missing HOME env var");
+    return `${home}/.config/specli`;
+}
+function configPathJson() {
+    return `${configDir()}/profiles.json`;
+}
+function configPathYaml() {
+    return `${configDir()}/profiles.yaml`;
+}
+export async function readProfiles() {
+    const jsonPath = configPathJson();
+    const yamlPath = configPathYaml();
+    const jsonExists = await fileExists(jsonPath);
+    const yamlExists = await fileExists(yamlPath);
+    const filePath = jsonExists ? jsonPath : yamlExists ? yamlPath : null;
+    if (!filePath)
+        return { profiles: [] };
+    const text = await readFileText(filePath);
+    let parsed;
+    try {
+        parsed = parseYamlContent(text);
+    }
+    catch {
+        parsed = JSON.parse(text);
+    }
+    const obj = parsed && typeof parsed === "object"
+        ? parsed
+        : {};
+    const profiles = Array.isArray(obj.profiles)
+        ? obj.profiles
+        : [];
+    return {
+        profiles: profiles.filter(Boolean),
+        defaultProfile: typeof obj.defaultProfile === "string"
+            ? obj.defaultProfile
+            : undefined,
+    };
+}
+export async function writeProfiles(data) {
+    const dir = configDir();
+    await mkdirp(dir);
+    await writeFileText(configPathJson(), JSON.stringify(data, null, 2));
+}
+export function getProfile(data, name) {
+    const wanted = name ?? data.defaultProfile;
+    if (!wanted)
+        return undefined;
+    return data.profiles.find((p) => p?.name === wanted);
+}
+export function upsertProfile(data, profile) {
+    const profiles = data.profiles.filter((p) => p.name !== profile.name);
+    profiles.push(profile);
+    profiles.sort((a, b) => a.name.localeCompare(b.name));
+    return { ...data, profiles };
+}
+export function removeProfile(data, name) {
+    return { ...data, profiles: data.profiles.filter((p) => p.name !== name) };
+}

package/dist/{src/cli → cli}/runtime/request.d.ts

@@ -33,4 +33,3 @@ export declare function buildRequest(input: BuildRequestInput): Promise<{
     request: Request;
     curl: string;
 }>;
-//# sourceMappingURL=request.d.ts.map