CLI automation API

Generated public TypeScript reference for @relkit/cli.

For configuration and examples, read automation.

Public imports

• @relkit/cli — 37 exports
• @relkit/cli/help — 6 exports
• @relkit/cli/editor — 1 exports
• @relkit/cli/scaffolding — 156 exports

All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API’s inline sample, a maintained repository usage, or the shared module walkthrough.

cli-help-model.ts

Static CLI help metadata; rendering never evaluates projects or starts support services.

“./cli-help-model.types.js” (namespace export)

Re-exports all named exports from the “./cli-help-model.types.js” module.

Signature

export * from "./cli-help-model.types.js";

Source

findCliHelp

Resolves a command path in the static tree without executing the command.

Signature

declare const findCliHelp: (path: readonly string[]) => CliHelpCommand | undefined;

Source

getCliHelpModel

Returns a frozen static help tree without acquiring command services.

Signature

declare const getCliHelpModel: (version: string) => CliHelpModel;

Source

cli-help-model.types.ts

One static option contract consumed by terminal and documentation renderers.

CliHelpArgument (interface)

Positional argument metadata; this describes syntax without parsing input.

Signature

export interface CliHelpArgument {
  readonly name: string;
  readonly required: boolean;
  readonly description: string;
}

Source

CliHelpCommand (interface)

Pure command tree shared by generated documentation and CLI help.

Signature

export interface CliHelpCommand {
  readonly name: string;
  readonly description: string;
  readonly usage: string;
  readonly examples: readonly { readonly command: string; readonly description: string }[];
  readonly options: readonly CliHelpOption[];
  readonly arguments: readonly CliHelpArgument[];
  readonly commands: readonly CliHelpCommand[];
}

Source

CliHelpModel (interface)

Versioned root command; returned instances are deeply frozen.

Signature

export interface CliHelpModel extends CliHelpCommand {
  readonly version: string;
}

Source

CliHelpOption (interface)

One static option contract consumed by terminal and documentation renderers.

Signature

export interface CliHelpOption {
  readonly name: string;
  readonly aliases?: readonly string[];
  readonly type: "boolean" | "string" | "integer" | "choice" | "key=value";
  readonly description: string;
  readonly values?: readonly string[];
  readonly repeatable?: boolean;
}

Source

dev-session.ts

Owns development session state and its public synchronous/Promise facade over scoped native operations.

DevSession (class)

Public Promise/synchronous facade over one native session owner.

Signature

declare class DevSession {
  constructor(options: DevOptions);
}

Source

attach (method)

Captures the acquired engine for the public compatibility facade. @param engine - Scoped operations.

Signature

declare const attach: (engine: DevSessionEngine) => void;

Source

start (method)

Acquires the manual public owner once; concurrent callers share startup.

Signature

declare const start: () => Promise<this>;

Source

activate (method)

Joins one requested source activation through the captured engine.

Signature

declare const activate: (version?: number, files?: readonly string[]) => Promise<boolean>;

Source

notifySourceChange (method)

Forwards an explicit source version to the serialized activation owner.

Signature

declare const notifySourceChange: (version: number, files?: readonly string[]) => Promise<boolean>;

Source

waitForShutdown (method)

Joins the captured session’s shared shutdown completion.

Signature

declare const waitForShutdown: () => Promise<void>;

Source

stop (method)

Closes the manual public owner and joins its shared release.

Signature

declare const stop: <Reason>(reason?: Reason | Error) => Promise<void>;

Source

drain (method)

Joins a retired generation’s drain through the captured engine.

Signature

declare const drain: (
  previous: StartedCandidate,
  active: SupervisorCandidateToken,
) => Promise<void>;

Source

resolveShutdownPromise (method)

Completes the retained synchronous compatibility shutdown latch.

Signature

declare const resolveShutdownPromise: () => void;

Source

clearSignals (method)

Closes the captured signal registration and its synchronous facade.

Signature

declare const clearSignals: () => void;

Source

markStopping (method)

Closes synchronous startup and activation admission.

Signature

declare const markStopping: () => void;

Source

runSynchronous (method)

Executes the retained synchronous watcher edge.

Signature

declare const runSynchronous: <A, E>(effect: Effect.Effect<A, E>) => A;

Source

projectRoot (property)

Signature

readonly projectRoot: string

Source

options (property)

Signature

readonly options: DevOptions

Source

inspectionIdentity (property)

Signature

readonly inspectionIdentity: { readonly sessionId: string; readonly token: string; }

Source

abortController (property)

Signature

readonly abortController: AbortController

Source

state (property)

Signature

readonly state: Ref.Ref<DevSessionState>

Source

log (property)

Signature

readonly log: DevLog

Source

observability (property)

Signature

readonly observability: SupervisorObservability

Source

stateMachine (property)

Signature

readonly stateMachine: SupervisorStateMachine

Source

proxy (property)

Signature

readonly proxy: SupervisorProxy

Source

dev.ts

DevActivationFingerprint

Signature

declare const DevActivationFingerprint: DevActivationFingerprint;

Source

DevLocalServices

Signature

declare const DevLocalServices: DevLocalServices;

Source

DevLog

Signature

declare const DevLog: DevLog;

Source

DevLogEvent

Signature

declare const DevLogEvent: DevLogEvent;

Source

DevOptions

Signature

declare const DevOptions: DevOptions;

Source

DevSession

Signature

declare const DevSession: typeof DevSession;

Source

acquireDevSessionEffect

Acquires a session in the caller’s native lifetime.

Signature

declare const acquireDevSessionEffect: (
  _options: DevOptions,
) => Effect.Effect<
  DevSession,
  CliAdapterError,
  | Scope
  | CliDevSupervisor
  | CliFileSystem
  | CliCleanup
  | CliPortProbe
  | CliSourceWatch
  | CliInspectorSupport
>;

Source

runDev

Runs development until the session’s scoped shutdown completes.

Signature

declare const runDev: (options: DevOptions) => Promise<void>;

Source

startDev

Starts and returns the manually owned public development session.

Signature

declare const startDev: (options: DevOptions) => Promise<DevSession>;

Source

dev.types.ts

Explicit development policy keeps resourceful work in the session’s Effect scope.

DevActivationFingerprint (type alias)

Full activation identity or an explicit foreign identity provider.

Signature

type DevActivationFingerprint =
  | RuntimeActivationFingerprint
  | ((
      candidate: StartedCandidate,
    ) => RuntimeActivationFingerprint | PromiseLike<RuntimeActivationFingerprint>);

Source

DevLocalServices (interface)

Existing manually owned local service compatibility boundary.

Signature

export interface DevLocalServices {
  /**
   * Joins native local resource cleanup before session shutdown completes.
   * @returns Shared local owner release completion.
   */
  readonly close: () => Promise<void>;
}

Source

DevLog (type alias)

Synchronous native logging callback; failures cannot change session lifecycle.

Signature

type DevLog = (event: DevLogEvent) => void;

Source

DevLogEvent (interface)

One admitted development log, rendered by the existing terminal policy.

Signature

export interface DevLogEvent {
  readonly level: LogLevel;
  readonly event: string;
  readonly fields?: Readonly<Record<string, JsonValue>>;
}

Source

DevOptions (interface)

Development host inputs; all process/session resources belong to one lifetime.

Signature

export interface DevOptions {
  readonly projectRoot?: string;
  readonly compile: CandidateCompile;
  readonly activationFingerprint?: DevActivationFingerprint;
  /**
   * Reuses the prepared identity only for a child installed from that validated receipt.
   * @param candidate - SDK child associated with one immutable preparation result.
   * @returns Its accepted identity, or absence for an independently checked fallback child.
   */
  readonly preparedActivationFingerprint?: (
    candidate: StartedCandidate,
  ) => RuntimeActivationFingerprint | undefined;
  /**
   * Proves application readiness after mandatory SDK cohort verification.
   * @param candidate - Unpublished child already matched to its graph/cohort.
   * @param signal - Activation cancellation consumed by readiness HTTP work.
   * @returns Joined proof or typed rejection before switching traffic.
   */
  readonly candidateVerificationEffect?: (
    candidate: StartedCandidate,
    signal: AbortSignal,
  ) => Effect.Effect<void, CliAdapterError>;
  /** Releases any request retained as the candidate's real route proof after publication. */
  readonly candidateVerificationPublished?: (candidate: StartedCandidate) => void;
  /** Releases a request retained by a candidate that could not be published. */
  readonly candidateVerificationRejected?: (candidate: StartedCandidate) => void;
  /**
   * Checks the final input epoch in the atomic traffic-switch turn.
   * @param candidate - Verified unpublished child.
   * @returns False when its prepared input epoch is obsolete.
   */
  readonly candidateAdmission?: (candidate: StartedCandidate) => boolean;
  readonly hostname?: string;
  readonly candidateHostname?: string;
  readonly stablePort?: number;
  readonly generatedDirectory?: string;
  readonly environment?: Readonly<Record<string, string | undefined>>;
  readonly maxStartupOutputBytes?: number;
  readonly candidateStopTimeoutMs?: number;
  readonly healthTimeoutMs?: number;
  /** Permits immutable prepared candidates to overlap independent health reads. */
  readonly candidateVerificationConcurrentHealth?: boolean;
  /** Native verification transport; prepared sessions restrict bearer credentials to internal probes. */
  readonly candidateVerificationFetch?: typeof fetch;
  readonly drainTimeoutMs?: number;
  readonly inspector?: Pick<InspectionBridgeOptions, "host" | "port"> | false;
  readonly inspectionRecords?: InspectionBridgeOptions["records"];
  /** Bridge credentials shared by every generation; generated per session when omitted. */
  readonly inspectionIdentity?: { readonly sessionId: string; readonly token: string };
  /**
   * Reads the bridge policy an accepted generation was built with.
   * @param generationToken - Promoted generation.
   * @returns Its policy, or undefined when the session keeps its current bridge.
   */
  readonly inspectionPolicy?: (generationToken: number) => DevInspectorPolicy | undefined;
  /**
   * Observes the bridge policy of every promoted generation, changed or not, once the
   * retired generation has drained.
   * @param policy - Bridge policy the session now serves.
   * @returns Completion after policy-owned resources are released or retained.
   */
  readonly inspectionApplied?: (policy: DevInspectorPolicy) => Effect.Effect<void>;
  /**
   * Observes a generation that was not promoted.
   * @param generationToken - Rejected, failed or superseded generation.
   * @returns Completion after resources prepared for it are rolled back.
   */
  readonly inspectionRejected?: (generationToken: number) => Effect.Effect<void>;
  /** Grace period after backend activation before optional inspector acquisition. */
  readonly supportStartupDelayMs?: number;
  readonly spawn?: typeof Bun.spawn;
  readonly signal?: AbortSignal;
  readonly installSignalHandlers?: boolean;
  readonly logger?: Omit<LoggerOptions, "component">;
  readonly onLog?: DevLog;
  /**
   * Consumes a projected native log envelope without lifecycle authority.
   * @param record - Existing structured log record.
   * @param origin - Declared process source.
   * @returns No value after synchronous admission.
   */
  readonly onRecord?: (record: LogRecord, origin: "application" | "relkit" | "inspector") => void;
  /**
   * Optionally intercepts a stable-proxy request before application routing.
   * @param request - Native incoming request.
   * @returns A native response receipt or absence to delegate to the backend.
   */
  readonly intercept?: (request: Request) => Promise<Response> | undefined;
  /**
   * Closes callback admission when shutdown begins.
   * @returns No value; resource cleanup remains with the session Scope.
   */
  readonly onStopping?: () => void;
  readonly terminal?: {
    readonly verbose?: boolean;
    readonly color?: boolean;
    readonly columns?: number;
  };
  readonly observability?: Omit<SupervisorObservabilityOptions, "activationFingerprint">;
  readonly localServices?: DevLocalServices;
  /** Native orchestration hook; acquired local owners close in the same session graph. */
  readonly localServicesEffect?: Effect.Effect<void>;
  /**
   * Native invalidation hook, captured by the owning compiler/cache service.
   * @param files - Admitted changed paths.
   * @returns Lazy session cache invalidation before the next compilation.
   */
  readonly sourceChangedEffect?: (files: readonly string[]) => Effect.Effect<void>;
}

Source

editor.ts

initialize

Creates the synchronous editor plugin using the editor’s own TypeScript instance.

Signature

declare const initialize: (modules: EditorModules) => ts.server.PluginModule;

Source

index.ts

“./commands/dev.js” (namespace export)

Re-exports all named exports from the “./commands/dev.js” module.

Signature

export * from "./commands/dev.js";

Source

“./main.js” (namespace export)

Re-exports all named exports from the “./main.js” module.

Signature

export * from "./main.js";

Source

tooling.ts

Exposes finite native ownership, byte identities and import policy to repository tooling through a declared package boundary. These exports acquire no CLI session; callers own cancellation, compilation and publication scopes.

DevSnapshot

Signature

declare const DevSnapshot: Struct<{
  readonly version: Literal<1>;
  readonly fingerprint: String;
  readonly graphHash: String;
  readonly graphFile: String;
  readonly activationFile: String;
  readonly manifestFile: String;
  readonly runtimeIntegrationsFile: String;
  readonly jobsManifestFile: optionalKey<String>;
  readonly localServicesFile: optionalKey<String>;
  readonly entrypoint: String;
  readonly importIndex: String;
  readonly activation: Struct<{
    readonly graphHash: String;
    readonly manifestHash: String;
    readonly jobsManifestHash: optionalKey<String>;
    readonly runtimeIntegrationsPlanHash: String;
    readonly localServicesPlanHash: optionalKey<String>;
  }>;
  readonly tools: Struct<{
    readonly layout: Literal<1>;
    readonly bun: String;
    readonly effect: String;
    readonly typescript: String;
    readonly relkit: String;
    readonly platform: Literals<
      readonly ["darwin-arm64", "darwin-x64", "linux-arm64", "linux-x64"]
    >;
  }>;
  readonly inspector: optionalKey<
    Struct<{
      readonly enabled: Boolean;
      readonly connection: Struct<{ readonly host: String; readonly port: Number }>;
      readonly maxPreviewBytes: Number;
    }>
  >;
  readonly ports: optionalKey<Struct<{ readonly backend: Number }>>;
  readonly readiness: Union<
    readonly [
      Struct<{
        readonly kind: Literal<"route">;
        readonly path: String;
        readonly status: Literal<200>;
        readonly body: String;
      }>,
      Struct<{ readonly kind: Literal<"graph">; readonly routeTableHash: String }>,
    ]
  >;
  readonly inputs: $Array<
    Struct<{ readonly path: String; readonly hash: String; readonly bytes: Number }>
  >;
  readonly typecheckInputs: Struct<{
    readonly files: $Array<
      Struct<{ readonly path: String; readonly hash: String; readonly bytes: Number }>
    >;
    readonly observations: $Array<
      Union<
        readonly [
          Struct<{
            readonly kind: Literals<readonly ["fileExists", "directoryExists"]>;
            readonly path: Union<readonly [String, Literal<".">]>;
            readonly exists: Boolean;
          }>,
          Struct<{
            readonly kind: Literals<readonly ["directories", "entries"]>;
            readonly path: Union<readonly [String, Literal<".">]>;
            readonly entries: $Array<String>;
          }>,
        ]
      >
    >;
  }>;
  readonly dependencies: $Array<
    Struct<{
      readonly name: String;
      readonly version: String;
      readonly root: String;
      readonly members: $Array<
        Struct<{ readonly path: String; readonly hash: String; readonly bytes: Number }>
      >;
    }>
  >;
  readonly artifacts: $Array<
    Struct<{ readonly path: String; readonly hash: String; readonly bytes: Number }>
  >;
  readonly routeImports: $Array<
    Struct<{ readonly routeId: String; readonly members: $Array<String> }>
  >;
}>;

Source

SnapshotFileOperations

Signature

declare const SnapshotFileOperations: SnapshotFileOperations;

Source

SnapshotFiles

Signature

declare const SnapshotFiles: typeof SnapshotFiles;

Source

SnapshotPointer

Signature

declare const SnapshotPointer: Struct<{
  readonly version: Literal<1>;
  readonly generation: String;
}>;

Source

narrowEffectImportPlugin

Signature

declare const narrowEffectImportPlugin: () => Bun.BunPlugin;

Source

narrowEffectImports

Signature

declare const narrowEffectImports: (source: string, path: string) => string;

Source

ownedNativePromise

Signature

declare const ownedNativePromise: <A>(
  operation: string,
  run: (signal: AbortSignal) => PromiseLike<A>,
) => Effect<Awaited<A>, CliAdapterError, never>;

Source

snapshotDigest

Signature

declare const snapshotDigest: (bytes: Uint8Array | string) => string;

Source

snapshotFilesLive

Signature

declare const snapshotFilesLive: Layer<SnapshotFiles, never, never>;

Source

main-generator.ts

Lazily loads CLI-owned scaffolding after command selection, validates the retained generator facade and preserves the public unavailable-API diagnostic.

isGeneratorApi

Validates the minimal foreign facade while preserving its original identity.

Signature

declare const isGeneratorApi: (value: unknown) => value is CreateRelkitGeneratorApi;

Source

loadCreateRelkit

Imports the optional generator using the existing public Promise contract.

Throws

The established unavailable-API failure.

Signature

declare const loadCreateRelkit: () => Promise<CreateRelkitGeneratorApi>;

Source

loadCreateRelkitEffect

Imports one foreign namespace lazily without creating a nested command runtime.

Signature

declare const loadCreateRelkitEffect: Effect.Effect<
  CreateRelkitGeneratorApi,
  CliAdapterError,
  never
>;

Source

main-support-types.ts

Defines CLI invocation I/O, presentation, runtime, and generator adapter contracts.

CliCommandContext (interface)

Borrowed command inputs; all resource owners live in the invocation’s service graph.

Signature

export interface CliCommandContext {
  /** Selected public command. */
  readonly command: string;
  /** Remaining public arguments. */
  readonly args: readonly string[];
  /** Whether output uses the established JSON protocol. */
  readonly json: boolean;
  /** Caller and native termination signals combined before prompting. */
  readonly signal: AbortSignal;
  /** Optional native terminal detection override. */
  readonly tty?: boolean;
  /** Optional borrowed output sinks. */
  readonly io?: CliIo;
  /** Public output/error projection. */
  readonly reporter: CliReporter;
  /** Synchronous callback into the scoped logger owner. */
  readonly log: CliLogger;
  /** Optional synchronous callback into the scoped status owner. */
  readonly onProgress?: (message: string) => void;
  /** Whether noninteractive continuous integration rules apply. */
  readonly ci?: boolean;
  /** Explicit working directory override. */
  readonly cwd?: string;
  /** Optional foreign prompt adapter, supplied before any prompt is admitted. */
  readonly promptDriver?: PromptDriver;
  /** Whether this invocation may ask the user for missing inputs. */
  readonly interactive?: boolean;
}

Source

CliFailure (type alias)

Original public error object enriched with stable CLI status metadata.

Signature

type CliFailure = Error & {
  /** Stable public diagnostic code. */
  readonly code: string;
  /** Established native exit status. */
  readonly exitCode: number;
  /** Native termination signal when one caused the failure. */
  readonly signal?: "SIGINT" | "SIGTERM" | "SIGHUP";
};

Source

CliIo (interface)

Borrowed synchronous output sinks; the invocation never closes these streams.

Signature

export interface CliIo {
  /** Writes one already formatted public output line. */
  readonly stdout: (line: string) => void;
  /** Writes one already formatted diagnostic line. */
  readonly stderr: (line: string) => void;
}

Source

CliLogger (type alias)

Synchronous native callback bridge to the invocation’s scoped logging queue.

Signature

type CliLogger = (
  level: LogLevel,
  message: string,
  fields?: Readonly<Record<string, unknown>>,
) => void;

Source

CliReporter (interface)

Established public JSON/human presentation contract.

Signature

export interface CliReporter {
  /** Emits an untrusted domain result with optional human presentation. */
  readonly output: (value: unknown, human?: string) => void;
  /** Emits the established public failure code and message. */
  readonly error: (code: string, message: string) => void;
}

Source

CliRuntime (interface)

Optional public invocation injection; defaults are acquired lazily by the selected domain.

Signature

export interface CliRuntime {
  /** Borrowed public output sinks. */
  readonly io?: CliIo;
  /** Explicit package version override used by public help/version output. */
  readonly version?: string;
  /** Explicit terminal detection override. */
  readonly tty?: boolean;
  /** Explicit continuous integration mode. */
  readonly ci?: boolean;
  /** Continuing caller cancellation; never replaced by a domain-owned controller. */
  readonly signal?: AbortSignal;
  /** Whether the invocation installs temporary native termination handlers. */
  readonly installSignalHandlers?: boolean;
  /** Optional individual foreign SDK loader; unused commands never call it. */
  readonly loadCreateRelkit?: () => Promise<CreateRelkitGeneratorApi>;
  /** Explicit project discovery root. */
  readonly cwd?: string;
  /** Optional native prompt adapter retaining its original public contract. */
  readonly promptDriver?: PromptDriver;
}

Source

CreateRelkitGeneratorApi (interface)

Narrow compatible generator SDK; domain values remain opaque until their owner validates them.

Signature

export interface CreateRelkitGeneratorApi {
  /** Parses the generator's existing synchronous create contract. */
  readonly normalizeCreateOptions: (
    args: readonly string[],
    context: { readonly json: boolean },
  ) => unknown;
  /** Executes the generator-owned transaction with its native cancellation receipt. */
  readonly generateProject: (
    options: unknown,
    context: CliCommandContext,
  ) => unknown | Promise<unknown>;
  /** Resolves missing create inputs without adding duplicate CLI confirmation. */
  readonly resolveCreateOptionsDetails?: (
    args: readonly string[],
    context: {
      readonly json: boolean;
      readonly interactive: boolean;
      readonly signal?: AbortSignal;
      readonly promptDriver?: PromptDriver;
    },
  ) => Promise<{ readonly options: unknown; readonly prompted: boolean }>;
  /** Previews a validated create plan without mutation. */
  readonly planCreate?: (
    options: unknown,
    context?: { readonly cwd?: string },
  ) => Promise<CreateScaffoldPlan>;
  /** Resolves the existing add selection flow with caller cancellation. */
  readonly resolveAddRequestDetails?: (
    args: readonly string[],
    context: {
      readonly cwd?: string;
      readonly interactive: boolean;
      readonly signal?: AbortSignal;
      readonly promptDriver?: PromptDriver;
    },
  ) => Promise<{ readonly request: AddRequest; readonly prompted: boolean }>;
  /** Previews the existing add plan. */
  readonly planAdd?: (request: AddRequest) => Promise<ScaffoldPlan>;
  /** Applies one generator-owned add transaction and its cleanup policy. */
  readonly applyScaffoldPlan?: (
    plan: ScaffoldPlan,
    context?: ApplyScaffoldContext,
  ) => Promise<AddResult>;
}

Source

main-support.ts

Presents CLI output, help and terminal failures while keeping command cancellation scoped to its invocation; optional scaffold loading has a separate lazy owner.

“./main-support-types.js” (namespace export)

Re-exports all named exports from the “./main-support-types.js” module.

Signature

export * from "./main-support-types.js";

Source

CLI_EXIT_CODES

Stable command, usage and native-signal exit statuses.

Signature

declare const CLI_EXIT_CODES: Readonly<{
  success: 0;
  failure: 1;
  usage: 2;
  sigint: 130;
  sigterm: 143;
  sighup: 129;
}>;

Source

CLI_VERSION

Version of this installed CLI package.

Signature

declare const CLI_VERSION: string;

Source

createReporter

Builds the existing result/error presentation policy.

Signature

declare const createReporter: (json: boolean, io: CliIo) => CliReporter;

Source

errorMessage

Formats an existing terminal diagnostic without changing Error identity.

Signature

declare const errorMessage: (error: unknown) => string;

Source

fail

Constructs the typed product failure while retaining public code/exit fields.

Signature

declare const fail: (
  code: string,
  message: string,
  exitCode?: number,
  signal?: "SIGINT" | "SIGTERM" | "SIGHUP",
) => CliFailureError;

Source

failSignal

Preserves signal-specific public cancellation codes.

Signature

declare const failSignal: (signal: "SIGINT" | "SIGTERM" | "SIGHUP") => CliFailure;

Source

helpPayload

Projects public machine-readable help from pure command metadata.

Signature

declare const helpPayload: (
  version: string,
  command: string | readonly string[] | undefined,
) => unknown;

Source

helpText

Formats the existing compact human help.

Signature

declare const helpText: (version: string, command: string | undefined) => string;

Source

installSignals

Installs native process cancellation for one invocation owner.

Signature

declare const installSignals: (controller: AbortController) => () => void;

Source

isGeneratorApi

Signature

declare const isGeneratorApi: (value: unknown) => value is CreateRelkitGeneratorApi;

Source

loadCreateRelkit

Signature

declare const loadCreateRelkit: () => Promise<CreateRelkitGeneratorApi>;

Source

loadCreateRelkitEffect

Signature

declare const loadCreateRelkitEffect: Effect<CreateRelkitGeneratorApi, CliAdapterError, never>;

Source

toFailure

Applies the terminal invocation error policy after owned cleanup completes.

Signature

declare const toFailure: (error: unknown, signal: AbortSignal) => CliFailure;

Source

main.ts

Owns one native CLI invocation, its cancellation signals, presentation and scoped cleanup.

“./cli-help-model.js” (namespace export)

Re-exports all named exports from the “./cli-help-model.js” module.

Signature

export * from "./cli-help-model.js";

Source

“./main-support.js” (namespace export)

Re-exports all named exports from the “./main-support.js” module.

Signature

export * from "./main-support.js";

Source

main

Runs the native process entry point using the same invocation owner.

Signature

declare const main: (argv?: readonly string[]) => Promise<number>;

Source

runCli

Executes one invocation with one service graph and scoped resources.

Signature

declare const runCli: (argv?: readonly string[], runtime?: CliRuntime) => Promise<number>;

Source

add-name.ts

Normalizes authored artifact names into stable file stems, identifiers and logical ID segments before add planning can mutate project files.

NormalizedArtifactName (interface)

Normalized user label, file stem, binding identifier and descriptor ID segment.

Signature

export interface NormalizedArtifactName {
  readonly input: string;
  readonly fileStem: string;
  readonly identifier: string;
  readonly idSegment: string;
}

Source

normalizeArtifactName

Normalizes one friendly label for source files, bindings, and stable IDs.

Signature

declare const normalizeArtifactName: (input: string) => NormalizedArtifactName;

Source

add-options.ts

Builds normalized existing-project add requests from CLI arguments and enforces headless requirements before interactive resolution.

normalizeAddRequest

Parses one complete non-interactive relkit add request.

Signature

declare const normalizeAddRequest: (
  args: readonly string[],
  context?: { readonly cwd?: string },
) => AddRequest;

Source

add-output.ts

Formats scaffold plans and apply results into terminal or JSON output while preserving verification failures and actionable next steps.

formatAddResult

Formats the completed add result and verification status.

Signature

declare const formatAddResult: (result: AddResult) => string;

Source

formatScaffoldPlan

Formats a scaffold plan for review before mutation.

Signature

declare const formatScaffoldPlan: (plan: ScaffoldPlan) => string;

Source

add-plan.ts

Composes project discovery, artifact planning and request-local builder state into an immutable scaffold plan before transaction acquisition.

ScaffoldPlanning (class)

Cohesive discovery and planning authority, with isolated Ref state per request.

Signature

declare class ScaffoldPlanning

Source

planAdd

Preserves the existing public Promise API and stable rejection constructors.

Signature

declare const planAdd: (request: AddRequest) => Promise<ScaffoldPlan>;

Source

planAddEffect

Plans an artifact through an explicitly supplied planning service.

Signature

declare const planAddEffect: (
  request: AddRequest,
) => Effect.Effect<ScaffoldPlan, GeneratorIoError | GeneratorDomainError, ScaffoldPlanning>;

Source

scaffoldPlanningLive

Planning Layer captures only declaration discovery and filesystem authority.

Signature

declare const scaffoldPlanningLive: Layer.Layer<
  ScaffoldPlanning,
  never,
  GeneratorFileSystem | ProjectDiscoveryServiceTag
>;

Source

add-resolver.ts

Composes add discovery and interactive resolution into one request workflow, preserving typed cancellation and validation failures.

AddResolution (class)

Ordered interactive-add resolution, distinct from applying the user’s final consent.

Signature

declare class AddResolution

Source

ResolveAddContext

Signature

declare const ResolveAddContext: ResolveAddContext;

Source

ResolvedAddRequest

Signature

declare const ResolvedAddRequest: ResolvedAddRequest;

Source

addResolutionLive

Captures declaration discovery, filesystem reads and prompt input at the owning Layer boundary.

Signature

declare const addResolutionLive: Layer.Layer<
  AddResolution,
  never,
  GeneratorFileSystem | GeneratorPrompt | ProjectDiscoveryServiceTag
>;

Source

resolveAddRequest

Preserves the existing normalized-request Promise API.

Signature

declare const resolveAddRequest: (
  args: readonly string[],
  context?: ResolveAddContext,
) => Promise<AddRequest>;

Source

resolveAddRequestDetails

Preserves the existing detailed Promise API and add-flow consent behavior.

Signature

declare const resolveAddRequestDetails: (
  args: readonly string[],
  context?: ResolveAddContext,
) => Promise<ResolvedAddRequest>;

Source

resolveAddRequestDetailsEffect

Resolves a request through explicit add-resolution authority while retaining consent metadata.

Signature

declare const resolveAddRequestDetailsEffect: (
  args: ReadonlyArray<string>,
  context?: ResolveAddContext | undefined,
) => Effect.Effect<
  ResolvedAddRequest,
  GeneratorIoError | GeneratorPromptError | GeneratorDomainError,
  AddResolution
>;

Source

add-resolver.types.ts

Composes add discovery and interactive resolution into one request workflow, preserving typed cancellation and validation failures. This companion contains the shared planning contracts without executing work.

AddResolutionService (interface)

Finite add-resolution owner with explicit discovery, prompt and source authority.

Signature

export interface AddResolutionService {
  /**
   * Resolves missing interactive add choices against source-discovered facts.
   * @param args - Literal flag and positional arguments.
   * @param context - Caller-owned settings and cancellation.
   * @returns An Effect returning a validated request and whether resolution prompted.
   */
  readonly resolve: (
    args: readonly string[],
    context: ResolveAddContext,
  ) => Effect.Effect<
    ResolvedAddRequest,
    GeneratorDomainError | GeneratorIoError | GeneratorPromptError
  >;
}

Source

ResolveAddContext (interface)

Existing interactive-add resolution context.

Signature

export interface ResolveAddContext {
  readonly cwd?: string;
  readonly interactive?: boolean;
  readonly promptDriver?: PromptDriver;
  readonly signal?: AbortSignal;
}

Source

ResolvedAddRequest (interface)

Existing resolved add request and consent-relevant prompted flag.

Signature

export interface ResolvedAddRequest {
  readonly request: AddRequest;
  readonly prompted: boolean;
}

Source

add-transaction.ts

Acquires file and lock snapshots before applying an immutable scaffold plan; commit, rollback and cleanup retain the original transaction owner.

AddCommandResult

Signature

declare const AddCommandResult: AddCommandResult;

Source

ApplyScaffoldContext

Signature

declare const ApplyScaffoldContext: ApplyScaffoldContext;

Source

ScaffoldTransaction (class)

Owns file mutation, install/check and rollback within one finite transaction scope.

Signature

declare class ScaffoldTransaction

Source

applyScaffoldPlan

Preserves the Promise transaction API and canonical public error constructors.

Signature

declare const applyScaffoldPlan: (
  plan: ScaffoldPlan,
  context?: ApplyScaffoldContext,
) => Promise<AddResult>;

Source

applyScaffoldPlanEffect

Applies a plan with a caller-supplied transaction service.

Signature

declare const applyScaffoldPlanEffect: (
  plan: ScaffoldPlan,
  context?: ApplyScaffoldContext | undefined,
) => Effect.Effect<
  AddResult,
  GeneratorIoError | GeneratorProcessError | GeneratorDomainError,
  ScaffoldTransaction
>;

Source

scaffoldTransactionLive

Transaction Layer captures explicit filesystem and process authority once.

Signature

declare const scaffoldTransactionLive: Layer.Layer<
  ScaffoldTransaction,
  never,
  GeneratorFileSystem | GeneratorProcess
>;

Source

add-transaction.types.ts

Acquires file and lock snapshots before applying an immutable scaffold plan; commit, rollback and cleanup retain the original transaction owner. This companion contains the shared planning contracts without executing work.

AddCommandResult (interface)

Existing command-runner result compatibility surface.

Signature

export interface AddCommandResult extends GeneratorCommandResult {}

Source

ApplyScaffoldContext (interface)

Existing scaffold transaction settings, preserving all caller injection points.

Signature

export interface ApplyScaffoldContext {
  readonly commandRunner?: GeneratorCommandRunner;
  readonly bunExecutable?: string;
  readonly relkitExecutable?: string;
  readonly signal?: AbortSignal;
  /**
   * Reports the current step through the caller's progress sink.
   * @param message - User-facing progress text for the current step.
   * @returns Completion after the sink receives one progress message.
   */
  readonly onProgress?: (message: string) => void;
  readonly deferVerification?: boolean;
}

Source

ScaffoldTransactionService (interface)

Scoped add-transaction owner; infrastructure remains an explicit Layer dependency.

Signature

export interface ScaffoldTransactionService {
  /**
   * Applies planned files, installs/checks when required and rolls back failure.
   * @param plan - Immutable conflict-checked scaffold plan.
   * @param context - Caller-owned settings and cancellation.
   * @returns A scoped Effect returning the unchanged AddResult after all owned cleanup settles.
   */
  readonly apply: (
    plan: ScaffoldPlan,
    context: ApplyScaffoldContext,
  ) => Effect.Effect<AddResult, GeneratorDomainError | GeneratorIoError | GeneratorProcessError>;
}

Source

index.ts

CLI-owned existing-project scaffolding; creation remains a lightweight dependency.

“./add-name.js” (namespace export)

Re-exports all named exports from the “./add-name.js” module.

Signature

export * from "./add-name.js";

Source

“./add-options.js” (namespace export)

Re-exports all named exports from the “./add-options.js” module.

Signature

export * from "./add-options.js";

Source

“./add-output.js” (namespace export)

Re-exports all named exports from the “./add-output.js” module.

Signature

export * from "./add-output.js";

Source

“./add-plan.js” (namespace export)

Re-exports all named exports from the “./add-plan.js” module.

Signature

export * from "./add-plan.js";

Source

“./add-resolver.js” (namespace export)

Re-exports all named exports from the “./add-resolver.js” module.

Signature

export * from "./add-resolver.js";

Source

“./add-transaction.js” (namespace export)

Re-exports all named exports from the “./add-transaction.js” module.

Signature

export * from "./add-transaction.js";

Source

“./plan-builder.js” (namespace export)

Re-exports all named exports from the “./plan-builder.js” module.

Signature

export * from "./plan-builder.js";

Source

“./project-catalog.js” (namespace export)

Re-exports all named exports from the “./project-catalog.js” module.

Signature

export * from "./project-catalog.js";

Source

“./project-discovery-types.js” (namespace export)

Re-exports all named exports from the “./project-discovery-types.js” module.

Signature

export * from "./project-discovery-types.js";

Source

“./project-discovery.js” (namespace export)

Re-exports all named exports from the “./project-discovery.js” module.

Signature

export * from "./project-discovery.js";

Source

“./render-database.js” (namespace export)

Re-exports all named exports from the “./render-database.js” module.

Signature

export * from "./render-database.js";

Source

“./source-edit.js” (namespace export)

Re-exports all named exports from the “./source-edit.js” module.

Signature

export * from "./source-edit.js";

Source

“create-relkit” (namespace export)

Re-exports all named exports from the “create-relkit” module.

Signature

export * from "create-relkit";

Source

plan-builder.ts

Exposes the synchronous planning facade over request-local Effect state; file writes remain deferred until the transaction applies the resulting plan.

PlanBuilder (class)

Per-request Effect owner with synchronous and Promise compatibility edges.

Signature

declare class PlanBuilder

Source

read (method)

Reads source through the Promise compatibility edge.

Signature

declare const read: (path: string) => Promise<string>;

Source

create (method)

Plans file creation through the Promise compatibility edge.

Signature

declare const create: (path: string, content: string, mode?: number) => Promise<void>;

Source

update (method)

Plans a source update through the Promise compatibility edge.

Signature

declare const update: (path: string, transform: (source: string) => string) => Promise<void>;

Source

dependency (method)

Preserves the existing synchronous dependency API.

Signature

declare const dependency: (name: ScaffoldDependencyName) => void;

Source

registerArtifact (method)

Preserves the existing synchronous artifact registration API.

Signature

declare const registerArtifact: (
  kind: DiscoveredArtifact["kind"],
  value: PlannedArtifactInput,
) => void;

Source

registerProfile (method)

Preserves the existing synchronous profile registration API.

Signature

declare const registerProfile: (profile: DiscoveredProfile) => void;

Source

script (method)

Preserves the existing synchronous script API.

Signature

declare const script: (name: string, command: string) => void;

Source

warning (method)

Preserves the existing synchronous warning API.

Signature

declare const warning: (code: string, message: string) => void;

Source

nextStep (method)

Preserves the existing synchronous next-step API.

Signature

declare const nextStep: (command: string) => void;

Source

envExample (method)

Preserves the environment-example Promise API.

Signature

declare const envExample: (name: string, value?: string) => Promise<void>;

Source

gitignore (method)

Preserves the gitignore Promise API.

Signature

declare const gitignore: (pattern: string) => Promise<void>;

Source

finish (method)

Preserves the immutable plan Promise API.

Signature

declare const finish: () => Promise<ScaffoldPlan>;

Source

relative (method)

Converts a source path into its existing project-relative representation.

Signature

declare const relative: (absolutePath: string) => string;

Source

project-catalog.ts

Resolves declared package versions for selected scaffold dependencies using installed project metadata and the portable release catalog.

resolveProjectDependencies

Preserves the project catalog Promise API and authored alias ownership.

Signature

declare const resolveProjectDependencies: (
  projectRoot: string,
  dependencies: Readonly<Record<string, string>>,
) => Promise<Readonly<Record<string, string>>>;

Source

resolveProjectDependenciesEffect

Resolves authored Bun aliases without replacing declarations or hiding filesystem authority.

Signature

declare const resolveProjectDependenciesEffect: (
  projectRoot: string,
  dependencies: Readonly<Record<string, string>>,
) => Effect.Effect<
  Readonly<Record<string, string>>,
  GeneratorIoError | GeneratorDomainError,
  GeneratorFileSystem
>;

Source

project-discovery-types.ts

Defines immutable declaration-only scaffold discovery records. Compiler syntax supplies layout/ownership; renderers preserve logical identities and provider declarations while creating sources at their selected physical boundaries.

DiscoveredArtifact (interface)

Static descriptor kind, identity, export form and owning source path.

Signature

export interface DiscoveredArtifact {
  readonly kind: SourceFactoryKind;
  readonly path: string;
  readonly domain?: string;
  readonly binding: string;
  readonly id?: string;
  readonly factory: string;
  readonly exported: boolean;
  readonly exportKind?: "default" | "named";
  readonly options: readonly string[];
}

Source

DiscoveredProfile (interface)

Static provider capability, name, adapter/model identity and default selection.

Signature

export interface DiscoveredProfile {
  readonly capability: "bucket" | "cache" | "job" | "event" | "model";
  readonly name: string;
  readonly adapter?: string;
  readonly modelId?: string;
  readonly isDefault: boolean;
}

Source

DiscoveredService (interface)

Source-declared service identity, capability, members and optional database facts.

Signature

export interface DiscoveredService {
  readonly domain: string;
  readonly path: string;
  readonly binding: string;
  readonly capability: "generic" | "database" | "auth";
  readonly dialect?: DatabaseDialect;
  readonly schemaPath?: string;
  readonly members: readonly DiscoveredServiceMember[];
}

Source

DiscoveredServiceMember (interface)

Statically discovered service member name and referenced binding.

Signature

export interface DiscoveredServiceMember {
  readonly name: string;
  readonly targetBinding?: string;
}

Source

ProjectDiscovery (interface)

Deterministic source-only app, provider, service and artifact facts for one project.

Signature

export interface ProjectDiscovery {
  /** Present on compiler-backed discovery; older supplied planning fixtures may omit it. */
  readonly layout?: ApplicationLayout;
  readonly projectRoot: string;
  readonly packagePath: string;
  readonly appPath: string;
  readonly appFactory: "defineApp" | "defineConfig";
  readonly envPath?: string;
  readonly services: readonly DiscoveredService[];
  readonly artifacts: readonly DiscoveredArtifact[];
  readonly profiles: readonly DiscoveredProfile[];
  readonly awsPulumiDeployment: boolean;
}

Source

project-discovery.ts

Composes source inspection and filesystem discovery into service, artifact and provider facts used by CLI scaffolding resolution.

ProjectDiscoveryServiceTag (class)

Declaration-only project discovery authority; never imports user application modules.

Signature

declare class ProjectDiscoveryServiceTag

Source

discoverProject

Preserves the existing Promise discovery API and original rejection constructors.

Signature

declare const discoverProject: (projectRoot: string) => Promise<ProjectDiscovery>;

Source

discoverProjectEffect

Discovers canonical RELKIT source facts using caller-provided filesystem authority.

Example

import { Effect } from "effect";
import { discoverProjectEffect, projectDiscoveryLive } from "@relkit/cli/scaffolding";
const inspect = discoverProjectEffect("./my-app").pipe(Effect.provide(projectDiscoveryLive));
// Supply GeneratorFileSystem at the application or test composition boundary.

Signature

declare const discoverProjectEffect: (
  projectRoot: string,
) => Effect.Effect<
  ProjectDiscovery,
  GeneratorIoError | GeneratorDomainError,
  ProjectDiscoveryServiceTag
>;

Source

projectDiscoveryLive

Discovery implementation with bounded independent reads and deterministic source order.

Signature

declare const projectDiscoveryLive: Layer.Layer<
  ProjectDiscoveryServiceTag,
  never,
  GeneratorFileSystem
>;

Source

render-database.ts

Plans one native Drizzle service at the selected application boundary, including schema tooling and environment declarations. Generator filesystem authority owns source publication; no database client or migration runs during this workflow.

RenderedDatabase

Signature

declare const RenderedDatabase: RenderedDatabase;

Source

renderDatabase

Preserves the renderDatabase Promise compatibility API.

Signature

declare const renderDatabase: (
  builder: PlanBuilder,
  request: Extract<AddRequest, { kind: "database" }>,
) => Promise<RenderedDatabase>;

Source

renderDatabaseEffect

Plans database through the owning request and typed filesystem authority.

Signature

declare const renderDatabaseEffect: (
  builder: PlanBuilder,
  request: AddRequestBase & {
    readonly kind: "database";
    readonly orm: "drizzle";
    readonly dialect: DatabaseDialect;
    readonly authSchema?: boolean;
  },
) => Effect.Effect<RenderedDatabase, GeneratorIoError | GeneratorDomainError, GeneratorFileSystem>;

Source

render-database.types.ts

Carries the selected native database dialect and physical source destinations between database/auth scaffold stages. Values describe source declarations; no connection, transaction or provider ownership is acquired by planning.

RenderedDatabase (interface)

Validated discovered/planned native database and registered schema locations.

Signature

export interface RenderedDatabase {
  readonly dialect: Extract<AddRequest, { kind: "database" }>["dialect"];
  readonly servicePath: string;
  readonly schemaPath: string;
}

Source

source-edit.ts

Applies focused TypeScript syntax edits to existing source text while retaining unrelated authored statements and the planner’s collision diagnostics.

addFactoryObjectMember

Inserts one property into a canonical factory object or one nested object property.

Signature

declare const addFactoryObjectMember: (
  source: string,
  fileName: string,
  factories: readonly string[],
  path: readonly string[],
  memberName: string,
  memberSource: string,
) => string;

Source

addSourceExport

Appends one export declaration after validating the source syntax.

Signature

declare const addSourceExport: (source: string, fileName: string, declaration: string) => string;

Source

addSourceImport

Signature

declare const addSourceImport: (source: string, fileName: string, declaration: string) => string;

Source

readFactoryObject

Parses the one supported factory object before editing its declarations.

Signature

declare const readFactoryObject: (
  source: string,
  fileName: string,
  factories: readonly string[],
) => ts.ObjectLiteralExpression;

Source

readFactoryStringProperty

Reads one literal string property from a supported factory call.

Signature

declare const readFactoryStringProperty: (
  source: string,
  fileName: string,
  factory: string,
  name: string,
  argumentIndex?: number,
) => string | undefined;

Source

staticPropertyName

Reads statically known property names without evaluating computed expressions.

Signature

declare const staticPropertyName: (node: ts.PropertyName | undefined) => string | undefined;