@amalgm/apps 0.1.3-preview.34176078280 → 0.1.3-preview.34545378804
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/PURPOSE.md +16 -13
- package/README.md +11 -10
- package/dist/apps.d.ts +6 -4
- package/dist/apps.js +19 -22
- package/dist/apps.js.map +1 -1
- package/dist/cli.d.ts +12 -14
- package/dist/cli.js +86 -106
- package/dist/cli.js.map +1 -1
- package/dist/command-input.d.ts +30 -0
- package/dist/command-input.js +62 -0
- package/dist/command-input.js.map +1 -0
- package/dist/command-surface.d.ts +34 -0
- package/dist/command-surface.js +237 -0
- package/dist/command-surface.js.map +1 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +3 -0
- package/dist/index.js.map +1 -1
- package/dist/mcp.d.ts +5 -0
- package/dist/mcp.js +15 -155
- package/dist/mcp.js.map +1 -1
- package/dist/portable.d.ts +13 -0
- package/dist/portable.js +70 -0
- package/dist/portable.js.map +1 -0
- package/dist/presentation.d.ts +3 -1
- package/dist/presentation.js +12 -1
- package/dist/presentation.js.map +1 -1
- package/dist/types.d.ts +40 -0
- package/docs/ENGINE_INTEGRATION.md +9 -65
- package/docs/SHELL_INTEGRATION.md +39 -0
- package/docs/SUPERVISION.md +28 -27
- package/package.json +6 -5
- package/skills/apps/SKILL.md +285 -0
|
@@ -0,0 +1,285 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: apps
|
|
3
|
+
description: Turn any runnable project into a locally owned, versioned application that Amalgm keeps alive — declare an amalgm.app.json, register it, and get immutable releases, one-command deploys and rollbacks, crash restarts, health monitoring, and a stable public URL without a remote hosting platform. Use when building, deploying, or operating an Amalgm app, writing an app manifest, wiring the ready/heartbeat health lease, driving the apps CLI or MCP tools, or embedding the Apps SDK in your own service.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Amalgm Apps
|
|
7
|
+
|
|
8
|
+
Apps turns any runnable project — any language, any framework — into a versioned application that Amalgm keeps alive on your machine. You describe the app once in an `amalgm.app.json` manifest and register it; from then on every deploy produces an immutable, content-addressed release, rollback is a one-command return to bytes that already exist, crashes are restarted automatically with backoff, and your app gets a stable identity: an id, an app ref, a port, and a public URL that all survive deploys, rollbacks, and renames. There is no remote build farm and no hosting account — state lives on disk under your Amalgm home directory, and the same SDK powers the CLI, the MCP tools, and the HTTP catalog.
|
|
9
|
+
|
|
10
|
+
## Installation
|
|
11
|
+
|
|
12
|
+
Everything ships in one npm package:
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm install @amalgm/apps
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
The package exposes four entry points, so you only import what your integration needs:
|
|
19
|
+
|
|
20
|
+
- `@amalgm/apps` — the full SDK: the `Apps` service class, `defaultStateDir`, `runCli`, manifest helpers (`readManifest`, `normalizeManifest`), package helpers (`inspectPackage`, `packPackage`, `unpackPackage`, `validatePackageFiles`, `materialize`), and MCP factories (`createMcpTools`, `createMcpServer`).
|
|
21
|
+
- `@amalgm/apps/lease` — the tiny client your *hosted app* imports to announce health: `connect`, `ready`, `heartbeat`, `grants`, `isManaged`. Zero configuration; inert outside Amalgm.
|
|
22
|
+
- `@amalgm/apps/http` — `createAppsHttpServer`, a read-only HTTP catalog of your apps for dashboards and embedders.
|
|
23
|
+
- `@amalgm/apps/mcp` — the MCP tool definitions alone, for hosts that assemble their own MCP server.
|
|
24
|
+
|
|
25
|
+
Installing the package also gives you two binaries: `amalgm-apps` (the CLI) and `amalgm-apps-mcp` (a stdio MCP server), both runnable with `npx`.
|
|
26
|
+
|
|
27
|
+
Node.js 24 or newer is required.
|
|
28
|
+
|
|
29
|
+
## Quickstart
|
|
30
|
+
|
|
31
|
+
Say you have a small Node server in `./hello`:
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
// hello/server.js
|
|
35
|
+
import http from 'node:http';
|
|
36
|
+
http
|
|
37
|
+
.createServer((_req, res) => res.end('hello from an Amalgm app'))
|
|
38
|
+
.listen(process.env.PORT);
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Add an `amalgm.app.json` next to it:
|
|
42
|
+
|
|
43
|
+
```json
|
|
44
|
+
{
|
|
45
|
+
"schemaVersion": 1,
|
|
46
|
+
"name": "Hello",
|
|
47
|
+
"description": "A minimal Amalgm app",
|
|
48
|
+
"buildCommand": null,
|
|
49
|
+
"startCommand": "node server.js",
|
|
50
|
+
"package": { "include": ["server.js"], "exclude": [] }
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Register it:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
npx --yes --package @amalgm/apps amalgm-apps create ./hello
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
That single command validates the manifest, packages the included files into a release, deploys it, starts the process on an assigned port, and prints the app as JSON — including its `id`, `appRef`, `port`, and `publicUrl`. Ship a new version any time with `npx --yes --package @amalgm/apps amalgm-apps deploy <app-id>`, and step back with `npx --yes --package @amalgm/apps amalgm-apps rollback <app-id>`.
|
|
61
|
+
|
|
62
|
+
The same flow from TypeScript:
|
|
63
|
+
|
|
64
|
+
```ts
|
|
65
|
+
import { Apps } from '@amalgm/apps';
|
|
66
|
+
|
|
67
|
+
const apps = new Apps();
|
|
68
|
+
const app = await apps.register({ cwd: './hello' });
|
|
69
|
+
console.log(app.publicUrl, app.port);
|
|
70
|
+
await apps.close();
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Continuous crash recovery and health monitoring require a long-lived Apps owner: Shell, the Apps MCP server, or an embedding service that calls `apps.boot()`. The CLI performs one operation and then releases its Apps owner. Use one owner for each state directory.
|
|
74
|
+
|
|
75
|
+
## The app manifest
|
|
76
|
+
|
|
77
|
+
`amalgm.app.json` at the project root is the only integration contract. Its full shape:
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
interface AppManifest {
|
|
81
|
+
schemaVersion: 1; // must be exactly 1
|
|
82
|
+
name: string; // required, non-empty
|
|
83
|
+
description: string; // optional in the file; '' when absent
|
|
84
|
+
buildCommand: string | null; // null skips the build step
|
|
85
|
+
startCommand: string; // required; '{port}' expands to the app's port
|
|
86
|
+
toolIds: string[]; // optional; opaque references to Amalgm tools
|
|
87
|
+
package: {
|
|
88
|
+
include: string[]; // required; must select at least one file
|
|
89
|
+
exclude: string[]; // optional
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Rules worth knowing before your first deploy:
|
|
95
|
+
|
|
96
|
+
- Unknown fields are rejected, not ignored — a typo like `"startCmd"` fails validation with a message naming the field.
|
|
97
|
+
- `package.include` and `package.exclude` are glob patterns; `include` must match at least one file. Only included files become part of a release, so build outputs your `startCommand` needs must be covered.
|
|
98
|
+
- `buildCommand: null` means "no build step". When set, it runs once per new release, before the release is activated.
|
|
99
|
+
- `startCommand` runs with the deployment directory as its working directory. Write `{port}` anywhere in it to interpolate the assigned port, or just read the `PORT` environment variable.
|
|
100
|
+
|
|
101
|
+
Check a project without deploying it:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
npx --yes --package @amalgm/apps amalgm-apps validate ./hello
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
This prints the parsed manifest, the release digest, the exact files that would be packaged, and anything excluded — the fastest way to debug an `include` pattern.
|
|
108
|
+
|
|
109
|
+
## Lifecycle
|
|
110
|
+
|
|
111
|
+
Three nouns cover everything you will observe:
|
|
112
|
+
|
|
113
|
+
- An **app** is a stable identity. Its `id`, `appRef`, `port`, and `publicUrl` are assigned at registration and never change; the manifest seeds the display name, and only `update` changes it afterward.
|
|
114
|
+
- A **release** is an immutable, content-addressed snapshot of your manifest plus packaged files. Deploying the same bytes twice yields the same release id — an existing release is never rebuilt.
|
|
115
|
+
- A **deployment** activates exactly one release. Deployment history is append-only, and a rollback appends a new deployment of an *existing* release — old bytes, never a rebuild.
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
const app = await apps.register({ cwd: './hello' }); // returns an AppView
|
|
119
|
+
await apps.deploy(app.id); // package sourceDir again -> new release if bytes changed
|
|
120
|
+
await apps.rollback(app.id); // previous release; or apps.rollback(id, { releaseId })
|
|
121
|
+
await apps.update(app.id, { name: 'Hello v2' });
|
|
122
|
+
apps.versions(app.id); // Release[]
|
|
123
|
+
apps.deployments(app.id); // Deployment[]
|
|
124
|
+
await apps.start(app.id); // start the current deployment, no rebuild
|
|
125
|
+
await apps.stop(app.id);
|
|
126
|
+
await apps.delete(app.id); // stops the process, removes all state and files
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### Safe deploys
|
|
130
|
+
|
|
131
|
+
Validation, packaging, and the build all finish **before** the currently running process is stopped, so a broken build never takes down the running version. If the newly started process dies inside its startup grace period (about one second), the deployment is marked `failed` and the previous runnable deployment is reactivated automatically.
|
|
132
|
+
|
|
133
|
+
The statuses you will see in `deployments` and process history:
|
|
134
|
+
|
|
135
|
+
```ts
|
|
136
|
+
type DeploymentStatus = 'prepared' | 'active' | 'superseded' | 'failed';
|
|
137
|
+
type GenerationStatus = 'starting' | 'running' | 'failed' | 'crashed' | 'exited';
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Keep-alive and health states
|
|
141
|
+
|
|
142
|
+
Amalgm supervises every registered app. When your process crashes, it is restarted in place — same deployment directory, no copying, no rebuild — with exponential backoff (starting around 2 seconds, capped at 60). An app that crashes 5 times inside a 5-minute window has exhausted its restart budget and is marked `degraded` instead of being restarted forever; that budget survives restarts of Amalgm itself, and an exhausted budget affects only that one app. An explicit `start` resets the budget.
|
|
143
|
+
|
|
144
|
+
An app's `status` field moves through:
|
|
145
|
+
|
|
146
|
+
```ts
|
|
147
|
+
type AppStatus =
|
|
148
|
+
| 'registered' | 'building' | 'running' | 'restarting'
|
|
149
|
+
| 'degraded' | 'error' | 'stopped' | 'unresponsive';
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
`unresponsive` appears only for apps that opted into heartbeats (next section) and then went silent; the process is still alive — the status is honest reporting, not a kill. A resumed heartbeat flips it back to `running`.
|
|
153
|
+
|
|
154
|
+
### Your app's environment
|
|
155
|
+
|
|
156
|
+
Every hosted process receives:
|
|
157
|
+
|
|
158
|
+
| Variable | Meaning |
|
|
159
|
+
| --- | --- |
|
|
160
|
+
| `PORT` | The port your server must listen on |
|
|
161
|
+
| `AMALGM_APP_ID` | The app's stable id |
|
|
162
|
+
| `AMALGM_APP_REF` | The app's stable ref (the subdomain) |
|
|
163
|
+
| `AMALGM_APP_URL` | The app's public URL |
|
|
164
|
+
| `AMALGM_APP_DATA_DIR` | The only directory where persistent data belongs |
|
|
165
|
+
|
|
166
|
+
Write durable data **only** to `AMALGM_APP_DATA_DIR`. It survives deploys and rollbacks; anything written inside a deployment directory does not, and never becomes part of a later release.
|
|
167
|
+
|
|
168
|
+
Each app records `https://<appRef>.<domain>/` (default domain `apps.amalgm.ai`) and a port allocated from 9100–9199 by default. Public reachability requires the composing host to publish that route and provide DNS and transport.
|
|
169
|
+
|
|
170
|
+
## The health lease
|
|
171
|
+
|
|
172
|
+
By default Amalgm only knows whether your process is alive. Opt into real health reporting from inside your app with the lease client — one import, one call:
|
|
173
|
+
|
|
174
|
+
```ts
|
|
175
|
+
import { connect } from '@amalgm/apps/lease';
|
|
176
|
+
|
|
177
|
+
const lease = connect({ heartbeatIntervalMs: 30_000 }); // 30s is the default
|
|
178
|
+
// on shutdown: lease.stop()
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
`connect` announces readiness once, then heartbeats on the interval you chose. Choose 5 seconds to 5 minutes; the host clamps its expected interval to that range. Miss 3 consecutive expected beats and your app shows as `unresponsive` until beats resume.
|
|
182
|
+
|
|
183
|
+
The lease is deliberately boring and safe:
|
|
184
|
+
|
|
185
|
+
- Outside Amalgm — running `node server.js` on your laptop, in CI, in a container — it is inert: `isManaged()` returns `false` and `connect` returns `{ active: false, stop() {} }`. You never need an environment check around it.
|
|
186
|
+
- Transport failures surface through an optional `onError` callback (or a console warning once per failure period). Keep the callback nonthrowing. The heartbeat timer never keeps your process alive on its own.
|
|
187
|
+
|
|
188
|
+
Lower-level pieces when you want manual control:
|
|
189
|
+
|
|
190
|
+
```ts
|
|
191
|
+
import { grants, isManaged, ready, heartbeat } from '@amalgm/apps/lease';
|
|
192
|
+
|
|
193
|
+
if (isManaged()) {
|
|
194
|
+
const { appId, appRef, publicUrl, dataDir, port } = grants();
|
|
195
|
+
await ready({ heartbeatIntervalMs: 10_000 });
|
|
196
|
+
setInterval(() => heartbeat(), 10_000);
|
|
197
|
+
}
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
## CLI
|
|
201
|
+
|
|
202
|
+
`amalgm-apps` takes a command plus arguments, prints the result as JSON, and exits non-zero on failure. The CLI, the MCP tools, and the SDK expose one command surface, so every verb below is also an MCP tool with the same input fields:
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
amalgm-apps create <dir> # validate, release, deploy, and start in one step
|
|
206
|
+
amalgm-apps validate <dir> # dry-run: manifest, digest, packaged files
|
|
207
|
+
amalgm-apps list # all apps with status and health
|
|
208
|
+
amalgm-apps get <app-id> # one app in full detail
|
|
209
|
+
amalgm-apps update <app-id> --name "New name" [--[no-]autostart] [--[no-]keep-alive] [--[no-]dns-connected]
|
|
210
|
+
amalgm-apps deploy <app-id> [dir] # new release from the source dir (or a new dir)
|
|
211
|
+
amalgm-apps rollback <app-id> [release-id]
|
|
212
|
+
amalgm-apps versions <app-id> # release history
|
|
213
|
+
amalgm-apps deployments <app-id> # deployment history with statuses
|
|
214
|
+
amalgm-apps logs <app-id> [lines] # trailing process log lines
|
|
215
|
+
amalgm-apps start <app-id>
|
|
216
|
+
amalgm-apps stop <app-id>
|
|
217
|
+
amalgm-apps export <app-id> # portable package: manifest, packed files, tool ids
|
|
218
|
+
amalgm-apps install --file portable.json # {"app": <export result>, "autostart"?: bool}
|
|
219
|
+
amalgm-apps routes # published routes of running healthy apps
|
|
220
|
+
amalgm-apps delete <app-id> # stop and remove everything
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
Bare arguments fill each command's positional fields in order; every field can also be passed as `--field value` (or `--field` / `--no-field` for booleans), and `--input '<json>'` or `--file <path>` supplies the whole input as one object, exactly as an MCP call would. `create` accepts `--port <n>` to pin a specific port, `--no-autostart` to register without launching on boot, `--no-keep-alive` to disable crash restarts, and `--no-connect-dns` to keep the app off the public route table. Every command also accepts a global `--state-dir <dir>` to operate on a non-default state directory. Run `amalgm-apps help` for the generated reference.
|
|
224
|
+
|
|
225
|
+
## MCP tools
|
|
226
|
+
|
|
227
|
+
Run `npx --yes --package @amalgm/apps amalgm-apps-mcp` for a stdio MCP server, or embed the tools in your own host:
|
|
228
|
+
|
|
229
|
+
```ts
|
|
230
|
+
import { Apps, createMcpTools, createMcpServer } from '@amalgm/apps';
|
|
231
|
+
|
|
232
|
+
const tools = createMcpTools(new Apps()); // name, description, inputSchema, handler
|
|
233
|
+
const server = createMcpServer(); // or a full JSON-RPC server: server.start()
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
The tools are the CLI commands one-for-one, named `amalgm_apps_<command>`: `amalgm_apps_create`, `amalgm_apps_list`, `amalgm_apps_get`, `amalgm_apps_update`, `amalgm_apps_delete`, `amalgm_apps_start`, `amalgm_apps_stop`, `amalgm_apps_deploy`, `amalgm_apps_rollback`, `amalgm_apps_versions`, `amalgm_apps_deployments`, `amalgm_apps_logs`, `amalgm_apps_validate`, `amalgm_apps_routes`, `amalgm_apps_export`, and `amalgm_apps_install`. Each carries the command's input schema and MCP annotations (read-only, destructive, idempotent). `appCommandDefinitions` from `@amalgm/apps` is that list, for hosts that build their own adapter. This is how an agent connected to Amalgm ships and operates apps on your behalf.
|
|
237
|
+
|
|
238
|
+
For read-only visibility — a dashboard, a status page — mount the HTTP catalog:
|
|
239
|
+
|
|
240
|
+
```ts
|
|
241
|
+
import { Apps, createAppsHttpServer } from '@amalgm/apps';
|
|
242
|
+
|
|
243
|
+
const server = createAppsHttpServer(new Apps());
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
It serves `GET /apps` (and `/apps/list`) plus `/apps/routes`. It is strictly a catalog: all lifecycle changes go through the SDK, CLI, or MCP tools.
|
|
247
|
+
|
|
248
|
+
## Where state lives
|
|
249
|
+
|
|
250
|
+
Apps keeps everything under one state directory. The standalone main binding defaults to `~/.amalgm/users/<scope>/apps`; preview and local bindings use separate namespaces under `~/.amalgm/environments/`. A composed host supplies its installation root through `AMALGM_ROOT`. Point it elsewhere with the `AMALGM_APPS_DIR` environment variable (used verbatim), `AMALGM_DIR` (state goes in an `apps/` folder under it), or the `stateDir` option / `--state-dir` flag.
|
|
251
|
+
|
|
252
|
+
Inside you will find, per app:
|
|
253
|
+
|
|
254
|
+
```
|
|
255
|
+
apps.db # the SQLite catalog: apps, releases, deployments, history
|
|
256
|
+
releases/<app-id>/ # immutable release contents, one directory per release
|
|
257
|
+
deployments/<app-id>/# the working copies your process actually runs from
|
|
258
|
+
data/<app-id>/ # your app's AMALGM_APP_DATA_DIR — survives every deploy
|
|
259
|
+
logs/<app-id>.log # captured stdout/stderr, rotated once at <app-id>.log.1
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
Treat these directories as read-only observability: inspect the logs, browse a release, back up `data/` — but let the CLI, SDK, and MCP tools make the changes. `delete` removes an app's releases, deployments, data, and logs in one step.
|
|
263
|
+
|
|
264
|
+
## Embedding the SDK
|
|
265
|
+
|
|
266
|
+
If you are building a long-lived service that hosts apps itself, construct one `Apps` instance and run its daemon lifecycle:
|
|
267
|
+
|
|
268
|
+
```ts
|
|
269
|
+
import { Apps } from '@amalgm/apps';
|
|
270
|
+
|
|
271
|
+
const apps = new Apps({
|
|
272
|
+
stateDir: '/var/lib/amalgm/apps',
|
|
273
|
+
publishRoutes: (routes, reason) => gateway.update(routes), // eligible routes changed
|
|
274
|
+
onChange: (app) => events.emit('app', app), // app updated, or { id, deleted: true }
|
|
275
|
+
onError: (error) => log.warn(error),
|
|
276
|
+
});
|
|
277
|
+
|
|
278
|
+
await apps.boot(); // take ownership, start health sweeps, resume apps
|
|
279
|
+
// ... serve ...
|
|
280
|
+
await apps.close({ stopProcesses: true }); // stop hosted apps on the way down
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
`boot()` adopts apps that should be running and resumes health monitoring; `close()` without `stopProcesses: true` detaches and leaves processes running for the next owner. Your callbacks are fault boundaries — an exception inside them is reported through `onError` and contained, never allowed to take the daemon down. `apps.routes()` returns the currently eligible `{ app_ref, port, name }` routes; routes fail closed, so an app that is stopped, degraded, or disconnected from DNS simply disappears from the table.
|
|
284
|
+
|
|
285
|
+
Only one live Apps service may manage a given state directory at a time; a second instance pointed at the same directory will refuse to take ownership rather than corrupt it.
|