Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.khal.ai/llms.txt

Use this file to discover all available pages before exploring further.

This page is the full local dev and testing loop for a pack. It assumes you have a pack already scaffolded — if not, start at Your first pack.
The FDE rule is test local first. Use this page for pack-level build/test work, then follow the FDE environment ladder to move from local PM2/dev-local proof into shared dev, customer dev/HML, and production gates.

​
Build and watch

From the pack repo root: 
bun run build
The build produces CJS + ESM + .d.ts outputs into package/dist/. The publish pipeline only ships what’s under package/.

​
Typecheck and lint

bun run typecheck
Both run through Biome under the hood. Fix on save is usually enough.

​
Unit tests

Vitest is the default. A tiny NATS mock is enough for most frontend tests: 
import { describe, it, expect, vi } from 'vitest';
import { render } from '@testing-library/react';
import TerminalPack from '../src';

vi.mock('@khal-os/sdk', () => ({
  useNats: () => ({
    publish: vi.fn(),
    subscribe: vi.fn((_subject, _cb) => () => {}),
  }),
}));

describe('TerminalPack', () => {
  it('renders an empty terminal', () => {
    const { container } = render(<TerminalPack />);
    expect(container.firstChild).toBeTruthy();
  });
});
Run tests: 
bun run test

​
Integration tests

For full-stack packs, a lightweight integration test talks to your service over a local NATS instance:
1

Start a local NATS

Any NATS server will do — e.g., nats-server -js if you have it installed, or a Docker one-liner.
2

Point your service at it

Set KHAL_NATS_URL=nats://localhost:4222 when running the service in test mode.
3

Publish and assert

From a test harness, publish on your service’s input subject and assert on its output subject.

​
The khal developer CLI

@khal-os/app-kit ships the public khal CLI. Install it from npmjs and use it for scaffolding, auth, install dry-runs, target context, doctor checks, logs, and the bundled design-system catalog. Key commands:
  • khal new app <name> — scaffold a new app from the bundled app template; also khal new service <name> and khal new workflow <name>.
  • khal install . --target dev --dry-run --json — validate a generated repo before touching a target.
  • khal doctor --target dev — check local and target prerequisites.
  • khal dev design-system — serve the bundled feature catalog and design-system recipes.
For the first-run install/login/scaffold path, start with FDE CLI quickstart. The legacy khal-dev binary is no longer the public FDE surface.

​
Debug tips

Frontend: DevTools

The shell runs in a browser (or Tauri WebView). F12 opens DevTools — console, network, React DevTools all work.

Service: container logs

docker logs -f <container> while running the service via docker run locally. In a deployed instance, logs flow through the platform’s standard log pipeline — your customer admin knows how to read them.

NATS traffic: pack-nats-viewer

The reference pack-nats-viewer app lets you see subjects flowing through your pack’s namespace. Invaluable for debugging message plumbing.

Manifest validation

khal-app.json is validated by @khal-os/types; run khal install . --target dev --dry-run --json for the current source/manifest/env preflight before mutating a target.
khal CLI QA output during a local test run

​
What’s next

Publish your pack

Push → CI builds → publish.

khal-app.json reference

The full manifest schema.