# @openpalm/lib

Shared control-plane library for OpenPalm.
CLI, admin, and scheduler use this package so stack behavior stays consistent.

> **Bun required.** This package ships TypeScript source and relies on Bun's native TS execution. It does not compile to JavaScript and is not compatible with Node.js.

The current model is direct-write over `~/.openpalm/` plus native Docker Compose.
Compose files in `stack/` and env files in `vault/` are the live runtime inputs.

## What lives here

- OpenPalm home/path helpers
- Env parsing and secret management
- Addon install/uninstall and registry helpers
- Compose lifecycle wrappers
- Memory and connection profile helpers
- Automation parsing used by the scheduler
- Shared structured logging

## Important context

- Some filenames still use legacy names like `staging`; those modules now support the direct-write compose model
- `config/` is user-owned, `knowledge/env/stack.env` is system-managed, `registry/` is catalog-only, and `stack/addons/` contains enabled runtime overlays
- New reusable control-plane logic belongs here, not duplicated in consumers

## Main module areas

| Module area | Purpose |
|---|---|
| `control-plane/home` and `control-plane/paths` | Resolve the OpenPalm home layout |
| `control-plane/env` and `control-plane/secrets` | Read, merge, and patch env files |
| `control-plane/lifecycle` and `control-plane/docker` | Compose operations and stack lifecycle helpers |
| `control-plane/portals` and `control-plane/components` | Addon discovery and install/uninstall logic |
| `control-plane/provider-models` | Provider model discovery helpers |
| `control-plane/scheduler` | Automation parsing and scheduler helpers |
| `logger` | Shared structured logger |

## Consumer model

- CLI: direct host-side orchestrator
- Admin: optional UI/API wrapper
- Scheduler: automation runner without Docker socket access

See `docs/technical/core-principles.md` for the authoritative filesystem contract and security rules.