@nyxa/automation 0.1.0

package/dist/claude-code.js

@@ -0,0 +1,182 @@
+import { AutomationError } from "./errors.js";
+import { createHarness, harnessProcessControls, } from "./harness.js";
+import { createHarnessPreflight, harnessProcessExitError, harnessProcessFailureCause, runHarnessProcess, } from "./harness-process.js";
+export const CLAUDE_CODE_HARNESS_PREFLIGHT = {
+    harnessName: "Claude Code",
+    minimumVersion: [2, 1, 205],
+    unsupportedVersionMessage: "Claude Code CLI 2.1.205 or later is required.",
+    versionPattern: /\b(\d+)\.(\d+)\.(\d+)(?:-([0-9a-z.-]+))?(?:\+[0-9a-z.-]+)?(?:\s|$)/iu,
+};
+const preflightClaudeCode = createHarnessPreflight(CLAUDE_CODE_HARNESS_PREFLIGHT);
+export function claudeCode(options = {}) {
+    const configuredOptions = Object.freeze({ ...options });
+    return createHarness({
+        name: "Claude Code",
+        async run(request) {
+            const executable = await preflightClaudeCode(configuredOptions.executable ?? "claude", request.environment, harnessProcessControls(request));
+            return executeClaudeCode(executable, configuredOptions, request);
+        },
+    });
+}
+async function executeClaudeCode(executable, options, request) {
+    const arguments_ = [
+        "-p",
+        "--output-format",
+        "json",
+        "--disallowed-tools",
+        "AskUserQuestion",
+        "--permission-mode",
+        claudeCodePermissionMode(request.access, request.approval),
+    ];
+    arguments_.push("--settings", JSON.stringify(claudeCodeRunSettings(request.access)));
+    if (options.model !== undefined) {
+        arguments_.push("--model", options.model);
+    }
+    if (options.effort !== undefined) {
+        arguments_.push("--effort", options.effort);
+    }
+    if (options.fallbackModel !== undefined) {
+        arguments_.push("--fallback-model", options.fallbackModel);
+    }
+    if (options.maxTurns !== undefined) {
+        arguments_.push("--max-turns", String(options.maxTurns));
+    }
+    if (options.maxBudgetUsd !== undefined) {
+        arguments_.push("--max-budget-usd", String(options.maxBudgetUsd));
+    }
+    if (request.output !== undefined) {
+        arguments_.push("--json-schema", JSON.stringify(request.output.toJSONSchema()));
+    }
+    if (request.nativeSessionId !== undefined) {
+        arguments_.push("--resume", request.nativeSessionId);
+    }
+    arguments_.push(request.prompt);
+    await request.start();
+    let envelope;
+    const result = await runHarnessProcess(executable, arguments_, request.workingDirectory, "Claude Code", {
+        environment: request.environment,
+        ...harnessProcessControls(request),
+        async onStdoutLine(line) {
+            if (line.trim().length === 0) {
+                return;
+            }
+            try {
+                envelope = JSON.parse(line);
+            }
+            catch (cause) {
+                throw new AutomationError("HARNESS_PROTOCOL_ERROR", "Claude Code emitted malformed JSON.", { cause });
+            }
+            await request.emitNativeEvent(envelope);
+        },
+    });
+    if (result.exitCode !== 0) {
+        if (request.approval === "auto" &&
+            automaticApprovalUnavailable(result.stderr)) {
+            throw new AutomationError("HARNESS_CAPABILITY_UNSUPPORTED", "Claude Code automatic approval is not available.", { cause: harnessProcessFailureCause(result.stderr) });
+        }
+        const structuredOutputFailure = request.output === undefined
+            ? undefined
+            : parseStructuredOutputFailure(result.stdout);
+        if (structuredOutputFailure !== undefined) {
+            throw new AutomationError("RUN_OUTPUT_INVALID", "The Claude Code Run could not produce valid structured output.", { cause: structuredOutputFailure });
+        }
+        throw harnessProcessExitError("Claude Code", result);
+    }
+    const structuredOutputFailure = request.output === undefined
+        ? undefined
+        : structuredOutputFailureCause(envelope);
+    if (structuredOutputFailure !== undefined) {
+        throw new AutomationError("RUN_OUTPUT_INVALID", "The Claude Code Run could not produce valid structured output.", { cause: structuredOutputFailure });
+    }
+    if (!isSuccessResult(envelope)) {
+        throw new AutomationError("HARNESS_PROTOCOL_ERROR", "Claude Code completed without a successful result.");
+    }
+    const nativeSessionId = envelope.session_id;
+    if (request.nativeSessionId !== undefined &&
+        nativeSessionId !== request.nativeSessionId) {
+        throw new AutomationError("HARNESS_PROTOCOL_ERROR", "Claude Code resumed a different Session than requested.");
+    }
+    if (request.output !== undefined) {
+        if (!Object.hasOwn(envelope, "structured_output")) {
+            request.sessionReady?.(nativeSessionId);
+            throw new AutomationError("RUN_OUTPUT_INVALID", "The Claude Code Run completed without structured output.", { cause: new TypeError("Missing Claude Code structured output.") });
+        }
+        return { nativeSessionId, value: envelope.structured_output };
+    }
+    if (!isTextResult(envelope)) {
+        throw new AutomationError("HARNESS_PROTOCOL_ERROR", "Claude Code completed without a textual result.");
+    }
+    return { nativeSessionId, value: envelope.result };
+}
+function automaticApprovalUnavailable(stderr) {
+    return /\bauto(?:matic)? mode\b.*\b(?:not available|unavailable|unsupported|requires)\b/iu.test(stderr);
+}
+function claudeCodeRunSettings(access) {
+    return {
+        ...(access === "read"
+            ? { permissions: { deny: ["Bash", "Edit"] } }
+            : {}),
+        ...(access === "write-workspace"
+            ? {
+                sandbox: {
+                    allowUnsandboxedCommands: false,
+                    enabled: true,
+                    failIfUnavailable: true,
+                },
+            }
+            : {}),
+    };
+}
+function claudeCodePermissionMode(access, approval) {
+    if (approval === "auto") {
+        return "auto";
+    }
+    switch (access) {
+        case "read":
+            return "plan";
+        case "write-workspace":
+            return "acceptEdits";
+        case "full":
+            return "bypassPermissions";
+    }
+}
+function parseStructuredOutputFailure(stdout) {
+    try {
+        return structuredOutputFailureCause(JSON.parse(stdout));
+    }
+    catch {
+        return undefined;
+    }
+}
+function structuredOutputFailureCause(value) {
+    if (typeof value !== "object" ||
+        value === null ||
+        value.type !== "result" ||
+        value.subtype !==
+            "error_max_structured_output_retries") {
+        return undefined;
+    }
+    const errors = value.errors;
+    const diagnostic = Array.isArray(errors)
+        ? errors
+            .filter((entry) => typeof entry === "string")
+            .join("\n")
+        : "";
+    return new Error(diagnostic.length === 0
+        ? "Claude Code exhausted its structured output attempts."
+        : diagnostic);
+}
+function isTextResult(value) {
+    return (isSuccessResult(value) &&
+        typeof value.result === "string");
+}
+function isSuccessResult(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.type === "result" &&
+        value.subtype === "success" &&
+        value.is_error === false &&
+        typeof value.session_id ===
+            "string" &&
+        value.session_id.length > 0);
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,487 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync, statSync, writeSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { tsImport } from "tsx/esm/api";
+import { AutomationError, isAutomationError } from "./errors.js";
+import { isMissingFileError } from "./filesystem.js";
+import { diagnoseEnvironment, } from "./doctor.js";
+import { initializeProject } from "./init.js";
+import { isConcurrencyLimit } from "./run-coordination.js";
+import { readStandardInput } from "./standard-input.js";
+import { executeWorkflowWithControls, isWorkflowDefinition, } from "./workflow.js";
+const PRE_EXECUTION_ERROR = 2;
+const EXECUTION_ERROR = 1;
+const CANCELLED = 130;
+const SUCCESS = 0;
+const PACKAGE_NAME = "@nyxa/automation";
+const HELP = `Usage: automation <workflow> [options]
+       automation run <workflow> [options]
+       automation init <workflow> [options]
+       automation <command>
+
+Commands:
+  init                 Initialize Automation in an existing npm project
+  doctor               Diagnose the local Automation environment
+
+Options:
+  --harness <name>     Select codex, claude-code, kimi-code, or opencode for init or doctor
+  --no-install         Generate a Workflow without installing the package
+  --yes                Accept init installation and auto-select one ready Harness
+  --input <json|->     Read Workflow Input from inline JSON or stdin
+  --input-file <path>  Read Workflow Input from a JSON file
+  --concurrency <n>    Limit concurrent Runs
+  --json               Write Automation Events as JSONL
+  --no-record          Disable the Run Journal
+  -h, --help           Show this help
+  -v, --version        Show the installed CLI version
+`;
+async function main(arguments_) {
+    const invocation = classifyInvocation(arguments_);
+    if (invocation === "help") {
+        writeSync(process.stdout.fd, HELP);
+        return SUCCESS;
+    }
+    if (invocation === "version") {
+        try {
+            writeSync(process.stdout.fd, `${ownPackageVersion()}\n`);
+            return SUCCESS;
+        }
+        catch (error) {
+            writeDiagnostic(error);
+            return PRE_EXECUTION_ERROR;
+        }
+    }
+    if (invocation === "doctor") {
+        try {
+            const harness = parseDoctorArguments(arguments_.slice(1));
+            const localPackage = resolveProjectLocalPackage(process.cwd());
+            const result = await diagnoseEnvironment({
+                environment: process.env,
+                ...(harness === undefined ? {} : { harness }),
+                ...(localPackage === undefined
+                    ? {}
+                    : {
+                        localPackage: {
+                            binaryAvailable: localPackage.binaryAvailable,
+                            version: localPackage.version,
+                        },
+                    }),
+            });
+            writeSync(process.stdout.fd, result.output);
+            return result.ready ? SUCCESS : EXECUTION_ERROR;
+        }
+        catch (error) {
+            writeDiagnostic(error);
+            return PRE_EXECUTION_ERROR;
+        }
+    }
+    if (invocation === "init") {
+        try {
+            const output = await initializeProject(arguments_.slice(1));
+            writeSync(process.stdout.fd, output);
+            return SUCCESS;
+        }
+        catch (error) {
+            writeDiagnostic(error);
+            return PRE_EXECUTION_ERROR;
+        }
+    }
+    if (invocation === "workflow") {
+        try {
+            const localPackage = resolveProjectLocalPackage(process.cwd());
+            if (localPackage === undefined) {
+                throw new Error(`A project-local installation of ${PACKAGE_NAME} is required to execute a Workflow. Install it as a development dependency before running this command.`);
+            }
+            if (!localPackage.binaryAvailable) {
+                throw new Error(`The project-local ${PACKAGE_NAME} package is missing its automation binary. Reinstall it before running a Workflow.`);
+            }
+            if (!isCurrentCli(localPackage.cliPath)) {
+                return await delegateToLocalCli(localPackage.cliPath, arguments_);
+            }
+        }
+        catch (error) {
+            writeDiagnostic(error);
+            return PRE_EXECUTION_ERROR;
+        }
+    }
+    let parsedArguments;
+    let loadedInput;
+    try {
+        parsedArguments = parseArguments(arguments_);
+        loadedInput = await loadWorkflowInput(parsedArguments.inputSource);
+    }
+    catch (error) {
+        writeDiagnostic(error);
+        return PRE_EXECUTION_ERROR;
+    }
+    let workflowModule;
+    try {
+        const workflowUrl = pathToFileURL(path.resolve(process.cwd(), parsedArguments.workflowPath));
+        workflowModule = (await tsImport(workflowUrl.href, import.meta.url));
+    }
+    catch (cause) {
+        writeDiagnostic(new AutomationError("WORKFLOW_MODULE_LOAD_FAILED", `Could not load Workflow module: ${errorMessage(cause)}`, { cause }));
+        return PRE_EXECUTION_ERROR;
+    }
+    if (!isWorkflowDefinition(workflowModule.default)) {
+        writeDiagnostic(new Error("The module must export a default Workflow Definition created by defineWorkflow()."));
+        return PRE_EXECUTION_ERROR;
+    }
+    let result;
+    let runStarted = false;
+    const cancellation = new AbortController();
+    const force = new AbortController();
+    let forceTimer;
+    let interrupted = false;
+    const handleInterrupt = () => {
+        if (!interrupted) {
+            interrupted = true;
+            cancellation.abort();
+            forceTimer = setTimeout(() => force.abort(), 5_000);
+            forceTimer.unref();
+            return;
+        }
+        force.abort();
+    };
+    process.on("SIGINT", handleInterrupt);
+    try {
+        const executeDynamicWorkflow = executeWorkflowWithControls;
+        const writeEvent = parsedArguments.json ? writeJsonEvent : writeHumanEvent;
+        const onEvent = (event) => {
+            if (event.type === "run.started") {
+                runStarted = true;
+            }
+            writeEvent(event);
+        };
+        const executionOptions = {
+            ...(parsedArguments.concurrency === undefined
+                ? {}
+                : { concurrency: parsedArguments.concurrency }),
+            ...(parsedArguments.noRecord ? { record: false } : {}),
+            onEvent,
+            signal: cancellation.signal,
+        };
+        result = loadedInput.hasInput
+            ? await executeDynamicWorkflow(workflowModule.default, {
+                ...executionOptions,
+                input: loadedInput.value,
+            }, force.signal)
+            : await executeDynamicWorkflow(workflowModule.default, executionOptions, force.signal);
+    }
+    catch (error) {
+        writeDiagnostic(error);
+        if (!runStarted && isPreExecutionError(error)) {
+            return PRE_EXECUTION_ERROR;
+        }
+        return isCancelled(error) ? CANCELLED : EXECUTION_ERROR;
+    }
+    finally {
+        process.removeListener("SIGINT", handleInterrupt);
+        if (forceTimer !== undefined) {
+            clearTimeout(forceTimer);
+        }
+    }
+    if (!parsedArguments.json) {
+        writeResult(result);
+    }
+    return SUCCESS;
+}
+function parseDoctorArguments(arguments_) {
+    if (arguments_.length === 0) {
+        return undefined;
+    }
+    if (arguments_[0] !== "--harness") {
+        throw new Error(`Unexpected doctor argument: ${String(arguments_[0])}`);
+    }
+    const harness = arguments_[1];
+    if (harness !== "codex" &&
+        harness !== "claude-code" &&
+        harness !== "kimi-code" &&
+        harness !== "opencode") {
+        throw new Error("The --harness option requires codex, claude-code, kimi-code, or opencode.");
+    }
+    if (arguments_.length !== 2) {
+        throw new Error(`Unexpected doctor argument: ${String(arguments_[2])}`);
+    }
+    return harness;
+}
+function classifyInvocation(arguments_) {
+    const [command] = arguments_;
+    if (command === undefined) {
+        return "missing";
+    }
+    if (command === "--help" || command === "-h") {
+        return "help";
+    }
+    if (command === "--version" || command === "-v") {
+        return "version";
+    }
+    if (command === "doctor") {
+        return "doctor";
+    }
+    if (command === "init") {
+        return "init";
+    }
+    return "workflow";
+}
+function ownPackageVersion() {
+    const manifest = readPackageManifest(fileURLToPath(new URL("../package.json", import.meta.url)));
+    if (typeof manifest.version !== "string") {
+        throw new Error(`The ${PACKAGE_NAME} package has no valid version.`);
+    }
+    return manifest.version;
+}
+function resolveProjectLocalPackage(invocationDirectory) {
+    let directory = path.resolve(invocationDirectory);
+    let dependencyDeclared = false;
+    while (true) {
+        const projectManifestPath = path.join(directory, "package.json");
+        try {
+            const projectManifest = readPackageManifest(projectManifestPath);
+            dependencyDeclared ||= hasAutomationDevelopmentDependency(projectManifest);
+        }
+        catch (error) {
+            if (!isMissingFileError(error)) {
+                throw error;
+            }
+        }
+        const manifestPath = path.join(directory, "node_modules", "@nyxa", "automation", "package.json");
+        if (dependencyDeclared) {
+            let manifest;
+            try {
+                manifest = readPackageManifest(manifestPath);
+            }
+            catch (error) {
+                if (!isMissingFileError(error)) {
+                    throw error;
+                }
+            }
+            if (manifest !== undefined) {
+                if (manifest.name !== PACKAGE_NAME) {
+                    throw new Error(`The project-local package at ${manifestPath} is not ${PACKAGE_NAME}.`);
+                }
+                const binary = typeof manifest.bin === "string"
+                    ? manifest.bin
+                    : manifest.bin?.automation;
+                if (typeof binary !== "string") {
+                    throw new Error(`The project-local ${PACKAGE_NAME} package does not expose the automation binary.`);
+                }
+                if (typeof manifest.version !== "string") {
+                    throw new Error(`The project-local ${PACKAGE_NAME} package has no valid version.`);
+                }
+                const cliPath = path.resolve(path.dirname(manifestPath), binary);
+                return {
+                    binaryAvailable: isRegularFile(cliPath),
+                    cliPath,
+                    version: manifest.version,
+                };
+            }
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory) {
+            return undefined;
+        }
+        directory = parent;
+    }
+}
+function isRegularFile(filePath) {
+    try {
+        return statSync(filePath).isFile();
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return false;
+        }
+        throw error;
+    }
+}
+function hasAutomationDevelopmentDependency(manifest) {
+    return typeof manifest.devDependencies?.[PACKAGE_NAME] === "string";
+}
+function readPackageManifest(manifestPath) {
+    const serialized = readFileSync(manifestPath, "utf8");
+    try {
+        return JSON.parse(serialized);
+    }
+    catch (cause) {
+        throw new Error(`Could not parse package manifest at ${manifestPath}.`, {
+            cause,
+        });
+    }
+}
+function isCurrentCli(localCliPath) {
+    const localCli = realpathSync(localCliPath);
+    const currentCli = realpathSync(fileURLToPath(import.meta.url));
+    return localCli === currentCli;
+}
+async function delegateToLocalCli(localCliPath, arguments_) {
+    const { spawn } = await import("node:child_process");
+    return await new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [localCliPath, ...arguments_], {
+            cwd: process.cwd(),
+            env: process.env,
+            stdio: "inherit",
+        });
+        child.once("error", (cause) => {
+            reject(new Error(`Could not start the project-local ${PACKAGE_NAME} CLI.`, {
+                cause,
+            }));
+        });
+        child.once("exit", (code, signal) => {
+            if (code !== null) {
+                resolve(code);
+                return;
+            }
+            resolve(signal === "SIGINT" ? CANCELLED : EXECUTION_ERROR);
+        });
+    });
+}
+function parseArguments(arguments_) {
+    if (arguments_.length === 0) {
+        throw new Error("A Workflow module path is required.");
+    }
+    const [commandOrPath, possiblePath] = arguments_;
+    const explicitRun = commandOrPath === "run";
+    const workflowPath = explicitRun ? possiblePath : commandOrPath;
+    if (workflowPath === undefined) {
+        throw new Error("A Workflow module path is required.");
+    }
+    let inputSource;
+    let concurrency;
+    let json = false;
+    let noRecord = false;
+    let index = explicitRun ? 2 : 1;
+    while (index < arguments_.length) {
+        const option = arguments_[index];
+        if (option === "--json") {
+            if (json) {
+                throw new Error("The --json option may only be provided once.");
+            }
+            json = true;
+            index += 1;
+            continue;
+        }
+        if (option === "--no-record") {
+            if (noRecord) {
+                throw new Error("The --no-record option may only be provided once.");
+            }
+            noRecord = true;
+            index += 1;
+            continue;
+        }
+        if (option === "--concurrency") {
+            if (concurrency !== undefined) {
+                throw new Error("The --concurrency option may only be provided once.");
+            }
+            const value = arguments_[index + 1];
+            if (value === undefined) {
+                throw new Error("The --concurrency option requires a value.");
+            }
+            concurrency = Number(value);
+            if (!isConcurrencyLimit(concurrency)) {
+                throw new Error("The --concurrency option must be a positive integer.");
+            }
+            index += 2;
+            continue;
+        }
+        if (option !== "--input" && option !== "--input-file") {
+            throw new Error(`Unexpected argument: ${option}`);
+        }
+        const value = arguments_[index + 1];
+        if (value === undefined) {
+            throw new Error(`The ${option} option requires a value.`);
+        }
+        if (inputSource !== undefined) {
+            throw new Error("Only one Workflow Input source may be provided.");
+        }
+        inputSource =
+            option === "--input-file"
+                ? { kind: "file", value }
+                : value === "-"
+                    ? { kind: "stdin" }
+                    : { kind: "inline", value };
+        index += 2;
+    }
+    return {
+        ...(concurrency === undefined ? {} : { concurrency }),
+        ...(inputSource === undefined ? {} : { inputSource }),
+        json,
+        noRecord,
+        workflowPath,
+    };
+}
+async function loadWorkflowInput(source) {
+    if (source === undefined) {
+        return { hasInput: false };
+    }
+    let serialized;
+    if (source.kind === "file") {
+        try {
+            serialized = await readFile(path.resolve(process.cwd(), source.value), "utf8");
+        }
+        catch (cause) {
+            throw new Error(`Could not read Workflow Input file: ${errorMessage(cause)}`, { cause });
+        }
+    }
+    else if (source.kind === "stdin") {
+        serialized = await readStandardInput();
+    }
+    else {
+        serialized = source.value;
+    }
+    try {
+        return { hasInput: true, value: JSON.parse(serialized) };
+    }
+    catch (cause) {
+        throw new Error(`Workflow Input must be valid JSON: ${errorMessage(cause)}`, {
+            cause,
+        });
+    }
+}
+function isPreExecutionError(error) {
+    return (isAutomationError(error) &&
+        (error.code === "HARNESS_NOT_FOUND" ||
+            error.code === "HARNESS_CAPABILITY_UNSUPPORTED" ||
+            error.code === "HARNESS_NOT_AUTHENTICATED" ||
+            error.code === "HARNESS_REQUIRED" ||
+            error.code === "HARNESS_VERSION_UNSUPPORTED" ||
+            error.code === "OUTPUT_SCHEMA_UNSUPPORTED" ||
+            error.code === "RUN_CWD_INVALID" ||
+            error.code === "RUN_JOURNAL_UNAVAILABLE" ||
+            error.code === "RUN_POLICY_INVALID" ||
+            error.code === "WORKFLOW_INPUT_INVALID" ||
+            error.code === "WORKFLOW_INPUT_UNEXPECTED"));
+}
+function isCancelled(error) {
+    return isAutomationError(error) && error.code === "RUN_CANCELLED";
+}
+function writeResult(result) {
+    if (result === undefined) {
+        return;
+    }
+    writeSync(process.stdout.fd, typeof result === "string" ? result : JSON.stringify(result));
+}
+function writeJsonEvent(event) {
+    writeSync(process.stdout.fd, `${JSON.stringify(event)}\n`);
+}
+function writeHumanEvent(event) {
+    if (event.type === "run.started") {
+        const run = event.runName ?? event.runId;
+        const harness = event.harness ?? "an unresolved Harness";
+        writeSync(process.stderr.fd, `Run ${run} started with ${harness}.\n`);
+    }
+    else if (event.type === "run.completed") {
+        const run = event.runName ?? event.runId;
+        writeSync(process.stderr.fd, `Run ${run} completed.\n`);
+    }
+}
+function writeDiagnostic(error) {
+    const code = isAutomationError(error) ? `${error.code}: ` : "";
+    writeSync(process.stderr.fd, `${code}${errorMessage(error)}\n`);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+process.exitCode = await main(process.argv.slice(2));

package/dist/codex-output.d.ts

@@ -0,0 +1,6 @@
+import type { JSONSchema } from "./schema.js";
+export interface PreparedCodexOutput {
+    readonly schema: JSONSchema;
+    normalize(value: unknown): unknown;
+}
+export declare function prepareCodexOutput(schema: JSONSchema): PreparedCodexOutput;