ui/server/src/coreExecutor

the executor seam: WHICH implementation runs a core activity for the Cockpit.

Cockpit server, v0.9. Source: ui/server/src/coreExecutor.mjs.

Classes#

ExecutionError#

Defined in: ui/server/src/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: ui/server/src/coreExecutor.mjs:42

Parameters

code

any

message

any

Returns

ExecutionError

Overrides

Error.constructor

Properties#

code

code: any

Defined in: ui/server/src/coreExecutor.mjs:45

name

name: string

Defined in: ui/server/src/coreExecutor.mjs:44

Inherited from

Error.name

Variables#

CLI_BIN_ENV#

const CLI_BIN_ENV: "CONSTRUCT_CLI_BIN" = 'CONSTRUCT_CLI_BIN'

Defined in: ui/server/src/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_TIMEOUT_ENV#

const CLI_TIMEOUT_ENV: "CONSTRUCT_CLI_TIMEOUT_MS" = 'CONSTRUCT_CLI_TIMEOUT_MS'

Defined in: ui/server/src/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: ui/server/src/coreExecutor.mjs:35

Functions#

parseJsonOutput()#

parseJsonOutput(raw, spec): any

Defined in: ui/server/src/coreExecutor.mjs:188

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(__namedParameters): any

Defined in: ui/server/src/coreExecutor.mjs:208

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#

__namedParameters

code

any

signal

any

stderr

any

stdout

any

Returns#

any

---

resolveCliBin()#

resolveCliBin(env?): string

Defined in: ui/server/src/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, #540 -- 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: ui/server/src/coreExecutor.mjs:232

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: ui/server/src/coreExecutor.mjs:171

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 (CONSTRUCT_* included), 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?

Function

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: "passed" | "failed"; violations: any[]; }>

Defined in: ui/server/src/coreExecutor.mjs:246

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?

Function

timeoutMs?

number

Returns#

Promise<{ mode: string; ok: boolean; report: string; status: "passed" | "failed"; 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.