Line
Version next
Search GitHub

You are reading the unreleased docs (next). See latest (v0.9)

ui/server/src/coreExecutor

coreExecutor.mjs is pure logic (CLI-binary resolution, subprocess spawn, JSON-output parsing) with no Cockpit-server dependency at all, so it now lives in packages/engine where construct's own root tests (executionMod...

Cockpit server, next. Source: ui/server/src/coreExecutor.mjs.

Classes#

ExecutionError#

Defined in: packages/engine/coreExecutor.mjs:41

A failure of the cli execution path, never a silent empty result. code is one of CLI_NOT_FOUND, CLI_START_FAILED, CLI_TIMEOUT, CLI_FAILED (non-success exit), CLI_BAD_OUTPUT (not the JSON document).

Extends#

  • Error

Constructors#

Constructor

new ExecutionError(code, message): ExecutionError

Defined in: packages/engine/coreExecutor.mjs:42

Parameters
code

any

message

any

Returns

ExecutionError

Overrides

Error.constructor

Properties#

code

code: any

Defined in: packages/engine/coreExecutor.mjs:45

name

name: string

Defined in: packages/engine/coreExecutor.mjs:44

Inherited from

Error.name

Variables#

CLI_BIN_ENV#

const CLI_BIN_ENV: "CONSTRUCT_CLI_BIN" = 'CONSTRUCT_CLI_BIN'

Defined in: packages/engine/coreExecutor.mjs:32

Env var naming the construct CLI to run in cli mode: a path to construct.mjs (source or the built packages/cli/dist/construct.mjs). Absolute, or relative to the Cockpit server's working directory.

CLI_ENV#

const CLI_ENV: readonly string[]

Defined in: packages/engine/coreExecutor.mjs:104

The CONSTRUCT_* names packages/cli, packages/core and packages/engine read from their environment (grep -rn "env.CONSTRUCT_" packages/); every one is a path, a URL, a number or a version, never a credential. A new CLI setting is added HERE (coreExecutor.test.mjs keeps this list equal to what the packages' sources read), never by widening to a prefix.

CLI_TIMEOUT_ENV#

const CLI_TIMEOUT_ENV: "CONSTRUCT_CLI_TIMEOUT_MS" = 'CONSTRUCT_CLI_TIMEOUT_MS'

Defined in: packages/engine/coreExecutor.mjs:34

Env var overriding the subprocess timeout, in milliseconds.

DEFAULT_CLI_TIMEOUT_MS#

const DEFAULT_CLI_TIMEOUT_MS: 120000 = 120_000

Defined in: packages/engine/coreExecutor.mjs:35

Functions#

childEnv()#

childEnv(env): ProcessEnv

Defined in: packages/engine/coreExecutor.mjs:115

The environment a cli-mode child gets: exported so a test can assert exactly what is (not) in it.

Parameters#

env

ProcessEnv

The parent process's environment to filter.

Returns#

ProcessEnv

A filtered copy — only allow-listed keys, with color output forced off, and anything shaped like a secret name (_SECRET/_TOKEN/_PASSWORD/_KEY suffix) always dropped.

parseJsonOutput()#

parseJsonOutput(raw, spec): any

Defined in: packages/engine/coreExecutor.mjs:205

Parse a verb's --format json output. Only the JSON document is read, never the text form. The exit code must be one of okCodes (a verb's own "this is a result" codes, e.g. 1 for "violations found"); every other exit, unparseable output, or a document check rejects is an ExecutionError, never a silent empty result.

Parameters#

raw

The process result.

code

number

signal?

string = null

stderr

string

stdout

string

spec

what names the document in messages; check returns a problem description, or null when the document has the expected shape.

check?

(doc, code) => string

okCodes?

number[] = ...

what

string

Returns#

any

The parsed document (an object or an array).

Throws#

CLI_FAILED for an unexpected exit, CLI_BAD_OUTPUT for anything that is not the document.

parseValidateOutput()#

parseValidateOutput(result): object

Defined in: packages/engine/coreExecutor.mjs:230

Parse construct validate --format json output. Only the JSON document is read, never the text form. Exit 0 with status "passed" or exit 1 with status "failed" are the two success shapes (exit 1 means "violations found", not "the CLI broke"); every other combination is an error.

Parameters#

result

The raw process result, as runCliVerb returns it.

code

number

signal

string

stderr

string

stdout

string

Returns#

object

The parsed validation report.

status

status: "failed" | "passed"

violations

violations: any[]

Throws#

CLI_FAILED (unexpected exit), CLI_BAD_OUTPUT (unparseable or wrong-shaped JSON, or an exit code that disagrees with the report's own status).

resolveCliBin()#

resolveCliBin(env?): string

Defined in: packages/engine/coreExecutor.mjs:59

Which construct binary cli mode runs. Order: the CONSTRUCT_CLI_BIN env var; else this repo's packages/cli/construct.mjs (the monorepo layout); else an installed @line/construct package (how the split Cockpit repo will consume it, -- found by walking up from the server's own node_modules, its bin.construct entry).

Parameters#

env?

ProcessEnv = process.env

Returns#

string

An absolute path to a file that exists.

Throws#

CLI_NOT_FOUND, naming every place that was looked at.

resolveExecutionMode()#

resolveExecutionMode(root): "engine" | "cli"

Defined in: packages/engine/coreExecutor.mjs:254

The execution mode a project asked for (project.execution.mode, default 'engine').

Parameters#

root

string

Project root (holds architecture.yml).

Returns#

"engine" | "cli"

Throws#

A ConstructError naming the bad value when architecture.yml is unreadable or the value is unknown.

runCliVerb()#

runCliVerb(root, argv, opts?): Promise<{ code: number; signal: string; stderr: string; stdout: string; }>

Defined in: packages/engine/coreExecutor.mjs:188

The ONE way any core activity runs in cli mode: node <construct.mjs> <argv...> --dir <root> with cwd = the project root, the allow-listed environment (childEnv: the CLI's own CONSTRUCT_* names only), a timeout and a process-group kill. root must be the server's own derived, contained project root (never a client string). Returns the raw process result; each verb's parser decides what is a valid document.

Parameters#

root

string

Resolved project root (the directory holding architecture.yml).

argv

string[]

The verb and its flags, WITHOUT --dir (appended here, last).

opts?

signal cancels the run (the process group gets SIGTERM, then SIGKILL after graceMs); onStart receives the child's pid.

bin?

string

env?

ProcessEnv = process.env

graceMs?

number

onStart?

(pid) => void

signal?

AbortSignal

spawnImpl?

any

timeoutMs?

number

Returns#

Promise<{ code: number; signal: string; stderr: string; stdout: string; }>

Throws#

CLI_NOT_FOUND, CLI_START_FAILED, CLI_TIMEOUT, CLI_CANCELLED, or CLI_BAD_OUTPUT (output overflow).

runValidate()#

runValidate(root, opts?): Promise<{ mode: string; ok: boolean; report: string; status: "failed" | "passed"; violations: any[]; }>

Defined in: packages/engine/coreExecutor.mjs:268

Run construct validate for a project root in the given mode.

Parameters#

root

string

Resolved project root (the directory holding architecture.yml).

opts?
bin?

string

env?

ProcessEnv = process.env

mode?

"engine" | "cli" = 'engine'

spawnImpl?

any

timeoutMs?

number

Returns#

Promise<{ mode: string; ok: boolean; report: string; status: "failed" | "passed"; violations: any[]; }>

report is the JSON document exactly as construct validate --format json prints it (without the final newline) -- built by the same formatReport in engine mode -- so both modes can be compared byte for byte.

Throws#

In cli mode: not found, not started, timed out, non-success exit, or output that is not the report.