API reference
Cockpit server API
The Express backend of the Cockpit: routes, jobs, auth, workspace containment.
58 modules, 362 documented exports. Version v0.9. All packages.
ui/server/src
- auth-1Exports: AuthConfigError, DEFAULT_SESSION_TTL_HOURS, SESSION_COOKIE, STATE_COOKIE, createAuth, isLoopbackHost, parseAllowedLogins, parseCookies, ...
- autoCommitCommit-on-save for the Cockpit — the trigger half, which is `ui/` (proprietary-future) because it is policy and lifecycle, not computation. Exports: AutoCommitError, DIRTY_ANSWERS, MAX_COALESCE_MS, answerDirtyPrompt, endSession, flushSession, getCommitConfig, getSessionStatus, ...
- blockCataloguethe Blocks catalogue: every mechanical block (PLAN_FLOWS entry) in plain words, with what it reads and writes, whether it can use a model, its arguments, one concrete example, the settings for this project and how man... Exports: BLOCK_DOCS, blockCatalogue, exampleStep, runCounts
- blocksApithe Blocks API: the catalogue of mechanical blocks with this project's settings and run counts, and the one write (turn a block off or on, pick its default engine and local model). Exports: MAX_BLOCKS_REQUEST_BYTES, createBlocksRouter, revFromHeader
- blockSettingsStoreper-project settings for the mechanical blocks (the PLAN_FLOWS): turn a block off for this project, and the default engine (Mechanical | AI) and default local model where the block supports one. Exports: BlockSettingsError, ENGINES, MAX_MODEL_CHARS, MODEL_RE, SETTING_FIELDS, SETTINGS_VERSION, applyPatch, blockSettingsFile, ...
- cloneApislice A -- REST surface for cloning a public repository into the workspace, and for connecting a local project to a remote ("origin"). Exports: createCloneRouter, createRemoteRouter, remoteStatus
- cloneAuthslice B -- the one-time access token for cloning a PRIVATE repository. Exports: ASKPASS_SCRIPT, AUTH_MESSAGE, AUTH_MESSAGE_WITH_TOKEN, MAX_TOKEN_LENGTH, TOKEN_USERNAME, createAskpass, feedToken, looksLikeAuthFailure, ...
- cloneJobs-1Exports: CLONE_STAMP, DEFAULT_MAX_BYTES, DEFAULT_TIMEOUT_MS, MARKER_PREFIX, cloneArgs, cloneEnv, createCloneJobs, dirBytes, ...
- commandRunnerRuns one of the core CLI's exported functions (create/refactor/research/ importCommand from src/cli.mjs) and turns its console output into a structured result the frontend can render — in particular, splitting out the... Exports: CommandTimeoutError, DEFAULT_COMMAND_TIMEOUT_SEC, DEFAULT_MAX_CONCURRENT_COMMANDS, resolveCommandTimeoutMs, resolveMaxConcurrentCommands, runCapturing, runningCommandCount, withDir
- componentsApiThe Components screen's API. Exports: MAX_COMPONENT_BYTES, MAX_EDIT_BYTES, componentDescribe, componentSave, componentsIndex, componentSource, createComponentsRouter, listComponents
- coreExecutorthe executor seam: WHICH implementation runs a core activity for the Cockpit. Exports: ExecutionError, CLI_BIN_ENV, CLI_TIMEOUT_ENV, DEFAULT_CLI_TIMEOUT_MS, parseJsonOutput, parseValidateOutput, resolveCliBin, resolveExecutionMode, ...
- coreVerbsthe 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... Exports: cliCommandResult, createArgv, importArgv, refactorArgv, runCreate, runDoctor, runImport, runRefactor, ...
- devActivityIs an agent or model working on Construct itself on this machine right now? Exports: ACTIVE_WINDOW_MS, createDevActivity, createDevStatusRouter, projectSlug, readDevActivity
- devServer-1Exports: DEFAULT_KILL_GRACE_MS, DEFAULT_PORT_BASE, DEFAULT_STARTUP_TIMEOUT_MS, REFUSALS, RESERVED_PORTS, busyPortFrom, createDevServerService, findFreePort, ...
- devServerApiREST surface for the target app's dev server (see devServer.mjs). Exports: createDevServerRouter
- dirBrowseThin HTTP-shaped adapter over src/dir-browser.mjs (all listing/allowlist/ symlink logic lives in core, reusable and tested there). Exports: handleBrowse
- flowApiFlow view: the read-only server half of the Browser pane's Files | Flow switch. Exports: clearFlowCache, featureFlow, flowFilePaths, projectSignature
- gitThe narrowest possible git interface the Cockpit needs. Exports: GitError, branchExists, commit, createBranch, currentBranch, git, hasStagedChanges, headSha, ...
- gitUrlslice A -- what a "clone this repository" request is allowed to name. Exports: CloneInputError, DEFAULT_CLONE_HOSTS, MAX_SLUG_LENGTH, MAX_URL_LENGTH, isPublicAddress, parseCloneUrl, resolveCloneHosts, validateBranch, ...
- health-1Exports: DEFAULT_MIN_FREE_MB, HEALTH_CACHE_MS, checkDir, createHealth, freeBytesOf, probeWritable, resolveMinFreeBytes
- logBufferA small, bounded, in-memory ring buffer of recent server/command output for the cockpit's Logs tab. Exports: MAX_ENTRIES, MAX_LOGINS, MAX_TEXT, serverLog, createLogBuffer, createLogRegistry, handleLogs
- newProjectApi(part of #562) -- "New project": one name in, an initialised project in the caller's workspace out. Exports: NEW_PROJECT_FRAMEWORKS, createNewProjectRouter, planNewProject
- notesApi(part of #373 / #561) -- the Notes API: durable, per-project drafts on this machine. Exports: MAX_NOTES_REQUEST_BYTES, createNotesRouter, revFromHeader, summarize
- notesStore(part of #367, drives story #561) — durable, per-project Notes. Exports: NotesStoreError, MAX_NOTE_BODY_BYTES, NOTE_STATUSES, notesDir, openNotesStore
- ollamaThin wrapper around Ollama's local HTTP API (default http://localhost:11434, overridable via OLLAMA_HOST for anyone running it on a non-default port/host). Exports: getOllamaStatus, listOllamaModels, removeOllamaModel, startOllamaPull
- pageChangesthin glue between the core change tracker (src/file-change-tracker.mjs), the core diff view model (src/text-diff.mjs) and the Pages Editor routes. Exports: pageChangeTracker, adoptOwnWrite, describePageChange
- pagesEditor.golden.casesGolden-case corpus for the Pages Editor's deterministic JSX operations. Exports: REPLACEMENTS, SNIPPETS, SOURCES, normalizeGolden, runGoldenCases
- pagesEditorBackend for epic #48 (visual page/JSX tree editor) — #49 pages browser, #50 JSX tree parse, #52 snippet save-back, #53 props inspector, #54 auto-map, #56 enforcement guard. Exports: PagesEditorError, addChildInSnippet, applyAutoMap, applyWrapConfirm, assertContentHash, buildAttributeSnippet, buildComponentUsageJsx, buildPaletteInsertion, ...
- pageSourcePages Editor source view: the full text of one page file plus live diagnostics for it. Exports: readPageSource
- planApiREST surface for Plan mode. Exports: createPlanRouter
- planService-1Exports: LOCAL_PROVIDER, MAX_SEEDS, MAX_STEPS, MAX_TEXT, NOT_OFFERED, PATH_ARGS, checkPlan, cockpitErrors, ...
- processesApiREST surface for the Processes drawer. Exports: LOCAL_ACTOR, createProcessesRouter
- processesService-1Exports: CONTROL_EVENTS, LOG_TAIL, createProcessesService, processView, versionedSummary
- processesSocketlive updates for the Processes drawer. Exports: attachProcessesSocket
- projectGuard"Is there a project, and is its root inside the workspace?". Exports: NO_PROJECT_BODY, OUTSIDE_ROOT_BODY, containedProjectRoot, requireProject, rootEscapesWorkspace
- projectNavClick-to-navigate: the server half. Exports: openReference, resolveProjectFile, viewPage, viewProjectFile
- projectTreethe Import Wizard's route/folder picker lists ONE directory of the OPEN PROJECT at a time. Exports: listProjectTree
- researchApi`POST /api/research` (the Cockpit's read-only "research" actions: summarize and doctor) honouring the project's `project.execution.mode`. Exports: NO_JSON_CONTRACT_NOTE, executionFor, handleResearch
- reviewAnalysesan analysis is a Process: one plan, one step, flow `review.analyze` (src/plan.mjs). Exports: ANALYSIS_FLOW, ANALYSIS_STEP, KEEP_FINISHED, analysisPlan, composeExecutors, createAnalyses, createResults, createReviewExecutor, ...
- reviewApiREST surface for Review mode. Exports: MAX_HEADS, createReviewRouter, slimReport
- reviewClithe `cli` execution mode of a Review analysis: the same job the forked worker runs (reviewRunner.mjs), but the PR-health report comes from the real `construct review <base> <head> --format json` subprocess (coreVerbs.... Exports: cliReviewRunner
- reviewJobs-1Exports: createReviewJobs
- reviewPlansthe "expected scope" source for Review mode: the saved plans of the CURRENT PROJECT, which are the plans of the processes in the process store (a process stores its plan verbatim, #287). Exports: createPlanSource, expectedOf
- reviewRefsthe Review mode's list source: LOCAL BRANCHES, read with `git for-each-ref`. Exports: localBranches, commitsAhead, defaultBase, listLocalBranches, resolveListed
- reviewRunnerruns ONE analysis in a forked child process (reviewWorker.mjs), so the synchronous PR-health engine can never stall the Cockpit server's request thread. Exports: CANCEL_GRACE_MS, JOB_TIMEOUT_MS, WORKER, forkRunner
- reviewWorkerruns ONE analysis in a child process, so the synchronous PR-health engine (seconds on a big change) can never stall the Cockpit server's request thread. Exports: MAX_SUMMARIZED, analyse, summarizeChangedUnits
- settingsIn-memory settings for the UI server: which LLM provider each distinct LLM-touching capability should use, and which Construct project directory every command targets. Exports: getBrowseRoots, getProjectDir, getSettings, lastProjectFilePath, preloadProject, updateSettings
- testRunsrunning a feature's tests is a Process: one plan, one step, flow `test.run` (src/plan.mjs), exactly like a Review-mode analysis (reviewAnalyses.mjs, #351). Exports: KEEP_FINISHED_RUNS, TEST_RUN_FLOW, TEST_RUN_STEP, TEST_RUN_WORKER, createRunResults, createTestRunExecutor, createTestRunJobs, createTestRuns, ...
- testsApithe Tests tab's REST surface: list a feature's tests with the scenario coverage table, read one test, clone a locked generated test, and (re)generate a feature's locked tests. Exports: createTestsRouter
- testsEnvcan Playwright launch Chromium on this machine? Exports: environmentState
- unitsApiThin REST adapter over src/engine/unitSummary.mjs (deterministic unit summaries for bots and the Cockpit). Exports: featuresIndex, featureSummary, unitsIndex, unitSummary
- validateApi`GET /api/validate`: runs the same validation `construct validate` runs (aggregateValidation + DEFAULT_ENFORCERS from the core) against the current project's root and returns the violations as data. Exports: MAX_VIOLATIONS, handleValidate, handleValidateForProject
- wizardSocketWebSocket endpoint for the `import --route` guided wizard — the one inherently multi-turn, chat-shaped flow in Construct. Exports: attachWizardSocket
- workflowsViewerBackend for epic #57. Exports: editWorkflowFile, listWorkflowFeatures, listWorkflowFiles, readWorkflowMachines, readWorkflowNarrative, resolveWorkflowFile
- workspaceThe workspace boundary. Exports: WorkspaceError, MAX_LOGIN_LENGTH, MAX_PATH_LENGTH, baseWorkspaceRoot, contain, containInWorkspace, containOrNull, currentLogin, ...
- writeVerbsApi`POST /api/create`, `/api/refactor` and `/api/import` honouring the project's `project.execution.mode` (the routes in index.mjs are thin calls into these handlers; research is researchApi.mjs). Exports: LLM_IN_PROCESS_NOTE, handleCreate, handleImport, handleRefactor
- wsUpgradeTwo WebSocketServers cannot both be built with `{ server, path }`: ws aborts an upgrade whose path is not its own with a 400, so the first one attached would refuse the second one's connections. Exports: pathnameOf, refuseUnknownUpgrades, routeUpgrade