@amalgm/apps 0.1.3-preview.34562094191 → 0.1.3-preview.35153911192

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/docs/STATUS.md ADDED
@@ -0,0 +1,73 @@
1
+ # Status
2
+
3
+ Last updated 2026-09-10.
4
+
5
+ ## Proven
6
+
7
+ amalgm-apps works on its own, as an SDK with a CLI and an MCP server on top.
8
+ It was tested on macOS with the real Design Canvas app, outside amalgm-shell.
9
+
10
+ - **All 16 commands work** from the CLI and as MCP tools: create, list, get,
11
+ update, delete, start, stop, deploy, rollback, versions, deployments, logs,
12
+ validate, routes, export, install.
13
+ - **Design Canvas runs as an Amalgm app.** `create` built it (npm install and a
14
+ UI build into an immutable release), started it, and it served on its port.
15
+ A design made through its own tool was saved in the app's data directory
16
+ and survived stop, start, deploy, and rollback.
17
+ - **Supervision works.** A killed app restarts by itself. A new owner (a new
18
+ MCP server) adopts the running app, and restarts it if it is killed.
19
+ - **Export and install work.** An exported app installed as a second app on
20
+ a free port with its own empty data.
21
+ - **Delete is clean.** No process, port, state file, or installed source is
22
+ left behind.
23
+ - `npm run verify` passes (45 tests) locally and in CI.
24
+
25
+ ## Fixed while testing
26
+
27
+ - **The CLI never exited** after create, start, or deploy. App output went
28
+ through pipes to the owner, which kept it alive; after a handoff the log had
29
+ no reader. Apps now write their own log through an inherited descriptor.
30
+ - **Install picked a busy port.** Allocation only checked its own database.
31
+ Each port is now proven free on the host (nothing answers on loopback).
32
+ - **A failed start did not say why.** The error now carries the log tail.
33
+
34
+ ## Cleaned up
35
+
36
+ Deleted the Engine-era importer, snake_case and `versionId` aliases, schema and
37
+ status migrations older than the first publish, unused options, internal
38
+ exports, and the Engine integration doc. The package index exports only the
39
+ SDK and its adapters.
40
+
41
+ ## Compared with the old Engine
42
+
43
+ The Engine gave agents 9 app tools: register, validate, list, routes,
44
+ redeploy, start, stop, connect DNS, disconnect DNS. It had no delete, get,
45
+ versions, deployment history, logs, or rollback for agents. Apps has 14
46
+ commands, identical on the CLI and MCP.
47
+
48
+ ## An app is a construct on the rails
49
+
50
+ An app's id is its entity UUID, and every deliberate act on an app — create,
51
+ deploy, rename, delete — is recorded once through the host's intentional door
52
+ (`recordConstruct`). The payload is the packed package, and the version is the
53
+ hash of those bytes, stored in `construct_version`: the app always reports the
54
+ version it is running, which is the only thing Apply and Verify believe.
55
+ `construct-surface.ts` is the whole seam — the access verbs sharing calls
56
+ (`resolve`, `dependencies`, `copy`, `trash`) and the Apply half the host drives
57
+ (`inspect`, `payloadDependencies`, `switchTo`, `applyStructure`). A received
58
+ version is materialized under `<stateDir>/imports`, so the rails never rewrite
59
+ or repoint the directory a person edits.
60
+
61
+ ## Remains
62
+
63
+ - **Testing inside amalgm-shell.** The shell hosts Apps in the product. Still
64
+ to prove there: the shell boots Apps and adopts running apps, the CLI and MCP
65
+ work through the shell, the UI catalog lists apps, and a public
66
+ `*.apps.amalgm.ai` link opens the app. The preview machine needs a shell
67
+ build that carries this version of Apps.
68
+ - **Follow-ups in this repo:** move register out of `apps.ts` (activation now
69
+ lives in `releases.ts`); delete the legacy `/artifacts` HTTP projection once
70
+ the UI reads `/apps`.
71
+ - **Outside this repo:** the shell still carries `bundle-apps.ts`, the pack
72
+ sharing adapter apps no longer needs. It goes when agents, automations and
73
+ tools are constructs too and nothing is left to copy by bundle.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@amalgm/apps",
3
- "version": "0.1.3-preview.34562094191",
3
+ "version": "0.1.3-preview.35153911192",
4
4
  "description": "Local-first, versioned application deployment for Amalgm.",
5
5
  "license": "UNLICENSED",
6
6
  "private": false,
@@ -89,11 +89,11 @@
89
89
  "package.json"
90
90
  ]
91
91
  },
92
- "gitHead": "62edf089a80bff8c4ac06371296846ff1b1e86a2",
92
+ "gitHead": "be09aba57fa434465525e13f1115aebc7de9b280",
93
93
  "amalgmSource": {
94
94
  "repository": "amalgm-inc/amalgm-apps",
95
95
  "branch": "preview",
96
- "commit": "62edf089a80bff8c4ac06371296846ff1b1e86a2",
97
- "occurrence": "34562094191"
96
+ "commit": "be09aba57fa434465525e13f1115aebc7de9b280",
97
+ "occurrence": "35153911192"
98
98
  }
99
99
  }
@@ -1,15 +0,0 @@
1
- /**
2
- * Portable apps: the export/install port every sharing layer builds on. An
3
- * exported app is the packed source plus the manifest facts an installer
4
- * needs to show before it registers anything. Installing materializes the
5
- * package under the local state directory and registers it as a new app on
6
- * this machine. Lineage (`sourceAppId`) is carried, never enforced: a
7
- * sharing layer that publishes an untethered copy strips it.
8
- */
9
- import type { Apps } from './apps.js';
10
- import type { AppView, InstallAppOptions, PortableApp } from './types.js';
11
- /** An installed app's source lives under the state dir and leaves with the app; a created app's source is the user's own. */
12
- declare function removeInstalledSource(apps: Apps, sourceDir: string): void;
13
- declare function exportApp(apps: Apps, appId: string): PortableApp;
14
- declare function installApp(apps: Apps, entry: PortableApp, options?: InstallAppOptions): Promise<AppView>;
15
- export { exportApp, installApp, removeInstalledSource };
package/dist/portable.js DELETED
@@ -1,78 +0,0 @@
1
- /**
2
- * Portable apps: the export/install port every sharing layer builds on. An
3
- * exported app is the packed source plus the manifest facts an installer
4
- * needs to show before it registers anything. Installing materializes the
5
- * package under the local state directory and registers it as a new app on
6
- * this machine. Lineage (`sourceAppId`) is carried, never enforced: a
7
- * sharing layer that publishes an untethered copy strips it.
8
- */
9
- import fs from 'node:fs';
10
- import path from 'node:path';
11
- import { unpackPackage } from './package.js';
12
- function slug(value) {
13
- return String(value || 'app').toLowerCase().replace(/[^a-z0-9._-]+/g, '-')
14
- .replace(/^-+|-+$/g, '').slice(0, 60) || 'app';
15
- }
16
- function importsRoot(apps) {
17
- return path.join(apps.stateDir, 'imports');
18
- }
19
- /** An installed app's source lives under the state dir and leaves with the app; a created app's source is the user's own. */
20
- function removeInstalledSource(apps, sourceDir) {
21
- if (path.dirname(path.resolve(sourceDir)) === importsRoot(apps))
22
- fs.rmSync(sourceDir, { recursive: true, force: true });
23
- }
24
- function allocate(root, name) {
25
- fs.mkdirSync(root, { recursive: true });
26
- const base = slug(name);
27
- for (let index = 0; index < 1000; index += 1) {
28
- const candidate = path.join(root, index ? `${base}-${index + 1}` : base);
29
- if (!fs.existsSync(candidate))
30
- return candidate;
31
- }
32
- throw new Error(`Could not allocate an install directory for app: ${String(name)}`);
33
- }
34
- function exportApp(apps, appId) {
35
- const app = apps.get(appId);
36
- if (!app)
37
- throw new Error(`App not found: ${appId}`);
38
- const packed = apps.pack(app.sourceDir);
39
- return {
40
- sourceAppId: app.id,
41
- manifest: packed.manifest,
42
- app: {
43
- name: packed.manifest.name,
44
- description: packed.manifest.description,
45
- buildCommand: packed.manifest.buildCommand,
46
- startCommand: packed.manifest.startCommand,
47
- autostart: true,
48
- keepAlive: true,
49
- },
50
- toolIds: packed.manifest.toolIds,
51
- files: packed.files,
52
- totalBytes: packed.totalBytes,
53
- skipped: packed.excluded,
54
- };
55
- }
56
- async function installApp(apps, entry, options = {}) {
57
- if (!Array.isArray(entry?.files) || !entry.files.length)
58
- throw new Error('A portable app must include files');
59
- const directory = allocate(importsRoot(apps), entry.manifest?.name || entry.app?.name);
60
- try {
61
- unpackPackage({ files: entry.files }, directory);
62
- const inspected = apps.validate(directory);
63
- if (entry.manifest && JSON.stringify(inspected.manifest) !== JSON.stringify(entry.manifest)) {
64
- throw new Error('Portable app manifest does not match its amalgm.app.json');
65
- }
66
- return await apps.register({
67
- cwd: directory,
68
- autostart: options.autostart ?? entry.app?.autostart ?? true,
69
- keepAlive: options.keepAlive ?? entry.app?.keepAlive ?? true,
70
- });
71
- }
72
- catch (error) {
73
- fs.rmSync(directory, { recursive: true, force: true });
74
- throw error;
75
- }
76
- }
77
- export { exportApp, installApp, removeInstalledSource };
78
- //# sourceMappingURL=portable.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"portable.js","sourceRoot":"","sources":["../src/portable.ts"],"names":[],"mappings":"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"}