@launchfile/sdk

TypeScript SDK for parsing, validating, and serializing Launchfiles.

Install

bun add launchfile
# or
npm install launchfile

CLI

The SDK includes a launchfile CLI for validating and inspecting Launchfiles.

# Validate a Launchfile (defaults to ./Launchfile)
launchfile validate
launchfile validate path/to/Launchfile

# Structured JSON output for CI pipelines
launchfile validate --json

# Silent mode — just the exit code
launchfile validate --quiet

# Evaluate as if fetched standalone rather than read from the app's own
# checkout — enables the D-43 reduced-portability check (PROVIDERS.md §6)
launchfile validate --detached

# Print the normalized form (after shorthand expansion) as JSON
launchfile inspect path/to/Launchfile

# Dump the JSON Schema to stdout
launchfile schema

The CLI refuses any long flag it does not declare: it prints Unknown flag: --<name> to stderr and exits 1 before running anything, rather than ignoring the flag. --schema-path without a value exits 1 the same way.

npx launchfile runs the separate launchfile package, not this CLI. This CLI is the @launchfile/sdk/cli export (dist/cli.js).

Global flags

• --no-color — Disable colored output (also respects NO_COLOR env var)
• --version — Print version
• --help — Show usage

Reduced-portability warnings (D-40, D-43)

validate warns, non-fatally, when a component has no portable build path
(runtime and/or commands.build/commands.install) or — with --detached
— is source-needing with no repository: to fall back to. Set
LAUNCHFILE_NO_PORTABILITY_WARNINGS (to any value except 0/false) to
silence both; every other validate warning keeps firing. The lintLaunch(launch, opts?) SDK export takes the
same two options (detached, suppressPortabilityWarnings) directly.

Validate in CI

# GitHub Actions
- run: npx launchfile validate --quiet

Editor Integration

Add JSON Schema support for autocompletion and validation in your editor:

# yaml-language-server: $schema=https://launchfile.dev/schema/v1
version: launch/v1
name: my-app

Usage

Parse a Launchfile

import { readLaunch } from "launchfile";

const app = readLaunch(`
  name: my-app
  runtime: node
  requires: [postgres]
  commands:
    start: "node server.js"
  health: /health
`);

// app.components.default.requires → [{ type: "postgres" }]
// app.components.default.health → { path: "/health" }

Validate pre-parsed data

import { validateLaunch } from "launchfile";

const app = validateLaunch({
  name: "my-app",
  runtime: "node",
  requires: ["postgres"],
});

Write back to YAML

import { writeLaunch } from "launchfile";

const yaml = writeLaunch(app);
// Collapses shorthands: { type: "postgres" } → "postgres"

Resolve expressions

import { resolveExpression } from "launchfile";

const url = resolveExpression("postgresql://${host}:${port}/${name}", {
  resource: { host: "localhost", port: 5432, name: "mydb" },
});
// → "postgresql://localhost:5432/mydb"

Check for expressions

import { isExpression } from "launchfile";

isExpression("$url");           // true
isExpression("hello");          // false
isExpression("$$escaped");      // false (literal $)

API

Every value export of src/index.ts is either a row below or an entry in
EXCLUDED_EXPORTS (scripts/check-readme-exports.ts, with a one-line reason —
mostly CLI-command implementations and the provider error-context vocabulary).
bun run check:exports (wired as a pretest hook) fails bun run test — and
CI’s sdk job — if a value export is undocumented, or if a row/exclusion goes
stale. For a row that lists parameters, it also checks the list against the
export function declaration: the same number of parameters, optional (? or
a default) in the same positions. A signature it cannot map — overloads, rest,
this or destructured parameters, a const or class — fails the check rather
than being skipped, unless ARITY_UNCHECKED in the same script lists the row
with a reason. useKeyOf is listed there: it destructures its one parameter.

The check reads names and parameter counts only. It does not read the
Description column, parameter names, or what a non-function export such as
CERTIFICATE means. A row that names a real export, lists the right
parameters, and still describes it wrongly is caught only by a person reading
the source.

Parse, validate, serialize

Expressions

Named endpoints (D-63)

$app.endpoints.<name>.* addresses one named published endpoint’s public
address; $components.<component>.<endpoint>.* addresses a named listener from
inside the deployment.

Publication context (D-58)

The orchestrator-supplied public URL a provider resolves $app.* from when
routing is owned upstream. A malformed value is refused, never degraded.

Listeners and certificates (D-61)

A provides entry’s protocol/port are its declared listener; its
effective listener is what that listener speaks in the configuration the
deployment selected. They differ only when a bound certificate is active.

Resource uses

A uses item is either a bare token (db) or a single-key map ({ db: cache })
naming one occurrence of a repeatable use. The use key — db, or db.cache
— is the prefix providers register properties under and $<resource>.<use>.…
addresses.

Command capture

One formatter for every surface a provider prints captures on, so sensitive
means the same thing on each (SPEC.md § Command Capture). Masking is display
only — keeping a value out of logs and state files is the provider redactor’s
job.

Component selection

Linting

validate runs these; call them directly to build a custom check.

Environment, storage, and host capabilities

Source mode

Deployment state

A pure event-sourced state model — fold LaunchEvents into a DeploymentState,
diff two states back into events, and resolve $-references against a state.

Toolchain detection

Types

All types are exported:

import type {
  Launch,
  NormalizedLaunch,
  Component,
  NormalizedComponent,
  Requirement,
  Provides,
  EnvVar,
  // ... see types.ts for full list
} from "launchfile";

License

MIT