@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
package/dist/portable.js
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
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 allocate(root, name) {
|
|
17
|
+
fs.mkdirSync(root, { recursive: true });
|
|
18
|
+
const base = slug(name);
|
|
19
|
+
for (let index = 0; index < 1000; index += 1) {
|
|
20
|
+
const candidate = path.join(root, index ? `${base}-${index + 1}` : base);
|
|
21
|
+
if (!fs.existsSync(candidate))
|
|
22
|
+
return candidate;
|
|
23
|
+
}
|
|
24
|
+
throw new Error(`Could not allocate an install directory for app: ${String(name)}`);
|
|
25
|
+
}
|
|
26
|
+
function exportApp(apps, appId) {
|
|
27
|
+
const app = apps.get(appId);
|
|
28
|
+
if (!app)
|
|
29
|
+
throw new Error(`App not found: ${appId}`);
|
|
30
|
+
const packed = apps.pack(app.sourceDir);
|
|
31
|
+
return {
|
|
32
|
+
sourceAppId: app.id,
|
|
33
|
+
manifest: packed.manifest,
|
|
34
|
+
app: {
|
|
35
|
+
name: packed.manifest.name,
|
|
36
|
+
description: packed.manifest.description,
|
|
37
|
+
buildCommand: packed.manifest.buildCommand,
|
|
38
|
+
startCommand: packed.manifest.startCommand,
|
|
39
|
+
autostart: true,
|
|
40
|
+
keepAlive: true,
|
|
41
|
+
},
|
|
42
|
+
toolIds: packed.manifest.toolIds,
|
|
43
|
+
files: packed.files,
|
|
44
|
+
totalBytes: packed.totalBytes,
|
|
45
|
+
skipped: packed.excluded,
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
async function installApp(apps, entry, options = {}) {
|
|
49
|
+
if (!Array.isArray(entry?.files) || !entry.files.length)
|
|
50
|
+
throw new Error('A portable app must include files');
|
|
51
|
+
const directory = allocate(path.join(apps.stateDir, 'imports'), entry.manifest?.name || entry.app?.name);
|
|
52
|
+
try {
|
|
53
|
+
unpackPackage({ files: entry.files }, directory);
|
|
54
|
+
const inspected = apps.validate(directory);
|
|
55
|
+
if (entry.manifest && JSON.stringify(inspected.manifest) !== JSON.stringify(entry.manifest)) {
|
|
56
|
+
throw new Error('Portable app manifest does not match its amalgm.app.json');
|
|
57
|
+
}
|
|
58
|
+
return await apps.register({
|
|
59
|
+
cwd: directory,
|
|
60
|
+
autostart: options.autostart ?? entry.app?.autostart ?? true,
|
|
61
|
+
keepAlive: options.keepAlive ?? entry.app?.keepAlive ?? true,
|
|
62
|
+
});
|
|
63
|
+
}
|
|
64
|
+
catch (error) {
|
|
65
|
+
fs.rmSync(directory, { recursive: true, force: true });
|
|
66
|
+
throw error;
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
export { exportApp, installApp };
|
|
70
|
+
//# sourceMappingURL=portable.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"portable.js","sourceRoot":"","sources":["../src/portable.ts"],"names":[],"mappings":"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"}
|
package/dist/presentation.d.ts
CHANGED
|
@@ -2,8 +2,10 @@ import type { Apps } from './apps.js';
|
|
|
2
2
|
import type { AppRecord, AppsOptions, AppRoute, AppView } from './types.js';
|
|
3
3
|
declare function appEnvironment(options: AppsOptions, app: AppRecord): NodeJS.ProcessEnv;
|
|
4
4
|
declare function appProcessEnvironment(app: AppRecord, supplied: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
|
|
5
|
+
/** What a tool linked to this app is told at call time: where the app is. */
|
|
6
|
+
declare function linkedToolEnvironment(app: AppRecord | null): Record<string, string>;
|
|
5
7
|
declare function replacePort(command: string, port: number): string;
|
|
6
8
|
declare function appView(service: Apps, app: AppRecord | null): AppView | null;
|
|
7
9
|
declare function eligibleRoutes(service: Apps): AppRoute[];
|
|
8
10
|
declare function queueRoutes(service: Apps, reason: string): Promise<unknown>;
|
|
9
|
-
export { appEnvironment, appProcessEnvironment, appView, eligibleRoutes, queueRoutes, replacePort, };
|
|
11
|
+
export { appEnvironment, appProcessEnvironment, appView, eligibleRoutes, linkedToolEnvironment, queueRoutes, replacePort, };
|
package/dist/presentation.js
CHANGED
|
@@ -21,6 +21,17 @@ function appProcessEnvironment(app, supplied) {
|
|
|
21
21
|
AMALGM_APP_DATA_DIR: app.dataDir,
|
|
22
22
|
};
|
|
23
23
|
}
|
|
24
|
+
/** What a tool linked to this app is told at call time: where the app is. */
|
|
25
|
+
function linkedToolEnvironment(app) {
|
|
26
|
+
if (!app)
|
|
27
|
+
return {};
|
|
28
|
+
return {
|
|
29
|
+
AMALGM_APP_ID: app.id,
|
|
30
|
+
AMALGM_APP_URL: app.publicUrl,
|
|
31
|
+
AMALGM_APP_PORT: String(app.port),
|
|
32
|
+
AMALGM_APP_DATA_DIR: app.dataDir,
|
|
33
|
+
};
|
|
34
|
+
}
|
|
24
35
|
function replacePort(command, port) {
|
|
25
36
|
return command.replace(/\{port\}/g, String(port));
|
|
26
37
|
}
|
|
@@ -59,5 +70,5 @@ function queueRoutes(service, reason) {
|
|
|
59
70
|
});
|
|
60
71
|
return service.routeQueue;
|
|
61
72
|
}
|
|
62
|
-
export { appEnvironment, appProcessEnvironment, appView, eligibleRoutes, queueRoutes, replacePort, };
|
|
73
|
+
export { appEnvironment, appProcessEnvironment, appView, eligibleRoutes, linkedToolEnvironment, queueRoutes, replacePort, };
|
|
63
74
|
//# sourceMappingURL=presentation.js.map
|
package/dist/presentation.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"presentation.js","sourceRoot":"","sources":["../src/presentation.ts"],"names":[],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"presentation.js","sourceRoot":"","sources":["../src/presentation.ts"],"names":[],"mappings":"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"}
|
package/dist/types.d.ts
CHANGED
|
@@ -203,6 +203,39 @@ export interface RollbackInput {
|
|
|
203
203
|
releaseId?: string;
|
|
204
204
|
versionId?: string;
|
|
205
205
|
}
|
|
206
|
+
export interface AppSettingsPatch {
|
|
207
|
+
name?: string;
|
|
208
|
+
description?: string;
|
|
209
|
+
autostart?: boolean;
|
|
210
|
+
keepAlive?: boolean;
|
|
211
|
+
dnsConnected?: boolean;
|
|
212
|
+
}
|
|
213
|
+
export interface AppLogs {
|
|
214
|
+
appId: string;
|
|
215
|
+
path: string;
|
|
216
|
+
lines: string[];
|
|
217
|
+
}
|
|
218
|
+
/** The export/install port shape. `sourceAppId` is lineage a sharing layer may strip. */
|
|
219
|
+
export interface PortableApp {
|
|
220
|
+
sourceAppId?: string;
|
|
221
|
+
manifest: AppManifest;
|
|
222
|
+
app: {
|
|
223
|
+
name: string;
|
|
224
|
+
description: string;
|
|
225
|
+
buildCommand: string | null;
|
|
226
|
+
startCommand: string;
|
|
227
|
+
autostart: boolean;
|
|
228
|
+
keepAlive: boolean;
|
|
229
|
+
};
|
|
230
|
+
toolIds: string[];
|
|
231
|
+
files: PackedPackage['files'];
|
|
232
|
+
totalBytes: number;
|
|
233
|
+
skipped: ExcludedPackageFile[];
|
|
234
|
+
}
|
|
235
|
+
export interface InstallAppOptions {
|
|
236
|
+
autostart?: boolean;
|
|
237
|
+
keepAlive?: boolean;
|
|
238
|
+
}
|
|
206
239
|
export interface ReadyOptions {
|
|
207
240
|
heartbeatIntervalMs?: number;
|
|
208
241
|
}
|
|
@@ -244,8 +277,15 @@ export interface McpResult {
|
|
|
244
277
|
}
|
|
245
278
|
export interface McpTool {
|
|
246
279
|
name: string;
|
|
280
|
+
title: string;
|
|
247
281
|
description: string;
|
|
248
282
|
inputSchema: Record<string, unknown>;
|
|
283
|
+
annotations: {
|
|
284
|
+
readOnlyHint: boolean;
|
|
285
|
+
destructiveHint: boolean;
|
|
286
|
+
idempotentHint: boolean;
|
|
287
|
+
openWorldHint: boolean;
|
|
288
|
+
};
|
|
249
289
|
handler(args?: Record<string, unknown>): Promise<McpResult>;
|
|
250
290
|
}
|
|
251
291
|
export interface JsonRpcRequest {
|
|
@@ -1,68 +1,12 @@
|
|
|
1
|
-
# Engine integration
|
|
1
|
+
# Historical Engine integration
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
Amalgm Engine is deprecated. It is useful only as read-only evidence for
|
|
4
|
+
legacy request shapes, migrations, and parity vectors. It is not a runtime
|
|
5
|
+
composer, source-flow destination, generated-product host, or fallback for
|
|
6
|
+
`@amalgm/apps`.
|
|
6
7
|
|
|
7
|
-
|
|
8
|
+
The former workflow copied generated Apps output into Engine. That workflow is
|
|
9
|
+
retired: product changes begin and remain in this repository, and active
|
|
10
|
+
machine composition uses the published package through `@amalgm/shell`.
|
|
8
11
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
- app, release, deployment, process, and health state;
|
|
12
|
-
- validation, packaging, builds, activation, rollback, and supervision;
|
|
13
|
-
- the SDK, CLI commands, MCP tool definitions, and the app-side lease.
|
|
14
|
-
|
|
15
|
-
In the target independently supervised composition, Engine owns:
|
|
16
|
-
|
|
17
|
-
- runtime URLs, authentication, ports, and public route publication;
|
|
18
|
-
- outer service-level availability and restart policy for the Apps product;
|
|
19
|
-
- state-event and UI composition;
|
|
20
|
-
- mechanical projection of Apps records into shared client surfaces;
|
|
21
|
-
- one-time import from Engine's superseded `apps.json` registry.
|
|
22
|
-
|
|
23
|
-
Engine adapters must call the public `Apps` service. They must not write the
|
|
24
|
-
Apps database, deployment directories, or release directories directly.
|
|
25
|
-
Engine's outer supervisor treats Apps as one product service and never starts,
|
|
26
|
-
stops, adopts, or restarts an individual app. The complete hierarchy is in
|
|
27
|
-
[SUPERVISION.md](./SUPERVISION.md).
|
|
28
|
-
|
|
29
|
-
## Source flow
|
|
30
|
-
|
|
31
|
-
From an Engine checkout next to this repository:
|
|
32
|
-
|
|
33
|
-
```sh
|
|
34
|
-
npm run apps:sync
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
Engine's `scripts/sync-products.mjs apps` builds the canonical TypeScript source,
|
|
38
|
-
then copies `PURPOSE.md`, `package.json`, and generated `dist/` into
|
|
39
|
-
`runtime/products/apps/`. It also writes `SOURCE.json` with the product
|
|
40
|
-
version, source commit, and a deterministic content digest.
|
|
41
|
-
`npm run apps:check` rejects generated drift without rewriting files. The
|
|
42
|
-
Engine npm package copies that generated runtime during its existing runtime
|
|
43
|
-
sync.
|
|
44
|
-
|
|
45
|
-
Make product changes here first, verify them here, then sync Engine. Files
|
|
46
|
-
under Engine's `runtime/products/apps/` are generated artifacts and are not
|
|
47
|
-
edited by hand.
|
|
48
|
-
|
|
49
|
-
## Composition
|
|
50
|
-
|
|
51
|
-
The `amalgm apps ...` command uses the generated product CLI with an HTTP
|
|
52
|
-
client for Engine's long-lived service. This keeps command parsing canonical
|
|
53
|
-
without creating a competing process supervisor. Engine's MCP server mounts
|
|
54
|
-
the product's MCP tool definitions over the same lazily resolved service.
|
|
55
|
-
Engine REST routes adapt their request and response shapes to it.
|
|
56
|
-
|
|
57
|
-
The event tunnel and local gateway use one shared Engine adapter that reads
|
|
58
|
-
routable ports from the product database. Runtime route readers never consult
|
|
59
|
-
the superseded registry.
|
|
60
|
-
|
|
61
|
-
On boot, Engine imports each existing app once while preserving its stable id,
|
|
62
|
-
app ref, public URL, port, desired state, and live process when possible.
|
|
63
|
-
Import progress is recorded independently. Invalid source data blocks cleanup
|
|
64
|
-
and remains recoverable; it never becomes a fallback runtime registry.
|
|
65
|
-
|
|
66
|
-
Apps and Tools may contain references to one another, but neither adapter
|
|
67
|
-
silently rewrites the other product. A workflow that intentionally changes
|
|
68
|
-
both must have an explicit owner outside Core's transport adapters.
|
|
12
|
+
See [SHELL_INTEGRATION.md](./SHELL_INTEGRATION.md) for the current boundary.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Shell integration
|
|
2
|
+
|
|
3
|
+
`@amalgm/apps` is the canonical Apps product. `@amalgm/shell` is the active
|
|
4
|
+
machine composer and imports the published package; it does not copy Apps
|
|
5
|
+
source or keep a second registry.
|
|
6
|
+
|
|
7
|
+
## Ownership boundary
|
|
8
|
+
|
|
9
|
+
Apps owns:
|
|
10
|
+
|
|
11
|
+
- app, release, deployment, process-generation, and health state;
|
|
12
|
+
- validation, packaging, builds, activation, rollback, and supervision;
|
|
13
|
+
- its SQLite store and release/deployment directories;
|
|
14
|
+
- SDK, CLI, MCP, HTTP, and app-side lease behavior.
|
|
15
|
+
|
|
16
|
+
Shell owns:
|
|
17
|
+
|
|
18
|
+
- the exact package version used by a Shell release;
|
|
19
|
+
- machine identity, authenticated route mounting, and host effects;
|
|
20
|
+
- selection of the machine-local Apps state directory;
|
|
21
|
+
- projection of the Apps catalog into runtime and UI surfaces; and
|
|
22
|
+
- orderly construction and shutdown of the one Apps service instance it owns.
|
|
23
|
+
|
|
24
|
+
Core supplies portable admission and supervision decision contracts. Neither
|
|
25
|
+
Core nor Shell writes the Apps database, starts an app process outside the
|
|
26
|
+
Apps public service, or reimplements release and deployment behavior.
|
|
27
|
+
|
|
28
|
+
## Current release boundary
|
|
29
|
+
|
|
30
|
+
Shell imports Apps and mounts its HTTP/MCP adapters in composed and development
|
|
31
|
+
hosts. In the signed machine host, Apps is initialized lazily when its selected
|
|
32
|
+
Toolbox route is invoked. The current signed service catalog still names Core,
|
|
33
|
+
Files, Agents, Tools, and Chat; a package dependency or mounted route is not by
|
|
34
|
+
itself admission as an independently booted signed service.
|
|
35
|
+
|
|
36
|
+
## Engine evidence
|
|
37
|
+
|
|
38
|
+
Legacy `/apps`, `/artifacts`, app-ref, and migration shapes may be compared with
|
|
39
|
+
Engine read-only. Engine never runs beside Shell and is never a fallback.
|
package/docs/SUPERVISION.md
CHANGED
|
@@ -1,36 +1,36 @@
|
|
|
1
1
|
# Supervision ownership
|
|
2
2
|
|
|
3
|
-
The Apps supervisor stays in `@amalgm/apps`. Standalone use and Amalgm
|
|
3
|
+
The Apps supervisor stays in `@amalgm/apps`. Standalone use and Amalgm Shell
|
|
4
4
|
composition execute the same supervisor; combining products does not move app
|
|
5
|
-
lifecycle logic into
|
|
5
|
+
lifecycle logic into Shell or Core.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## Active composition
|
|
8
8
|
|
|
9
9
|
```text
|
|
10
|
-
|
|
11
|
-
├──
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
│ └── @amalgm/events supervisor
|
|
17
|
-
└── Realtime product-service supervisor
|
|
18
|
-
└── @amalgm/realtime supervisor
|
|
10
|
+
@amalgm/shell
|
|
11
|
+
├── Core identity, transport, and portable supervision policy
|
|
12
|
+
└── @amalgm/apps public service
|
|
13
|
+
└── @amalgm/apps supervisor
|
|
14
|
+
├── App A process generations
|
|
15
|
+
└── App B process generations
|
|
19
16
|
```
|
|
20
17
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
18
|
+
Apps owns its domain supervisor. Shell constructs the product once for the
|
|
19
|
+
selected state directory and supplies host effects. Core owns portable route
|
|
20
|
+
admission, health vocabulary, and restart decision contracts; it does not own
|
|
21
|
+
the Apps store or a stateful app-process supervisor. The levels have different
|
|
22
|
+
authority:
|
|
24
23
|
|
|
25
24
|
| Supervisor | Owns | Does not own |
|
|
26
25
|
| --- | --- | --- |
|
|
27
|
-
| Apps supervisor | app desired state, deployments, process generations, health, restart budgets |
|
|
26
|
+
| Apps supervisor | app desired state, deployments, process generations, health, restart budgets | Shell lifecycle or other products |
|
|
28
27
|
| Apps product-service supervisor | Apps-service availability, service restart budget, shutdown and readiness | individual app processes or the Apps database |
|
|
29
|
-
|
|
|
28
|
+
| Core contracts | app-route admission, health vocabulary, portable restart decisions | Apps persistence or process ownership |
|
|
29
|
+
| Shell composition | machine effects, identity, route mounting, product availability | app lifecycle decisions or Apps persistence |
|
|
30
30
|
|
|
31
|
-
There is never a second Apps supervisor in
|
|
32
|
-
the
|
|
33
|
-
|
|
31
|
+
There is never a second Apps supervisor in Shell or Core. Shell instantiates
|
|
32
|
+
the public Apps service or communicates with a process that does. CLI, MCP,
|
|
33
|
+
HTTP, gateways, and UI code are clients or adapters.
|
|
34
34
|
|
|
35
35
|
## One owner per state directory
|
|
36
36
|
|
|
@@ -49,13 +49,14 @@ Failures remain inside the smallest responsible supervisor:
|
|
|
49
49
|
|
|
50
50
|
- an app crash is handled by the Apps supervisor and changes only that app;
|
|
51
51
|
- an exhausted app restart budget degrades that app, not the Apps service;
|
|
52
|
-
- an Apps-service failure makes Apps unavailable to
|
|
53
|
-
-
|
|
54
|
-
|
|
55
|
-
-
|
|
52
|
+
- an Apps-service failure makes Apps unavailable to Shell;
|
|
53
|
+
- Shell may restart or disable the Apps service without restarting unrelated
|
|
54
|
+
products or the rest of the runtime;
|
|
55
|
+
- Shell and Core never repair an Apps-service failure by editing app process
|
|
56
|
+
state.
|
|
56
57
|
|
|
57
|
-
This distinction is what
|
|
58
|
-
|
|
58
|
+
This distinction is what lets Shell compose many products without recreating a
|
|
59
|
+
monolithic supervisor.
|
|
59
60
|
|
|
60
61
|
## Lifecycle modes
|
|
61
62
|
|
|
@@ -67,7 +68,7 @@ The Apps supervisor owns both product behaviors:
|
|
|
67
68
|
- **always on** — the supervisor starts the app with the service and applies
|
|
68
69
|
its durable restart budget while the desired state remains running.
|
|
69
70
|
|
|
70
|
-
These are policies of the Apps supervisor.
|
|
71
|
+
These are policies of the Apps supervisor. A host may request a policy change,
|
|
71
72
|
but it does not implement the policy itself. Explicit `start` and `stop`
|
|
72
73
|
already provide the no-rebuild process mechanics; the first-class
|
|
73
74
|
`runtimeMode` and idle policy remain to be implemented.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@amalgm/apps",
|
|
3
|
-
"version": "0.1.3-preview.
|
|
3
|
+
"version": "0.1.3-preview.34545378804",
|
|
4
4
|
"description": "Local-first, versioned application deployment for Amalgm.",
|
|
5
5
|
"license": "UNLICENSED",
|
|
6
6
|
"private": false,
|
|
@@ -36,6 +36,7 @@
|
|
|
36
36
|
"files": [
|
|
37
37
|
"docs",
|
|
38
38
|
"dist",
|
|
39
|
+
"skills",
|
|
39
40
|
"PURPOSE.md",
|
|
40
41
|
"README.md"
|
|
41
42
|
],
|
|
@@ -56,7 +57,7 @@
|
|
|
56
57
|
"node": ">=24"
|
|
57
58
|
},
|
|
58
59
|
"dependencies": {
|
|
59
|
-
"@amalgm/core": "0.
|
|
60
|
+
"@amalgm/core": "0.5.1-preview.34318364556",
|
|
60
61
|
"@types/better-sqlite3": "^7.6.13",
|
|
61
62
|
"@types/node": "^20.19.43",
|
|
62
63
|
"better-sqlite3": "^12.6.2",
|
|
@@ -88,11 +89,11 @@
|
|
|
88
89
|
"package.json"
|
|
89
90
|
]
|
|
90
91
|
},
|
|
91
|
-
"gitHead": "
|
|
92
|
+
"gitHead": "4cacd05a52114be92df76e204fb80a5b0d06406b",
|
|
92
93
|
"amalgmSource": {
|
|
93
94
|
"repository": "amalgm-inc/amalgm-apps",
|
|
94
95
|
"branch": "preview",
|
|
95
|
-
"commit": "
|
|
96
|
-
"occurrence": "
|
|
96
|
+
"commit": "4cacd05a52114be92df76e204fb80a5b0d06406b",
|
|
97
|
+
"occurrence": "34545378804"
|
|
97
98
|
}
|
|
98
99
|
}
|