API reference
Cockpit server API
The Express backend of the Cockpit: routes, jobs, auth, workspace containment.
74 modules, 446 documented exports. Version next. All packages.
ui/server/src
- auth-1Exports: AuthConfigError, DEFAULT_SESSION_TTL_HOURS, SESSION_COOKIE, STATE_COOKIE, createAuth, isLoopbackHost, loadOrCreatePersistedSecret, parseAllowedLogins, ...
- 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, guard, 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, NOT_VISIBLE_CODE, NOT_VISIBLE_MESSAGE, TOKEN_USERNAME, createAskpass, ...
- cloneJobs-1Exports: CLONE_STAMP, DEFAULT_MAX_BYTES, DEFAULT_TIMEOUT_MS, LOGIN_HOSTS, MARKER_PREFIX, UNSAFE_PULL_CONFIG, cloneArgs, cloneEnv, ...
- 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, componentUsedBy, componentWorkflow, ...
- coreExecutorcoreExecutor.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... Exports: ExecutionError, CLI_BIN_ENV, CLI_ENV, CLI_TIMEOUT_ENV, DEFAULT_CLI_TIMEOUT_MS, childEnv, parseJsonOutput, parseValidateOutput, ...
- 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, ...
- debugApiLIN-137 (part of LIN-82/epic ) -- the debug chain's UI half: one route, POST /api/debug/read, over packages/core/debug-chain.mjs's four choosers (debug.reproduce -> debug.isolate -> debug.fix -> debug.verify). Exports: MAX_ANSWERS, MAX_FEATURE, MAX_REQUEST_BYTES, createDebugRouter, readDebug
- 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
- envelopesApithin REST adapter over packages/core/flows.mjs: every named, reusable flow saved under the open project's `.construct/flows/`, a deterministic envelope preview, a preview/commit save, and "Run this flow" through the e... Exports: createEnvelopesRouter, envelopePreview, envelopeRun, envelopeSave, envelopeShow, envelopesIndex
- 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, ...
- githubRepoApithe HTTP surface of "Connect GitHub for private repositories" (repoConnection.mjs holds the token). Exports: REPO_STATE_COOKIE, createGithubRouter, mountRepoAuthRoutes
- 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
- lintBufferApi`POST /api/lint-buffer` -- buffer-scope rule diagnostics for one unsaved editor buffer (the core's lintBuffer, packages/core/lint-buffer.mjs; see its header for exactly which rules run here vs. Exports: MAX_VIOLATIONS, handleLintBuffer
- 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 ) -- "New project": one name in, an initialised project in the caller's workspace out. Exports: NEW_PROJECT_FRAMEWORKS, createNewProjectRouter, planNewProject
- notesApi(part of / ) -- the Notes API: durable, per-project drafts on this machine. Exports: MAX_NOTES_REQUEST_BYTES, createNotesRouter, revFromHeader, summarize
- notesStore(part of , drives story ) — 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
- pagesEditorpagesEditor.mjs's implementation is pure logic (JSX tree edits, Palette insertion, enforcement checks) with no Cockpit-server dependency beyond a path-containment helper, so it now lives in packages/engine where const... Exports: PagesEditorError, addChildInSnippet, applyAutoMap, applyWrapConfirm, assertContentHash, buildAttributeSnippet, buildComponentUsageJsx, buildPaletteInsertion, ...
- pagesGitStatusInspector/tree "Git changed-vs-main" signal: whether the open page file differs from `main` -- the same read-only block prHealth already uses for a PR-style diff (packages/engine/gitTrees.mjs), plus ui/server/src/git.... Exports: pageChangedVsMain
- pagesImpactInspector "Impact" section: "if I change this file, which other features are reached" — the same deterministic blast-radius block componentUsedBy already seeds with one file (packages/engine/impact.mjs), scoped here t... Exports: pageImpact
- pageSourcePages Editor source view: the full text of one page file plus live diagnostics for it, and buffer-scoped linting + quick fixes for an unsaved edit in the code drill-down. Exports: lintPageBuffer, quickFixPageBuffer, 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, openSourceLocation, resolveProjectFile, viewPage, viewProjectFile
- projectTreethe Import Wizard's route/folder picker lists ONE directory of the OPEN PROJECT at a time. Exports: listProjectTree
- repoConnection"Connect GitHub for private repositories": a second, opt-in consent that lets the Cockpit clone a private repository with the signed-in person's own GitHub access, with no token pasted. Exports: DEFAULT_API_BASE, DEFAULT_OAUTH_BASE, MAX_PENDING_PER_KEY, PENDING_TTL_MS, REFRESH_MARGIN_MS, REPOS_CACHE_MS, REQUEST_TIMEOUT_MS, createRepoConnections, ...
- requirementApi(part of epic ) -- the requirement chain, read back before anything is written. Exports: MAX_ANSWERS, MAX_REQUEST_BYTES, MAX_TEXT, createRequirementRouter, featureNameOf, readRequirement, withDecisions
- requirementProofApi(part of ) -- the proof of a generated screen, on the Requirement screen. Exports: MAX_PROOF_REQUEST_BYTES, PROOF_REASON, PROOF_RUN_TIMEOUT_MS, checkReason, createProofHandlers, proofTarget, shapeRun
- 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, ). 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
- rulesApithin REST adapter over packages/core/rules-catalog.mjs: every rule `construct validate` can report, with severity resolved against the open project's `architecture.yml` (falls back to the built-in default with no over... Exports: createRulesRouter, globListSave, presetApply, projectSettingsSave, ruleExceptionSave, ruleSeveritySave, rulesIndex
- settingsSettings 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, settingsFilePath, updateSettings
- storiesApi(slice 17 of epic ) -- the Story tab's REST surface: read a feature's `story.md`, "Add a story", apply a freshly-fetched snapshot, mark a compare drift reviewed, and toggle "Keep out of git". Exports: createStoriesRouter
- storyAiApi(design docs/design/ia-five-screens.md 9.6) -- the HTTP surface for the two AI-assisted story flows: POST /api/story-ai/skeleton structure-only skeleton of a login-only page (no model call) -- shown to the user BEFORE... Exports: MAX_HTML_BYTES, createStoryAiRouter
- storyBridgeApi(part of ): the server side of the Picker's "propose selectors as a diff to story.md" (design docs/design/ia-five-screens.md section 9.7). Exports: StoryBridgeError, MAX_PAYLOAD_BYTES, createStoryBridgeRouter, validateSelector
- storyFetchApi(design: docs/design/ia-five-screens.md 9.3, 9.6, 9.6b) -- the HTTP surface for `StoryApi.fetch(url)`: POST /api/story/fetch one guarded fetch, strategy chosen per link, consent enforced first GET /api/story/consent t... Exports: createStoryFetchRouter
- storyFrontMatterA minimal, targeted reader/writer for ONLY the `sources: [{url, parse}]` front matter shape documented in docs/design/ia-five-screens.md section 9.2. Exports: StoryFrontMatterError, mergeStorySource, mergeStoryValues, readStoryFile
- 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, ). 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
- testSeamsthe CONSTRUCT_E2E_* test seams: environment variables that exist only so the e2e suite can start the Cockpit with a project already open, clone from a local directory, or point the GitHub connection at a mock. Exports: TEST_SEAM_VARS, TEST_SEAMS, isProduction, refuseTestSeam, resolveHarnessSeams
- 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 . 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