toolcraft-openapi 0.0.1

package/README.md

@@ -0,0 +1,64 @@
+# toolcraft-openapi
+
+tools for agents and humans
+
+Scaffold for OpenAPI-driven toolcraft clients.
+
+## Usage
+
+```ts
+import { bearerTokenAuth, requestJson } from "agent-kit-openapi";
+
+const auth = bearerTokenAuth({
+  serviceName: "internal-agent",
+  envVar: "INTERNAL_AGENT_TOKEN",
+  whoamiPath: "/whoami"
+});
+```
+
+## Generator CLI
+
+`agent-kit-openapi-generate` reads an OpenAPI document from disk or a URL, writes generated
+command files, and stores the current spec hash in `openapi.lock`.
+
+- `--input <path-or-url>` — OpenAPI document to read. Defaults to `openapi.json`.
+- `--output <dir>` — directory for generated files. Defaults to `src/generated`.
+- `--lock <path>` — lock file path. Defaults to `openapi.lock`.
+- `--check` — exits non-zero when generated files or `openapi.lock` would change.
+
+### CI drift check
+
+```sh
+agent-kit-openapi-generate --check
+```
+
+## Exports
+
+- `bearerTokenAuth(opts)`
+- `requestJson(options)`
+- `HttpError`
+- `TokenSource`
+- `CommandContributor`
+- `AuthProvider`
+
+## Environment variables
+
+- `<envVar passed to bearerTokenAuth>` — bearer token override; wins over stored credentials.
+- `AUTH_BACKEND` — forwarded to `auth-store` to select `file` or `keychain` storage.
+
+## Configuration
+
+### `bearerTokenAuth(opts)`
+
+- `serviceName: string` — auth-store service name and file-store key.
+- `envVar: string` — environment variable checked before stored credentials.
+- `whoamiPath?: string` — optional authenticated endpoint used by `login` and `status`.
+- `commandPrefix?: string` — CLI auth group name. Defaults to `auth`.
+
+## Auth commands
+
+`bearerTokenAuth()` contributes a CLI-only `<commandPrefix>` group with:
+
+- `login`
+- `logout`
+- `status`

package/dist/api-command.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from "agent-kit";
+import { defineCommand } from "agent-kit";
+import type { ObjectSchema } from "agent-kit-schema";
+import type { OpenApiClientServices } from "./define-client.js";
+type ApiScope = readonly ["cli", "mcp", "sdk"];
+export declare function defineApiCommand<TParamsSchema extends ObjectSchema<any>>(config: Parameters<typeof defineCommand<OpenApiClientServices, string, TParamsSchema, undefined, unknown, ApiScope>>[0]): Command<OpenApiClientServices, TParamsSchema, undefined, unknown>;
+export {};

package/dist/api-command.js

@@ -0,0 +1,4 @@
+import { defineCommand } from "agent-kit";
+export function defineApiCommand(config) {
+    return defineCommand(config);
+}

package/dist/auth/bearer-token-auth.d.ts

@@ -0,0 +1,8 @@
+import type { AuthProvider } from "./types.js";
+export interface BearerTokenAuthOptions {
+    serviceName: string;
+    envVar: string;
+    whoamiPath?: string;
+    commandPrefix?: string;
+}
+export declare function bearerTokenAuth(options: BearerTokenAuthOptions): AuthProvider;

package/dist/auth/bearer-token-auth.js

@@ -0,0 +1,216 @@
+import { defineCommand, defineGroup, S, UserError } from "agent-kit";
+import { isCancel, password } from "@poe-code/design-system";
+import { createSecretStore } from "auth-store";
+import { requestJson } from "../http.js";
+const DEFAULT_COMMAND_PREFIX = "auth";
+const loginParams = S.Object({
+    token: S.Optional(S.String({ description: "Bearer token to store." })),
+    tokenStdin: S.Optional(S.Boolean({ description: "Read the token from stdin instead of prompting." })),
+});
+const emptyParams = S.Object({});
+const KEYCHAIN_ACCOUNT = "token";
+const DEFAULT_STORE_DIRECTORY = ".agent-kit-openapi";
+const DEFAULT_STORE_VERSION = "v1";
+export function bearerTokenAuth(options) {
+    const commandPrefix = options.commandPrefix ?? DEFAULT_COMMAND_PREFIX;
+    const { store, backend } = createSecretStore({
+        fileStore: {
+            salt: `${options.serviceName}:agent-kit-openapi:${DEFAULT_STORE_VERSION}`,
+            defaultDirectory: DEFAULT_STORE_DIRECTORY,
+            defaultFileName: `${options.serviceName}.enc`,
+        },
+        keychainStore: {
+            service: options.serviceName,
+            account: KEYCHAIN_ACCOUNT,
+        },
+    });
+    async function resolveToken() {
+        const envToken = normalizeToken(process.env[options.envVar]);
+        if (envToken) {
+            return {
+                token: envToken,
+                tokenSource: `env (${options.envVar})`,
+            };
+        }
+        const storedToken = normalizeToken(await store.get());
+        if (!storedToken) {
+            return null;
+        }
+        return {
+            token: storedToken,
+            tokenSource: backend,
+        };
+    }
+    const loginCommand = defineCommand({
+        name: "login",
+        description: "Store a bearer token for future requests.",
+        params: loginParams,
+        handler: async (ctx) => {
+            const token = await resolveLoginToken(ctx.params, ctx.readStdin);
+            const identity = await resolveIdentity(token, ctx, options.whoamiPath);
+            if (options.whoamiPath !== undefined && identity.isEmployee !== true) {
+                throw new UserError("Authenticated account is not an employee.");
+            }
+            await store.set(token);
+            return {
+                email: identity.email,
+                isEmployee: identity.isEmployee,
+                storageBackend: backend,
+            };
+        },
+        render: {
+            rich: (result, { logger }) => {
+                logger.success(formatLoginMessage(result));
+                logger.message(result.storageBackend === "keychain"
+                    ? "Stored in macOS Keychain."
+                    : "Stored in encrypted file store.");
+            },
+            json: (result) => result,
+        },
+    });
+    const logoutCommand = defineCommand({
+        name: "logout",
+        description: "Remove the stored bearer token.",
+        params: emptyParams,
+        handler: async () => {
+            await store.delete();
+            return {
+                storageBackend: backend,
+            };
+        },
+        render: {
+            rich: (_result, { logger }) => {
+                logger.success("Removed stored credential.");
+            },
+            json: (result) => result,
+        },
+    });
+    const statusCommand = defineCommand({
+        name: "status",
+        description: "Show where the current bearer token resolves from.",
+        params: emptyParams,
+        handler: async (ctx) => {
+            const resolvedToken = await resolveToken();
+            if (!resolvedToken) {
+                return { loggedIn: false };
+            }
+            const identity = await resolveIdentity(resolvedToken.token, ctx, options.whoamiPath);
+            return {
+                loggedIn: true,
+                tokenSource: resolvedToken.tokenSource,
+                email: identity.email,
+                isEmployee: identity.isEmployee,
+            };
+        },
+        render: {
+            rich: (result, { logger }) => {
+                if (!result.loggedIn) {
+                    logger.message("Not logged in.");
+                    return;
+                }
+                logger.success(result.email ? `Logged in as ${result.email}` : "Logged in.");
+                logger.message(`Token source: ${result.tokenSource}`);
+            },
+            json: (result) => result,
+        },
+    });
+    return {
+        async getToken() {
+            const resolvedToken = await resolveToken();
+            if (resolvedToken) {
+                return resolvedToken.token;
+            }
+            throw new UserError(`Run '${commandPrefix} login' first.`);
+        },
+        async invalidate() {
+            await store.delete();
+        },
+        commands: [defineGroup({
+                name: commandPrefix,
+                description: "Manage stored bearer-token authentication.",
+                scope: ["cli"],
+                children: [loginCommand, logoutCommand, statusCommand],
+            })],
+    };
+}
+async function resolveLoginToken(params, readStdin) {
+    const providedToken = normalizeToken(params.token);
+    if (providedToken && params.tokenStdin) {
+        throw new UserError("Pass either --token or --token-stdin, not both.");
+    }
+    if (providedToken) {
+        return providedToken;
+    }
+    if (params.tokenStdin) {
+        const stdinToken = normalizeToken(await (readStdin?.() ?? readAllFromStdin()));
+        if (!stdinToken) {
+            throw new UserError("Received an empty token from stdin.");
+        }
+        return stdinToken;
+    }
+    const promptedToken = await password({
+        message: "Paste your API key:",
+    });
+    if (isCancel(promptedToken)) {
+        throw new UserError("Authentication cancelled.");
+    }
+    const normalizedPromptedToken = normalizeToken(promptedToken);
+    if (!normalizedPromptedToken) {
+        throw new UserError("Token cannot be empty.");
+    }
+    return normalizedPromptedToken;
+}
+async function resolveIdentity(token, services, whoamiPath) {
+    if (whoamiPath === undefined) {
+        return {};
+    }
+    if (!services.baseUrl) {
+        throw new UserError("Auth verification requires a baseUrl service.");
+    }
+    const response = await requestJson({
+        baseUrl: services.baseUrl,
+        path: whoamiPath,
+        method: "GET",
+        auth: "required",
+        tokenSource: {
+            getToken: async () => token,
+        },
+        fetch: services.fetch,
+    });
+    return parseIdentity(response);
+}
+function parseIdentity(response) {
+    if (!isRecord(response)) {
+        return {};
+    }
+    return {
+        email: typeof response.email === "string" ? response.email : undefined,
+        isEmployee: typeof response.is_employee === "boolean" ? response.is_employee : undefined,
+    };
+}
+async function readAllFromStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+function normalizeToken(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function formatLoginMessage(result) {
+    if (!result.email) {
+        return "Authenticated.";
+    }
+    if (result.isEmployee === true) {
+        return `Authenticated as ${result.email} (employee confirmed).`;
+    }
+    return `Authenticated as ${result.email}.`;
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/dist/auth/types.d.ts

@@ -0,0 +1,9 @@
+import type { CommandNode } from "agent-kit";
+export interface TokenSource {
+    getToken(): Promise<string>;
+    invalidate?(): Promise<void>;
+}
+export interface CommandContributor {
+    commands: CommandNode<any>[];
+}
+export type AuthProvider = TokenSource & CommandContributor;

package/dist/auth/types.js

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

package/dist/bin/generate.d.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+interface GenerateCliFileSystem {
+    mkdir(directoryPath: string, options?: {
+        recursive?: boolean;
+    }): Promise<unknown>;
+    readFile(filePath: string, encoding: BufferEncoding): Promise<string>;
+    readdir(directoryPath: string): Promise<string[]>;
+    rm(targetPath: string, options?: {
+        force?: boolean;
+    }): Promise<void>;
+    stat(targetPath: string): Promise<{
+        isDirectory(): boolean;
+    }>;
+    writeFile(filePath: string, contents: string, encoding: BufferEncoding): Promise<void>;
+}
+interface GenerateCliWriter {
+    write(chunk: string | Uint8Array): boolean;
+}
+interface GenerateCliServices {
+    cwd: string;
+    fetch: typeof globalThis.fetch;
+    fs: GenerateCliFileSystem;
+    stderr: GenerateCliWriter;
+    stdout: GenerateCliWriter;
+}
+interface GenerateCliOptions {
+    check: boolean;
+    input: string;
+    lockPath: string;
+    outputDir: string;
+}
+interface SyncGeneratedClientResult {
+    deletedFileCount: number;
+    drifted: boolean;
+    specSha: string;
+    updatedFileCount: number;
+}
+export declare function runGenerateCli(argv?: string[], services?: GenerateCliServices): Promise<number>;
+export declare function syncGeneratedClient(options: GenerateCliOptions, services: Pick<GenerateCliServices, "cwd" | "fetch" | "fs">): Promise<SyncGeneratedClientResult>;
+export {};

package/dist/bin/generate.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { UserError } from "agent-kit";
+import { generate } from "../generate.js";
+import { readOpenApiLock, writeOpenApiLock } from "../lock.js";
+import { parseOpenApiDocument, readOpenApiSourceText } from "../spec-source.js";
+const DEFAULT_OPTIONS = {
+    check: false,
+    input: "openapi.json",
+    lockPath: "openapi.lock",
+    outputDir: "src/generated"
+};
+const HELP_TEXT = `Usage: agent-kit-openapi-generate [options]
+
+Options:
+  --input <path-or-url>  OpenAPI document to read (default: openapi.json)
+  --output <dir>         Directory for generated command files (default: src/generated)
+  --lock <path>          Lock file path (default: openapi.lock)
+  --check                Exit non-zero if generated output or lock file would change
+  -h, --help             Show this help text
+`;
+export async function runGenerateCli(argv = process.argv, services = {
+    cwd: process.cwd(),
+    fetch: globalThis.fetch,
+    fs,
+    stderr: process.stderr,
+    stdout: process.stdout
+}) {
+    try {
+        const parsed = parseGenerateCliArgs(argv.slice(2));
+        if (parsed === "help") {
+            services.stdout.write(HELP_TEXT);
+            return 0;
+        }
+        const result = await syncGeneratedClient(parsed, services);
+        if (parsed.check) {
+            if (result.drifted) {
+                services.stderr.write(`OpenAPI output is out of date for ${parsed.outputDir}. Run the generator without --check to update it.\n`);
+                return 1;
+            }
+            services.stdout.write(`OpenAPI output is up to date (${result.specSha}).\n`);
+            return 0;
+        }
+        if (result.drifted) {
+            services.stdout.write(`Updated OpenAPI output (${result.updatedFileCount} written, ${result.deletedFileCount} deleted).\n`);
+            return 0;
+        }
+        services.stdout.write(`OpenAPI output is up to date (${result.specSha}).\n`);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof UserError) {
+            services.stderr.write(`${error.message}\n`);
+            return 1;
+        }
+        throw error;
+    }
+}
+export async function syncGeneratedClient(options, services) {
+    const sourceText = await readOpenApiSourceText(options.input, services);
+    const specSha = createSpecSha(sourceText);
+    const document = parseOpenApiDocument(sourceText, options.input);
+    const generatedFiles = generate(document, { specSha });
+    const outputDir = path.resolve(services.cwd, options.outputDir);
+    const lockPath = path.resolve(services.cwd, options.lockPath);
+    const currentLock = await readOpenApiLock(services.fs, lockPath);
+    const currentFiles = await readGeneratedFiles(services.fs, outputDir);
+    const desiredFiles = new Map([
+        ...generatedFiles.map((file) => [path.resolve(outputDir, file.path), file.contents]),
+        ...createDownloadedSpecFiles(options.input, sourceText).map((file) => [path.resolve(outputDir, file.path), file.contents])
+    ]);
+    const updatedFiles = collectUpdatedFiles(currentFiles, desiredFiles);
+    const deletedFiles = collectDeletedFiles(currentFiles, desiredFiles);
+    const drifted = currentLock?.specSha !== specSha || updatedFiles.length > 0 || deletedFiles.length > 0;
+    if (!options.check && drifted) {
+        await writeGeneratedFiles(services.fs, updatedFiles);
+        await deleteGeneratedFiles(services.fs, deletedFiles);
+        await writeOpenApiLock(services.fs, lockPath, { specSha });
+    }
+    return {
+        drifted,
+        specSha,
+        updatedFileCount: updatedFiles.length,
+        deletedFileCount: deletedFiles.length
+    };
+}
+function parseGenerateCliArgs(argv) {
+    const options = { ...DEFAULT_OPTIONS };
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index] ?? "";
+        if (argument === "-h" || argument === "--help") {
+            return "help";
+        }
+        if (argument === "--check") {
+            options.check = true;
+            continue;
+        }
+        if (argument === "--input" || argument === "--output" || argument === "--lock") {
+            const value = argv[index + 1];
+            if (value === undefined) {
+                throw new UserError(`Missing value for ${JSON.stringify(argument)}.`);
+            }
+            assignOptionValue(options, argument, value);
+            index += 1;
+            continue;
+        }
+        if (argument.startsWith("--input=")) {
+            assignOptionValue(options, "--input", argument.slice("--input=".length));
+            continue;
+        }
+        if (argument.startsWith("--output=")) {
+            assignOptionValue(options, "--output", argument.slice("--output=".length));
+            continue;
+        }
+        if (argument.startsWith("--lock=")) {
+            assignOptionValue(options, "--lock", argument.slice("--lock=".length));
+            continue;
+        }
+        throw new UserError(`Unknown argument ${JSON.stringify(argument)}.`);
+    }
+    return options;
+}
+function assignOptionValue(options, argument, value) {
+    if (value.length === 0) {
+        throw new UserError(`Missing value for ${JSON.stringify(argument)}.`);
+    }
+    if (argument === "--input") {
+        options.input = value;
+        return;
+    }
+    if (argument === "--output") {
+        options.outputDir = value;
+        return;
+    }
+    options.lockPath = value;
+}
+function createSpecSha(sourceText) {
+    return `sha256:${createHash("sha256").update(sourceText).digest("hex")}`;
+}
+function createDownloadedSpecFiles(input, sourceText) {
+    const inputUrl = tryParseUrl(input);
+    if (inputUrl === null || (inputUrl.protocol !== "http:" && inputUrl.protocol !== "https:")) {
+        return [];
+    }
+    return [
+        {
+            path: getDownloadedSpecFileName(inputUrl),
+            contents: sourceText
+        }
+    ];
+}
+function getDownloadedSpecFileName(inputUrl) {
+    const basename = path.posix.basename(inputUrl.pathname);
+    return basename.length > 0 ? basename : "openapi.json";
+}
+function tryParseUrl(input) {
+    if (input instanceof URL) {
+        return input;
+    }
+    try {
+        return new URL(input);
+    }
+    catch {
+        return null;
+    }
+}
+async function readGeneratedFiles(fs, directoryPath) {
+    const files = new Map();
+    try {
+        const entries = await fs.readdir(directoryPath);
+        for (const entry of entries) {
+            const entryPath = path.resolve(directoryPath, entry);
+            const stats = await fs.stat(entryPath);
+            if (stats.isDirectory()) {
+                for (const [nestedPath, nestedContents] of await readGeneratedFiles(fs, entryPath)) {
+                    files.set(nestedPath, nestedContents);
+                }
+                continue;
+            }
+            files.set(entryPath, await fs.readFile(entryPath, "utf8"));
+        }
+    }
+    catch (error) {
+        if (!isNotFoundError(error)) {
+            throw error;
+        }
+    }
+    return files;
+}
+function collectUpdatedFiles(currentFiles, desiredFiles) {
+    const updatedFiles = [];
+    for (const [filePath, contents] of desiredFiles) {
+        if (currentFiles.get(filePath) === contents) {
+            continue;
+        }
+        updatedFiles.push({ path: filePath, contents });
+    }
+    return updatedFiles;
+}
+function collectDeletedFiles(currentFiles, desiredFiles) {
+    const deletedFiles = [];
+    for (const filePath of currentFiles.keys()) {
+        if (desiredFiles.has(filePath)) {
+            continue;
+        }
+        deletedFiles.push(filePath);
+    }
+    return deletedFiles;
+}
+async function writeGeneratedFiles(fs, filesToWrite) {
+    for (const file of filesToWrite) {
+        await fs.mkdir(path.dirname(file.path), { recursive: true });
+        await fs.writeFile(file.path, file.contents, "utf8");
+    }
+}
+async function deleteGeneratedFiles(fs, filePaths) {
+    for (const filePath of filePaths) {
+        await fs.rm(filePath, { force: true });
+    }
+}
+function isNotFoundError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function isDirectExecution(moduleUrl, argv) {
+    const entryPoint = argv[1];
+    if (entryPoint === undefined) {
+        return false;
+    }
+    try {
+        return path.resolve(fileURLToPath(moduleUrl)) === realpathSync(path.resolve(entryPoint));
+    }
+    catch {
+        return false;
+    }
+}
+if (isDirectExecution(import.meta.url, process.argv)) {
+    const exitCode = await runGenerateCli();
+    if (exitCode !== 0) {
+        process.exit(exitCode);
+    }
+}

package/dist/define-client.d.ts

@@ -0,0 +1,20 @@
+import type { CommandNode, Group } from "agent-kit";
+import type { AuthProvider, TokenSource } from "./auth/types.js";
+export interface OpenApiClientServices {
+    baseUrl: string;
+    tokenSource: TokenSource;
+}
+export interface DefineClientOptions<TServices extends object = Record<string, never>> {
+    name: string;
+    baseUrl: string;
+    auth: AuthProvider;
+    commands: CommandNode<OpenApiClientServices & TServices>[];
+    handwrittenCommands?: CommandNode<OpenApiClientServices & TServices>[];
+}
+export interface DefinedClient<TServices extends object = Record<string, never>> {
+    name: string;
+    mcpPrefix: string;
+    root: Group<OpenApiClientServices & TServices>;
+    services: OpenApiClientServices;
+}
+export declare function defineClient<TServices extends object = Record<string, never>>(options: DefineClientOptions<TServices>): DefinedClient<TServices>;