ui/server/src/coreVerbs · Developer Docs

the per-verb wrappers on the executor seam (coreExecutor.mjs): one function per core activity, each running EITHER in-process (engine: the very same packages/core function the Cockpit endpoint has always called, thr...

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

Functions#

cliCommandResult()#

cliCommandResult(run, shape?): Promise<any>

Defined in: ui/server/src/coreVerbs.mjs:107

Run a cli-mode verb and shape the outcome like runCapturing does ({ok, output, attribution, durationSeconds, httpStatus, ...}), plus mode, so the Cockpit renders it exactly as it renders the in-process path. A failure of the CLI itself (not found, timeout, non-success exit, output that is not the document) is an ok:false result with the CLI's own words and HTTP 502, never an empty success. The run goes through the same per-login queue and concurrency cap as the in-process path (runCapturing).

Parameters#

run

() => Promise<{ doc: any; exitCode: number; mode: string; report: string; }>

A verb runner from this file, already bound to its root and options.

shape?

lines turns the result into the output lines (default: the report split at newlines); attribution (a value, or a function of the result) labels tool vs LLM work.

attribution?

{ llm: string; tool: string; } | ((result) => object) = null

lines?

(result) => string[]

Returns#

Promise<any>

The runCapturing-shaped result, with mode: 'cli'.

createArgv()#

createArgv(p?): { argv: string[]; } | { error: string; }

Defined in: ui/server/src/coreVerbs.mjs:194

The argv (without --dir) of POST /api/create's three forms, or a 400 message.

Parameters#

p?

The request fields.

feature?

string

kind?

string

layer?

string

layers?

string[]

name?

string

Returns#

{ argv: string[]; } | { error: string; }

The verb's arguments, or why the request is refused.

importArgv()#

importArgv(p?, resolveRead?): { argv: string[]; } | { error: string; }

Defined in: ui/server/src/coreVerbs.mjs:221

The argv (without --dir or --llm) of POST /api/import's two modes, or a 400 message. resolveRead maps a file the server will read (from, planPath) to its contained absolute path, and may throw.

Parameters#

p?

The request fields.

feature?

string

from?

string

layers?

string[]

mode?

string

name?

string

planPath?

string

resolveRead?

(value) => string

Containment for the two path fields (default: as given).

Returns#

{ argv: string[]; } | { error: string; }

The verb's arguments, or why the request is refused.

refactorArgv()#

refactorArgv(p?): { argv: string[]; } | { error: string; }

Defined in: ui/server/src/coreVerbs.mjs:207

The argv (without --dir) of POST /api/refactor's two actions, or a 400 message.

Parameters#

p?

The request fields.

action?

string

feature?

string

from?

string

layer?

string

name?

string

newName?

string

to?

string

Returns#

{ argv: string[]; } | { error: string; }

The verb's arguments, or why the request is refused.

runCreate()#

runCreate(root, params, opts?): Promise<{ doc: any; exitCode: number; mode: string; report: string; }>

Defined in: ui/server/src/coreVerbs.mjs:244

construct create feature|layer|<layer> ... --format json: scaffold from templates, no model call.

Parameters#

root

string

Resolved project root.

params

As createArgv.

feature?

string

kind?

string

layer?

string

layers?

string[]

name?

string

opts?

bin?

string

env?

ProcessEnv

mode?

"engine" | "cli"

spawnImpl?

Function

timeoutMs?

number

Returns#

Promise<{ doc: any; exitCode: number; mode: string; report: string; }>

doc.ok is false, with doc.error, for a refusal.

Throws#

CLI_START_FAILED for an invalid request; otherwise as runVerb.

runDoctor()#

runDoctor(root, opts?): Promise<{ doc: any; exitCode: number; mode: string; report: string; }>

Defined in: ui/server/src/coreVerbs.mjs:86

construct doctor --format json: node and npm versions, whether the project has an architecture.yml, and which enforcer modules are installed.

Parameters#

root

string

Resolved project root.

opts?

bin?

string

env?

ProcessEnv

mode?

"engine" | "cli" = 'engine'

spawnImpl?

Function

timeoutMs?

number

Returns#

Promise<{ doc: any; exitCode: number; mode: string; report: string; }>

Throws#

As runVerb.

runImport()#

runImport(root, params, opts?): Promise<{ doc: any; exitCode: number; mode: string; report: string; }>

Defined in: ui/server/src/coreVerbs.mjs:274

construct import <name> --feature ... --from ... or --plan <path>, --format json, without --llm.

Parameters#

root

string

Resolved project root.

params

As importArgv; from and planPath must already be contained absolute paths.

feature?

string

from?

string

layers?

string[]

mode?

string

name?

string

planPath?

string

opts?

bin?

string

env?

ProcessEnv

mode?

"engine" | "cli"

spawnImpl?

Function

timeoutMs?

number

Returns#

Promise<{ doc: any; exitCode: number; mode: string; report: string; }>

doc.ok is false, with doc.error, for a refusal.

Throws#

CLI_START_FAILED for an invalid request; otherwise as runVerb.

runRefactor()#

runRefactor(root, params, opts?): Promise<{ doc: any; exitCode: number; mode: string; report: string; }>

Defined in: ui/server/src/coreVerbs.mjs:259

construct refactor move|rename ... --format json: the mechanical relocation plus the re-validation of the moved file.

Parameters#

root

string

Resolved project root.

params

As refactorArgv.

action?

string

feature?

string

from?

string

layer?

string

name?

string

newName?

string

to?

string

opts?

bin?

string

env?

ProcessEnv

mode?

"engine" | "cli"

spawnImpl?

Function

timeoutMs?

number

Returns#

Promise<{ doc: any; exitCode: number; mode: string; report: string; }>

doc.ok is false, with doc.error, for a refusal.

Throws#

CLI_START_FAILED for an invalid request; otherwise as runVerb.

runReview()#

runReview(root, opts?): Promise<{ doc: any; exitCode: number; mode: string; report: string; }>

Defined in: ui/server/src/coreVerbs.mjs:148

construct review <base> <head> [--plan <file>|--features a,b] [--no-merge-base] --format json: the deterministic PR-health report (packages/engine/prHealth.mjs). In engine mode this is prHealth(...) itself, the call the Cockpit's review worker makes, printed the way the CLI prints it.

expected (the declared scope) travels as the CLI's own --features a,b when it is a list of feature names, and as a private temporary --plan file (removed afterwards) when it is an object ({features, files} or a plan). The refs are checked here too: a ref that could be read as a flag is refused before anything runs.

Parameters#

root

string

Resolved project root (must be its own nearest architecture.yml directory, see reviewCli.mjs).

opts?

base

string

bin?

string

env?

ProcessEnv

expected?

any = null

graceMs?

number

head

string

mergeBase?

boolean = true

mode?

"engine" | "cli" = 'engine'

onStart?

(pid) => void

signal?

AbortSignal

spawnImpl?

Function

timeoutMs?

number

Returns#

Promise<{ doc: any; exitCode: number; mode: string; report: string; }>

doc.ok is false, with doc.error, for a refusal (unknown ref, not a repository).

Throws#

As runVerb, plus CLI_START_FAILED for a ref that is not a plain ref name.

runSummarize()#

runSummarize(root, opts?): Promise<{ doc: any[]; exitCode: number; mode: string; report: string; }>

Defined in: ui/server/src/coreVerbs.mjs:68

construct summarize [--feature <f>] --format json: the deterministic project summary, an array with one entry per feature (packages/core/summarize.mjs).

Parameters#

root

string

Resolved project root.

opts?

bin?

string

env?

ProcessEnv

feature?

string

mode?

"engine" | "cli" = 'engine'

spawnImpl?

Function

timeoutMs?

number

Returns#

Promise<{ doc: any[]; exitCode: number; mode: string; report: string; }>

Throws#

As runVerb.

runVerb()#

runVerb(spec): Promise<{ doc: any; exitCode: number; mode: string; report: string; }>

Defined in: ui/server/src/coreVerbs.mjs:34

Run one verb in the given mode with one argv and return the common result shape.

Parameters#

spec

any

{ mode, root, verb, argv, engineFn, what, okCodes?, check?, cli }: engineFn is the packages/core function (called with argv plus --dir root), cli the options runCliVerb takes.

Returns#

Promise<{ doc: any; exitCode: number; mode: string; report: string; }>

Throws#

ENGINE_FAILED when the in-process call throws; the cli codes of coreExecutor otherwise.

summarizeHasJsonContract()#

summarizeHasJsonContract(params?): boolean

Defined in: ui/server/src/coreVerbs.mjs:55

Does construct summarize have a --format json contract for this request? Only the default project/feature summary does. The human views (md, compact, prose) and since (git-diff text that is not one JSON document) have none, so the Cockpit serves those in-process in both modes.

Parameters#

params?

The request's format and since (both optional).

format?

string

since?

string

Returns#

boolean

True when cli mode can serve it.