Package Lifecycle API

The /lifecycle entry point provides one implementation for local builds, CI checks, and explicit publication. Every operation compiles the same authoring definition and applies the same verification contract.

Configure a Command Builder

commandTargetBuilder adapts a project-owned build command to the SDK TargetBuilder contract. The command receives the selected target, immutable release, staged descriptor, staging root, target output root, and resolved target definition through environment variables.

import {
  commandTargetBuilder,
  type CommandTargetBuilderOptions,
} from '@theaiplatform/miniapp-sdk/lifecycle';

const options: CommandTargetBuilderOptions = {
  id: 'rslib',
  command: 'pnpm',
  args: ['run', 'build:target'],
};

export const builder = commandTargetBuilder(options);

The adapter captures bounded command output. A nonzero exit, signal, or process error rejects the active lifecycle before package assembly.

Build and Check

buildTapMiniapp compiles authoring, validates the staged descriptor, runs each target builder, assembles and verifies a portable package, invokes project verification hooks, and atomically replaces output. checkTapMiniapp runs the same path in temporary output and then removes it.

import {
  buildTapMiniapp,
  checkTapMiniapp,
  type TapMiniappBuildResult,
  type TapMiniappCheckResult,
  type TapMiniappLifecycleOptions,
} from '@theaiplatform/miniapp-sdk/lifecycle';

const options: TapMiniappLifecycleOptions = {
  root: process.cwd(),
  output: 'dist',
};

const built: TapMiniappBuildResult = await buildTapMiniapp(options);
const checked: TapMiniappCheckResult = await checkTapMiniapp(options);

console.log(built.packageRoot, checked.verified);

Neither operation invokes a publisher. A failed build preserves the previous complete output and removes its temporary staging transaction.

Publish Explicitly

publishTapMiniapp requires one publisher adapter in the authoring config. Without from, it performs the complete build path and publishes the verified staged package. With from, it revalidates an existing assembled package before invoking the adapter.

import {
  publishTapMiniapp,
  type PublishTapMiniappOptions,
  type TapMiniappPublishResult,
} from '@theaiplatform/miniapp-sdk/lifecycle';

const options: PublishTapMiniappOptions = {
  root: process.cwd(),
  from: 'dist',
};

const published: TapMiniappPublishResult = await publishTapMiniapp(options);

console.log(published.publisherId, published.packageRoot);

Publication receives exactly one verified package. Missing adapters, tampered artifacts, invalid locks, project hook failures, or publisher failures reject without mutating the assembled package.

Public Export Contract

ExportPurposeInputs and resultLifecycle and errorsWorking example
CommandTargetBuilderOptionsConfigures a project command as one lifecycle target builder.Supplies command, arguments, optional environment values, and optional stable ID.Type only; invalid or empty command values throw when the adapter is created.Configure a command builder
TapMiniappLifecycleOptionsSelects project root, output path, and optional authoring config path.Supplies common options consumed by build, check, and publish operations.Paths must remain confined to the project and cannot overlap SDK staging.Build and check
PublishTapMiniappOptionsAdds an optional assembled-package source to common lifecycle options.Supplies lifecycle options and an optional project-relative from directory.Existing output is reverified before any publisher receives it.Publish explicitly
TapMiniappBuildResultReports one successful transactional package build.Returns command name, immutable release, finalized descriptor, and package root.Available only after builders, assembly, portability, and verification all pass.Build and check
TapMiniappCheckResultReports one successful ephemeral package verification.Returns command name, immutable release, finalized descriptor, and verified status.Temporary package output is removed after success or failure and never replaces dist.Build and check
TapMiniappPublishResultReports one explicit publication and provider-specific result.Returns release, descriptor, package root, publisher ID, and adapter result.Available only after complete verification and one successful adapter invocation.Publish explicitly
commandTargetBuilderAdapts a project-owned subprocess to the typed target builder contract.Accepts CommandTargetBuilderOptions and returns an immutable TargetBuilder.Nonzero exit, signal, spawn error, or invalid configuration rejects the lifecycle.Configure a command builder
buildTapMiniappBuilds and atomically installs one complete verified package generation.Accepts lifecycle options and resolves with TapMiniappBuildResult.Any compiler, builder, assembly, or verification failure preserves previous output.Build and check
checkTapMiniappRuns the complete build and verification path without replacing output.Accepts lifecycle options and resolves with TapMiniappCheckResult.It never publishes and always removes its temporary package transaction.Build and check
publishTapMiniappPublishes exactly one package through the configured explicit adapter.Accepts publish options and resolves with TapMiniappPublishResult.It verifies before adapter invocation and rejects missing adapters or tampered bytes.Publish explicitly