API reference
Engine API
Pipeline, Context Envelope, processes, impact analysis, workflow narrator, test generator.
56 modules, 364 documented exports. Version v0.9. 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
- botRunnerthe bot runner: the `executeStep` #287'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
- 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, 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, annotateJsxSource, parseCxSrc
- 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: constructPreview, 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
- 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
- propLinksPROP-LINK: cross-references a component's DECLARED props (react-docgen, via describeComponent, #434) 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
- safeFetchthe ONE guarded HTTP fetch for everything that reads a URL a person typed (story fetch #384, real API calls #400, and the clone address check). Exports: DEFAULT_MAX_BYTES, DEFAULT_TIMEOUT_MS, MAX_REDIRECTS, isPublicAddress, safeFetch
- 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
- testAttributesthe test-attribute convention, in one place (owner decision on #284: 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 #574) -- 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, 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, ...
- workflowContextEpic #223 -- read a machine's typed context from source (AST only). Exports: contextTypeInfo, setupObjectOf
- workflowEditorEpic #57 / #61 -- deterministic, non-LLM XState source edits. Exports: editWorkflow
- workflowExplainEpic #185 -- 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 #57 / #60 -- 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 #185 / #186 -- explain an XState machine in plain English. Exports: contextSentences, delayText, guardText, humanize, initialText, machineTitle, narrateMachine, stateLabel, ...
- workflowScenariosEpic #185 / #187 -- scenarios and health findings for an XState machine. Exports: DEFAULT_MAX_SCENARIOS, branchOf, enumerateScenarios, findHealthIssues, graphOf, guardedSiblings
- workflowSourceEpic #185 / #188 -- 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