appport

The Node 20+ command line for adding AppPort to new or existing repositories, generating an implementation boundary, and validating the resulting contract and artifact. It works without AppBoundry Cloud or FeltDB.

Quickstart

Add AppPort to an existing Node application:

cd your-application
npm install @appport/sdk
npm install --save-dev appport
npx appport contract init
npx appport add             # interactively define the first capability
npx appport validate

appport contract init creates appboundry.contract.json. If AppBoundry already exported that authoritative contract for you, put it at that path and skip the init command. appport add then inspects the repository and creates the AppPort implementation boundary without replacing developer-owned source files. Implement the generated capability stubs and follow appport/README.md to build the generated WASM project. Finally, appport validate verifies contract coverage and confirms that the configured WASM artifact is real and current.

Add another capability at any time with npx appport contract add. The wizard asks for its name, typed input and output fields, permissions, and description; then rerun npx appport add to regenerate the typed boundary.

To scaffold a new application instead:

npx appport init my-app
cd my-app
npm install
npm run dev

During development, the usual loop is:

npx appport dev           # HTTP, WebSocket, and Studio
npx appport capabilities  # inspect the public capability surface
npx appport build         # regenerate manifest and typed client
npx appport test          # run protocol and transport conformance
npx appport doctor        # diagnose contract and compatibility issues
npx appport validate      # verify implementation and WASM artifact

Every command is available without a global installation:

npx appport --help

appport init            scaffold AppPort into an existing application
appport add             inspect an existing repo and add a contract-driven boundary
appport dev             HTTP, WebSocket and Studio against your capabilities
appport build           write the manifest and the generated client
appport validate        validate coverage, generated files, and the WASM artifact
appport doctor          check names, schemas, permissions and compatibility
appport connect        attest this repository as an AppBoundry implementation source
appport manifest        print the manifest (--write to save it)
appport capabilities    list capabilities, versions and required permissions
appport generate        generate a typed client from the manifest
appport test            check every transport reaches the same capabilities
appport web             scaffold the web runtime
appport desktop         scaffold the desktop runtime (--target electron|tauri)

Configuration

// appport.config.ts
import { defineConfig } from "appport";

export default defineConfig({
  entry: "./appport/server.ts",
  outDir: "./appport/generated",
  dev: { port: 4400, studio: true }
});

The entry module default-exports an AppPortApplication, an AppPortServer, or a factory returning one. Node strips TypeScript types on import, so there is no build step between editing a capability and running it.

doctor

appport doctor checks what the specification requires and what tooling can see:

When appport.source.json exists, doctor also re-attests appboundry.contract.json against the authoritative AppBoundry contract and revalidates this source's implementation coverage, repository identity, ref and commit. See application sources. capability and event names, reverse-domain application identity, opaque schemas that would weaken cross-language interoperability, mutating capabilities that declare no permissions, events emitted but not declared, and — against a previously written manifest — every breaking change, classified by the rules in §8.4.

test

appport test connects over in-process, HTTP and WebSocket and checks that all three reach the same capabilities, answer appport.ping, report UNKNOWN_CAPABILITY for a missing capability, and refuse a foreign protocol version.

The CLI is the developer tool for the AppPort protocol; @appport/sdk is the application API. AppBoundry integration is optional and begins only when a repository is connected to an authority. The documented commands and exported configuration helpers form the supported surface; internal generators are not public APIs. Node is the only currently qualified CLI runtime. See the AppPort specification for protocol semantics.