@matatbread/matbot-host-node 0.0.0-stage → 0.5.0
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/LICENSE +201 -0
- package/README.md +31 -2
- package/package.json +40 -3
- package/src/env-vault.ts +89 -0
- package/src/index.ts +7 -0
- package/src/plugin-description.ts +125 -0
- package/src/plugin-members.ts +112 -0
- package/src/plugin-resolver.ts +89 -0
- package/src/principal-als.ts +29 -0
- package/src/register.js +9 -0
- package/src/typescript-hooks.d.ts +5 -0
- package/src/typescript-hooks.js +46 -0
- package/src/usage-als.ts +16 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright 2026 Mat Woolf
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
package/README.md
CHANGED
|
@@ -1,3 +1,32 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @matatbread/matbot-host-node
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
What a Node application needs to embed [matbot](https://github.com/MatAtBread/matbot) that
|
|
4
|
+
`@matatbread/matbot-core` cannot hold, because it uses Node APIs and core must also run in a browser. Not a
|
|
5
|
+
plugin: an application building a machine with `assembleMachine` imports these and passes them in. Nothing
|
|
6
|
+
here assumes a config file, a directory layout or how plugins are acquired; each takes the path or
|
|
7
|
+
directory it works on.
|
|
8
|
+
|
|
9
|
+
**`@matatbread/matbot-host-node/register`** — start the application with
|
|
10
|
+
`node --import @matatbread/matbot-host-node/register app.ts`. matbot's packages are published as TypeScript
|
|
11
|
+
source, so this registers the two module hooks Node needs to load them: a `.js` import resolves to the `.ts`
|
|
12
|
+
file, and types are stripped under `node_modules` too, where Node refuses to. A host with hooks of its own
|
|
13
|
+
registers the pair from **`/typescript-hooks`** (`typescriptHooks()`) beneath them, as the matbot CLI does.
|
|
14
|
+
|
|
15
|
+
**`@matatbread/matbot-host-node`**:
|
|
16
|
+
|
|
17
|
+
- `createAlsPrincipalCarrier`, `createAlsUsageCarrier` — `AsyncLocalStorage` carriers, so concurrent
|
|
18
|
+
requests and turns each keep their own principal and token accounting. Install them before anything
|
|
19
|
+
reads one, then `runAs(principal, …)` at each entry point (a request handler, a message). core's
|
|
20
|
+
`createConstantPrincipalCarrier` is the alternative for a single-principal process.
|
|
21
|
+
- `nodePluginMembers(machine, baseDir)` — `loadPlugin`, `unloadPlugin`, `resolver` and
|
|
22
|
+
`TypeScriptStripper` for a host that loads plugins already on disk: a path (relative to `baseDir`), or a
|
|
23
|
+
package installed where `baseDir` resolves. Nothing is fetched or installed. A host that acquires
|
|
24
|
+
plugins itself resolves each specifier its own way and loads the result with
|
|
25
|
+
`loadPluginsWithDescriptions`; `nodePluginResolver`, `readPluginMeta` and `backfillPluginDescription`
|
|
26
|
+
are the other pieces the matbot CLI builds its own loading from.
|
|
27
|
+
- `EnvFileVault.open(path, env?)` — a vault persisted to an environment file. Values are plaintext,
|
|
28
|
+
readable by anything that can read the file. `parseEnvFile`/`readEnvFile` read the same format.
|
|
29
|
+
|
|
30
|
+
Storage is a plugin's: `@matatbread/matbot-storage-filesystem` exports `FilesystemStorageBackend` for a
|
|
31
|
+
host to boot on, and core's `MemoryStorageBackend` (`@matatbread/matbot-core/storage-base`) persists
|
|
32
|
+
nothing.
|
package/package.json
CHANGED
|
@@ -1,6 +1,43 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@matatbread/matbot-host-node",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
|
|
3
|
+
"version": "0.5.0",
|
|
4
|
+
"engines": {
|
|
5
|
+
"node": ">=24.0.0"
|
|
6
|
+
},
|
|
7
|
+
"files": [
|
|
8
|
+
"src"
|
|
9
|
+
],
|
|
10
|
+
"description": "What a Node application needs to embed matbot that core cannot hold, being Node-only: AsyncLocalStorage principal and usage carriers, the module hooks that load matbot's TypeScript-source packages, plugin loading from disk, and a .env-file vault.",
|
|
11
|
+
"keywords": [
|
|
12
|
+
"matbot",
|
|
13
|
+
"llm",
|
|
14
|
+
"ai",
|
|
15
|
+
"agent"
|
|
16
|
+
],
|
|
17
|
+
"license": "Apache-2.0",
|
|
18
|
+
"type": "module",
|
|
19
|
+
"exports": {
|
|
20
|
+
".": "./src/index.ts",
|
|
21
|
+
"./register": "./src/register.js",
|
|
22
|
+
"./typescript-hooks": "./src/typescript-hooks.js"
|
|
23
|
+
},
|
|
24
|
+
"repository": {
|
|
25
|
+
"type": "git",
|
|
26
|
+
"url": "git+https://github.com/MatAtBread/matbot.git",
|
|
27
|
+
"directory": "host-node"
|
|
28
|
+
},
|
|
29
|
+
"publishConfig": {
|
|
30
|
+
"access": "public"
|
|
31
|
+
},
|
|
32
|
+
"peerDependencies": {
|
|
33
|
+
"@matatbread/matbot-core": "^0.5.0"
|
|
34
|
+
},
|
|
35
|
+
"devDependencies": {
|
|
36
|
+
"@types/node": "^22.0.0",
|
|
37
|
+
"typescript": "^6.0.3",
|
|
38
|
+
"@matatbread/matbot-core": "^0.5.0"
|
|
39
|
+
},
|
|
40
|
+
"scripts": {
|
|
41
|
+
"typecheck": "tsc --noEmit"
|
|
42
|
+
}
|
|
6
43
|
}
|
package/src/env-vault.ts
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
import { VaultImpl } from '@matatbread/matbot-core';
|
|
2
|
+
import { readFile, writeFile } from 'node:fs/promises';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* A vault persisted to an environment file (`NAME=value` lines): secrets stored at runtime survive a
|
|
6
|
+
* restart. The values are plaintext, readable by anything that can read the file — a shell tool included.
|
|
7
|
+
*
|
|
8
|
+
* It reads and writes its own file, so the two cannot disagree about the format: a value is written in the
|
|
9
|
+
* form {@link parseEnvFile} reads back unchanged, quoted where it would otherwise be reinterpreted (a ` #`
|
|
10
|
+
* read as a comment, surrounding quotes or whitespace stripped), and one it cannot represent (a line break)
|
|
11
|
+
* is refused rather than written broken.
|
|
12
|
+
*
|
|
13
|
+
* Persistence hooks the write primitive, not createSecret — so the reference and dedup paths of
|
|
14
|
+
* createSecret (which never call writeSecret) never append a dead line to the file.
|
|
15
|
+
*
|
|
16
|
+
* The file may also be read as an environment file by whatever starts the process (a systemd
|
|
17
|
+
* `EnvironmentFile=`), so the name policy is narrower than the base vault's: anything else is written,
|
|
18
|
+
* accepted, and then dropped by such a reader with at most a log line nobody sees.
|
|
19
|
+
*/
|
|
20
|
+
export class EnvFileVault extends VaultImpl {
|
|
21
|
+
private readonly envPath: string;
|
|
22
|
+
|
|
23
|
+
/** The vault over `envPath`, holding what the file holds; `env` (say `process.env`) wins over it. */
|
|
24
|
+
static async open(envPath: string, env?: Record<string, string | undefined>): Promise<EnvFileVault> {
|
|
25
|
+
return new EnvFileVault(envPath, { ...await readEnvFile(envPath), ...env });
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** Over `envPath`, holding exactly `env`: the file is written to, never read. {@link open} reads it. */
|
|
29
|
+
constructor(envPath: string, env?: Record<string, string | undefined>) {
|
|
30
|
+
super({}, env);
|
|
31
|
+
this.envPath = envPath;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
override unstorableKey(name: string): string | undefined {
|
|
35
|
+
return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name)
|
|
36
|
+
? undefined
|
|
37
|
+
: 'this vault persists to a .env file, so a secret name must be a valid environment-variable name: a letter or underscore, then letters, digits or underscores only (e.g. ACME_EMAIL_PASSWORD)';
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
override async writeSecret(name: string, value: string): Promise<void> {
|
|
41
|
+
if (/[\r\n]/.test(value)) throw new Error(`Secret "${name}" contains a line break, which a .env file cannot hold`);
|
|
42
|
+
await super.writeSecret(name, value);
|
|
43
|
+
|
|
44
|
+
let existing = '';
|
|
45
|
+
try { existing = await readFile(this.envPath, 'utf8'); } catch { /* no file yet */ }
|
|
46
|
+
const lines = existing
|
|
47
|
+
? existing.split('\n').filter(l => l !== '' && !l.startsWith(`${name}=`))
|
|
48
|
+
: [];
|
|
49
|
+
if (value !== '') lines.push(`${name}=${envValue(value)}`);
|
|
50
|
+
await writeFile(this.envPath, lines.length ? lines.join('\n') + '\n' : '', 'utf8');
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
// Bare where the reader would return it unchanged; otherwise quoted, which the reader strips and nothing else.
|
|
55
|
+
function envValue(value: string): string {
|
|
56
|
+
const bare = value === value.trim() && !/\s#/.test(value) && !/^(["']).*\1$/s.test(value);
|
|
57
|
+
if (bare) return value;
|
|
58
|
+
return value.includes("'") ? `"${value}"` : `'${value}'`;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** The `NAME=value` lines of an environment file: `#` comments, an optional `export `, and a value either
|
|
62
|
+
* quoted (the quotes stripped) or bare (a trailing ` # comment` and surrounding whitespace dropped). */
|
|
63
|
+
export function parseEnvFile(text: string): Record<string, string> {
|
|
64
|
+
const out: Record<string, string> = {};
|
|
65
|
+
for (const raw of text.split('\n')) {
|
|
66
|
+
const line = raw.trim();
|
|
67
|
+
if (!line || line.startsWith('#')) continue;
|
|
68
|
+
const stripped = line.startsWith('export ') ? line.slice(7).trimStart() : line;
|
|
69
|
+
const eq = stripped.indexOf('=');
|
|
70
|
+
if (eq === -1) continue;
|
|
71
|
+
const key = stripped.slice(0, eq).trimEnd();
|
|
72
|
+
if (!key) continue;
|
|
73
|
+
let val = stripped.slice(eq + 1);
|
|
74
|
+
if (val.length >= 2 && ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'")))) {
|
|
75
|
+
val = val.slice(1, -1);
|
|
76
|
+
} else {
|
|
77
|
+
const commentIdx = val.search(/\s+#/);
|
|
78
|
+
if (commentIdx !== -1) val = val.slice(0, commentIdx);
|
|
79
|
+
val = val.trim();
|
|
80
|
+
}
|
|
81
|
+
out[key] = val;
|
|
82
|
+
}
|
|
83
|
+
return out;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** {@link parseEnvFile} of the file at `envPath`; an absent or unreadable file holds nothing. */
|
|
87
|
+
export async function readEnvFile(envPath: string): Promise<Record<string, string>> {
|
|
88
|
+
try { return parseEnvFile(await readFile(envPath, 'utf8')); } catch { return {}; }
|
|
89
|
+
}
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
export { createAlsPrincipalCarrier } from './principal-als.js';
|
|
2
|
+
export { createAlsUsageCarrier } from './usage-als.js';
|
|
3
|
+
export { EnvFileVault, parseEnvFile, readEnvFile } from './env-vault.js';
|
|
4
|
+
export { nodePluginResolver } from './plugin-resolver.js';
|
|
5
|
+
export { loadPluginsWithDescriptions, readPluginMeta, backfillPluginDescription } from './plugin-description.js';
|
|
6
|
+
export type { PluginLoadRequest } from './plugin-description.js';
|
|
7
|
+
export { nodePluginMembers, nodeTypeScriptStripper } from './plugin-members.js';
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
import { readFile } from 'node:fs/promises';
|
|
2
|
+
import { fileURLToPath, pathToFileURL } from 'node:url';
|
|
3
|
+
import { createRequire } from 'node:module';
|
|
4
|
+
import path from 'node:path';
|
|
5
|
+
import { loadPlugins } from '@matatbread/matbot-core';
|
|
6
|
+
import type { MatbotPlugin, PluginManifest, MatbotMachine, PromptFn, Runtime } from '@matatbread/matbot-core';
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* A fully host-resolved plugin load request. The CLI resolves a config/human specifier (`spec`) to
|
|
10
|
+
* the URL it actually imports (`importSpec`) and reads the resolved package.json for `name`/`runtimes`,
|
|
11
|
+
* so the loader records `spec` as `plugin.specifier` (matching matbot.yaml) while importing `importSpec`.
|
|
12
|
+
*/
|
|
13
|
+
export interface PluginLoadRequest {
|
|
14
|
+
spec: string;
|
|
15
|
+
importSpec: string;
|
|
16
|
+
name?: string;
|
|
17
|
+
version?: string;
|
|
18
|
+
runtimes?: readonly Runtime[];
|
|
19
|
+
/** Resolution-time findings the loader appends to a failure it records for this spec. */
|
|
20
|
+
notes?: readonly string[];
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
// Where to begin the upward package.json search for a load specifier. Specifiers that
|
|
24
|
+
// reach the runtime are file: URLs (resolved by the CLI before registration); install-time
|
|
25
|
+
// specifiers may be relative paths or bare npm names. A bare name is resolved through the
|
|
26
|
+
// project's module graph, which only works once the package is actually on disk.
|
|
27
|
+
export function startDir(specifier: string, baseDir: string): string | undefined {
|
|
28
|
+
const bare = (specifier.split('?')[0]) ?? specifier;
|
|
29
|
+
if (bare.startsWith('file://')) return path.dirname(fileURLToPath(bare));
|
|
30
|
+
if (bare.startsWith('./') || bare.startsWith('../') || path.isAbsolute(bare)) {
|
|
31
|
+
return path.resolve(baseDir, bare);
|
|
32
|
+
}
|
|
33
|
+
try {
|
|
34
|
+
const require = createRequire(pathToFileURL(path.join(baseDir, 'index.js')).href);
|
|
35
|
+
return path.dirname(require.resolve(bare));
|
|
36
|
+
} catch {
|
|
37
|
+
return undefined;
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
async function descriptionFromPackageJson(specifier: string, baseDir: string): Promise<string | undefined> {
|
|
42
|
+
let dir = startDir(specifier, baseDir);
|
|
43
|
+
if (dir === undefined) return undefined;
|
|
44
|
+
while (true) {
|
|
45
|
+
try {
|
|
46
|
+
const pkg = JSON.parse(await readFile(path.join(dir, 'package.json'), 'utf8')) as { description?: string };
|
|
47
|
+
if (pkg.description) return pkg.description;
|
|
48
|
+
} catch { /* no package.json here, keep walking up */ }
|
|
49
|
+
const parent = path.dirname(dir);
|
|
50
|
+
if (parent === dir) return undefined;
|
|
51
|
+
dir = parent;
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Read the canonical name (+ optional version and matbotRuntime) from the package.json governing a
|
|
57
|
+
* resolved import URL — the node analogue of the web assembler's specNames. Walks up to the first
|
|
58
|
+
* package.json carrying a `name` (a nameless intermediate is not the plugin's manifest), so the CLI can
|
|
59
|
+
* hand the loader a precomputed identity and `plugin.specifier` can stay the human/config specifier.
|
|
60
|
+
*
|
|
61
|
+
* The version comes from here for the same reason the name does: the resolver's own lookup starts from
|
|
62
|
+
* the config specifier, which for a bare name, a URL or a version range reaches no manifest.
|
|
63
|
+
*/
|
|
64
|
+
export async function readPluginMeta(specifier: string, baseDir: string): Promise<{ name?: string; version?: string; runtimes?: Runtime[] }> {
|
|
65
|
+
let dir = startDir(specifier, baseDir);
|
|
66
|
+
if (dir === undefined) return {};
|
|
67
|
+
while (true) {
|
|
68
|
+
try {
|
|
69
|
+
const pkg = JSON.parse(await readFile(path.join(dir, 'package.json'), 'utf8')) as { name?: string; version?: unknown; matbotRuntime?: unknown };
|
|
70
|
+
if (typeof pkg.name === 'string') {
|
|
71
|
+
const runtimes = Array.isArray(pkg.matbotRuntime)
|
|
72
|
+
? pkg.matbotRuntime.filter((r): r is Runtime => typeof r === 'string')
|
|
73
|
+
: undefined;
|
|
74
|
+
return {
|
|
75
|
+
name: pkg.name,
|
|
76
|
+
...(typeof pkg.version === 'string' ? { version: pkg.version } : {}),
|
|
77
|
+
...(runtimes !== undefined ? { runtimes } : {}),
|
|
78
|
+
};
|
|
79
|
+
}
|
|
80
|
+
} catch { /* no package.json here, keep walking up */ }
|
|
81
|
+
const parent = path.dirname(dir);
|
|
82
|
+
if (parent === dir) return {};
|
|
83
|
+
dir = parent;
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
// Fill in plugin.manifest.description from the plugin's package.json, unless the plugin
|
|
88
|
+
// already declares a description. Presence is checked with `in` so a getter (a description
|
|
89
|
+
// computed at read time from some condition) counts as declared and is left untouched —
|
|
90
|
+
// we never read it, only observe that it exists.
|
|
91
|
+
export async function backfillPluginDescription(
|
|
92
|
+
plugin: MatbotPlugin,
|
|
93
|
+
specifier: string,
|
|
94
|
+
baseDir: string,
|
|
95
|
+
): Promise<void> {
|
|
96
|
+
if (plugin.manifest !== undefined && 'description' in plugin.manifest) return;
|
|
97
|
+
const description = await descriptionFromPackageJson(specifier, baseDir);
|
|
98
|
+
if (description === undefined) return;
|
|
99
|
+
if (plugin.manifest !== undefined) {
|
|
100
|
+
(plugin.manifest as { description?: string }).description = description;
|
|
101
|
+
} else {
|
|
102
|
+
(plugin as { manifest?: PluginManifest }).manifest = { description };
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
// loadPlugins lives in the platform-neutral runner and so cannot read package.json itself.
|
|
107
|
+
// This wrapper is the Node entry point: every CLI plugin load goes through it, so a freshly
|
|
108
|
+
// loaded plugin always has its package.json description folded into its manifest. baseDir is
|
|
109
|
+
// the project directory (where package.json paths and node_modules resolve from).
|
|
110
|
+
export async function loadPluginsWithDescriptions(
|
|
111
|
+
requests: readonly PluginLoadRequest[],
|
|
112
|
+
services: MatbotMachine,
|
|
113
|
+
baseDir: string,
|
|
114
|
+
bustCache = false,
|
|
115
|
+
prompt?: PromptFn,
|
|
116
|
+
onLoadError: 'skip' | 'throw' = 'skip',
|
|
117
|
+
): Promise<MatbotPlugin[]> {
|
|
118
|
+
const plugins = await loadPlugins(requests, services, bustCache, prompt, onLoadError);
|
|
119
|
+
// plugin.specifier is the config-level `spec`; the package.json lives at the resolved importSpec.
|
|
120
|
+
const importByCfg = new Map(requests.map(r => [r.spec, r.importSpec]));
|
|
121
|
+
for (const plugin of plugins) {
|
|
122
|
+
await backfillPluginDescription(plugin, importByCfg.get(plugin.specifier) ?? plugin.specifier, baseDir);
|
|
123
|
+
}
|
|
124
|
+
return plugins;
|
|
125
|
+
}
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
import { readFile } from 'node:fs/promises';
|
|
2
|
+
import { createRequire, stripTypeScriptTypes } from 'node:module';
|
|
3
|
+
import { fileURLToPath, pathToFileURL } from 'node:url';
|
|
4
|
+
import path from 'node:path';
|
|
5
|
+
import { getPluginNameForSpecifier, getRegisteredPlugins, unloadPlugin } from '@matatbread/matbot-core';
|
|
6
|
+
import type { HostMembers, MatbotMachine, MatbotPlugin, PromptFn } from '@matatbread/matbot-core';
|
|
7
|
+
import { loadPluginsWithDescriptions, readPluginMeta, type PluginLoadRequest } from './plugin-description.js';
|
|
8
|
+
import { nodePluginResolver } from './plugin-resolver.js';
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* Given a package exports field (or any nested value), return the first
|
|
12
|
+
* string entry point, preferring "import" > "default" > first value.
|
|
13
|
+
*/
|
|
14
|
+
function resolveExportsEntry(value: unknown): string | undefined {
|
|
15
|
+
if (typeof value === 'string') return value;
|
|
16
|
+
if (typeof value !== 'object' || value === null) return undefined;
|
|
17
|
+
const obj = value as Record<string, unknown>;
|
|
18
|
+
// Subpath map: { ".": ... } → unwrap the "." entry
|
|
19
|
+
if ('.' in obj) return resolveExportsEntry(obj['.']);
|
|
20
|
+
// Condition map: prefer import > default > first
|
|
21
|
+
for (const key of ['import', 'default', ...Object.keys(obj)]) {
|
|
22
|
+
if (key in obj) return resolveExportsEntry(obj[key]);
|
|
23
|
+
}
|
|
24
|
+
return undefined;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** The import URL of a package directory: its `exports["."]` entry, else the directory itself. So config
|
|
28
|
+
* can name the package folder rather than a deep `src/` path. */
|
|
29
|
+
export async function packageEntry(dir: string): Promise<string> {
|
|
30
|
+
try {
|
|
31
|
+
const pkg = JSON.parse(await readFile(path.join(dir, 'package.json'), 'utf8')) as Record<string, unknown>;
|
|
32
|
+
const main = resolveExportsEntry(pkg['exports']);
|
|
33
|
+
if (typeof main === 'string') return pathToFileURL(path.resolve(dir, main)).href;
|
|
34
|
+
} catch { /* no package.json or unparseable — import the directory */ }
|
|
35
|
+
return pathToFileURL(dir).href;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** The import URL of an installed package, resolved from each of `fromDirs` in turn; undefined when none
|
|
39
|
+
* has it on disk. */
|
|
40
|
+
export function installedEntry(spec: string, fromDirs: readonly string[]): string | undefined {
|
|
41
|
+
for (const dir of fromDirs) {
|
|
42
|
+
try { return pathToFileURL(createRequire(path.join(dir, '_')).resolve(spec)).href; } catch { /* try the next */ }
|
|
43
|
+
}
|
|
44
|
+
return undefined;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** A load request for `importSpec`, carrying the name, version and runtimes its package.json declares. */
|
|
48
|
+
export async function loadRequest(spec: string, importSpec: string, baseDir: string): Promise<PluginLoadRequest> {
|
|
49
|
+
const meta = await readPluginMeta(importSpec, baseDir);
|
|
50
|
+
return {
|
|
51
|
+
spec,
|
|
52
|
+
importSpec,
|
|
53
|
+
...(meta.name !== undefined ? { name: meta.name } : {}),
|
|
54
|
+
...(meta.version !== undefined ? { version: meta.version } : {}),
|
|
55
|
+
...(meta.runtimes !== undefined ? { runtimes: meta.runtimes } : {}),
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Resolve a plugin that is already where Node can import it: a path (relative to `baseDir`), or a package
|
|
61
|
+
* installed where `baseDir` resolves. Nothing is fetched or installed — that is acquisition, which is the
|
|
62
|
+
* host's own (the CLI's is in `apps/cli/src/plugins`). A specifier that resolves to nothing passes
|
|
63
|
+
* through, so the loader reports it.
|
|
64
|
+
*/
|
|
65
|
+
export async function resolveInstalledPlugin(spec: string, baseDir: string): Promise<PluginLoadRequest> {
|
|
66
|
+
const bare = (spec.split('?')[0]) ?? spec;
|
|
67
|
+
if (bare.startsWith('file://') || bare.startsWith('./') || bare.startsWith('../') || path.isAbsolute(bare)) {
|
|
68
|
+
const dir = bare.startsWith('file://') ? fileURLToPath(bare) : path.resolve(baseDir, bare);
|
|
69
|
+
return loadRequest(spec, await packageEntry(dir), baseDir);
|
|
70
|
+
}
|
|
71
|
+
const entry = installedEntry(spec, [baseDir]);
|
|
72
|
+
return entry !== undefined ? loadRequest(spec, entry, baseDir) : { spec, importSpec: spec };
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** Unload by the specifier a plugin was loaded with, or by its canonical name. */
|
|
76
|
+
export async function unloadNodePlugin(specifier: string, machine: MatbotMachine): Promise<boolean> {
|
|
77
|
+
const name = getPluginNameForSpecifier(specifier)
|
|
78
|
+
?? (getRegisteredPlugins().some(p => p.name === specifier) ? specifier : undefined);
|
|
79
|
+
if (name === undefined) {
|
|
80
|
+
console.warn(`[matbot] No loaded plugin found for "${specifier}"`);
|
|
81
|
+
return false;
|
|
82
|
+
}
|
|
83
|
+
return unloadPlugin(name, machine);
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** Node's own type stripper: blanks types in place, so line numbers survive. */
|
|
87
|
+
export const nodeTypeScriptStripper: NonNullable<HostMembers['TypeScriptStripper']> = {
|
|
88
|
+
strip: (source: string) => stripTypeScriptTypes(source),
|
|
89
|
+
};
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* The plugin-loading members of a Node host that loads only what is already on disk — a matbot embedded
|
|
93
|
+
* in an application, with a fixed set of plugins and no `plugin` tool. A host that acquires plugins (the
|
|
94
|
+
* CLI) resolves through acquisition instead, and builds its own `loadPlugin` from the same pieces.
|
|
95
|
+
*/
|
|
96
|
+
export function nodePluginMembers(
|
|
97
|
+
machine: () => MatbotMachine, baseDir: string,
|
|
98
|
+
): Pick<HostMembers, 'loadPlugin' | 'unloadPlugin' | 'resolver' | 'TypeScriptStripper' | 'projectDir'> {
|
|
99
|
+
return {
|
|
100
|
+
async loadPlugin(specifier: string, prompt?: PromptFn): Promise<MatbotPlugin> {
|
|
101
|
+
const request = await resolveInstalledPlugin(specifier, baseDir);
|
|
102
|
+
const plugin = (await loadPluginsWithDescriptions([request], machine(), baseDir, /* bustCache */ false, prompt, /* onLoadError */ 'throw'))[0];
|
|
103
|
+
if (plugin === undefined) throw new Error(`No plugin loaded for specifier "${specifier}"`);
|
|
104
|
+
return plugin;
|
|
105
|
+
},
|
|
106
|
+
unloadPlugin: (specifier: string) => unloadNodePlugin(specifier, machine()),
|
|
107
|
+
resolver: nodePluginResolver(baseDir),
|
|
108
|
+
TypeScriptStripper: nodeTypeScriptStripper,
|
|
109
|
+
// What relative specifiers resolve from is what a plugin writing code for this host to load needs.
|
|
110
|
+
projectDir: baseDir,
|
|
111
|
+
};
|
|
112
|
+
}
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
import { readFile } from 'node:fs/promises';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import type { PluginResolver, Runtime } from '@matatbread/matbot-core';
|
|
4
|
+
import { startDir } from './plugin-description.js';
|
|
5
|
+
|
|
6
|
+
const VALID_RUNTIMES: readonly Runtime[] = ['node', 'browser'];
|
|
7
|
+
|
|
8
|
+
/** Coerce a raw package.json `matbotRuntime` value into a runtime list, or undefined if absent/malformed. */
|
|
9
|
+
function normalizeRuntimes(raw: unknown, pkgName: string): readonly Runtime[] | undefined {
|
|
10
|
+
if (raw === undefined) return undefined;
|
|
11
|
+
if (!Array.isArray(raw)) {
|
|
12
|
+
console.warn(`[matbot] Ignoring matbotRuntime in "${pkgName}": expected an array of ${VALID_RUNTIMES.join('/')}, got ${typeof raw}.`);
|
|
13
|
+
return undefined;
|
|
14
|
+
}
|
|
15
|
+
const valid = raw.filter((r): r is Runtime => VALID_RUNTIMES.includes(r as Runtime));
|
|
16
|
+
for (const r of raw) {
|
|
17
|
+
if (!VALID_RUNTIMES.includes(r as Runtime)) {
|
|
18
|
+
console.warn(`[matbot] Ignoring unknown matbotRuntime "${String(r)}" in "${pkgName}" (known: ${VALID_RUNTIMES.join(', ')}).`);
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
return valid;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* Node host PluginResolver: derives a plugin's canonical name (its package.json `name`) from the
|
|
26
|
+
* specifier it was loaded with. This is the single source of plugin identity on the node host —
|
|
27
|
+
* the loader calls identify() to stamp `MatbotPlugin.name`, so authors no longer hand-declare it.
|
|
28
|
+
*
|
|
29
|
+
* A bare npm name is already the package name and passes through. A path / file: URL is resolved to
|
|
30
|
+
* a start directory and the nearest package.json walked up to; its `name` wins, falling back to the
|
|
31
|
+
* directory's basename if no package.json carries one.
|
|
32
|
+
*/
|
|
33
|
+
export function nodePluginResolver(baseDir: string): PluginResolver {
|
|
34
|
+
return {
|
|
35
|
+
async identify(specifier: string): Promise<string> {
|
|
36
|
+
const bare = (specifier.split('?')[0]) ?? specifier;
|
|
37
|
+
const isPathLike = bare.startsWith('file://') || bare.startsWith('./') ||
|
|
38
|
+
bare.startsWith('../') || path.isAbsolute(bare);
|
|
39
|
+
if (!isPathLike) return specifier; // bare npm name — already the package name
|
|
40
|
+
|
|
41
|
+
let dir = startDir(specifier, baseDir);
|
|
42
|
+
if (dir === undefined) return specifier;
|
|
43
|
+
const fallback = path.basename(dir);
|
|
44
|
+
|
|
45
|
+
while (true) {
|
|
46
|
+
try {
|
|
47
|
+
const pkg = JSON.parse(await readFile(path.join(dir, 'package.json'), 'utf8')) as { name?: string };
|
|
48
|
+
if (pkg.name) return pkg.name;
|
|
49
|
+
} catch { /* no package.json here, keep walking up */ }
|
|
50
|
+
const parent = path.dirname(dir);
|
|
51
|
+
if (parent === dir) return fallback; // filesystem root reached without a named package.json
|
|
52
|
+
dir = parent;
|
|
53
|
+
}
|
|
54
|
+
},
|
|
55
|
+
|
|
56
|
+
// Read `version` off the plugin's package.json — the nearest named one, the same boundary
|
|
57
|
+
// identify() uses. Undefined when unreadable (no package.json / no version field).
|
|
58
|
+
async version(specifier: string): Promise<string | undefined> {
|
|
59
|
+
let dir = startDir(specifier, baseDir);
|
|
60
|
+
if (dir === undefined) return undefined;
|
|
61
|
+
while (true) {
|
|
62
|
+
try {
|
|
63
|
+
const pkg = JSON.parse(await readFile(path.join(dir, 'package.json'), 'utf8')) as { name?: string; version?: string };
|
|
64
|
+
if (pkg.name) return pkg.version;
|
|
65
|
+
} catch { /* no package.json here, keep walking up */ }
|
|
66
|
+
const parent = path.dirname(dir);
|
|
67
|
+
if (parent === dir) return undefined;
|
|
68
|
+
dir = parent;
|
|
69
|
+
}
|
|
70
|
+
},
|
|
71
|
+
|
|
72
|
+
// Read `matbotRuntime` off the plugin's package.json — the nearest one with a `name`, the same
|
|
73
|
+
// boundary identify() uses — so a declaration on the plugin (not an enclosing monorepo root) wins.
|
|
74
|
+
// Undefined means "not declared": the loader then imports and falls back to load/rollback.
|
|
75
|
+
async runtimes(specifier: string): Promise<readonly Runtime[] | undefined> {
|
|
76
|
+
let dir = startDir(specifier, baseDir);
|
|
77
|
+
if (dir === undefined) return undefined;
|
|
78
|
+
while (true) {
|
|
79
|
+
try {
|
|
80
|
+
const pkg = JSON.parse(await readFile(path.join(dir, 'package.json'), 'utf8')) as { name?: string; matbotRuntime?: unknown };
|
|
81
|
+
if (pkg.name) return normalizeRuntimes(pkg.matbotRuntime, pkg.name);
|
|
82
|
+
} catch { /* no package.json here, keep walking up */ }
|
|
83
|
+
const parent = path.dirname(dir);
|
|
84
|
+
if (parent === dir) return undefined;
|
|
85
|
+
dir = parent;
|
|
86
|
+
}
|
|
87
|
+
},
|
|
88
|
+
};
|
|
89
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { AsyncLocalStorage } from 'node:async_hooks';
|
|
2
|
+
import type { Principal, PrincipalCarrier } from '@matatbread/matbot-core';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Node `PrincipalCarrier` backed by `AsyncLocalStorage`. Each `run`/`enter` scope is isolated per
|
|
6
|
+
* async flow, so the many concurrent per-session `pump` loops (and per-request frontend handlers)
|
|
7
|
+
* each carry their own principal without leaking into one another — the multi-user case ALS exists
|
|
8
|
+
* for. The browser counterpart is `createConstantPrincipalCarrier` (single principal, no isolation).
|
|
9
|
+
*/
|
|
10
|
+
export function createAlsPrincipalCarrier(): PrincipalCarrier {
|
|
11
|
+
const als = new AsyncLocalStorage<Principal>();
|
|
12
|
+
return {
|
|
13
|
+
current(): Principal {
|
|
14
|
+
const p = als.getStore();
|
|
15
|
+
if (p === undefined) {
|
|
16
|
+
throw new Error('No principal in context — currentPrincipal() called outside any runAs/enter scope.');
|
|
17
|
+
}
|
|
18
|
+
return p;
|
|
19
|
+
},
|
|
20
|
+
tryCurrent: () => als.getStore(),
|
|
21
|
+
run: (principal, fn) => als.run(principal, fn),
|
|
22
|
+
enter(principal): void {
|
|
23
|
+
if (als.getStore() !== undefined) {
|
|
24
|
+
throw new Error('A principal is already established — enter() is for entry points; use runAs for nested/delegated scopes.');
|
|
25
|
+
}
|
|
26
|
+
als.enterWith(principal);
|
|
27
|
+
},
|
|
28
|
+
};
|
|
29
|
+
}
|
package/src/register.js
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
// `node --import @matatbread/matbot-host-node/register app.ts` — what an application needs before it can
|
|
2
|
+
// import matbot's packages, which are published as TypeScript source. See typescript-hooks.js.
|
|
3
|
+
//
|
|
4
|
+
// In-thread, through `registerHooks()`: `register()` runs hooks on a thread of their own, which since Node
|
|
5
|
+
// 24.12 costs a round trip for every resolve and load, and is deprecated (DEP0205).
|
|
6
|
+
import { registerHooks } from 'node:module';
|
|
7
|
+
import { typescriptHooks } from './typescript-hooks.js';
|
|
8
|
+
|
|
9
|
+
registerHooks(typescriptHooks());
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import type { ResolveHookSync, LoadHookSync } from 'node:module';
|
|
2
|
+
|
|
3
|
+
/** The resolve (`.js` import → `.ts` file) and load (strip types, under node_modules too) hooks that loading
|
|
4
|
+
* matbot's TypeScript-source packages needs, for a host registering them alongside hooks of its own. */
|
|
5
|
+
export function typescriptHooks(): { resolve: ResolveHookSync; load: LoadHookSync };
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
// The two Node module hooks that loading matbot's packages needs. They are published as TypeScript source
|
|
2
|
+
// importing `./x.js` where the file on disk is `./x.ts`, and Node, which strips types itself, does neither
|
|
3
|
+
// half of that: it does not try `.ts` for a `.js` import, and it refuses to strip anything under
|
|
4
|
+
// node_modules (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), which is where every package lives once
|
|
5
|
+
// installed. `register.js` beside this registers them; a host composing hooks of its own takes them here.
|
|
6
|
+
//
|
|
7
|
+
// Plain JavaScript with declarations beside it, for the same reason as cache-layout.js: this IS the type
|
|
8
|
+
// stripper, so it cannot itself be a `.ts`.
|
|
9
|
+
//
|
|
10
|
+
// Which of the two is tried first depends on who is importing. From a `.ts` file, `./x.js` is TypeScript's
|
|
11
|
+
// spelling of the sibling `./x.ts`, so that is tried first — matbot's own source is hundreds of such imports,
|
|
12
|
+
// and failing a `.js` lookup before each is a measurable share of a boot. From anything else the `.js` is
|
|
13
|
+
// tried first, so a package that ships compiled output is never shadowed by source it also ships.
|
|
14
|
+
// `require()` passes through untouched: CommonJS has its own rules, and a `.ts` it loads is not an ES
|
|
15
|
+
// module by fiat. A query string (a reload's cache-buster) is not part of the file name.
|
|
16
|
+
import { stripTypeScriptTypes } from 'node:module';
|
|
17
|
+
import { readFileSync } from 'node:fs';
|
|
18
|
+
import { fileURLToPath } from 'node:url';
|
|
19
|
+
|
|
20
|
+
const isRequire = context => context.conditions?.includes('require') ?? false;
|
|
21
|
+
const TS_FILE = /^file:[^?#]*\.[cm]?ts(?:[?#].*)?$/;
|
|
22
|
+
|
|
23
|
+
export function typescriptHooks() {
|
|
24
|
+
return {
|
|
25
|
+
resolve(specifier, context, nextResolve) {
|
|
26
|
+
if (isRequire(context) || !specifier.endsWith('.js')) return nextResolve(specifier, context);
|
|
27
|
+
const ts = specifier.slice(0, -3) + '.ts';
|
|
28
|
+
if (TS_FILE.test(context.parentURL ?? '')) {
|
|
29
|
+
try { return nextResolve(ts, context); }
|
|
30
|
+
catch { return nextResolve(specifier, context); }
|
|
31
|
+
}
|
|
32
|
+
try {
|
|
33
|
+
return nextResolve(specifier, context);
|
|
34
|
+
} catch (e) {
|
|
35
|
+
if (e?.code !== 'ERR_MODULE_NOT_FOUND') throw e;
|
|
36
|
+
try { return nextResolve(ts, context); }
|
|
37
|
+
catch { throw e; }
|
|
38
|
+
}
|
|
39
|
+
},
|
|
40
|
+
load(url, context, nextLoad) {
|
|
41
|
+
if (isRequire(context) || !TS_FILE.test(url)) return nextLoad(url, context);
|
|
42
|
+
const source = readFileSync(fileURLToPath(url.replace(/[?#].*$/, '')), 'utf8');
|
|
43
|
+
return { format: 'module', source: stripTypeScriptTypes(source, { mode: 'strip', sourceUrl: url }), shortCircuit: true };
|
|
44
|
+
},
|
|
45
|
+
};
|
|
46
|
+
}
|
package/src/usage-als.ts
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { AsyncLocalStorage } from 'node:async_hooks';
|
|
2
|
+
import type { UsageCarrier, UsageScope } from '@matatbread/matbot-core';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Node `UsageCarrier` backed by `AsyncLocalStorage`. Each turn's `withUsageScope` runs in its own
|
|
6
|
+
* isolated scope, so the concurrent per-session `pump` loops accrue token accounting independently —
|
|
7
|
+
* a completion run inside one turn's tool never lands in another's tally. The browser counterpart is
|
|
8
|
+
* `createSerialUsageCarrier` (single scope, no async isolation).
|
|
9
|
+
*/
|
|
10
|
+
export function createAlsUsageCarrier(): UsageCarrier {
|
|
11
|
+
const als = new AsyncLocalStorage<UsageScope>();
|
|
12
|
+
return {
|
|
13
|
+
run: (scope, fn) => als.run(scope, fn),
|
|
14
|
+
tryCurrent: () => als.getStore(),
|
|
15
|
+
};
|
|
16
|
+
}
|