@yodaos-pkg/aix 0.10.0 → 0.12.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/README.md +221 -15
- package/check/index.d.ts +7 -0
- package/check/index.js +69 -0
- package/check/types.d.ts +48 -0
- package/check/types.js +1 -0
- package/index.d.ts +88 -10
- package/index.js +114 -19
- package/jsr.json +1 -1
- package/package.json +1 -2
- package/pkg/README.md +221 -15
- package/pkg/aix_web.d.ts +49 -14
- package/pkg/aix_web.js +144 -11
- package/pkg/aix_web_bg.wasm +0 -0
- package/pkg/aix_web_bg.wasm.d.ts +16 -9
- package/pkg/package.json +1 -1
- package/pkg-reader/README.md +455 -0
- package/pkg-reader/aix_web.d.ts +77 -0
- package/pkg-reader/aix_web.js +654 -0
- package/pkg-reader/aix_web_bg.wasm +0 -0
- package/pkg-reader/aix_web_bg.wasm.d.ts +23 -0
- package/pkg-reader/package.json +15 -0
package/index.js
CHANGED
|
@@ -1,5 +1,36 @@
|
|
|
1
|
-
import
|
|
2
|
-
|
|
1
|
+
import initReader, { AixReaderWasm } from './pkg-reader/aix_web.js';
|
|
2
|
+
let toolingPromise;
|
|
3
|
+
let readerPromise;
|
|
4
|
+
function initializeReader() {
|
|
5
|
+
return readerPromise ?? (readerPromise = initReader().catch((error) => {
|
|
6
|
+
readerPromise = undefined;
|
|
7
|
+
throw error;
|
|
8
|
+
}));
|
|
9
|
+
}
|
|
10
|
+
// A shared promise prevents concurrent pack/check calls from instantiating
|
|
11
|
+
// separate memories. A failed fetch may be retried by a later SDK call.
|
|
12
|
+
function loadTooling() {
|
|
13
|
+
return toolingPromise ?? (toolingPromise = import('./pkg/aix_web.js').then(async (module) => {
|
|
14
|
+
await module.default();
|
|
15
|
+
return module;
|
|
16
|
+
}).catch((error) => {
|
|
17
|
+
toolingPromise = undefined;
|
|
18
|
+
throw error;
|
|
19
|
+
}));
|
|
20
|
+
}
|
|
21
|
+
/** A package failed the optional source check in AIX.From(). */
|
|
22
|
+
export class AixCheckError extends Error {
|
|
23
|
+
constructor(report) {
|
|
24
|
+
const count = report.diagnostics.filter(diagnostic => diagnostic.severity === 'error').length;
|
|
25
|
+
super(`AIX check failed with ${count} ${count === 1 ? 'error' : 'errors'}`);
|
|
26
|
+
this.report = report;
|
|
27
|
+
this.name = 'AixCheckError';
|
|
28
|
+
}
|
|
29
|
+
/** All check diagnostics, including warnings. */
|
|
30
|
+
get diagnostics() {
|
|
31
|
+
return this.report.diagnostics;
|
|
32
|
+
}
|
|
33
|
+
}
|
|
3
34
|
function generateBuildId() {
|
|
4
35
|
const cryptoApi = globalThis.crypto;
|
|
5
36
|
if (typeof cryptoApi?.randomUUID === 'function') {
|
|
@@ -24,12 +55,37 @@ export class AIX {
|
|
|
24
55
|
constructor(reader) {
|
|
25
56
|
this.reader = reader;
|
|
26
57
|
}
|
|
58
|
+
/** Run source structure, JS/TS syntax, schema, and permission checks in memory. */
|
|
59
|
+
static async checkFromSource(files, options) {
|
|
60
|
+
options?.onProgress?.({ type: 'loading_checker' });
|
|
61
|
+
const [tooling, { checkSource }] = await Promise.all([loadTooling(), import('./check/index.js')]);
|
|
62
|
+
return checkSource(files, tooling, options);
|
|
63
|
+
}
|
|
64
|
+
/** Check a browser directory selection, retaining webkitRelativePath. */
|
|
65
|
+
static async checkFromFiles(files, options) {
|
|
66
|
+
const sources = await Promise.all(files.map(async (file) => ({
|
|
67
|
+
path: resolveWebFilePath(file),
|
|
68
|
+
data: new Uint8Array(await file.arrayBuffer()),
|
|
69
|
+
})));
|
|
70
|
+
const selectedRoot = sources[0]?.path.split('/')[0];
|
|
71
|
+
if (selectedRoot && files.every((file) => file.webkitRelativePath?.startsWith(`${selectedRoot}/`))) {
|
|
72
|
+
for (const source of sources)
|
|
73
|
+
source.path = source.path.slice(selectedRoot.length + 1);
|
|
74
|
+
}
|
|
75
|
+
return AIX.checkFromSource(sources, options);
|
|
76
|
+
}
|
|
27
77
|
/**
|
|
28
78
|
* Initialize the WASM module and create an AIX instance from the given data.
|
|
29
79
|
* @param data The .aix file content as Uint8Array or File
|
|
80
|
+
* @param limits Caller budgets; set all three when accepting untrusted archives.
|
|
81
|
+
* Values must be non-negative safe integers. Without limits, retains the
|
|
82
|
+
* historical unlimited policy. Input bytes and caller-retained copies are
|
|
83
|
+
* outside these budgets.
|
|
84
|
+
* @param check Run the source checker before returning; defaults to false.
|
|
85
|
+
* Error diagnostics reject with AixCheckError; warnings alone are accepted.
|
|
30
86
|
*/
|
|
31
|
-
static async From(data) {
|
|
32
|
-
await
|
|
87
|
+
static async From(data, limits, check = false) {
|
|
88
|
+
await initializeReader();
|
|
33
89
|
let buffer;
|
|
34
90
|
if (data instanceof Uint8Array) {
|
|
35
91
|
buffer = data;
|
|
@@ -38,14 +94,32 @@ export class AIX {
|
|
|
38
94
|
const arrayBuffer = await data.arrayBuffer();
|
|
39
95
|
buffer = new Uint8Array(arrayBuffer);
|
|
40
96
|
}
|
|
41
|
-
const reader =
|
|
42
|
-
|
|
97
|
+
const reader = limits === undefined
|
|
98
|
+
? new AixReaderWasm(buffer)
|
|
99
|
+
: AixReaderWasm.with_limits(buffer, limits);
|
|
100
|
+
try {
|
|
101
|
+
if (check) {
|
|
102
|
+
const files = reader.list()
|
|
103
|
+
.filter(entry => !entry.name.endsWith('/') && entry.name !== 'VERSION'
|
|
104
|
+
&& !entry.name.startsWith('META-INF/aix/'))
|
|
105
|
+
.map(entry => ({ path: entry.name, data: reader.read_file(entry.name) }));
|
|
106
|
+
const report = await AIX.checkFromSource(files);
|
|
107
|
+
if (report.diagnostics.some(diagnostic => diagnostic.severity === 'error')) {
|
|
108
|
+
throw new AixCheckError(report);
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
return new AIX(reader);
|
|
112
|
+
}
|
|
113
|
+
catch (error) {
|
|
114
|
+
reader.free();
|
|
115
|
+
throw error;
|
|
116
|
+
}
|
|
43
117
|
}
|
|
44
118
|
static async pack(files, options) {
|
|
45
|
-
await
|
|
119
|
+
const tooling = await loadTooling();
|
|
46
120
|
const buildId = options?.buildId ?? generateBuildId();
|
|
47
121
|
const optimize = options?.optimize === false ? undefined : options?.optimize;
|
|
48
|
-
const result = pack_aix(files, buildId, options?.engine, optimize);
|
|
122
|
+
const result = tooling.pack_aix(files, buildId, options?.engine, optimize, options?.agentId);
|
|
49
123
|
return { data: result.data, report: result.report, warnings: result.warnings ?? [] };
|
|
50
124
|
}
|
|
51
125
|
/**
|
|
@@ -56,12 +130,12 @@ export class AIX {
|
|
|
56
130
|
* `.aixignore` files are honored, and the rule files are omitted.
|
|
57
131
|
*/
|
|
58
132
|
static async packFromSource(files, options) {
|
|
59
|
-
await
|
|
133
|
+
const tooling = await loadTooling();
|
|
60
134
|
const buildId = options?.buildId ?? generateBuildId();
|
|
61
135
|
const optimize = options?.optimize === false ? undefined : options?.optimize;
|
|
62
136
|
const result = options?.onProgress
|
|
63
|
-
? getPackFromSourceWithProgress()(files, buildId, options.engine, optimize, options.onProgress)
|
|
64
|
-
: getPackFromSource()(files, buildId, options?.engine, optimize);
|
|
137
|
+
? getPackFromSourceWithProgress(tooling)(files, buildId, options.engine, optimize, options.onProgress, options.agentId)
|
|
138
|
+
: getPackFromSource(tooling)(files, buildId, options?.engine, optimize, options?.agentId);
|
|
65
139
|
return { data: result.data, report: result.report, warnings: result.warnings ?? [] };
|
|
66
140
|
}
|
|
67
141
|
static async packFromFiles(files, options) {
|
|
@@ -72,11 +146,11 @@ export class AIX {
|
|
|
72
146
|
return AIX.packFromSource(sourceFiles, options);
|
|
73
147
|
}
|
|
74
148
|
static async optimize(data, options) {
|
|
75
|
-
await
|
|
149
|
+
const tooling = await loadTooling();
|
|
76
150
|
const buffer = data instanceof Uint8Array
|
|
77
151
|
? data
|
|
78
152
|
: new Uint8Array(await data.arrayBuffer());
|
|
79
|
-
const result = optimize_aix(buffer, options);
|
|
153
|
+
const result = tooling.optimize_aix(buffer, options);
|
|
80
154
|
return { data: result.data, report: result.report, warnings: result.warnings ?? [] };
|
|
81
155
|
}
|
|
82
156
|
/**
|
|
@@ -98,6 +172,10 @@ export class AIX {
|
|
|
98
172
|
getVersion() {
|
|
99
173
|
return this.reader.get_version();
|
|
100
174
|
}
|
|
175
|
+
/** Stable project ID from the manifest; undefined for legacy packages. */
|
|
176
|
+
getAgentId() {
|
|
177
|
+
return this.reader.get_agent_id();
|
|
178
|
+
}
|
|
101
179
|
supportsEngine(currentVersion) {
|
|
102
180
|
return this.reader.supports_engine(currentVersion);
|
|
103
181
|
}
|
|
@@ -107,17 +185,34 @@ export class AIX {
|
|
|
107
185
|
getTitle() {
|
|
108
186
|
return this.reader.get_title();
|
|
109
187
|
}
|
|
188
|
+
/**
|
|
189
|
+
* Get permission names declared in app.json, in declaration order.
|
|
190
|
+
* Missing declarations return []; invalid configuration throws.
|
|
191
|
+
* This does not query runtime or device authorization.
|
|
192
|
+
*/
|
|
193
|
+
getPermissions() {
|
|
194
|
+
return this.reader.get_permissions();
|
|
195
|
+
}
|
|
110
196
|
/**
|
|
111
197
|
* Get all pages from app.json and pages/*.json.
|
|
112
198
|
*/
|
|
113
199
|
getPages() {
|
|
114
200
|
return this.reader.get_pages();
|
|
115
201
|
}
|
|
202
|
+
/**
|
|
203
|
+
* Resolve readable page resources and metadata, excluding failed pages/tools.
|
|
204
|
+
* Inspect diagnostics to distinguish a valid empty result from resolution errors.
|
|
205
|
+
* Widget/title fields are independent. This does not run full source checks.
|
|
206
|
+
*/
|
|
207
|
+
resolveMetadata() {
|
|
208
|
+
return this.reader.resolve_metadata();
|
|
209
|
+
}
|
|
116
210
|
/**
|
|
117
211
|
* Get all widgets from app.json after validating that each .ink entry exists.
|
|
212
|
+
* When locale is provided, merge displayName and description from app.<locale>.json.
|
|
118
213
|
*/
|
|
119
|
-
getWidgets() {
|
|
120
|
-
return this.reader.get_widgets();
|
|
214
|
+
getWidgets(locale) {
|
|
215
|
+
return this.reader.get_widgets(locale);
|
|
121
216
|
}
|
|
122
217
|
/**
|
|
123
218
|
* Get all tools from app.json and pages/*.json in OpenAI format.
|
|
@@ -130,15 +225,15 @@ function resolveWebFilePath(file) {
|
|
|
130
225
|
const candidate = file.webkitRelativePath;
|
|
131
226
|
return candidate && candidate.length > 0 ? candidate : file.name;
|
|
132
227
|
}
|
|
133
|
-
function getPackFromSource() {
|
|
134
|
-
const packFromSource =
|
|
228
|
+
function getPackFromSource(tooling) {
|
|
229
|
+
const packFromSource = tooling.pack_aix_from_source;
|
|
135
230
|
if (!packFromSource) {
|
|
136
231
|
throw new Error('pack_aix_from_source is not available in the current WASM bundle');
|
|
137
232
|
}
|
|
138
233
|
return packFromSource;
|
|
139
234
|
}
|
|
140
|
-
function getPackFromSourceWithProgress() {
|
|
141
|
-
const packFromSourceWithProgress =
|
|
235
|
+
function getPackFromSourceWithProgress(tooling) {
|
|
236
|
+
const packFromSourceWithProgress = tooling.pack_aix_from_source_with_progress;
|
|
142
237
|
if (!packFromSourceWithProgress) {
|
|
143
238
|
throw new Error('pack_aix_from_source_with_progress is not available in the current WASM bundle');
|
|
144
239
|
}
|
package/jsr.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@yodaos-pkg/aix",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.12.0",
|
|
4
4
|
"description": "Ink AIX Package Reader",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "index.js",
|
|
@@ -8,7 +8,6 @@
|
|
|
8
8
|
"files": [
|
|
9
9
|
"*"
|
|
10
10
|
],
|
|
11
|
-
"dependencies": {},
|
|
12
11
|
"repository": {
|
|
13
12
|
"url": "https://github.com/jsar-project/ink"
|
|
14
13
|
},
|
package/pkg/README.md
CHANGED
|
@@ -30,7 +30,134 @@ async function fromFile(file: File) {
|
|
|
30
30
|
}
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
-
##
|
|
33
|
+
## WASM Loading
|
|
34
|
+
|
|
35
|
+
By default, `AIX.From()` and all instance methods initialize a separate reader-only WASM.
|
|
36
|
+
They do not load image codecs, script minification, or source/schema checking.
|
|
37
|
+
The optional `AIX.From(data, limits, true)` check also loads the full tooling module.
|
|
38
|
+
The first pack, optimize, or source-check call lazily loads the full module;
|
|
39
|
+
concurrent tooling calls share initialization. Existing reader instances remain
|
|
40
|
+
valid after tooling loads, and tooling-only calls do not fetch reader WASM.
|
|
41
|
+
|
|
42
|
+
The generated distribution includes `pkg-reader/` and `pkg/`; self-host both
|
|
43
|
+
with their adjacent JS/WASM files. The existing raw `pkg/aix_web.js` exports
|
|
44
|
+
remain complete and the npm CLI keeps its synchronous full Node.js bundle.
|
|
45
|
+
Rust builds default to the `tooling` feature; `--no-default-features` produces
|
|
46
|
+
reader exports without the packer dependency. `npm run build` builds both web
|
|
47
|
+
artifacts; `npm run build:wasm:reader` builds only the reader artifact.
|
|
48
|
+
|
|
49
|
+
Local measurements reduced reader WASM from 5,514,021 to 355,365 bytes. Mixed
|
|
50
|
+
reader/tooling workflows load both binaries and retain two module memories.
|
|
51
|
+
See the repository's `docs/wasm.md` for baseline samples, timing limits, the
|
|
52
|
+
compatibility plan, and reproduction commands.
|
|
53
|
+
|
|
54
|
+
## Archive Resource Limits
|
|
55
|
+
|
|
56
|
+
Pass caller-selected budgets when reading untrusted packages:
|
|
57
|
+
|
|
58
|
+
```typescript
|
|
59
|
+
const aix = await AIX.From(file, {
|
|
60
|
+
maxEntries: 1024,
|
|
61
|
+
maxEntryBytes: 8 * 1024 * 1024,
|
|
62
|
+
maxTotalBytes: 32 * 1024 * 1024,
|
|
63
|
+
});
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
All limits are inclusive non-negative safe integers. Directories and signature
|
|
67
|
+
metadata count too. Metadata is rejected before extraction if over budget;
|
|
68
|
+
extraction also bounds output and retains CRC and size checks. `maxTotalBytes`
|
|
69
|
+
is the sum of declared uncompressed sizes, not a cumulative read budget.
|
|
70
|
+
Zero allows no entries or bytes. Omitted fields and the original `AIX.From(data)`
|
|
71
|
+
call remain unlimited for compatibility; set all three limits for untrusted
|
|
72
|
+
packages. The input archive buffer, parsed objects, and retained copies need
|
|
73
|
+
separate budgets. This policy applies to readers, not `AIX.optimize`.
|
|
74
|
+
|
|
75
|
+
Direct WASM consumers can call `AixReaderWasm.with_limits(data, limits)` using
|
|
76
|
+
the same fields. The existing `new AixReaderWasm(data)` constructor is unchanged.
|
|
77
|
+
|
|
78
|
+
## Open and Check
|
|
79
|
+
|
|
80
|
+
Pass `true` as the third `AIX.From` argument to run the source checker before
|
|
81
|
+
receiving the package. The second argument remains the optional read limits;
|
|
82
|
+
pass `undefined` there when no limits are needed.
|
|
83
|
+
|
|
84
|
+
```typescript
|
|
85
|
+
import { AIX, AixCheckError } from '@yodaos-pkg/aix';
|
|
86
|
+
|
|
87
|
+
async function openCheckedPackage(file: File) {
|
|
88
|
+
try {
|
|
89
|
+
return await AIX.From(file, undefined, true);
|
|
90
|
+
} catch (error) {
|
|
91
|
+
if (error instanceof AixCheckError) console.table(error.diagnostics);
|
|
92
|
+
throw error;
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Warnings alone pass. Error diagnostics reject with the exported `AixCheckError`
|
|
98
|
+
(`name: 'AixCheckError'`), an `Error` subclass with the complete `CheckReport` in
|
|
99
|
+
`report` and the same diagnostic array in `diagnostics`, including warnings.
|
|
100
|
+
The check uses `checkFromSource` on the package's source files without running
|
|
101
|
+
project code. It adds work and retains extracted check inputs; read limits still
|
|
102
|
+
apply but do not bound total checker memory. Archive, extraction, loading, and
|
|
103
|
+
collection failures retain their original operation errors rather than a check
|
|
104
|
+
report. Omitting the third argument or passing `false` preserves the existing
|
|
105
|
+
reader-only behavior.
|
|
106
|
+
|
|
107
|
+
## Check Source Files
|
|
108
|
+
|
|
109
|
+
The Web SDK and npm CLI use the same complete in-memory check engine:
|
|
110
|
+
|
|
111
|
+
```typescript
|
|
112
|
+
import { AIX, type CheckReport } from '@yodaos-pkg/aix';
|
|
113
|
+
|
|
114
|
+
const encode = (source: string) => new TextEncoder().encode(source);
|
|
115
|
+
const report: CheckReport = await AIX.checkFromSource([
|
|
116
|
+
{ path: 'app.json', data: encode('{"pages":[]}') },
|
|
117
|
+
{ path: 'main.ts', data: encode('const count: number = ;') },
|
|
118
|
+
], { onProgress: (event) => console.log(event.type) });
|
|
119
|
+
console.log(report.diagnostics); // AIX029: invalid TypeScript syntax at main.ts:1
|
|
120
|
+
|
|
121
|
+
// Files from an <input type="file" webkitdirectory> selection also work.
|
|
122
|
+
const fileReport = await AIX.checkFromFiles(Array.from(input.files ?? []));
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Checks cover JSON/config validity, Page/Widget structure, component references
|
|
126
|
+
and cycles, JS/TS syntax, statically recognizable permissions, and Page JSON Schemas. Each diagnostic has `code`, `severity`, `path`,
|
|
127
|
+
`line`, `column`, and `message`. Source errors are returned in the report;
|
|
128
|
+
invalid input paths or collection failures reject the promise.
|
|
129
|
+
|
|
130
|
+
`checkFromSource` takes paths relative to the application root. `checkFromFiles`
|
|
131
|
+
uses `webkitRelativePath`, removing the selected directory's outer folder.
|
|
132
|
+
Both apply nested `.aixignore` rules and exclude local `.aix` caches. The shared
|
|
133
|
+
check adapter loads only when checking is first requested. It uses the WASM
|
|
134
|
+
engine without a Node filesystem, Node polyfills, or dependency downloads.
|
|
135
|
+
The same API also works in a Web Worker.
|
|
136
|
+
|
|
137
|
+
Both methods accept `CheckOptions` with an optional `onProgress` callback.
|
|
138
|
+
`CheckProgressEvent` reports checker loading, source/schema validation (input
|
|
139
|
+
file count), and diagnostic collection. These are stage notifications, not a
|
|
140
|
+
percentage estimate. Browser checks are synchronous after loading; run the API
|
|
141
|
+
in a Web Worker to keep a browser progress display responsive.
|
|
142
|
+
|
|
143
|
+
`check_finished` events carry an exported `CheckResult` with `id`, `label`,
|
|
144
|
+
`status` (`passed`, `warning`, `failed`, or `skipped`), `errors`, `warnings`, and
|
|
145
|
+
an optional `detail` explaining incomplete/skipped checks. The CLI uses the same
|
|
146
|
+
results for its final checklist. The returned `CheckReport` remains a diagnostic
|
|
147
|
+
report, so JSON callers do not need to parse terminal output.
|
|
148
|
+
|
|
149
|
+
JavaScript and TypeScript are syntax-checked, including `.ts`, `.mts`, `.cts`,
|
|
150
|
+
and Ink `<script lang="ts">` blocks. Inline diagnostics retain their original
|
|
151
|
+
Ink file locations. TypeScript semantic, import-resolution, and compiler-option
|
|
152
|
+
checks are currently excluded. No type environment is loaded, and checks do not
|
|
153
|
+
emit or run code.
|
|
154
|
+
|
|
155
|
+
Page `schema.data` is validated against `$schema` (2020-12 by default), including
|
|
156
|
+
nested keywords, patterns, and local references. Missing/null schemas remain
|
|
157
|
+
accepted. External schema resources are not fetched. These checks validate
|
|
158
|
+
schema declarations, not runtime data; packing and reader semantics are unchanged.
|
|
159
|
+
|
|
160
|
+
## Using Play
|
|
34
161
|
|
|
35
162
|
The official browser lab now lives in the docs site at `/play`.
|
|
36
163
|
|
|
@@ -79,7 +206,7 @@ This is useful for verifying whether `app.json`, page schemas, and `getTools()`
|
|
|
79
206
|
### Pack and Optimize
|
|
80
207
|
|
|
81
208
|
The Web package includes the same in-memory packer and pure Rust resource
|
|
82
|
-
optimizer
|
|
209
|
+
optimizer used by the npm CLI:
|
|
83
210
|
|
|
84
211
|
```ts
|
|
85
212
|
const packed = await AIX.pack(
|
|
@@ -121,8 +248,10 @@ files and wants to invoke the low-level packer directly.
|
|
|
121
248
|
|
|
122
249
|
The main class to interact with an AIX package.
|
|
123
250
|
|
|
124
|
-
#### `static async From(data: Uint8Array | File): Promise<AIX>`
|
|
251
|
+
#### `static async From(data: Uint8Array | File, limits?: AixReadLimits, check?: boolean): Promise<AIX>`
|
|
125
252
|
Initializes the WASM module and creates an AIX instance from the given `.aix` file content. It supports both `Uint8Array` and the standard Web `File` object.
|
|
253
|
+
`check` defaults to `false`. Set it to `true` to check before returning and reject
|
|
254
|
+
with `AixCheckError` when errors are reported; see [Open and Check](#open-and-check).
|
|
126
255
|
```typescript
|
|
127
256
|
// From Uint8Array
|
|
128
257
|
const aix = await AIX.From(new Uint8Array(buffer));
|
|
@@ -157,6 +286,17 @@ Extracts the navigation bar title from the `app.json`.
|
|
|
157
286
|
const title = aix.getTitle();
|
|
158
287
|
```
|
|
159
288
|
|
|
289
|
+
#### `getPermissions(): string[]`
|
|
290
|
+
Returns the permission names declared in `app.json.permissions`, preserving their
|
|
291
|
+
order, duplicates, and custom names. An omitted or empty list returns `[]`.
|
|
292
|
+
Throws if `app.json` is missing, unreadable, invalid, or `permissions` is not an
|
|
293
|
+
array of strings. This reads declarations without querying authorization or
|
|
294
|
+
prompting for access.
|
|
295
|
+
```typescript
|
|
296
|
+
const permissions = aix.getPermissions();
|
|
297
|
+
// e.g. ['GEOLOCATION', 'CAMERA']
|
|
298
|
+
```
|
|
299
|
+
|
|
160
300
|
#### `getPages(): PageInfo[]`
|
|
161
301
|
Returns information about all pages defined in the package, including their paths, titles, and data schemas.
|
|
162
302
|
```typescript
|
|
@@ -165,18 +305,52 @@ const pages = aix.getPages();
|
|
|
165
305
|
[{
|
|
166
306
|
name: "pages/index/index",
|
|
167
307
|
title: "Home",
|
|
168
|
-
|
|
308
|
+
description: null,
|
|
309
|
+
data_schema: { ... },
|
|
310
|
+
size: { width: 480, height: 168 }
|
|
169
311
|
}]
|
|
170
312
|
*/
|
|
171
313
|
```
|
|
172
314
|
|
|
173
|
-
#### `getWidgets(): WidgetInfo[]`
|
|
174
|
-
Returns widget declarations after verifying that every path resolves to an `.ink` entry in the package. Throws when a declared entry is missing.
|
|
315
|
+
#### `getWidgets(locale?): WidgetInfo[]`
|
|
316
|
+
Returns widget declarations after verifying that every path resolves to an `.ink` entry in the package. When `locale` is provided, merges `displayName` and `description` from the matching `app.<locale>.json` overlay. Throws when a declared entry is missing or the selected locale file is invalid.
|
|
317
|
+
```typescript
|
|
318
|
+
const widgets = aix.getWidgets('en-US');
|
|
319
|
+
// [{ path: "widgets/clock/index", family: "1x1", placement: "persistent", displayName: "Clock", description: "Shows the current time." }]
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
#### `resolveMetadata(): MetadataResolution`
|
|
323
|
+
|
|
324
|
+
Returns `{ pages, tools, diagnostics }` synchronously. Missing/unreadable resources,
|
|
325
|
+
UTF-8 errors, and malformed page metadata produce `{ path, message }` diagnostics,
|
|
326
|
+
one per failed page. Failed pages are excluded from both result lists; other
|
|
327
|
+
pages retain declaration order. A valid empty page list has no diagnostics;
|
|
328
|
+
invalid/unreadable `app.json.pages` produces an `app.json` diagnostic.
|
|
329
|
+
|
|
175
330
|
```typescript
|
|
176
|
-
const
|
|
177
|
-
|
|
331
|
+
const result = aix.resolveMetadata();
|
|
332
|
+
console.log(result.diagnostics);
|
|
333
|
+
const tools = result.tools; // only successfully resolved pages
|
|
334
|
+
// For all-or-nothing acceptance, require result.diagnostics.length === 0.
|
|
178
335
|
```
|
|
179
336
|
|
|
337
|
+
This API requires readable `.ink`, or both `.json` and `.wxml` for traditional
|
|
338
|
+
pages, and checks ZIP integrity and UTF-8 for resources it reads. It deserializes
|
|
339
|
+
page JSON and complete Ink `<script def>` blocks. Optional definitions, schemas,
|
|
340
|
+
and styles may be absent; present styles must be readable (`.wcss` before `.wxss`).
|
|
341
|
+
A broken Ink entry never falls back to traditional files. Use source checking
|
|
342
|
+
for full syntax, component, and JSON Schema validation. Runtime execution and
|
|
343
|
+
packing validation are unchanged.
|
|
344
|
+
|
|
345
|
+
`getPages()`/`getTools()` remain tolerant and can return default metadata/tools
|
|
346
|
+
even for missing resources. Page, Widget, and title fields are parsed separately;
|
|
347
|
+
invalid Widget fields no longer hide valid pages. `getWidgets()` still reports
|
|
348
|
+
Widget errors. Direct WASM consumers use `reader.resolve_metadata()`.
|
|
349
|
+
|
|
350
|
+
Exported `MetadataResolution` has `pages: PageInfo[]`, `tools: Tool[]`, and
|
|
351
|
+
`diagnostics: MetadataDiagnostic[]`; `MetadataDiagnostic` has `path` and `message`
|
|
352
|
+
string fields.
|
|
353
|
+
|
|
180
354
|
#### `getTools(): Tool[]`
|
|
181
355
|
Generates a list of OpenAI-compatible tool definitions based on the pages and their schemas.
|
|
182
356
|
```typescript
|
|
@@ -184,6 +358,8 @@ const tools = aix.getTools();
|
|
|
184
358
|
/*
|
|
185
359
|
[{
|
|
186
360
|
type: "function",
|
|
361
|
+
target: "_blank",
|
|
362
|
+
layout: { width: 480, height: 168 },
|
|
187
363
|
function: {
|
|
188
364
|
name: "pages_index_index",
|
|
189
365
|
description: "Home",
|
|
@@ -204,12 +380,28 @@ interface AixEntry {
|
|
|
204
380
|
}
|
|
205
381
|
```
|
|
206
382
|
|
|
383
|
+
### JSON and layout types
|
|
384
|
+
```typescript
|
|
385
|
+
type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
|
|
386
|
+
interface JsonObject { [key: string]: JsonValue }
|
|
387
|
+
type JsonSchema = JsonValue;
|
|
388
|
+
interface PageConstraint { width: number; height: number }
|
|
389
|
+
type ToolTarget = '_current' | '_blank';
|
|
390
|
+
type WidgetPlacement = 'persistent' | 'overlay';
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
`JsonSchema` retains arbitrary JSON, including boolean schemas and unvalidated
|
|
394
|
+
legacy values. Use `AIX.checkFromSource()` for schema validation. Page `size`
|
|
395
|
+
and tool `layout` both contain numeric width/height constraints.
|
|
396
|
+
|
|
207
397
|
### `PageInfo`
|
|
208
398
|
```typescript
|
|
209
399
|
interface PageInfo {
|
|
210
400
|
name: string;
|
|
211
|
-
title
|
|
212
|
-
|
|
401
|
+
title: string | null;
|
|
402
|
+
description: string | null;
|
|
403
|
+
data_schema: JsonSchema;
|
|
404
|
+
size: PageConstraint;
|
|
213
405
|
}
|
|
214
406
|
```
|
|
215
407
|
|
|
@@ -218,6 +410,9 @@ interface PageInfo {
|
|
|
218
410
|
interface WidgetInfo {
|
|
219
411
|
path: string;
|
|
220
412
|
family: string;
|
|
413
|
+
placement: WidgetPlacement;
|
|
414
|
+
displayName: string | null;
|
|
415
|
+
description: string | null;
|
|
221
416
|
}
|
|
222
417
|
```
|
|
223
418
|
|
|
@@ -226,14 +421,25 @@ OpenAI compatible tool format.
|
|
|
226
421
|
```typescript
|
|
227
422
|
interface Tool {
|
|
228
423
|
type: string;
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
424
|
+
target: ToolTarget;
|
|
425
|
+
layout: PageConstraint;
|
|
426
|
+
function: FunctionDefinition;
|
|
427
|
+
}
|
|
428
|
+
interface FunctionDefinition {
|
|
429
|
+
name: string;
|
|
430
|
+
description: string | null;
|
|
431
|
+
parameters: JsonSchema;
|
|
234
432
|
}
|
|
235
433
|
```
|
|
236
434
|
|
|
435
|
+
Metadata fields above are always present. Missing strings and nested JSON null
|
|
436
|
+
values now remain `null` through raw WASM, SDK getters, and `resolveMetadata()`,
|
|
437
|
+
matching native Rust JSON. Earlier WASM builds returned `undefined` for these
|
|
438
|
+
values; update explicit `=== undefined` checks to `=== null` when migrating
|
|
439
|
+
metadata consumers. Standalone `getTitle()` and `getVersion()` retain their
|
|
440
|
+
`string | undefined` return type. Tools currently emit `type: "function"` and
|
|
441
|
+
underscore-prefixed targets; `current`/`blank` are input aliases only.
|
|
442
|
+
|
|
237
443
|
## Build
|
|
238
444
|
|
|
239
445
|
To build the library for distribution:
|
package/pkg/aix_web.d.ts
CHANGED
|
@@ -13,15 +13,28 @@ export class AixPackResultWasm {
|
|
|
13
13
|
export class AixReaderWasm {
|
|
14
14
|
free(): void;
|
|
15
15
|
[Symbol.dispose](): void;
|
|
16
|
+
get_agent_id(): string | undefined;
|
|
16
17
|
get_pages(): any;
|
|
18
|
+
get_permissions(): any;
|
|
17
19
|
get_title(): string | undefined;
|
|
18
20
|
get_tools(): any;
|
|
19
21
|
get_version(): string | undefined;
|
|
20
|
-
get_widgets(): any;
|
|
22
|
+
get_widgets(locale?: string | null): any;
|
|
21
23
|
list(): any;
|
|
24
|
+
/**
|
|
25
|
+
* Compatibility constructor without caller resource budgets.
|
|
26
|
+
*/
|
|
22
27
|
constructor(data: Uint8Array);
|
|
23
28
|
read_file(name: string): Uint8Array;
|
|
29
|
+
/**
|
|
30
|
+
* Resolve readable pages/tools and expose per-resource failures as diagnostics.
|
|
31
|
+
*/
|
|
32
|
+
resolve_metadata(): any;
|
|
24
33
|
supports_engine(current_version: string): boolean;
|
|
34
|
+
/**
|
|
35
|
+
* Create a reader with inclusive caller budgets. Omitted fields are unlimited.
|
|
36
|
+
*/
|
|
37
|
+
static with_limits(data: Uint8Array, limits: any): AixReaderWasm;
|
|
25
38
|
}
|
|
26
39
|
|
|
27
40
|
export class AixSourcePackBuilderWasm {
|
|
@@ -29,43 +42,65 @@ export class AixSourcePackBuilderWasm {
|
|
|
29
42
|
[Symbol.dispose](): void;
|
|
30
43
|
add_file(path: string, data: Uint8Array): void;
|
|
31
44
|
constructor();
|
|
32
|
-
pack_from_source_with_progress(build_id: string, engine: string | null | undefined, optimize_options: any, progress: Function): AixPackResultWasm;
|
|
45
|
+
pack_from_source_with_progress(build_id: string, engine: string | null | undefined, optimize_options: any, progress: Function, agent_id?: string | null): AixPackResultWasm;
|
|
33
46
|
}
|
|
34
47
|
|
|
48
|
+
/**
|
|
49
|
+
* Check source files using the same collection rules as the pack command.
|
|
50
|
+
*/
|
|
51
|
+
export function check_aix_from_source(files: any): any;
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* Collect a pre-optimization source snapshot using the packer's shared rules.
|
|
55
|
+
*/
|
|
56
|
+
export function collect_aix_source(files: any): any;
|
|
57
|
+
|
|
35
58
|
export function optimize_aix(data: Uint8Array, options: any): AixPackResultWasm;
|
|
36
59
|
|
|
37
|
-
export function pack_aix(files: any, build_id: string, engine: string | null | undefined, optimize_options: any): AixPackResultWasm;
|
|
60
|
+
export function pack_aix(files: any, build_id: string, engine: string | null | undefined, optimize_options: any, agent_id?: string | null): AixPackResultWasm;
|
|
61
|
+
|
|
62
|
+
export function pack_aix_from_source(files: any, build_id: string, engine: string | null | undefined, optimize_options: any, agent_id?: string | null): AixPackResultWasm;
|
|
38
63
|
|
|
39
|
-
export function
|
|
64
|
+
export function pack_aix_from_source_with_progress(files: any, build_id: string, engine: string | null | undefined, optimize_options: any, progress: Function, agent_id?: string | null): AixPackResultWasm;
|
|
40
65
|
|
|
41
|
-
|
|
66
|
+
/**
|
|
67
|
+
* Check source files and return diagnostics with executed check coverage.
|
|
68
|
+
*/
|
|
69
|
+
export function prepare_aix_check(files: any): any;
|
|
42
70
|
|
|
43
71
|
export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
|
|
44
72
|
|
|
45
73
|
export interface InitOutput {
|
|
46
74
|
readonly memory: WebAssembly.Memory;
|
|
47
75
|
readonly __wbg_aixpackresultwasm_free: (a: number, b: number) => void;
|
|
48
|
-
readonly __wbg_aixreaderwasm_free: (a: number, b: number) => void;
|
|
49
76
|
readonly __wbg_aixsourcepackbuilderwasm_free: (a: number, b: number) => void;
|
|
50
77
|
readonly aixpackresultwasm_data: (a: number) => any;
|
|
51
78
|
readonly aixpackresultwasm_report: (a: number) => [number, number, number];
|
|
52
79
|
readonly aixpackresultwasm_warnings: (a: number) => [number, number, number];
|
|
80
|
+
readonly aixsourcepackbuilderwasm_add_file: (a: number, b: number, c: number, d: number, e: number) => void;
|
|
81
|
+
readonly aixsourcepackbuilderwasm_new: () => number;
|
|
82
|
+
readonly aixsourcepackbuilderwasm_pack_from_source_with_progress: (a: number, b: number, c: number, d: number, e: number, f: any, g: any, h: number, i: number) => [number, number, number];
|
|
83
|
+
readonly check_aix_from_source: (a: any) => [number, number, number];
|
|
84
|
+
readonly collect_aix_source: (a: any) => [number, number, number];
|
|
85
|
+
readonly optimize_aix: (a: number, b: number, c: any) => [number, number, number];
|
|
86
|
+
readonly pack_aix: (a: any, b: number, c: number, d: number, e: number, f: any, g: number, h: number) => [number, number, number];
|
|
87
|
+
readonly pack_aix_from_source: (a: any, b: number, c: number, d: number, e: number, f: any, g: number, h: number) => [number, number, number];
|
|
88
|
+
readonly pack_aix_from_source_with_progress: (a: any, b: number, c: number, d: number, e: number, f: any, g: any, h: number, i: number) => [number, number, number];
|
|
89
|
+
readonly prepare_aix_check: (a: any) => [number, number, number];
|
|
90
|
+
readonly __wbg_aixreaderwasm_free: (a: number, b: number) => void;
|
|
91
|
+
readonly aixreaderwasm_get_agent_id: (a: number) => [number, number, number, number];
|
|
53
92
|
readonly aixreaderwasm_get_pages: (a: number) => [number, number, number];
|
|
93
|
+
readonly aixreaderwasm_get_permissions: (a: number) => [number, number, number];
|
|
54
94
|
readonly aixreaderwasm_get_title: (a: number) => [number, number];
|
|
55
95
|
readonly aixreaderwasm_get_tools: (a: number) => [number, number, number];
|
|
56
96
|
readonly aixreaderwasm_get_version: (a: number) => [number, number];
|
|
57
|
-
readonly aixreaderwasm_get_widgets: (a: number) => [number, number, number];
|
|
97
|
+
readonly aixreaderwasm_get_widgets: (a: number, b: number, c: number) => [number, number, number];
|
|
58
98
|
readonly aixreaderwasm_list: (a: number) => [number, number, number];
|
|
59
99
|
readonly aixreaderwasm_new: (a: number, b: number) => [number, number, number];
|
|
60
100
|
readonly aixreaderwasm_read_file: (a: number, b: number, c: number) => [number, number, number, number];
|
|
101
|
+
readonly aixreaderwasm_resolve_metadata: (a: number) => [number, number, number];
|
|
61
102
|
readonly aixreaderwasm_supports_engine: (a: number, b: number, c: number) => [number, number, number];
|
|
62
|
-
readonly
|
|
63
|
-
readonly aixsourcepackbuilderwasm_new: () => number;
|
|
64
|
-
readonly aixsourcepackbuilderwasm_pack_from_source_with_progress: (a: number, b: number, c: number, d: number, e: number, f: any, g: any) => [number, number, number];
|
|
65
|
-
readonly optimize_aix: (a: number, b: number, c: any) => [number, number, number];
|
|
66
|
-
readonly pack_aix: (a: any, b: number, c: number, d: number, e: number, f: any) => [number, number, number];
|
|
67
|
-
readonly pack_aix_from_source: (a: any, b: number, c: number, d: number, e: number, f: any) => [number, number, number];
|
|
68
|
-
readonly pack_aix_from_source_with_progress: (a: any, b: number, c: number, d: number, e: number, f: any, g: any) => [number, number, number];
|
|
103
|
+
readonly aixreaderwasm_with_limits: (a: number, b: number, c: any) => [number, number, number];
|
|
69
104
|
readonly __wbindgen_malloc: (a: number, b: number) => number;
|
|
70
105
|
readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
|
|
71
106
|
readonly __wbindgen_exn_store: (a: number) => void;
|