@meistrari/tela-cli 0.7.58 → 0.8.0

package/dist/commands/ingredients.js

@@ -0,0 +1,824 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTelactlCommand = runTelactlCommand;
+exports.runIngredientEnvCommand = runIngredientEnvCommand;
+exports.fetchIngredientCatalog = fetchIngredientCatalog;
+exports.joinUrl = joinUrl;
+exports.parseHttpieArg = parseHttpieArg;
+exports.extractGitHubFilePath = extractGitHubFilePath;
+exports.resolveGuidePath = resolveGuidePath;
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const tela_local_config_1 = require("@meistrari/tela-local-config");
+const credentials_1 = require("../credentials");
+const output_1 = require("../output");
+const PANTRY_BASE_URL = 'https://pantry-api.tela.tools';
+const INGREDIENT_PAGE_LIMIT = 100;
+const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+const FALLBACK_ENVIRONMENT_ORDER = ['tooling', 'production', 'staging', 'development'];
+const PANTRY_INGREDIENT = {
+    slug: 'pantry',
+    name: 'Pantry',
+    description: 'Ingredient registry and API catalog',
+    type: 'api',
+    status: 'active',
+    environments: [{ slug: 'production', url: PANTRY_BASE_URL }],
+};
+async function runTelactlCommand(command, args, options, io) {
+    try {
+        if (command === 'update')
+            return await updateIngredients(args, options, io);
+        if (command === 'api')
+            return await callIngredientApi(args, options, io);
+        if (command === 'docs')
+            return await runDocsCommand(args, options, io);
+        if (command === 'whoami')
+            return await whoami(args, options, io);
+        if (command === 'token')
+            return await tokenAlias(args, options, io);
+        (0, output_1.writeError)(io, `Unknown telactl command: ${command}`);
+        return 1;
+    }
+    catch (error) {
+        (0, output_1.writeError)(io, error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+async function runIngredientEnvCommand(args, options, io) {
+    const [action, ...rest] = args;
+    if (action === 'set')
+        return await setIngredientEnvironment(rest, io);
+    if (action === 'list' && rest.some(arg => !arg.startsWith('-')))
+        return await listIngredientEnvironments(rest, options, io);
+    return null;
+}
+async function updateIngredients(args, options, io) {
+    const flags = parseCommonFlags(args);
+    if ('error' in flags)
+        return usageError(flags.error, io);
+    if (flags.rest.length > 0)
+        return usageError(`Unknown update argument: ${flags.rest[0]}`, io);
+    const session = await loadSession(flags.contextId);
+    const cache = {
+        updatedAt: new Date().toISOString(),
+        ingredients: await fetchIngredientCatalog(requestHeaders(session.credential)),
+    };
+    await writeCache(cache);
+    if (options.json) {
+        (0, output_1.writeJson)(io, {
+            cache: {
+                updatedAt: cache.updatedAt,
+                ingredientCount: cache.ingredients.length,
+                contextId: session.resolved.id,
+                refreshed: session.refreshed,
+            },
+        });
+        return 0;
+    }
+    (0, output_1.writeLine)(io, `Cached ${cache.ingredients.length} ingredients`);
+    return 0;
+}
+async function callIngredientApi(args, _options, io) {
+    const flags = parseApiFlags(args);
+    if ('error' in flags)
+        return usageError(flags.error, io);
+    const [slug, method, routePath, ...httpieArgs] = flags.rest;
+    if (!slug || !method || !routePath) {
+        return usageError('Usage: tela api <slug> <METHOD> <PATH> [args...] [--env <slug>] [--body <json>] [-p|--pretty]', io);
+    }
+    if (!HTTP_METHODS.has(method.toUpperCase()))
+        return usageError(`Unsupported HTTP method: ${method}`, io);
+    const ingredient = requireIngredient(slug, 'api');
+    const environment = resolveIngredientEnvironment(ingredient, flags.env);
+    if (!environment) {
+        return usageError(`Ingredient '${slug}' has no environments configured. Run \`tela update\` after Pantry is updated.`, io);
+    }
+    const headers = new Headers();
+    const queryParams = [];
+    const fields = {};
+    let hasFields = false;
+    for (const arg of httpieArgs) {
+        const parsed = parseHttpieArg(arg);
+        if (!parsed)
+            return usageError(`Invalid argument '${arg}'. Use Key:Value, name=value, name==value, or name:=rawJson.`, io);
+        if (parsed.kind === 'query') {
+            queryParams.push([parsed.key, parsed.value]);
+            continue;
+        }
+        if (parsed.kind === 'header') {
+            headers.set(parsed.key.trim(), parsed.value.trim());
+            continue;
+        }
+        if (parsed.kind === 'field') {
+            fields[parsed.key] = parsed.value;
+            hasFields = true;
+            continue;
+        }
+        try {
+            fields[parsed.key] = JSON.parse(parsed.value);
+        }
+        catch {
+            return usageError(`Invalid JSON for raw field '${parsed.key}': ${parsed.value}`, io);
+        }
+        hasFields = true;
+    }
+    const url = new URL(joinUrl(environment.url, routePath));
+    for (const [key, value] of queryParams)
+        url.searchParams.append(key, value);
+    const session = await loadSession(flags.contextId);
+    for (const [key, value] of Object.entries(requestHeaders(session.credential))) {
+        if (!headers.has(key))
+            headers.set(key, value);
+    }
+    if (!headers.has('Accept'))
+        headers.set('Accept', 'application/json');
+    let requestBody;
+    if (flags.body !== undefined) {
+        requestBody = flags.body;
+    }
+    else if (hasFields) {
+        requestBody = JSON.stringify(fields);
+    }
+    if (requestBody !== undefined && !headers.has('Content-Type'))
+        headers.set('Content-Type', 'application/json');
+    const response = await fetch(url, {
+        method: method.toUpperCase(),
+        headers,
+        body: requestBody,
+    });
+    const text = await response.text();
+    assertHttpOk(response, text);
+    if (flags.pretty) {
+        const parsed = tryParseJson(text);
+        if (parsed !== null) {
+            (0, output_1.writeJson)(io, parsed);
+            return 0;
+        }
+    }
+    (0, output_1.writeLine)(io, text);
+    return 0;
+}
+async function runDocsCommand(args, options, io) {
+    const [action, ...rest] = args;
+    if (!action || action === 'help' || action === '--help' || action === '-h') {
+        writeDocsHelp(io);
+        return 0;
+    }
+    if (action === 'endpoints')
+        return await docsEndpoints(rest, options, io);
+    if (action === 'reference')
+        return await docsReference(rest, options, io);
+    if (action === 'guide')
+        return await docsGuide(rest, options, io);
+    return usageError(`Unknown docs command: ${action}`, io);
+}
+async function docsEndpoints(args, options, io) {
+    const flags = parseCommonFlags(args);
+    if ('error' in flags)
+        return usageError(flags.error, io);
+    const [slug] = flags.rest;
+    if (!slug)
+        return usageError('Usage: tela docs endpoints <slug> [-p|--pretty]', io);
+    requireIngredient(slug, 'api');
+    const spec = await fetchOpenApiSpec(slug, flags.contextId);
+    const paths = (isRecord(spec.paths) ? spec.paths : {});
+    if (flags.pretty && !options.json) {
+        (0, output_1.writeLine)(io, formatEndpointsTable(paths));
+        return 0;
+    }
+    (0, output_1.writeJson)(io, paths);
+    return 0;
+}
+async function docsReference(args, options, io) {
+    const flags = parseCommonFlags(args);
+    if ('error' in flags)
+        return usageError(flags.error, io);
+    const [slug, first, second] = flags.rest;
+    if (!slug)
+        return usageError('Usage: tela docs reference <slug> [METHOD PATH|file-path] [-p|--pretty]', io);
+    const ingredient = requireIngredient(slug);
+    if (ingredient.type === 'api') {
+        if (first && !second && HTTP_METHODS.has(first.toUpperCase())) {
+            return usageError('Both METHOD and PATH are required to show a specific endpoint', io);
+        }
+        const spec = await fetchOpenApiSpec(slug, flags.contextId);
+        if (first && second) {
+            if (!HTTP_METHODS.has(first.toUpperCase()))
+                return usageError(`Unsupported HTTP method: ${first}`, io);
+            const pathEntry = isRecord(spec.paths) && isRecord(spec.paths[second]) ? spec.paths[second] : null;
+            if (!pathEntry)
+                return usageError(`Path not found: ${second}`, io);
+            const op = pathEntry[first.toLowerCase()];
+            if (!op)
+                return usageError(`Method ${first.toUpperCase()} not found for ${second}`, io);
+            if (flags.pretty && !options.json) {
+                (0, output_1.writeLine)(io, formatEndpoint(spec, op, first, second));
+                return 0;
+            }
+            (0, output_1.writeJson)(io, op);
+            return 0;
+        }
+        if (flags.pretty && !options.json) {
+            (0, output_1.writeJson)(io, spec);
+            return 0;
+        }
+        (0, output_1.writeLine)(io, JSON.stringify(spec));
+        return 0;
+    }
+    if (ingredient.type !== 'library')
+        return usageError(`Ingredient '${slug}' is not an API or library ingredient.`, io);
+    const ingredientBody = await fetchIngredient(slug, flags.contextId);
+    const apiRef = isRecord(ingredientBody.docs) ? stringValue(ingredientBody.docs.api) : '';
+    if (!apiRef)
+        return usageError(`Library ${slug} has no API reference`, io);
+    const filePath = extractGitHubFilePath(apiRef);
+    if (!filePath)
+        return usageError(`Could not extract file path from API reference URL: ${apiRef}`, io);
+    const slashIndex = filePath.lastIndexOf('/');
+    const dir = slashIndex === -1 ? '' : filePath.slice(0, slashIndex + 1);
+    const relativePath = first ? first.replace(/^\/+/, '') : 'globals.md';
+    const guide = await fetchGuide(slug, `${dir}${relativePath}`, flags.contextId);
+    (0, output_1.writeLine)(io, stringValue(guide.content));
+    return 0;
+}
+async function docsGuide(args, _options, io) {
+    const flags = parseCommonFlags(args);
+    if ('error' in flags)
+        return usageError(flags.error, io);
+    const [slug, providedPath] = flags.rest;
+    if (!slug)
+        return usageError('Usage: tela docs guide <slug> [path] [-p|--pretty]', io);
+    const ingredient = requireIngredient(slug);
+    if (ingredient.type !== 'api' && ingredient.type !== 'library') {
+        return usageError(`Ingredient '${slug}' is not an API or library ingredient.`, io);
+    }
+    const ingredientBody = await fetchIngredient(slug, flags.contextId);
+    const guidesRef = isRecord(ingredientBody.docs) ? stringValue(ingredientBody.docs.guides) : '';
+    if (!guidesRef)
+        return usageError(`Ingredient ${slug} has no guide`, io);
+    const filePath = extractGitHubFilePath(guidesRef);
+    if (!filePath)
+        return usageError(`Could not extract file path from guide URL: ${guidesRef}`, io);
+    const guide = await fetchGuide(slug, resolveGuidePath(filePath, providedPath), flags.contextId);
+    (0, output_1.writeLine)(io, stringValue(guide.content));
+    return 0;
+}
+async function listIngredientEnvironments(args, options, io) {
+    const flags = parseCommonFlags(args);
+    if ('error' in flags)
+        return usageError(flags.error, io);
+    const [slug] = flags.rest;
+    if (!slug)
+        return usageError('Usage: tela env list <ingredient-slug> [-p|--pretty|--json]', io);
+    const ingredient = requireIngredient(slug);
+    const environments = ingredient.environments ?? [];
+    if (options.json || !flags.pretty) {
+        (0, output_1.writeJson)(io, { environments });
+        return 0;
+    }
+    if (environments.length === 0) {
+        (0, output_1.writeLine)(io, '(no environments configured)');
+        return 0;
+    }
+    const slugWidth = Math.max(...environments.map(environment => environment.slug.length));
+    for (const environment of environments) {
+        (0, output_1.writeLine)(io, `${environment.slug.padEnd(slugWidth)}  ${environment.url}`);
+    }
+    return 0;
+}
+async function setIngredientEnvironment(args, io) {
+    const [slug, environment] = args;
+    if (!slug || !environment)
+        return usageError('Usage: tela env set <ingredient-slug> <environment>', io);
+    const ingredient = requireIngredient(slug);
+    if (!ingredient.environments.some(candidate => candidate.slug === environment)) {
+        const available = ingredient.environments.map(candidate => candidate.slug).join(', ') || '(none)';
+        return usageError(`Environment '${environment}' not found for '${slug}'. Available: ${available}`, io);
+    }
+    const defaults = await readEnvironmentDefaults();
+    defaults[slug] = environment;
+    await writeEnvironmentDefaults(defaults);
+    (0, output_1.writeLine)(io, `Set default environment for '${slug}' to '${environment}'`);
+    return 0;
+}
+async function whoami(args, _options, io) {
+    const flags = parseCommonFlags(args);
+    if ('error' in flags)
+        return usageError(flags.error, io);
+    if (flags.rest.length > 0)
+        return usageError(`Unknown whoami argument: ${flags.rest[0]}`, io);
+    const session = await loadSession(flags.contextId);
+    if (!session.credential.accessToken) {
+        return usageError(`Context ${session.resolved.id} does not have an access token credential.`, io);
+    }
+    const response = await fetch(new URL('/api/auth/applications/whoami', session.resolved.environment.authApiUrl), {
+        headers: {
+            'Accept': 'application/json',
+            'x-tela-access-token': session.credential.accessToken,
+        },
+    });
+    const text = await response.text();
+    assertHttpOk(response, text);
+    if (flags.pretty) {
+        const parsed = tryParseJson(text);
+        if (parsed !== null) {
+            (0, output_1.writeJson)(io, parsed);
+            return 0;
+        }
+    }
+    (0, output_1.writeLine)(io, text);
+    return 0;
+}
+async function tokenAlias(args, _options, io) {
+    const flags = parseCommonFlags(args);
+    if ('error' in flags)
+        return usageError(flags.error, io);
+    if (flags.rest.length > 0)
+        return usageError(`Unknown token argument: ${flags.rest[0]}`, io);
+    const session = await loadSession(flags.contextId);
+    if (!session.credential.accessToken)
+        return usageError(`Context ${session.resolved.id} does not have an access token credential.`, io);
+    (0, output_1.writeLine)(io, session.credential.accessToken);
+    return 0;
+}
+async function fetchOpenApiSpec(slug, contextId) {
+    const session = await loadSession(contextId);
+    const response = await fetch(getPantryOpenapiUrl(slug), {
+        headers: requestHeaders(session.credential),
+    });
+    const text = await response.text();
+    assertHttpOk(response, text, 'Failed to fetch OpenAPI spec');
+    const parsed = JSON.parse(text);
+    if (!isRecord(parsed))
+        throw new Error('OpenAPI response was not a JSON object');
+    return parsed;
+}
+async function fetchIngredient(slug, contextId) {
+    const session = await loadSession(contextId);
+    const response = await fetch(getPantryIngredientUrl(slug), {
+        headers: requestHeaders(session.credential),
+    });
+    const text = await response.text();
+    assertHttpOk(response, text, 'Failed to fetch ingredient');
+    const parsed = JSON.parse(text);
+    if (!isRecord(parsed))
+        throw new Error('Ingredient response was not a JSON object');
+    return parsed;
+}
+async function fetchGuide(slug, filePath, contextId) {
+    const session = await loadSession(contextId);
+    const response = await fetch(getPantryGuideUrl(slug, filePath), {
+        headers: requestHeaders(session.credential),
+    });
+    const text = await response.text();
+    assertHttpOk(response, text, 'Failed to fetch guide');
+    const parsed = JSON.parse(text);
+    if (!isRecord(parsed))
+        throw new Error('Guide response was not a JSON object');
+    return parsed;
+}
+async function loadSession(contextId) {
+    const config = await (0, tela_local_config_1.loadConfig)();
+    const resolved = (0, tela_local_config_1.resolveContext)(config, { contextId });
+    const credentials = (0, credentials_1.createCliCredentialAdapter)();
+    const credentialRef = resolved.context.credentialRef;
+    const originalCredential = await credentials.get(credentialRef);
+    if (!originalCredential)
+        throw new Error(`Missing credential for Tela context ${resolved.id}`);
+    const credential = originalCredential.kind === 'user-session'
+        ? await (0, tela_local_config_1.refreshUserSessionCredential)(resolved.environment, credentialRef, originalCredential, credentials)
+        : originalCredential;
+    return {
+        resolved,
+        credentialRef,
+        credential,
+        refreshed: credential !== originalCredential,
+    };
+}
+function requestHeaders(credential) {
+    if (credential.kind === 'data-token' && credential.dataToken) {
+        return {
+            'Accept': 'application/json',
+            'x-data-token': credential.dataToken,
+        };
+    }
+    if (credential.accessToken) {
+        return {
+            Accept: 'application/json',
+            Authorization: `Bearer ${credential.accessToken}`,
+        };
+    }
+    throw new Error(`Credential ${credential.kind} does not contain usable token material`);
+}
+function requireIngredient(slug, type) {
+    const ingredient = readModules().find(candidate => candidate.slug === slug);
+    if (!ingredient)
+        throw new Error(`Ingredient '${slug}' not found. Run \`tela update\` first.`);
+    if (type && ingredient.type !== type)
+        throw new Error(`Ingredient '${slug}' is not a ${type} ingredient.`);
+    return ingredient;
+}
+async function fetchIngredientCatalog(headers, fetchImpl = fetch) {
+    const ingredients = [];
+    let total = null;
+    for (let offset = 0;; offset += INGREDIENT_PAGE_LIMIT) {
+        const url = new URL('/ingredients', PANTRY_BASE_URL);
+        url.searchParams.set('limit', String(INGREDIENT_PAGE_LIMIT));
+        url.searchParams.set('offset', String(offset));
+        const response = await fetchImpl(url.toString(), { headers });
+        const text = await response.text();
+        assertHttpOk(response, text, 'Failed to fetch ingredients');
+        const data = JSON.parse(text);
+        const rawPageIngredients = data.ingredients ?? [];
+        const pageIngredients = rawPageIngredients.map(normalizeCachedIngredient).filter(ingredient => ingredient.slug);
+        ingredients.push(...pageIngredients);
+        total = typeof data.total === 'number' ? data.total : total;
+        if (total !== null && ingredients.length >= total)
+            break;
+        if (rawPageIngredients.length < INGREDIENT_PAGE_LIMIT)
+            break;
+    }
+    return ingredients;
+}
+function normalizeCachedIngredient(ingredient) {
+    return {
+        slug: stringValue(ingredient.slug),
+        name: stringValue(ingredient.name),
+        description: stringValue(ingredient.description),
+        type: normalizeIngredientType(ingredient.type),
+        status: stringValue(ingredient.status),
+        environments: (ingredient.environments ?? []).map(environment => ({
+            slug: environment.slug,
+            url: environment.url,
+        })).filter(environment => environment.slug && environment.url),
+    };
+}
+function readModules() {
+    const cache = readCache();
+    const ingredients = cache?.ingredients ?? [];
+    return ingredients.some(ingredient => ingredient.slug === PANTRY_INGREDIENT.slug)
+        ? ingredients
+        : [...ingredients, PANTRY_INGREDIENT];
+}
+function readCache() {
+    try {
+        const text = (0, node_fs_1.readFileSync)(cachePath(), 'utf8');
+        const parsed = JSON.parse(text);
+        if (!Array.isArray(parsed.ingredients))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeCache(cache) {
+    const filePath = cachePath();
+    await (0, promises_1.mkdir)((0, node_path_1.dirname)(filePath), { recursive: true });
+    await (0, promises_1.writeFile)(filePath, `${JSON.stringify(cache, null, 2)}\n`, 'utf8');
+}
+function cachePath() {
+    return (0, node_path_1.join)((0, tela_local_config_1.getTelaLocalPaths)().rootDir, 'ingredients.json');
+}
+async function readEnvironmentDefaults() {
+    try {
+        return JSON.parse(await (0, promises_1.readFile)(environmentDefaultsPath(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+async function writeEnvironmentDefaults(defaults) {
+    const filePath = environmentDefaultsPath();
+    await (0, promises_1.mkdir)((0, node_path_1.dirname)(filePath), { recursive: true });
+    await (0, promises_1.writeFile)(filePath, `${JSON.stringify(defaults, null, 2)}\n`, 'utf8');
+}
+function environmentDefaultsPath() {
+    return (0, node_path_1.join)((0, tela_local_config_1.getTelaLocalPaths)().rootDir, 'ingredient-environments.json');
+}
+function resolveIngredientEnvironment(ingredient, override) {
+    const environments = ingredient.environments ?? [];
+    if (override) {
+        const found = environments.find(environment => environment.slug === override);
+        if (!found) {
+            const available = environments.map(environment => environment.slug).join(', ') || '(none)';
+            throw new Error(`Environment '${override}' not found for ingredient '${ingredient.slug}'. Available: ${available}`);
+        }
+        return found;
+    }
+    if (environments.length === 0)
+        return null;
+    if (environments.length === 1)
+        return environments[0] ?? null;
+    const defaults = readEnvironmentDefaultsSync();
+    const saved = defaults[ingredient.slug];
+    if (saved) {
+        const found = environments.find(environment => environment.slug === saved);
+        if (found)
+            return found;
+    }
+    for (const preferred of FALLBACK_ENVIRONMENT_ORDER) {
+        const found = environments.find(environment => environment.slug === preferred);
+        if (found)
+            return found;
+    }
+    const available = environments.map(environment => environment.slug).join(', ');
+    throw new Error(`Multiple environments configured for '${ingredient.slug}' and no default matches.\n`
+        + `Available: ${available}\n`
+        + `Use --env <slug> to pick one, or run \`tela env set ${ingredient.slug} <environment>\` to save a default.`);
+}
+function readEnvironmentDefaultsSync() {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(environmentDefaultsPath(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function parseCommonFlags(args) {
+    const flags = {
+        pretty: false,
+        rest: [],
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === undefined)
+            continue;
+        if (arg === '--context') {
+            const value = args[index + 1];
+            if (!value)
+                return { error: 'Expected value after --context' };
+            flags.contextId = value;
+            index += 1;
+            continue;
+        }
+        if (arg === '--pretty' || arg === '-p') {
+            flags.pretty = true;
+            continue;
+        }
+        flags.rest.push(arg);
+    }
+    return flags;
+}
+function parseApiFlags(args) {
+    const flags = {
+        pretty: false,
+        rest: [],
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === undefined)
+            continue;
+        if (arg === '--context') {
+            const value = args[index + 1];
+            if (!value)
+                return { error: 'Expected value after --context' };
+            flags.contextId = value;
+            index += 1;
+            continue;
+        }
+        if (arg === '--env') {
+            const value = args[index + 1];
+            if (!value)
+                return { error: 'Expected value after --env' };
+            flags.env = value;
+            index += 1;
+            continue;
+        }
+        if (arg === '--body') {
+            const value = args[index + 1];
+            if (value === undefined)
+                return { error: 'Expected value after --body' };
+            flags.body = value;
+            index += 1;
+            continue;
+        }
+        if (arg === '--pretty' || arg === '-p') {
+            flags.pretty = true;
+            continue;
+        }
+        flags.rest.push(arg);
+    }
+    return flags;
+}
+function joinUrl(base, routePath) {
+    const trimmedBase = base.replace(/\/$/, '');
+    const prefixedPath = routePath.startsWith('/') ? routePath : `/${routePath}`;
+    return `${trimmedBase}${prefixedPath}`;
+}
+function parseHttpieArg(arg) {
+    for (let index = 0; index < arg.length; index += 1) {
+        const two = arg.slice(index, index + 2);
+        if (two === '==')
+            return { kind: 'query', key: arg.slice(0, index), value: arg.slice(index + 2) };
+        if (two === ':=')
+            return { kind: 'rawField', key: arg.slice(0, index), value: arg.slice(index + 2) };
+        if (arg[index] === ':')
+            return { kind: 'header', key: arg.slice(0, index), value: arg.slice(index + 1) };
+        if (arg[index] === '=')
+            return { kind: 'field', key: arg.slice(0, index), value: arg.slice(index + 1) };
+    }
+    return null;
+}
+function getPantryOpenapiUrl(slug) {
+    return slug === 'pantry' ? `${PANTRY_BASE_URL}/openapi` : `${PANTRY_BASE_URL}/ingredients/${slug}/openapi`;
+}
+function getPantryIngredientUrl(slug) {
+    return `${PANTRY_BASE_URL}/ingredients/${slug}`;
+}
+function getPantryGuideUrl(slug, filePath) {
+    const base = `${PANTRY_BASE_URL}/ingredients/${slug}/guide`;
+    if (!filePath)
+        return base;
+    const params = new URLSearchParams({ path: filePath });
+    return `${base}?${params.toString()}`;
+}
+function formatEndpointsTable(paths) {
+    const lines = [];
+    for (const [routePath, methods] of Object.entries(paths)) {
+        for (const [method, op] of Object.entries(methods)) {
+            if (method.startsWith('x-'))
+                continue;
+            const summary = op.summary ?? op.operationId ?? '';
+            lines.push(`${method.toUpperCase().padEnd(7)} ${routePath}  ${summary}`);
+        }
+    }
+    return lines.join('\n');
+}
+function formatEndpoint(spec, op, method, routePath) {
+    if (!isRecord(op))
+        return '';
+    const lines = [`${method.toUpperCase()} ${routePath}`];
+    if (typeof op.summary === 'string')
+        lines.push(`\n${op.summary}`);
+    if (typeof op.description === 'string' && op.description !== op.summary)
+        lines.push(op.description);
+    const parameters = Array.isArray(op.parameters) ? op.parameters : [];
+    if (parameters.length > 0) {
+        lines.push('\n## Parameters\n');
+        for (const parameter of parameters) {
+            const resolved = isRecord(parameter) && typeof parameter.$ref === 'string' ? resolveRef(spec, parameter.$ref) : parameter;
+            if (!isRecord(resolved))
+                continue;
+            const required = resolved.required ? ' (required)' : '';
+            const description = typeof resolved.description === 'string' ? ` - ${resolved.description}` : '';
+            const schema = isRecord(resolved.schema) ? resolved.schema : {};
+            const type = typeof schema.type === 'string' ? schema.type : '';
+            lines.push(`  ${stringValue(resolved.in)}  ${stringValue(resolved.name)}: ${type}${required}${description}`);
+        }
+    }
+    if (isRecord(op.requestBody)) {
+        lines.push('\n## Request Body\n');
+        const content = isRecord(op.requestBody.content) ? op.requestBody.content : {};
+        for (const [contentType, media] of Object.entries(content)) {
+            if (!isRecord(media))
+                continue;
+            lines.push(`  Content-Type: ${contentType}`);
+            const schema = resolveSchema(spec, media.schema);
+            if (schema)
+                lines.push(formatSchema(schema, 1));
+        }
+    }
+    if (isRecord(op.responses)) {
+        lines.push('\n## Responses\n');
+        for (const [status, response] of Object.entries(op.responses)) {
+            const resolved = isRecord(response) && typeof response.$ref === 'string' ? resolveRef(spec, response.$ref) : response;
+            if (!isRecord(resolved))
+                continue;
+            lines.push(`  ${status}: ${stringValue(resolved.description)}`);
+            const content = isRecord(resolved.content) ? resolved.content : {};
+            for (const media of Object.values(content)) {
+                if (!isRecord(media))
+                    continue;
+                const schema = resolveSchema(spec, media.schema);
+                if (schema)
+                    lines.push(formatSchema(schema, 2));
+            }
+        }
+    }
+    return lines.join('\n');
+}
+function resolveRef(spec, ref) {
+    const parts = ref.replace('#/', '').split('/');
+    let current = spec;
+    for (const part of parts) {
+        current = isRecord(current) ? current[part] : undefined;
+    }
+    return current;
+}
+function resolveSchema(spec, schema) {
+    if (!isRecord(schema))
+        return null;
+    if (typeof schema.$ref === 'string')
+        return resolveSchema(spec, resolveRef(spec, schema.$ref));
+    if (schema.items)
+        return { ...schema, items: resolveSchema(spec, schema.items) };
+    if (isRecord(schema.properties)) {
+        const resolved = {};
+        for (const [key, value] of Object.entries(schema.properties)) {
+            resolved[key] = resolveSchema(spec, value) ?? value;
+        }
+        return { ...schema, properties: resolved };
+    }
+    return schema;
+}
+function formatSchema(schema, indent = 0) {
+    if (!schema)
+        return '';
+    const pad = '  '.repeat(indent);
+    if (schema.type === 'object' && isRecord(schema.properties)) {
+        const requiredFields = Array.isArray(schema.required) ? schema.required.filter(item => typeof item === 'string') : [];
+        return Object.entries(schema.properties).map(([key, prop]) => {
+            if (!isRecord(prop))
+                return `${pad}${key}: unknown`;
+            const required = requiredFields.includes(key) ? '' : '?';
+            const type = typeof prop.type === 'string' ? prop.type : 'object';
+            const description = typeof prop.description === 'string' ? ` - ${prop.description}` : '';
+            if (prop.type === 'object' && isRecord(prop.properties)) {
+                return `${pad}${key}${required}: {${description}\n${formatSchema(prop, indent + 1)}\n${pad}}`;
+            }
+            if (prop.type === 'array' && isRecord(prop.items)) {
+                const itemType = typeof prop.items.type === 'string' ? prop.items.type : 'object';
+                return `${pad}${key}${required}: ${itemType}[]${description}`;
+            }
+            return `${pad}${key}${required}: ${type}${description}`;
+        }).join('\n');
+    }
+    return `${pad}${typeof schema.type === 'string' ? schema.type : 'unknown'}`;
+}
+function extractGitHubFilePath(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    const parts = parsed.pathname
+        .replace(/^\/+|\/+$/g, '')
+        .split('/')
+        .filter(Boolean)
+        .map(part => decodeURIComponent(part));
+    if (parsed.hostname === 'github.com') {
+        const [owner, repo, scope, ref, ...filePathParts] = parts;
+        if (!owner || !repo || scope !== 'blob' || !ref || filePathParts.length === 0)
+            return null;
+        return filePathParts.join('/');
+    }
+    if (parsed.hostname === 'raw.githubusercontent.com') {
+        const [owner, repo, firstRefPart, ...rest] = parts;
+        if (!owner || !repo || !firstRefPart)
+            return null;
+        if (firstRefPart === 'refs') {
+            const [, , ...filePathParts] = rest;
+            return filePathParts.length > 0 ? filePathParts.join('/') : null;
+        }
+        return rest.length > 0 ? rest.join('/') : null;
+    }
+    return null;
+}
+function resolveGuidePath(rootFilePath, providedPath) {
+    const slashIndex = rootFilePath.lastIndexOf('/');
+    const dir = slashIndex === -1 ? '' : rootFilePath.slice(0, slashIndex + 1);
+    const basename = slashIndex === -1 ? rootFilePath : rootFilePath.slice(slashIndex + 1);
+    const relativePath = providedPath ? providedPath.replace(/^\/+/, '') : basename;
+    return `${dir}${relativePath}`;
+}
+function assertHttpOk(response, bodyText, context) {
+    if (response.ok)
+        return;
+    const prefix = context ? `${context}: ` : '';
+    throw new Error(`${prefix}${response.status} ${response.statusText}${bodyText ? `\n${bodyText}` : ''}`);
+}
+function usageError(message, io) {
+    (0, output_1.writeError)(io, message);
+    return 1;
+}
+function writeDocsHelp(io) {
+    (0, output_1.writeLine)(io, 'Usage: tela docs <command> [args]');
+    (0, output_1.writeLine)(io);
+    (0, output_1.writeLine)(io, 'Commands:');
+    (0, output_1.writeLine)(io, '  docs endpoints <slug> [-p|--pretty] [--json]');
+    (0, output_1.writeLine)(io, '  docs reference <slug> [METHOD PATH|file-path] [-p|--pretty] [--json]');
+    (0, output_1.writeLine)(io, '  docs guide <slug> [path] [-p|--pretty]');
+}
+function tryParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function stringValue(value) {
+    return typeof value === 'string' ? value : '';
+}
+function normalizeIngredientType(value) {
+    if (value === 'library' || value === 'skill')
+        return value;
+    return 'api';
+}