API reference
Engine API
Pipeline, Context Envelope, processes, impact analysis, workflow narrator, test generator.
75 modules, 473 documented exports. Version next. All packages.
packages/engine
- approvalGatethe approval gate: the ONLY place a bot's output (possibly from a local model) is written into the user's working tree. Exports: GATE_CODES, createApprovalGate, pathProblem
- availableActions(Block 2 of 's framework) -- availableActions(block, state, catalog, projectCtx): the legal action menu at ANY level (app, feature, each layer unit, workflow, page, component, route, controller, service, domain, expre... Exports: ActionBlock, ActionCandidate, AvailableAction, availableActions, pageActionCatalog, processActionCatalog
- botRunnerthe bot runner: the `executeStep` 's engine is waiting for. Exports: botBranch, createBotRunner, resolveMaxConcurrent
- commitMessageDeterministic commit messages for Cockpit saves. Exports: COMMIT_MODES, DEFAULT_COALESCE_MS, DEFAULT_COMMIT_CONFIG, DEFAULT_SESSION_BRANCH_PREFIX, MAX_FILE_LINES, MAX_SLUG, SCHEMA_VERSION, SERIAL_DIGITS, ...
- controllerBinderTicket 7.4 -- Zero-LLM controller binder. Exports: extractHookSignature, extractPropsInterfaceMembers, generateController, matchSlotsToHandlers, resolveSourceFiles
- coreExecutorthe executor seam: WHICH implementation runs a core activity for the Cockpit. Exports: ExecutionError, CLI_BIN_ENV, CLI_ENV, CLI_TIMEOUT_ENV, DEFAULT_CLI_TIMEOUT_MS, childEnv, parseJsonOutput, parseValidateOutput, ...
- defaultEnforcersThe canonical enforcer list `construct validate` runs -- pulled out of packages/core/cli.mjs (which still imports this, unchanged behavior) so packages/engine/pipeline.mjs can validate a buffered transaction against e... Exports: DEFAULT_ENFORCERS
- describeComponent`describeComponent(root, relPath)`: a deterministic block that documents ONE component file. Exports: DESCRIBE_DEFAULTS, DESCRIBE_EXTENSIONS, describeComponent
- describeDocgenThe react-docgen adapter behind `describeComponent`. Exports: describeSource, typeText
- diagnosticsRead-only diagnostics for one source file: TypeScript compiler diagnostics (syntactic + semantic, resolved against the project's own tsconfig when it has one) plus Construct's architecture and separation-of-concerns r... Exports: collectDiagnostics, fromViolation, lintBuffer, ruleDiagnostics, typescriptDiagnostics
- envelopeTicket 7.1 -- Context Envelope helpers. Exports: ENVELOPE_VERSION, createEnvelope, validateEnvelope
- gitTreesRead-only git access for PR health: resolve refs, list changed files, and read the tree at a commit — without ever touching the user's working tree, index, branch or stash. Exports: GIT_TIMEOUT_MS, changedFiles, git, liveTreeCount, mergeBase, reclaimTreesOf, repoInfo, resolveCommit, ...
- gitVersionwhich git is installed, asked once per process, and what that version can do. Exports: GIT_VERSION_TIMEOUT_MS, MIN_GIT_FOR_CURLOPT_RESOLVE, atLeast, formatVersion, gitVersion, parseGitVersion, resetGitVersionCache, supportsCurloptResolve
- impactImpact analysis: given a set of seed units (or changed files), compute the blast radius — which features and layers a change touches, which files are implicated and WHY, what is shared and therefore risky, and what th... Exports: DEFAULT_DEPTH, DEFAULT_LIMITS, ENTRY_PROVENANCE, SCHEMA_VERSION, SEED_METHODS, SEED_PROVENANCE, SHARED_BY_FEATURES, analyzeImpact, ...
- jsxSourceAnnotatorDeterministic JSX source annotator (Cockpit live preview, click-to-source). Exports: CX_SRC_ATTR, annotateJsxFile, annotateJsxSource, parseCxSrc
- pageComponentsPAGE-COMPONENTS: loop the existing per-node analysis blocks (parseJsxTree, scopeLinks, describeComponent, classifyProjectFile) across a WHOLE page instead of one node at a time -- the building blocks already exist, no... Exports: resolvePageComponents
- pagesEditorBackend for epic (visual page/JSX tree editor) — pages browser, JSX tree parse, snippet save-back, props inspector, auto-map, enforcement guard. Exports: PagesEditorError, addChildInSnippet, applyAutoMap, applyWrapConfirm, assertContentHash, buildAttributeSnippet, buildComponentUsageJsx, buildPaletteInsertion, ...
- pageTransformerTicket 7.2 -- Pristine page transformer (Subframe JSX ingestion). Exports: featureFlow, ingestPage, transformPristineSource
- palettePages editor block palette read model. Exports: buildPalette, buildWrapSuggestions, describeWrapHit, expressionShape, findWrapHit, wrapFit
- pipelineTicket 7.1 -- Context Envelope pipeline runner. Exports: runPipeline
- planTemplateplan templates: a NAMED, REUSABLE, PARAMETERISED plan. Exports: TemplateError, PARAM_TYPES, TEMPLATE_ERROR_CODES, TEMPLATE_VERSION, checkParamValue, createTemplateRegistry, instantiate, loadTemplate, ...
- previewBridgePreview bridge: the tiny in-page half of click-to-source. Exports: PREVIEW_MESSAGE_TYPE, installPreviewBridge, previewBridgeScript
- previewFiberLive preview v2: click-to-source by reading React's own dev-time internals from the running app, with NOTHING installed in the target app. Exports: PREVIEW_FIBER_LIMITS, PREVIEW_FIBER_MESSAGES, PREVIEW_FIBER_PROTOCOL, applySourceMap, decodeMappings, installPreviewFiberBridge, parseStackFrames, pickSourceFrame, ...
- previewVitePluginVite plugin: opt-in, dev-server-only wiring for the Cockpit live preview. Exports: HARNESS_PATH, constructPreview, harnessHtml, transformForPreview
- prHealthPR health: what a change between two commits MEANS, computed deterministically. Exports: FLOW_SCENARIO_MAX, MAX_LISTED, MECHANICAL_RULES, SCHEMA_VERSION, prHealth, prHealthApiManifest, renderPrHealthMarkdown
- processEnginethe driver: control semantics for a running process. Exports: StepAborted, ValidateFn, createProcessEngine, materializeCommand
- processGc`construct process gc`: the sweep nothing else runs on its own. Exports: gcProcesses
- processMachinethe process lifecycle, as a real XState machine. Exports: PROCESS_EVENTS, PROCESS_GUARDS, PROCESS_MACHINE, PROCESS_STATE_PATHS, PROCESS_STATES, RUNNING_SUBSTATES, TERMINAL_STATES, allowedEvents, ...
- processModelthe process record: what a running plan actually is, as JSON. Exports: ARTIFACT_CHANGES, LOG_PROVENANCE, MAX_LOG_ENTRIES, PENDING_CONTROLS, PROCESS_ACTION_NAMES, PROCESS_ERROR_CODES, PROCESS_REQUIRED_FIELDS, PROCESS_TOP_LEVEL_FIELDS, ...
- processStorewhere a process lives between one Cockpit session and the next. Exports: atomicWriteJson, openProcessStore, processDir, projectKey, resolveStateDir
- proofRunner(part of ) -- run the render proofs of a feature (`features/<f>/tests/generated/*.proof.test.ts`, written by `construct create proof`) and say WHAT KIND of failure each one is, in the words of the Playwright runner (t... Exports: classifyProofFailure, readTap, renderProofRunText, runProofs
- propLinksPROP-LINK: cross-references a component's DECLARED props (react-docgen, via describeComponent, ) against what every real JSX call site of that component in the project actually PASSES. Exports: checkPropLinks, propLinkViolations
- referenceLinksReference links: which identifiers in a source file point at another file, decided deterministically from the AST -- no I/O, no LLM. Exports: collectReferences, exportOrigin
- rule-change-impactDeterministic before/after impact of a PROPOSED architecture.yml rule change: "this makes 14 files newly violate PAGE-004", computed before anything is written to the real project. Exports: simulateRuleChangeImpact
- safeFetchthe ONE guarded HTTP fetch for everything that reads a URL a person typed (story fetch , real API calls , and the clone address check). Exports: DEFAULT_MAX_BYTES, DEFAULT_TIMEOUT_MS, MAX_REDIRECTS, isPublicAddress, safeFetch
- scopeGatethe per-transition invariant: after a block/step writes files, three checks run in order, reusing what already exists rather than rebuilding it: 1. Exports: affectedSet, checkScope, checkTransition, declaredFilePaths, validateAffectedSet
- scopeLinksScope/binding link graph: for ONE element of a page, which of the page's in-scope names (destructured props, useState values/setters) flow into which of that element's props, and which props the child component declar... Exports: buildScopeLinks, importOfTag, providerExposedFields, providerHookImports
- storyConsentStore(design: docs/design/ia-five-screens.md 9.6, `ia-story-consent`) -- "a story file is not a permission": the first use of any (host, url) NAMED BY A FILE needs an explicit in-Cockpit consent before the server (or, late... Exports: StoryConsentError, CONSENT_DECISIONS, CONSENT_SCOPES, consentFile, openConsentStore
- storyCoveragethe Tests screen's acceptance-criteria coverage (design 9.5: "Tests may carry `@story S2`, so the Tests screen shows acceptance coverage"). Exports: featureStoryCoverage
- storyExtractextract/verify: parse HTML fetched through safeFetch and pull out picked fields by CSS or XPath selector, using `linkedom` (ISC) instead of a hand-rolled parser or a browser-grade DOM (jsdom/happy-dom). Exports: DEFAULT_MAX_HTML_BYTES, DEFAULT_TIMEOUT_MS, MAX_FIELDS, MAX_SELECTOR_LENGTH, escapeHtml, extract, validateFields, verify
- storyFetchService(design: docs/design/ia-five-screens.md 9.3, 9.6) -- one call, `StoryApi.fetch(url)` / `POST /api/story/fetch`, one strategy chosen per link: 1. Exports: DEFAULT_STORY_FETCH_HOSTS, chooseStrategy, fetchStory, sanitizeText
- storyPatternProposal(design docs/design/ia-five-screens.md 9.6, "Preferred: AI proposes the parse pattern once") -- turns a proposed `{url, parse}` (from a model call over `storySkeleton.mjs`'s skeleton or `storyStrippedText.mjs`'s strip... Exports: PatternProposalError, proposePattern
- storySelectors(design: docs/design/ia-five-screens.md 9.6b) -- what a `story.md` front-matter `parse` value is allowed to say, and the multiple-match rule once matches exist. Exports: SelectorError, LIST_FIELDS, MAX_SELECTOR_LENGTH, SINGLE_VALUE_FIELDS, applyMultiMatchRule, validateCssSelector, validateParseSpec, validateSelectorDescriptor, ...
- storySkeleton(design docs/design/ia-five-screens.md 9.6, last bullet) -- the structure-only skeleton a login-only page is reduced to before "AI proposes a pattern" ever sees it: tag/id/class/data-testid tree, text truncated to 40... Exports: MAX_SKELETON_BYTES, MAX_TEXT_LEN, buildSkeleton
- storyStrippedText(design docs/design/ia-five-screens.md 9.6, "Preferred: AI proposes the parse pattern once") -- for a PUBLIC page (mode c, `StoryApi.fetch` strategy 'server'), the one-time pattern-proposal call sends the model a stri... Exports: MAX_STRIPPED_BYTES, buildStrippedText
- storyUiStatethe two small pieces of per-feature Story-tab state that do NOT belong in `story.md` itself: - `reviewed[feature]`: the `summaryDriftHash` (packages/core/story.mjs) the user last dismissed with "Mark reviewed" (design... Exports: openStoryUiState, storyUiStateFile
- storyVerifyExtraction(design docs/design/ia-five-screens.md 9.6, "If the user chooses extraction on every use") -- the mechanical verification step: every field an AI extraction proposed must be QUOTED TEXT found in the fetched page text,... Exports: isQuotedIn, verifyExtraction
- testAttributesthe test-attribute convention, in one place (owner decision on : events bind by `data-testid` convention, no binding file). Exports: assignTestIds, eventTestId, kebab, machineKeys, slotTestId, userEventsOf
- testClonelisting a feature's tests and cloning a LOCKED generated test so QA can edit it. Exports: CLONE_MARKER, CLONE_NAME_RE, cloneGeneratedTest, listFeatureTests, locate, parseLineage, readFeatureTest, readRegular
- testFreshnessis a CLONE still in step with the flow it was cloned from? Exports: assessClone, compareClone, diffFlow, flowStepsOf, listFeatureTestsFresh
- testGeneratorlocked, per-scenario Playwright specs generated from a feature's XState machines. Exports: GENERATED_MARKER, assertLockDeclared, assertSafeDir, beatsOf, featureMachines, generateFeatureTests, machineHash, planFeatureTests, ...
- testRunnerrun a feature's Playwright tests and say WHAT KIND of failure each one is. Exports: DEFAULT_BASE_URL, KILL_GRACE_MS, MAX_OUTPUT, MAX_SPECS, MAX_TESTS, RUN_DIR_PREFIX, RUN_TIMEOUT_MS, TRACE_DIR_PREFIX, ...
- testSpecRenderthe ONE renderer of a generated spec's executable part, shared by the generator and the step editor (testSteps.mjs), so a step document and its Playwright file can never drift apart: the generator builds steps from a... Exports: HELPERS, comment, lit, machineLine, startUrlLine, stepLines, testBlockLines
- testStepsa cloned or authored Playwright spec as a STRUCTURED STEP DOCUMENT QA edits without code. Exports: applyStepEdit, describeSteps, machineInfo, parseSpec, parseSpecRaw, previewStepEdit, readStepDocument, renderDoc, ...
- testUnitGenerator(part of ) -- locked, model-based unit test per workflow machine: every reachable state and every user-event transition, walked with @xstate/graph under node's test runner, no browser. Exports: UNIT_TEST_DEPENDENCIES, UNIT_TEST_SUFFIX, generateUnitTests, missingUnitTestDependencies, pathModel, planUnitTests, renderUnitTest, unsupportedReason
- transactionalWriterTicket 7.1 -- in-memory transactional file compiler. Exports: createTransaction
- tsFileMove"what does moving this file change?", answered by the TypeScript language service instead of a regex. Exports: MAX_CACHED, MAX_FILES, applyEdits, clearMoveCache, planFileMove
- unitSummaryUnit summaries for bots and humans: one deterministic, LLM-free, MCP-ready API that answers "what is this thing and is it healthy?" for any unit in the ecosystem (project, feature, layer, file, component, hook, servic... Exports: DETAILS, SCHEMA_VERSION, TOKEN_BUDGETS, listFeatures, listUnits, renderUnitMarkdown, resolveUnit, resolveUnitIn, ...
- verifyRunner(part of ) -- the two read-only verification blocks of a plan, run and classified: `check.types` (`construct test types`) and `check.build` (`construct test build`). Exports: checkExitCode, renderCheckText, runBuildCheck, runTypesCheck
- workflowContextEpic -- read a machine's typed context from source (AST only). Exports: contextTypeInfo, setupObjectOf
- workflowEditorEpic / -- deterministic, non-LLM XState source edits. Exports: editWorkflow
- workflowExplainEpic -- one call that explains every machine in a workflow file: plain-English narrative + scenarios + health findings, plus the text renderers shared by the CLI and the UI server. Exports: explainMachine, explainSource, renderExplained, renderFindings, renderScenarios
- workflowExtractorEpic / -- static XState machine extraction from real source. Exports: analyzeMachines, extractMachines
- workflowGeneratorTicket 7.3 -- JSON state graph -> XState v5 workflow AST generator. Exports: STATE_UNION_MARKER, compileStateUnion, compileWorkflow, eventsToEnvelope, extractEventNames, generateWorkflow, parseTypeString
- workflowNarratorEpic / -- explain an XState machine in plain English. Exports: contextSentences, delayText, guardText, humanize, initialText, machineTitle, narrateMachine, stateLabel, ...
- workflowScenariosEpic / -- scenarios and health findings for an XState machine. Exports: DEFAULT_MAX_SCENARIOS, branchOf, enumerateScenarios, findHealthIssues, graphOf, guardedSiblings
- workflowSourceEpic / -- path-scoped, read-only access to a feature's workflow files for the CLI. Exports: listWorkflowSourceFiles, readWorkflowSource, workflowsDirOf
packages/engine/units
- factsShared, pure "fact" blocks for unit summaries (deterministic, no LLM). Exports: SOURCE_EXT, createContext, fileEntry, fileFacts, healthFrom, isTestFile, testsFor, violationsFor
- flowThe FLOW section of a feature summary: how a URL reaches a feature's code and what that code is made of, drawn from the REAL import graph, not from a fixed layer order. Exports: NOTE_NO_ROUTE, buildFlow, renderFlowMarkdown
- machinesWorkflow machines of a set of workflow-layer files, narrated in plain English by the existing extractor/narrator/scenario blocks (packages/engine/workflow*.mjs). Exports: machinesOf
- registryPluggable registry of unit-kind summarizers. Exports: createUnitRegistry, defaultUnitRegistry
- route-adaptersRoute discovery as a per-framework adapter. Exports: ROUTE_ADAPTERS, discoverRoutes, featureRoutes, frameworkOf, importBindings, isStructuralFile, readRouteTable, routeAdapterFor, ...
packages/engine/units/kinds
- codeUnit kinds for code below the feature level: file + one kind per layer (component, hook, service, domain, page, controller, workflow), a single export, a route, and a package (any directory, including Construct's own... Exports: exportKind, fileKinds, packageKind, routeKind
- featureUnit kinds: project, feature, layer. Exports: CORE_LAYERS, featureKind, layerKind, projectKind, featureNames, refOf
- metaUnit kinds that describe Construct's own vocabulary: rule, envelope, generator. Exports: CONSTRUCT_ROOT, envelopeKind, generatorKind, ruleKind