stageflow 0.1.0

package/dist/cli/providersCommand.js

@@ -0,0 +1,275 @@
+import { defaultContext, detectPiHome, getAuthStatus, getCredentialSourceSettings, listProviders, loginWithApiKey, loginWithOauth, logoutProvider, ProviderAuthError, setCredentialSource, } from "../agent/providerAuth.js";
+import { createTerminalAuthInteraction } from "./terminalAuthInteraction.js";
+import { promptSecret, readApiKeyFromEnv } from "./terminalSecret.js";
+export const PROVIDERS_USAGE = `Usage:
+  sf providers list
+  sf providers status [--provider <id>]
+  sf providers detect
+  sf providers source [get | set <pi_home|sf_owned>]
+  sf providers login <providerId> [--type api_key|oauth] [--api-key-env <VAR>]
+  sf providers logout <providerId>`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+    env: process.env,
+    readSecret: promptSecret,
+    createAuthInteraction: (signal) => createTerminalAuthInteraction({ signal }),
+};
+function scrub(message, secrets) {
+    let out = message;
+    for (const secret of secrets) {
+        if (secret.length === 0)
+            continue;
+        out = out.split(secret).join("[redacted]");
+    }
+    return out;
+}
+function formatStatus(status) {
+    const parts = [
+        status.providerId,
+        status.configured ? "configured" : "disconnected",
+    ];
+    if (status.authKind !== undefined)
+        parts.push(`kind=${status.authKind}`);
+    if (status.source !== undefined)
+        parts.push(`source=${status.source}`);
+    return parts.join("\t");
+}
+function formatProvider(p) {
+    const caps = [];
+    if (p.supportsApiKey)
+        caps.push("api_key");
+    if (p.supportsOauth)
+        caps.push("oauth");
+    const label = p.oauthLabel !== undefined && p.oauthLabel.length > 0
+        ? `\t${p.oauthLabel}`
+        : "";
+    return `${p.id}\t${p.name}\t${caps.join(",") || "none"}${label}`;
+}
+function parseProvidersArgs(args) {
+    if (args.length === 0) {
+        return { help: false, positionals: [] };
+    }
+    if (args[0] === "--help" || args[0] === "-h") {
+        return { help: true, positionals: [] };
+    }
+    const subcommand = args[0];
+    let providerFlag;
+    let type;
+    let apiKeyEnv;
+    let help = false;
+    const positionals = [];
+    for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--provider") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --provider");
+            }
+            providerFlag = value;
+        }
+        else if (arg === "--type") {
+            const value = args[++i];
+            if (value !== "api_key" && value !== "oauth") {
+                throw new Error("--type must be api_key or oauth");
+            }
+            type = value;
+        }
+        else if (arg === "--api-key-env") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --api-key-env");
+            }
+            apiKeyEnv = value;
+        }
+        else if (arg === "--api-key") {
+            throw new Error("Raw --api-key is not supported; use a prompt or --api-key-env <VAR>");
+        }
+        else if (arg.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    return { subcommand, help, providerFlag, type, apiKeyEnv, positionals };
+}
+function resolveLoginType(provider, type) {
+    if (provider.supportsApiKey && provider.supportsOauth) {
+        if (type === undefined) {
+            throw new Error("Provider supports both api_key and oauth; pass --type api_key|oauth");
+        }
+        return type;
+    }
+    if (type === "api_key") {
+        if (!provider.supportsApiKey) {
+            throw new Error("Provider does not support api_key login");
+        }
+        return "api_key";
+    }
+    if (type === "oauth") {
+        if (!provider.supportsOauth) {
+            throw new Error("Provider does not support oauth login");
+        }
+        return "oauth";
+    }
+    if (provider.supportsOauth)
+        return "oauth";
+    if (provider.supportsApiKey)
+        return "api_key";
+    throw new Error("Provider does not support interactive login");
+}
+export async function runProvidersCommand(args, cwd, io = {}, ctx = defaultContext) {
+    const out = { ...defaultIo, ...io };
+    let secrets = [];
+    try {
+        const parsed = parseProvidersArgs(args);
+        if (parsed.help || !parsed.subcommand) {
+            out.error(PROVIDERS_USAGE);
+            return parsed.help ? 0 : 1;
+        }
+        switch (parsed.subcommand) {
+            case "list": {
+                const listed = await listProviders(cwd, ctx);
+                for (const provider of listed.providers) {
+                    out.log(formatProvider(provider));
+                }
+                return 0;
+            }
+            case "status": {
+                try {
+                    const status = await getAuthStatus(cwd, parsed.providerFlag, ctx);
+                    if (Array.isArray(status)) {
+                        for (const row of status)
+                            out.log(formatStatus(row));
+                    }
+                    else {
+                        out.log(formatStatus(status));
+                    }
+                    return 0;
+                }
+                catch (err) {
+                    if (err instanceof ProviderAuthError && err.status === 404) {
+                        out.error("Provider not found");
+                        return 1;
+                    }
+                    throw err;
+                }
+            }
+            case "detect": {
+                const detected = detectPiHome(cwd);
+                const sourceLine = detected.credentialSource !== undefined
+                    ? `credentialSource=${detected.credentialSource}`
+                    : "credentialSource=(unset)";
+                out.log([
+                    `piHomeUsable=${detected.piHomeUsable}`,
+                    sourceLine,
+                    `provisional=${detected.provisional}`,
+                    `bindingSource=${detected.source}`,
+                ].join("\t"));
+                return 0;
+            }
+            case "source": {
+                const action = parsed.positionals[0] ?? "get";
+                if (action === "get") {
+                    const settings = getCredentialSourceSettings(cwd);
+                    if (settings.credentialSource !== undefined) {
+                        out.log(settings.credentialSource);
+                    }
+                    else {
+                        out.log(`(unset; binding=${settings.binding.source}${settings.binding.provisional ? ", provisional" : ""})`);
+                    }
+                    return 0;
+                }
+                if (action === "set") {
+                    const value = parsed.positionals[1];
+                    if (value !== "pi_home" && value !== "sf_owned") {
+                        out.error('source set requires pi_home or sf_owned');
+                        out.error(PROVIDERS_USAGE);
+                        return 1;
+                    }
+                    const result = setCredentialSource(cwd, value);
+                    out.log(result.credentialSource);
+                    return 0;
+                }
+                out.error(`Unknown source action: ${action}`);
+                out.error(PROVIDERS_USAGE);
+                return 1;
+            }
+            case "login": {
+                const providerId = parsed.positionals[0];
+                if (!providerId) {
+                    out.error("Missing providerId");
+                    out.error(PROVIDERS_USAGE);
+                    return 1;
+                }
+                const listed = await listProviders(cwd, ctx);
+                const provider = listed.providers.find((p) => p.id === providerId);
+                if (!provider) {
+                    out.error("Provider not found");
+                    return 1;
+                }
+                const loginType = resolveLoginType(provider, parsed.type);
+                if (loginType === "api_key") {
+                    let apiKey;
+                    if (parsed.apiKeyEnv !== undefined) {
+                        apiKey = readApiKeyFromEnv(out.env, parsed.apiKeyEnv);
+                    }
+                    else {
+                        apiKey = await out.readSecret(`API key for ${providerId}`);
+                    }
+                    secrets = [apiKey];
+                    if (apiKey.trim().length === 0) {
+                        out.error("API key is required");
+                        return 1;
+                    }
+                    const status = await loginWithApiKey(cwd, providerId, apiKey, ctx);
+                    out.log(formatStatus(status));
+                    return 0;
+                }
+                const abort = new AbortController();
+                const onSigInt = () => abort.abort();
+                process.once("SIGINT", onSigInt);
+                try {
+                    const interaction = out.createAuthInteraction(abort.signal);
+                    const result = await loginWithOauth(cwd, providerId, interaction, ctx);
+                    if (result.warning) {
+                        out.error(result.warning);
+                    }
+                    out.log(formatStatus(result.provider));
+                    return 0;
+                }
+                finally {
+                    process.removeListener("SIGINT", onSigInt);
+                }
+            }
+            case "logout": {
+                const providerId = parsed.positionals[0];
+                if (!providerId) {
+                    out.error("Missing providerId");
+                    out.error(PROVIDERS_USAGE);
+                    return 1;
+                }
+                const status = await logoutProvider(cwd, providerId, ctx);
+                out.log(formatStatus(status));
+                return 0;
+            }
+            default:
+                out.error(`Unknown providers subcommand: ${parsed.subcommand}`);
+                out.error(PROVIDERS_USAGE);
+                return 1;
+        }
+    }
+    catch (err) {
+        const raw = err instanceof Error
+            ? err.message
+            : typeof err === "string"
+                ? err
+                : "Provider command failed";
+        out.error(scrub(raw, secrets));
+        return 1;
+    }
+}

package/dist/cli/terminalAuthInteraction.d.ts

@@ -0,0 +1,8 @@
+import type { AuthInteraction } from "@earendil-works/pi-ai";
+export type TerminalAuthInteractionOptions = {
+    signal?: AbortSignal;
+    write?: (line: string) => void;
+    promptLine?: (message: string) => Promise<string>;
+    promptSecretLine?: (message: string) => Promise<string>;
+};
+export declare function createTerminalAuthInteraction(options?: TerminalAuthInteractionOptions): AuthInteraction;

package/dist/cli/terminalAuthInteraction.js

@@ -0,0 +1,65 @@
+import * as readline from "node:readline";
+import { promptSecret } from "./terminalSecret.js";
+function defaultPromptLine(message) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    return new Promise((resolve, reject) => {
+        rl.question(`${message}: `, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+        rl.on("close", () => {
+            // no-op; question callback handles resolve
+        });
+        rl.on("SIGINT", () => {
+            rl.close();
+            reject(new Error("Login cancelled"));
+        });
+    });
+}
+export function createTerminalAuthInteraction(options = {}) {
+    const write = options.write ?? ((line) => {
+        process.stderr.write(`${line}\n`);
+    });
+    const promptLine = options.promptLine ?? defaultPromptLine;
+    const promptSecretLine = options.promptSecretLine ?? promptSecret;
+    return {
+        signal: options.signal,
+        notify(event) {
+            if (event.type === "info" || event.type === "progress") {
+                write(event.message);
+                return;
+            }
+            if (event.type === "auth_url") {
+                if (event.instructions)
+                    write(event.instructions);
+                write(`Open: ${event.url}`);
+                return;
+            }
+            if (event.type === "device_code") {
+                write(`Visit: ${event.verificationUri}`);
+                write(`Code: ${event.userCode}`);
+            }
+        },
+        async prompt(prompt) {
+            if (options.signal?.aborted || prompt.signal?.aborted) {
+                throw new Error("Login cancelled");
+            }
+            if (prompt.type === "secret") {
+                return promptSecretLine(prompt.message);
+            }
+            if (prompt.type === "select") {
+                write(prompt.message);
+                for (const opt of prompt.options) {
+                    const desc = opt.description !== undefined ? ` — ${opt.description}` : "";
+                    write(`  [${opt.id}] ${opt.label}${desc}`);
+                }
+                return promptLine("Select option id");
+            }
+            const suffix = prompt.placeholder !== undefined ? ` (${prompt.placeholder})` : "";
+            return promptLine(`${prompt.message}${suffix}`);
+        },
+    };
+}

package/dist/cli/terminalSecret.d.ts

@@ -0,0 +1,2 @@
+export declare function readApiKeyFromEnv(env: NodeJS.ProcessEnv, varName: string): string;
+export declare function promptSecret(message: string): Promise<string>;

package/dist/cli/terminalSecret.js

@@ -0,0 +1,67 @@
+import { stdin as input, stderr as output } from "node:process";
+export function readApiKeyFromEnv(env, varName) {
+    if (typeof varName !== "string" || varName.length === 0) {
+        throw new Error("Missing value for --api-key-env");
+    }
+    const value = env[varName];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`Environment variable ${varName} is not set`);
+    }
+    return value;
+}
+export function promptSecret(message) {
+    return new Promise((resolve, reject) => {
+        output.write(`${message}: `);
+        if (!input.isTTY || typeof input.setRawMode !== "function") {
+            let buf = "";
+            const onData = (chunk) => {
+                buf += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+                if (buf.includes("\n") || buf.includes("\r")) {
+                    cleanup();
+                    resolve(buf.replace(/\r?\n$/, ""));
+                }
+            };
+            const onEnd = () => {
+                cleanup();
+                resolve(buf);
+            };
+            const cleanup = () => {
+                input.removeListener("data", onData);
+                input.removeListener("end", onEnd);
+                input.pause();
+            };
+            input.resume();
+            input.on("data", onData);
+            input.once("end", onEnd);
+            return;
+        }
+        input.setRawMode(true);
+        input.resume();
+        input.setEncoding("utf8");
+        let buf = "";
+        const onData = (ch) => {
+            if (ch === "\n" || ch === "\r" || ch === "\u0004") {
+                cleanup();
+                output.write("\n");
+                resolve(buf);
+            }
+            else if (ch === "\u0003") {
+                cleanup();
+                output.write("\n");
+                reject(new Error("Cancelled"));
+            }
+            else if (ch === "\u007f" || ch === "\b") {
+                buf = buf.slice(0, -1);
+            }
+            else if (ch >= " ") {
+                buf += ch;
+            }
+        };
+        const cleanup = () => {
+            input.setRawMode(false);
+            input.pause();
+            input.removeListener("data", onData);
+        };
+        input.on("data", onData);
+    });
+}

package/dist/cli/validateCommand.d.ts

@@ -0,0 +1,11 @@
+import { validateCatalog as defaultValidateCatalog, type ValidationResult } from "../config/validateCatalog.js";
+export declare const VALIDATE_USAGE = "Usage:\n  sf validate [--pipeline <name-or-path>] [--strict] [--json]";
+export type ValidateCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare function runValidateCommand(args: string[], options?: {
+    cwd?: string;
+    io?: Partial<ValidateCommandIo>;
+    validateCatalog?: (options: Parameters<typeof defaultValidateCatalog>[0]) => Promise<ValidationResult>;
+}): Promise<number>;

package/dist/cli/validateCommand.js

@@ -0,0 +1,81 @@
+import { validateCatalog as defaultValidateCatalog, } from "../config/validateCatalog.js";
+import { exitCodeForValidation, formatValidationHuman, formatValidationJson, } from "./validateOutput.js";
+export const VALIDATE_USAGE = `Usage:
+  sf validate [--pipeline <name-or-path>] [--strict] [--json]`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+function parseValidateArgs(args) {
+    if (args.length === 0) {
+        return { help: false, strict: false, json: false };
+    }
+    if (args[0] === "--help" || args[0] === "-h") {
+        return { help: true, strict: false, json: false };
+    }
+    let pipeline;
+    let strict = false;
+    let json = false;
+    let help = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--pipeline") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --pipeline");
+            }
+            pipeline = value;
+        }
+        else if (arg === "--strict") {
+            strict = true;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+    }
+    return { help, pipeline, strict, json };
+}
+export async function runValidateCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const out = { ...defaultIo, ...options.io };
+    const validateCatalogFn = options.validateCatalog ?? defaultValidateCatalog;
+    try {
+        const parsed = parseValidateArgs(args);
+        if (parsed.help) {
+            out.error(VALIDATE_USAGE);
+            return 0;
+        }
+        const result = await validateCatalogFn({
+            scope: parsed.pipeline ? "pipeline" : "full",
+            cwd,
+            pipeline: parsed.pipeline,
+            strict: parsed.strict,
+        });
+        if (parsed.json) {
+            out.log(formatValidationJson(result));
+        }
+        else {
+            out.log(formatValidationHuman(result, { strict: parsed.strict }));
+        }
+        return exitCodeForValidation(result);
+    }
+    catch (err) {
+        const message = err instanceof Error
+            ? err.message
+            : typeof err === "string"
+                ? err
+                : "Validate command failed";
+        out.error(message);
+        out.error(VALIDATE_USAGE);
+        return 1;
+    }
+}

package/dist/cli/validateOutput.d.ts

@@ -0,0 +1,8 @@
+import type { ValidationResult } from "../config/validateCatalog.js";
+export declare const VALIDATION_SCOPE_LINE = "Scope: pipeline and stage YAML only (task, checkout, providers not checked).";
+export declare const VALIDATION_CHECKS = "pipeline and stage YAML only";
+export declare function formatValidationHuman(result: ValidationResult, options?: {
+    strict?: boolean;
+}): string;
+export declare function formatValidationJson(result: ValidationResult): string;
+export declare function exitCodeForValidation(result: ValidationResult): 0 | 1;

package/dist/cli/validateOutput.js

@@ -0,0 +1,75 @@
+import { effectiveSeverity } from "../config/validateCatalog.js";
+export const VALIDATION_SCOPE_LINE = "Scope: pipeline and stage YAML only (task, checkout, providers not checked).";
+export const VALIDATION_CHECKS = "pipeline and stage YAML only";
+function effectiveSeverityRank(finding, strict) {
+    return effectiveSeverity(finding, strict) === "error" ? 0 : 1;
+}
+function orderedPaths(findings) {
+    const paths = [];
+    const seen = new Set();
+    for (const finding of findings) {
+        if (seen.has(finding.path))
+            continue;
+        seen.add(finding.path);
+        paths.push(finding.path);
+    }
+    return paths;
+}
+function findingsForPath(findings, filePath, strict) {
+    return findings
+        .filter((finding) => finding.path === filePath)
+        .sort((a, b) => {
+        const sevCmp = effectiveSeverityRank(a, strict) - effectiveSeverityRank(b, strict);
+        if (sevCmp !== 0)
+            return sevCmp;
+        return a.message.localeCompare(b.message);
+    });
+}
+function formatSummary(result) {
+    const { errors, warnings } = result.summary;
+    if (result.ok) {
+        if (result.findings.length === 0) {
+            return "Validation passed.";
+        }
+        return `Validation passed: ${errors} error(s), ${warnings} warning(s).`;
+    }
+    return `Validation failed: ${errors} error(s), ${warnings} warning(s).`;
+}
+export function formatValidationHuman(result, options = {}) {
+    const strict = options.strict ?? false;
+    const lines = [VALIDATION_SCOPE_LINE];
+    if (result.findings.length > 0) {
+        lines.push("");
+        for (const filePath of orderedPaths(result.findings)) {
+            lines.push(filePath);
+            for (const finding of findingsForPath(result.findings, filePath, strict)) {
+                const severity = effectiveSeverity(finding, strict);
+                lines.push(`${severity}: ${finding.message}`);
+            }
+            lines.push("");
+        }
+        lines.pop();
+    }
+    lines.push("");
+    lines.push(formatSummary(result));
+    return lines.join("\n");
+}
+export function formatValidationJson(result) {
+    const payload = {
+        ok: result.ok,
+        scope: result.scope,
+        checks: VALIDATION_CHECKS,
+        summary: result.summary,
+        findings: result.findings.map((finding) => ({
+            severity: finding.severity,
+            category: finding.category,
+            code: finding.code,
+            file: finding.path,
+            message: finding.message,
+        })),
+    };
+    return JSON.stringify(payload, null, 2);
+}
+export function exitCodeForValidation(result) {
+    return result.ok ? 0 : 1;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};