ui/server/src · Developer Docs

Cockpit server, v0.8. Source: n/a.

Variables#

app#

const app: any

The Express app and the resolved auth surface, exported so tests can exercise the real route table (and the real gate) without a listener.

auth#

auth: any

Defined in: ui/server/src/index.mjs:122

The Express app and the resolved auth surface, exported so tests can exercise the real route table (and the real gate) without a listener.

CLIENT_ORIGIN#

const CLIENT_ORIGIN: any

Defined in: ui/server/src/index.mjs:94

cloneJobs#

const cloneJobs: object

Defined in: ui/server/src/index.mjs:1108

Type Declaration#

gitStatus

gitStatus: () => { cloneEnabled: boolean; code: string; minimum: string; ok: boolean; reason: any; version: any; } | { cloneEnabled: boolean; code: string; minimum: string; ok: boolean; reason: string; version: any; } | { cloneEnabled: boolean; code?: undefined; minimum: string; ok: boolean; reason?: undefined; version: any; }

#423: whether clone may run on this machine's git. Below 2.37.0 git silently ignores http.curloptResolve, the pin that keeps git on the addresses that were just checked to be public, so the anti-rebinding half of the SSRF defence would be off without a word. Refused rather than degraded: a clone with half its defence is not one we want to run. -> {ok, version, minimum, cloneEnabled, reason?, code?}

Returns

{ cloneEnabled: boolean; code: string; minimum: string; ok: boolean; reason: any; version: any; } | { cloneEnabled: boolean; code: string; minimum: string; ok: boolean; reason: string; version: any; } | { cloneEnabled: boolean; code?: undefined; minimum: string; ok: boolean; reason?: undefined; version: any; }

list

list: () => object[]

Returns

object[]

live

live: () => number

Test seam: resolves when the given job has finished.

Returns

number

cancel()

cancel(id): { body: { error: string; job?: undefined; ok: boolean; }; status: number; } | { body: { error: string; job: { branch?: any; bytes: any; code?: any; dir?: any; error?: any; finishedAt: any; id: any; kind: string; log: any; name: any; private: boolean; progress: any; startedAt: any; state: any; title: string; url: any; }; ok: boolean; }; status: number; } | { body: { error?: undefined; job: { branch?: any; bytes: any; code?: any; dir?: any; error?: any; finishedAt: any; id: any; kind: string; log: any; name: any; private: boolean; progress: any; startedAt: any; state: any; title: string; url: any; }; ok: boolean; }; status: number; }

-> {status, body}

Parameters

id

any

Returns

{ body: { error: string; job?: undefined; ok: boolean; }; status: number; } | { body: { error: string; job: { branch?: any; bytes: any; code?: any; dir?: any; error?: any; finishedAt: any; id: any; kind: string; log: any; name: any; private: boolean; progress: any; startedAt: any; state: any; title: string; url: any; }; ok: boolean; }; status: number; } | { body: { error?: undefined; job: { branch?: any; bytes: any; code?: any; dir?: any; error?: any; finishedAt: any; id: any; kind: string; log: any; name: any; private: boolean; progress: any; startedAt: any; state: any; title: string; url: any; }; ok: boolean; }; status: number; }

get()

get(id): object

Parameters

id

any

Returns

object

branch?

optional branch?: any = j.branch

bytes

bytes: any = j.bytes

code?

optional code?: any = j.errorCode

dir?

optional dir?: any = j.dest

error?

optional error?: any = j.error

finishedAt

finishedAt: any = j.finishedAt

id

id: any = j.id

kind

kind: string = 'clone'

log

log: any

name

name: any = j.slug

private

private: boolean

progress

progress: any = j.progress

startedAt

startedAt: any = j.startedAt

state

state: any = j.state

title

title: string

url

url: any = j.url

pull()

pull(opts?): Promise<any>

"Pull latest" for a clone this Cockpit made: git pull --ff-only, argv only, contained, with the same one-time token handling as start(). -> {ok:true, name, upToDate, message, detail} | {ok:false, status, code, error}

Parameters

opts?

Returns

Promise<any>

recoverInterrupted()

recoverInterrupted(): object

#422: sweep the workspace for markers left by a server that is gone (called at server start, and usable any time). Removes only directories that carry OUR marker, are real directories, and sit directly under the workspace root; stops an orphaned git first when it is still running. A marker whose server is alive is kept. -> {removed: string[], killed: string[], kept: {slug, why}[], badMarkers: string[]}

Returns

object

badMarkers

badMarkers: any[] = []

kept

kept: any[] = []

killed

killed: any[] = []

removed

removed: any[] = []

start()

start(opts?): Promise<{ code?: undefined; done: Promise<any>; error?: undefined; job: { branch?: any; bytes: any; code?: any; dir?: any; error?: any; finishedAt: any; id: any; kind: string; log: any; name: any; private: boolean; progress: any; startedAt: any; state: any; title: string; url: any; }; ok: boolean; status?: undefined; } | { code: string; error: string; ok: boolean; status: number; }>

Validate and start. token (optional, a string) is a one-time access token for a private repository: it is validated, held as a Buffer, given to the process only through the per-job askpass helper, and zeroed when the job ends. -> {ok:true, job} | {ok:false, status, code, error}

Parameters

opts?

Returns

Promise<{ code?: undefined; done: Promise<any>; error?: undefined; job: { branch?: any; bytes: any; code?: any; dir?: any; error?: any; finishedAt: any; id: any; kind: string; log: any; name: any; private: boolean; progress: any; startedAt: any; state: any; title: string; url: any; }; ok: boolean; status?: undefined; } | { code: string; error: string; ok: boolean; status: number; }>

devServer#

const devServer: object

Defined in: ui/server/src/index.mjs:112

Type Declaration#

start

start: (__namedParameters) => Promise<{ body: { branch: string; branchKind: string; code: string; command: { display: string; script: string; text: string; }; error: any; failure: any; ok: boolean; pid: any; port: any; refusal: any; root: any; startedAt: any; state: any; url: any; version: number; }; status: number; } | { body: { branch: string; branchKind: string; command: { display: string; script: string; text: string; }; failure: any; ok: boolean; pid: any; port: any; refusal: any; root: any; startedAt: any; state: any; url: any; version: number; }; status: number; }>

Parameters

__namedParameters?

Returns

Promise<{ body: { branch: string; branchKind: string; code: string; command: { display: string; script: string; text: string; }; error: any; failure: any; ok: boolean; pid: any; port: any; refusal: any; root: any; startedAt: any; state: any; url: any; version: number; }; status: number; } | { body: { branch: string; branchKind: string; command: { display: string; script: string; text: string; }; failure: any; ok: boolean; pid: any; port: any; refusal: any; root: any; startedAt: any; state: any; url: any; version: number; }; status: number; }>

stop

stop: () => Promise<{ body: { branch: string; branchKind: string; command: { display: string; script: string; text: string; }; failure: any; ok: boolean; pid: any; port: any; refusal: any; root: any; startedAt: any; state: any; url: any; version: number; }; status: number; }>

Returns

Promise<{ body: { branch: string; branchKind: string; command: { display: string; script: string; text: string; }; failure: any; ok: boolean; pid: any; port: any; refusal: any; root: any; startedAt: any; state: any; url: any; version: number; }; status: number; }>

currentRoot()

currentRoot(): string

The project root a stop-on-close should target: the one the Cockpit is looking at now, or null.

Returns

string

restart()

restart(opts?): Promise<{ body: { branch: string; branchKind: string; code: string; command: { display: string; script: string; text: string; }; error: any; failure: any; ok: boolean; pid: any; port: any; refusal: any; root: any; startedAt: any; state: any; url: any; version: number; }; status: number; } | { body: { branch: string; branchKind: string; command: { display: string; script: string; text: string; }; failure: any; ok: boolean; pid: any; port: any; refusal: any; root: any; startedAt: any; state: any; url: any; version: number; }; status: number; }>

Parameters

opts?

Returns

status()

status(): object

Returns

object

branch

branch: string

branchKind

branchKind: string

command

command: object

command.display

display: string

command.script

script: string

command.text

text: string

failure

failure: any

ok

ok: boolean = true

pid

pid: any

port

port: any

refusal

refusal: any

root

root: any

startedAt

startedAt: any

state

state: any

url

url: any

version

version: number

stopAll()

stopAll(): Promise<void>

Stop every dev server (Sign out). Never throws.

Returns

Promise<void>

stopForRoot()

stopForRoot(root): Promise<void>

Stop the dev server of one project (Close project / switching projects). Never throws.

Parameters

root

any

Returns

Promise<void>

health#

const health: object

Defined in: ui/server/src/index.mjs:185

Type Declaration#

describeStartup()

describeStartup(): object[]

The same facts as {level, text} lines for the server's startup log (these MAY name paths: the log is local).

Returns

object[]

snapshot()

snapshot(__namedParameters?): any

The health document; cached for cacheMs unless fresh is asked for.

Parameters

__namedParameters?

fresh?

boolean = false

Returns

any

planService#

const planService: object

Defined in: ui/server/src/index.mjs:1055

Type Declaration#

context()

context(): any

Returns

any

impact()

impact(body): any

seeds: unit refs the user picked (explicit). accepted: refs the user confirmed from the proposals; they are recomputed from text here, so they keep their evidence and stay inferred.

Parameters

body

any

Returns

any

propose()

propose(body): any

Proposals only. Nothing is analysed and no model is called: a heuristic text match with evidence.

Parameters

body

any

Returns

any

run()

run(body): any

Re-validates, then starts. On ANY error nothing is created and nothing is started.

Parameters

body

any

Returns

any

validate()

validate(body): any

Parameters

body

any

Returns

any

processesService#

const processesService: object

Defined in: ui/server/src/index.mjs:1049

Type Declaration#

currentRoot

currentRoot: () => any

Returns

any

engine

engine: () => any

The engine for the current project, for a harness that has to start work.

Returns

any

store

store: () => any

Returns

any

artifactDiff()

artifactDiff(id, filePath): { body: { diff?: undefined; error: string; ok: boolean; reason?: undefined; truncated?: undefined; }; status: number; } | { body: { diff: any; error?: undefined; ok: boolean; reason: any; truncated?: undefined; }; status: number; } | { body: { diff: any; error?: undefined; ok: boolean; reason?: undefined; truncated: boolean; }; status: number; }

The unified diff of one recorded artifact, read from the bot's branch. filePath must equal a path recorded on the process; the branch name is derived from the id the store returned, not the client's string.

Parameters

id

any

filePath

any

Returns

{ body: { diff?: undefined; error: string; ok: boolean; reason?: undefined; truncated?: undefined; }; status: number; } | { body: { diff: any; error?: undefined; ok: boolean; reason: any; truncated?: undefined; }; status: number; } | { body: { diff: any; error?: undefined; ok: boolean; reason?: undefined; truncated: boolean; }; status: number; }

control()

control(id, verb): { body: { controls?: undefined; error: string; ok: boolean; process?: undefined; }; status: number; } | { body: { controls: any; error: any; ok: boolean; process?: undefined; }; status: number; } | { body: { controls?: undefined; error?: undefined; ok: boolean; process: { artifacts: any; log: any; logHidden: any; steps: any; summary: any; }; }; status: number; }

Parameters

id

any

verb

any

Returns

{ body: { controls?: undefined; error: string; ok: boolean; process?: undefined; }; status: number; } | { body: { controls: any; error: any; ok: boolean; process?: undefined; }; status: number; } | { body: { controls?: undefined; error?: undefined; ok: boolean; process: { artifacts: any; log: any; logHidden: any; steps: any; summary: any; }; }; status: number; }

decide()

decide(id, __namedParameters): object

#341 — ONE decision on ONE artifact. by is an argument the ROUTER derives from the signed session; nothing in the request body can reach it. diffSha256 is passed through exactly as the client echoed it; it is never computed or defaulted here, so the gate compares it with the diff it re-derives. -> { status, body }

Parameters

id

any

__namedParameters

by

any

diffSha256

any

path

any

verdict

any

Returns

object

body

body: any

status

status: number

detail()

detail(id): { body: { error: string; ok: boolean; process?: undefined; }; status: number; } | { body: { error?: undefined; ok: boolean; process: { artifacts: any; log: any; logHidden: any; steps: any; summary: any; }; }; status: number; }

-> { status, body }

Parameters

id

any

Returns

{ body: { error: string; ok: boolean; process?: undefined; }; status: number; } | { body: { error?: undefined; ok: boolean; process: { artifacts: any; log: any; logHidden: any; steps: any; summary: any; }; }; status: number; }

isCurrent()

isCurrent(record): boolean

Does record belong to the project the Cockpit is looking at?

Parameters

record

any

Returns

boolean

list()

list(): object

Returns

object

problems

problems: any

processes

processes: any

projectRoot

projectRoot: any = entry.root

review()

review(id): object

#341 — the gate's read-only review of one process: per artifact the exact diff, its sha256, the refusals and whether it is applicable. -> { status, body }

Parameters

id

any

Returns

object

body

body: any = review

status

status: number = 200

setExecutor()

setExecutor(fn): void

Swap the executor (tests and the e2e harness). Applies to projects opened afterwards.

Parameters

fn

any

Returns

void

startPlan()

startPlan(plan): { error: any; ok: boolean; processId?: undefined; status: number; } | { error?: undefined; ok: boolean; processId: any; status?: undefined; }

#289 — create a process from a plan the caller has ALREADY validated (planService.run) and start it. The project is the service's own; createProcess() validates the plan once more and throws on a bad one.

Parameters

plan

any

Returns

{ error: any; ok: boolean; processId?: undefined; status: number; } | { error?: undefined; ok: boolean; processId: any; status?: undefined; }

subscribe()

subscribe(fn): () => boolean

Parameters

fn

any

Returns

() => boolean

reviewExecutor#

const reviewExecutor: object

Defined in: ui/server/src/index.mjs:1046

Type Declaration#

executeStep

executeStep: (__namedParameters) => Promise<{ artifacts: any[]; error: any; llm: any; ok: boolean; } | { artifacts: any[]; llm: any; ok: boolean; }>

Parameters

__namedParameters

log

any

process

any

signal

any

step

any

Returns

Promise<{ artifacts: any[]; error: any; llm: any; ok: boolean; } | { artifacts: any[]; llm: any; ok: boolean; }>

results

results: object

results.delete

delete: (id) => boolean

Parameters

id

any

Returns

boolean

results.get

get: (id) => any

Parameters

id

any

Returns

any

results.set()

set(id, value): void

Parameters

id

any

value

any

Returns

void

reviewJobs#

const reviewJobs: object

Defined in: ui/server/src/index.mjs:1066

Type Declaration#

get

get: (job) => any

The current state ({state, processId?, result?, error?}), or {state:'none'}.

Parameters

job

any

Returns

any

cancel()

cancel(job): any

Cancel the live analysis of this comparison with the machine's own CANCEL. -> {status, body} | null when none is live.

Parameters

job

any

Returns

any

enqueue()

enqueue(job): any

Start the analysis unless one for the same comparison is live or finished. Returns its state.

Parameters

job

any

Returns

any

pending()

pending(): number

How many analyses are waiting or running (tests and status).

Returns

number

testRunExecutor#

const testRunExecutor: object

Defined in: ui/server/src/index.mjs:1048

Type Declaration#

executeStep

executeStep: (__namedParameters) => Promise<{ artifacts: any[]; error: any; llm: any; ok: boolean; } | { artifacts: any[]; llm: any; ok: boolean; }>

Parameters

__namedParameters

log

any

process

any

signal

any

step

any

Returns

Promise<{ artifacts: any[]; error: any; llm: any; ok: boolean; } | { artifacts: any[]; llm: any; ok: boolean; }>

results

results: object

results.delete

delete: (id) => boolean

Parameters

id

any

Returns

boolean

results.get

get: (id) => any

Parameters

id

any

Returns

any

results.set()

set(id, value): void

Parameters

id

any

value

any

Returns

void

testRunJobs#

const testRunJobs: object

Defined in: ui/server/src/index.mjs:1094

Type Declaration#

cancel()

cancel(root, feature): any

Cancel the feature's live run with the machine's own CANCEL. -> {status, body} | null when none is live.

Parameters

root

any

feature

any

Returns

any

enqueue()

enqueue(root, feature, target, origin): { error?: undefined; live: { processId: any; state: any; target: any; }; processId?: undefined; started: boolean; } | { error: any; live?: undefined; processId?: undefined; started: boolean; } | { error?: undefined; live?: undefined; processId: any; started: boolean; }

Start a run unless this feature already has a live one. -> {started:true, processId} | {started:false, live} | {started:false, error}

Parameters

root

any

feature

any

target

any

origin

any

Returns

{ error?: undefined; live: { processId: any; state: any; target: any; }; processId?: undefined; started: boolean; } | { error: any; live?: undefined; processId?: undefined; started: boolean; } | { error?: undefined; live?: undefined; processId: any; started: boolean; }

last()

last(root, feature): object

Latest outcome per test file across the feature's finished runs (newest wins) and the run it came from.

Parameters

root

any

feature

any

Returns

object

lastRun

lastRun: object

lastRun.baseUrl

baseUrl: any = e.result.baseUrl

lastRun.counts

counts: any = e.result.counts

lastRun.durationMs

durationMs: any = e.result.durationMs

lastRun.processId

processId: any = e.processId

lastRun.target

target: any = e.target

tests

tests: any[]

live()

live(root, feature): object

The feature's queued/running run, or null.

Parameters

root

any

feature

any

Returns

object

processId

processId: any = e.processId

state

state: any = e.state

target

target: any = e.target

pending()

pending(): number

Returns

number

problem()

problem(root, feature): object

The newest run that did not produce a result (a refusal, a failure or a cancel), unless a newer one finished.

Parameters

root

any

feature

any

Returns

object

code

code: any

message

message: any

state

state: any = newest.state

target

target: any = newest.target

Functions#

createUiServer()#

createUiServer(): any

Defined in: ui/server/src/index.mjs:1145

Build the HTTP server with the wizard WebSocket attached. The socket gets the same auth object the REST gate uses, so it can never be the more permissive of the two.

Returns#

any

start()#

start(): any

Defined in: ui/server/src/index.mjs:1153

Returns#

any