@yodaos-pkg/aix 0.9.0 → 0.11.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 +188 -10
- 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 +80 -8
- package/index.js +78 -16
- package/jsr.json +1 -1
- package/package.json +1 -2
- package/pkg/README.md +188 -10
- package/pkg/aix_web.d.ts +47 -12
- package/pkg/aix_web.js +142 -9
- package/pkg/aix_web_bg.wasm +0 -0
- package/pkg/aix_web_bg.wasm.d.ts +15 -8
- package/pkg/package.json +1 -1
- package/pkg-reader/README.md +412 -0
- package/pkg-reader/aix_web.d.ts +75 -0
- package/pkg-reader/aix_web.js +644 -0
- package/pkg-reader/aix_web_bg.wasm +0 -0
- package/pkg-reader/aix_web_bg.wasm.d.ts +22 -0
- package/pkg-reader/package.json +15 -0
package/README.md
CHANGED
|
@@ -30,7 +30,104 @@ async function fromFile(file: File) {
|
|
|
30
30
|
}
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
-
##
|
|
33
|
+
## WASM Loading
|
|
34
|
+
|
|
35
|
+
`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 first pack, optimize, or source-check call lazily loads the full module;
|
|
38
|
+
concurrent tooling calls share initialization. Existing reader instances remain
|
|
39
|
+
valid after tooling loads, and tooling-only calls do not fetch reader WASM.
|
|
40
|
+
|
|
41
|
+
The generated distribution includes `pkg-reader/` and `pkg/`; self-host both
|
|
42
|
+
with their adjacent JS/WASM files. The existing raw `pkg/aix_web.js` exports
|
|
43
|
+
remain complete and the npm CLI keeps its synchronous full Node.js bundle.
|
|
44
|
+
Rust builds default to the `tooling` feature; `--no-default-features` produces
|
|
45
|
+
reader exports without the packer dependency. `npm run build` builds both web
|
|
46
|
+
artifacts; `npm run build:wasm:reader` builds only the reader artifact.
|
|
47
|
+
|
|
48
|
+
Local measurements reduced reader WASM from 5,514,021 to 355,365 bytes. Mixed
|
|
49
|
+
reader/tooling workflows load both binaries and retain two module memories.
|
|
50
|
+
See the repository's `docs/wasm.md` for baseline samples, timing limits, the
|
|
51
|
+
compatibility plan, and reproduction commands.
|
|
52
|
+
|
|
53
|
+
## Archive Resource Limits
|
|
54
|
+
|
|
55
|
+
Pass caller-selected budgets when reading untrusted packages:
|
|
56
|
+
|
|
57
|
+
```typescript
|
|
58
|
+
const aix = await AIX.From(file, {
|
|
59
|
+
maxEntries: 1024,
|
|
60
|
+
maxEntryBytes: 8 * 1024 * 1024,
|
|
61
|
+
maxTotalBytes: 32 * 1024 * 1024,
|
|
62
|
+
});
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
All limits are inclusive non-negative safe integers. Directories and signature
|
|
66
|
+
metadata count too. Metadata is rejected before extraction if over budget;
|
|
67
|
+
extraction also bounds output and retains CRC and size checks. `maxTotalBytes`
|
|
68
|
+
is the sum of declared uncompressed sizes, not a cumulative read budget.
|
|
69
|
+
Zero allows no entries or bytes. Omitted fields and the original `AIX.From(data)`
|
|
70
|
+
call remain unlimited for compatibility; set all three limits for untrusted
|
|
71
|
+
packages. The input archive buffer, parsed objects, and retained copies need
|
|
72
|
+
separate budgets. This policy applies to readers, not `AIX.optimize`.
|
|
73
|
+
|
|
74
|
+
Direct WASM consumers can call `AixReaderWasm.with_limits(data, limits)` using
|
|
75
|
+
the same fields. The existing `new AixReaderWasm(data)` constructor is unchanged.
|
|
76
|
+
|
|
77
|
+
## Check Source Files
|
|
78
|
+
|
|
79
|
+
The Web SDK and npm CLI use the same complete in-memory check engine:
|
|
80
|
+
|
|
81
|
+
```typescript
|
|
82
|
+
import { AIX, type CheckReport } from '@yodaos-pkg/aix';
|
|
83
|
+
|
|
84
|
+
const encode = (source: string) => new TextEncoder().encode(source);
|
|
85
|
+
const report: CheckReport = await AIX.checkFromSource([
|
|
86
|
+
{ path: 'app.json', data: encode('{"pages":[]}') },
|
|
87
|
+
{ path: 'main.ts', data: encode('const count: number = ;') },
|
|
88
|
+
], { onProgress: (event) => console.log(event.type) });
|
|
89
|
+
console.log(report.diagnostics); // AIX029: invalid TypeScript syntax at main.ts:1
|
|
90
|
+
|
|
91
|
+
// Files from an <input type="file" webkitdirectory> selection also work.
|
|
92
|
+
const fileReport = await AIX.checkFromFiles(Array.from(input.files ?? []));
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Checks cover JSON/config validity, Page/Widget structure, component references
|
|
96
|
+
and cycles, JS/TS syntax, statically recognizable permissions, and Page JSON Schemas. Each diagnostic has `code`, `severity`, `path`,
|
|
97
|
+
`line`, `column`, and `message`. Source errors are returned in the report;
|
|
98
|
+
invalid input paths or collection failures reject the promise.
|
|
99
|
+
|
|
100
|
+
`checkFromSource` takes paths relative to the application root. `checkFromFiles`
|
|
101
|
+
uses `webkitRelativePath`, removing the selected directory's outer folder.
|
|
102
|
+
Both apply nested `.aixignore` rules and exclude local `.aix` caches. The shared
|
|
103
|
+
check adapter loads only when checking is first requested. It uses the WASM
|
|
104
|
+
engine without a Node filesystem, Node polyfills, or dependency downloads.
|
|
105
|
+
The same API also works in a Web Worker.
|
|
106
|
+
|
|
107
|
+
Both methods accept `CheckOptions` with an optional `onProgress` callback.
|
|
108
|
+
`CheckProgressEvent` reports checker loading, source/schema validation (input
|
|
109
|
+
file count), and diagnostic collection. These are stage notifications, not a
|
|
110
|
+
percentage estimate. Browser checks are synchronous after loading; run the API
|
|
111
|
+
in a Web Worker to keep a browser progress display responsive.
|
|
112
|
+
|
|
113
|
+
`check_finished` events carry an exported `CheckResult` with `id`, `label`,
|
|
114
|
+
`status` (`passed`, `warning`, `failed`, or `skipped`), `errors`, `warnings`, and
|
|
115
|
+
an optional `detail` explaining incomplete/skipped checks. The CLI uses the same
|
|
116
|
+
results for its final checklist. The returned `CheckReport` remains a diagnostic
|
|
117
|
+
report, so JSON callers do not need to parse terminal output.
|
|
118
|
+
|
|
119
|
+
JavaScript and TypeScript are syntax-checked, including `.ts`, `.mts`, `.cts`,
|
|
120
|
+
and Ink `<script lang="ts">` blocks. Inline diagnostics retain their original
|
|
121
|
+
Ink file locations. TypeScript semantic, import-resolution, and compiler-option
|
|
122
|
+
checks are currently excluded. No type environment is loaded, and checks do not
|
|
123
|
+
emit or run code.
|
|
124
|
+
|
|
125
|
+
Page `schema.data` is validated against `$schema` (2020-12 by default), including
|
|
126
|
+
nested keywords, patterns, and local references. Missing/null schemas remain
|
|
127
|
+
accepted. External schema resources are not fetched. These checks validate
|
|
128
|
+
schema declarations, not runtime data; packing and reader semantics are unchanged.
|
|
129
|
+
|
|
130
|
+
## Using Play
|
|
34
131
|
|
|
35
132
|
The official browser lab now lives in the docs site at `/play`.
|
|
36
133
|
|
|
@@ -79,7 +176,7 @@ This is useful for verifying whether `app.json`, page schemas, and `getTools()`
|
|
|
79
176
|
### Pack and Optimize
|
|
80
177
|
|
|
81
178
|
The Web package includes the same in-memory packer and pure Rust resource
|
|
82
|
-
optimizer
|
|
179
|
+
optimizer used by the npm CLI:
|
|
83
180
|
|
|
84
181
|
```ts
|
|
85
182
|
const packed = await AIX.pack(
|
|
@@ -165,11 +262,52 @@ const pages = aix.getPages();
|
|
|
165
262
|
[{
|
|
166
263
|
name: "pages/index/index",
|
|
167
264
|
title: "Home",
|
|
168
|
-
|
|
265
|
+
description: null,
|
|
266
|
+
data_schema: { ... },
|
|
267
|
+
size: { width: 480, height: 168 }
|
|
169
268
|
}]
|
|
170
269
|
*/
|
|
171
270
|
```
|
|
172
271
|
|
|
272
|
+
#### `getWidgets(locale?): WidgetInfo[]`
|
|
273
|
+
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.
|
|
274
|
+
```typescript
|
|
275
|
+
const widgets = aix.getWidgets('en-US');
|
|
276
|
+
// [{ path: "widgets/clock/index", family: "1x1", placement: "persistent", displayName: "Clock", description: "Shows the current time." }]
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
#### `resolveMetadata(): MetadataResolution`
|
|
280
|
+
|
|
281
|
+
Returns `{ pages, tools, diagnostics }` synchronously. Missing/unreadable resources,
|
|
282
|
+
UTF-8 errors, and malformed page metadata produce `{ path, message }` diagnostics,
|
|
283
|
+
one per failed page. Failed pages are excluded from both result lists; other
|
|
284
|
+
pages retain declaration order. A valid empty page list has no diagnostics;
|
|
285
|
+
invalid/unreadable `app.json.pages` produces an `app.json` diagnostic.
|
|
286
|
+
|
|
287
|
+
```typescript
|
|
288
|
+
const result = aix.resolveMetadata();
|
|
289
|
+
console.log(result.diagnostics);
|
|
290
|
+
const tools = result.tools; // only successfully resolved pages
|
|
291
|
+
// For all-or-nothing acceptance, require result.diagnostics.length === 0.
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
This API requires readable `.ink`, or both `.json` and `.wxml` for traditional
|
|
295
|
+
pages, and checks ZIP integrity and UTF-8 for resources it reads. It deserializes
|
|
296
|
+
page JSON and complete Ink `<script def>` blocks. Optional definitions, schemas,
|
|
297
|
+
and styles may be absent; present styles must be readable (`.wcss` before `.wxss`).
|
|
298
|
+
A broken Ink entry never falls back to traditional files. Use source checking
|
|
299
|
+
for full syntax, component, and JSON Schema validation. Runtime execution and
|
|
300
|
+
packing validation are unchanged.
|
|
301
|
+
|
|
302
|
+
`getPages()`/`getTools()` remain tolerant and can return default metadata/tools
|
|
303
|
+
even for missing resources. Page, Widget, and title fields are parsed separately;
|
|
304
|
+
invalid Widget fields no longer hide valid pages. `getWidgets()` still reports
|
|
305
|
+
Widget errors. Direct WASM consumers use `reader.resolve_metadata()`.
|
|
306
|
+
|
|
307
|
+
Exported `MetadataResolution` has `pages: PageInfo[]`, `tools: Tool[]`, and
|
|
308
|
+
`diagnostics: MetadataDiagnostic[]`; `MetadataDiagnostic` has `path` and `message`
|
|
309
|
+
string fields.
|
|
310
|
+
|
|
173
311
|
#### `getTools(): Tool[]`
|
|
174
312
|
Generates a list of OpenAI-compatible tool definitions based on the pages and their schemas.
|
|
175
313
|
```typescript
|
|
@@ -177,6 +315,8 @@ const tools = aix.getTools();
|
|
|
177
315
|
/*
|
|
178
316
|
[{
|
|
179
317
|
type: "function",
|
|
318
|
+
target: "_blank",
|
|
319
|
+
layout: { width: 480, height: 168 },
|
|
180
320
|
function: {
|
|
181
321
|
name: "pages_index_index",
|
|
182
322
|
description: "Home",
|
|
@@ -197,12 +337,39 @@ interface AixEntry {
|
|
|
197
337
|
}
|
|
198
338
|
```
|
|
199
339
|
|
|
340
|
+
### JSON and layout types
|
|
341
|
+
```typescript
|
|
342
|
+
type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
|
|
343
|
+
interface JsonObject { [key: string]: JsonValue }
|
|
344
|
+
type JsonSchema = JsonValue;
|
|
345
|
+
interface PageConstraint { width: number; height: number }
|
|
346
|
+
type ToolTarget = '_current' | '_blank';
|
|
347
|
+
type WidgetPlacement = 'persistent' | 'overlay';
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
`JsonSchema` retains arbitrary JSON, including boolean schemas and unvalidated
|
|
351
|
+
legacy values. Use `AIX.checkFromSource()` for schema validation. Page `size`
|
|
352
|
+
and tool `layout` both contain numeric width/height constraints.
|
|
353
|
+
|
|
200
354
|
### `PageInfo`
|
|
201
355
|
```typescript
|
|
202
356
|
interface PageInfo {
|
|
203
357
|
name: string;
|
|
204
|
-
title
|
|
205
|
-
|
|
358
|
+
title: string | null;
|
|
359
|
+
description: string | null;
|
|
360
|
+
data_schema: JsonSchema;
|
|
361
|
+
size: PageConstraint;
|
|
362
|
+
}
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
### `WidgetInfo`
|
|
366
|
+
```typescript
|
|
367
|
+
interface WidgetInfo {
|
|
368
|
+
path: string;
|
|
369
|
+
family: string;
|
|
370
|
+
placement: WidgetPlacement;
|
|
371
|
+
displayName: string | null;
|
|
372
|
+
description: string | null;
|
|
206
373
|
}
|
|
207
374
|
```
|
|
208
375
|
|
|
@@ -211,14 +378,25 @@ OpenAI compatible tool format.
|
|
|
211
378
|
```typescript
|
|
212
379
|
interface Tool {
|
|
213
380
|
type: string;
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
381
|
+
target: ToolTarget;
|
|
382
|
+
layout: PageConstraint;
|
|
383
|
+
function: FunctionDefinition;
|
|
384
|
+
}
|
|
385
|
+
interface FunctionDefinition {
|
|
386
|
+
name: string;
|
|
387
|
+
description: string | null;
|
|
388
|
+
parameters: JsonSchema;
|
|
219
389
|
}
|
|
220
390
|
```
|
|
221
391
|
|
|
392
|
+
Metadata fields above are always present. Missing strings and nested JSON null
|
|
393
|
+
values now remain `null` through raw WASM, SDK getters, and `resolveMetadata()`,
|
|
394
|
+
matching native Rust JSON. Earlier WASM builds returned `undefined` for these
|
|
395
|
+
values; update explicit `=== undefined` checks to `=== null` when migrating
|
|
396
|
+
metadata consumers. Standalone `getTitle()` and `getVersion()` retain their
|
|
397
|
+
`string | undefined` return type. Tools currently emit `type: "function"` and
|
|
398
|
+
underscore-prefixed targets; `current`/`blank` are input aliases only.
|
|
399
|
+
|
|
222
400
|
## Build
|
|
223
401
|
|
|
224
402
|
To build the library for distribution:
|
package/check/index.d.ts
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { CheckEngine, CheckOptions, CheckReport } from './types.js';
|
|
2
|
+
export type { CheckDiagnostic, CheckOptions, CheckProgressEvent, CheckReport, CheckResult } from './types.js';
|
|
3
|
+
/** The complete check pipeline shared by the Web SDK and npm CLI. */
|
|
4
|
+
export declare function checkSource(files: {
|
|
5
|
+
path: string;
|
|
6
|
+
data: Uint8Array;
|
|
7
|
+
}[], engine: CheckEngine, options?: CheckOptions): CheckReport;
|
package/check/index.js
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
// ts/check/results.ts
|
|
2
|
+
function sourceResults(prepared) {
|
|
3
|
+
let { coverage, report } = prepared, groups = /* @__PURE__ */ new Map();
|
|
4
|
+
for (let diagnostic of report.diagnostics) {
|
|
5
|
+
let id = sourceCategory(diagnostic.code), group = groups.get(id);
|
|
6
|
+
group || groups.set(id, group = []), group.push(diagnostic);
|
|
7
|
+
}
|
|
8
|
+
let blocked = coverage.structure ? void 0 : "app.json could not be validated", inputErrors = groups.get("json")?.some((diagnostic) => diagnostic.severity === "error"), syntaxErrors = groups.get("syntax")?.some((diagnostic) => diagnostic.severity === "error");
|
|
9
|
+
return [
|
|
10
|
+
result(
|
|
11
|
+
"json",
|
|
12
|
+
`JSON syntax and text encoding (${count(coverage.text_files, "file")})`,
|
|
13
|
+
groups.get("json"),
|
|
14
|
+
coverage.text_files ? void 0 : "no text source files"
|
|
15
|
+
),
|
|
16
|
+
result(
|
|
17
|
+
"structure",
|
|
18
|
+
"App, Page, Widget, and component structure",
|
|
19
|
+
groups.get("structure"),
|
|
20
|
+
blocked ?? (inputErrors ? "some source files could not be parsed" : void 0)
|
|
21
|
+
),
|
|
22
|
+
result(
|
|
23
|
+
"syntax",
|
|
24
|
+
`JS/TS syntax (${count(coverage.scripts, "script")})`,
|
|
25
|
+
groups.get("syntax"),
|
|
26
|
+
blocked ?? (coverage.scripts ? void 0 : "no scripts to check")
|
|
27
|
+
),
|
|
28
|
+
result(
|
|
29
|
+
"permissions",
|
|
30
|
+
"Permission declarations and direct API use",
|
|
31
|
+
groups.get("permissions"),
|
|
32
|
+
blocked ?? (inputErrors || syntaxErrors ? "some source files could not be parsed" : void 0)
|
|
33
|
+
),
|
|
34
|
+
result(
|
|
35
|
+
"schemas",
|
|
36
|
+
`Page JSON Schemas (${count(coverage.schemas, "schema")})`,
|
|
37
|
+
groups.get("schemas"),
|
|
38
|
+
blocked ?? (coverage.schemas ? void 0 : "no Page schemas checked")
|
|
39
|
+
)
|
|
40
|
+
];
|
|
41
|
+
}
|
|
42
|
+
function result(id, label, diagnostics = [], detail) {
|
|
43
|
+
let errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error").length, warnings = diagnostics.length - errors;
|
|
44
|
+
return {
|
|
45
|
+
id,
|
|
46
|
+
label,
|
|
47
|
+
errors,
|
|
48
|
+
warnings,
|
|
49
|
+
status: errors ? "failed" : warnings ? "warning" : detail ? "skipped" : "passed",
|
|
50
|
+
...detail ? { detail } : {}
|
|
51
|
+
};
|
|
52
|
+
}
|
|
53
|
+
function sourceCategory(code) {
|
|
54
|
+
return ["AIX001", "AIX002", "AIX014"].includes(code) ? "json" : ["AIX006", "AIX007", "AIX027", "AIX028", "AIX033", "AIX037", "AIX038"].includes(code) ? "permissions" : code === "AIX029" ? "syntax" : ["AIX031", "AIX047"].includes(code) ? "schemas" : "structure";
|
|
55
|
+
}
|
|
56
|
+
function count(value, unit) {
|
|
57
|
+
return `${value} ${unit}${value === 1 ? "" : "s"}`;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
// ts/check/index.ts
|
|
61
|
+
function checkSource(files, engine, options = {}) {
|
|
62
|
+
options.onProgress?.({ type: "checking_sources", fileCount: files.length });
|
|
63
|
+
let prepared = engine.prepare_aix_check(files);
|
|
64
|
+
for (let check of sourceResults(prepared)) options.onProgress?.({ type: "check_finished", check });
|
|
65
|
+
return options.onProgress?.({ type: "collecting_diagnostics" }), prepared.report;
|
|
66
|
+
}
|
|
67
|
+
export {
|
|
68
|
+
checkSource
|
|
69
|
+
};
|
package/check/types.d.ts
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
export interface CheckDiagnostic {
|
|
2
|
+
code: string;
|
|
3
|
+
severity: 'error' | 'warning';
|
|
4
|
+
path: string;
|
|
5
|
+
line: number;
|
|
6
|
+
column: number;
|
|
7
|
+
message: string;
|
|
8
|
+
}
|
|
9
|
+
export interface CheckReport {
|
|
10
|
+
diagnostics: CheckDiagnostic[];
|
|
11
|
+
}
|
|
12
|
+
export interface CheckResult {
|
|
13
|
+
id: 'json' | 'structure' | 'syntax' | 'permissions' | 'schemas';
|
|
14
|
+
label: string;
|
|
15
|
+
status: 'passed' | 'warning' | 'failed' | 'skipped';
|
|
16
|
+
errors: number;
|
|
17
|
+
warnings: number;
|
|
18
|
+
detail?: string;
|
|
19
|
+
}
|
|
20
|
+
export type CheckProgressEvent = {
|
|
21
|
+
type: 'loading_checker';
|
|
22
|
+
} | {
|
|
23
|
+
type: 'checking_sources';
|
|
24
|
+
fileCount: number;
|
|
25
|
+
} | {
|
|
26
|
+
type: 'check_finished';
|
|
27
|
+
check: CheckResult;
|
|
28
|
+
} | {
|
|
29
|
+
type: 'collecting_diagnostics';
|
|
30
|
+
};
|
|
31
|
+
export interface CheckOptions {
|
|
32
|
+
onProgress?: (event: CheckProgressEvent) => void;
|
|
33
|
+
}
|
|
34
|
+
export interface PreparedCheck {
|
|
35
|
+
report: CheckReport;
|
|
36
|
+
coverage: {
|
|
37
|
+
text_files: number;
|
|
38
|
+
structure: boolean;
|
|
39
|
+
scripts: number;
|
|
40
|
+
schemas: number;
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
export interface CheckEngine {
|
|
44
|
+
prepare_aix_check(files: {
|
|
45
|
+
path: string;
|
|
46
|
+
data: Uint8Array;
|
|
47
|
+
}[]): PreparedCheck;
|
|
48
|
+
}
|
package/check/types.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
package/index.d.ts
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import type { CheckOptions, CheckReport } from './check/types.js';
|
|
2
|
+
export type { CheckDiagnostic, CheckOptions, CheckProgressEvent, CheckReport, CheckResult } from './check/types.js';
|
|
1
3
|
export interface AixInputFile {
|
|
2
4
|
path: string;
|
|
3
5
|
data: Uint8Array;
|
|
@@ -29,6 +31,8 @@ export interface PackResult {
|
|
|
29
31
|
}
|
|
30
32
|
export interface PackOptions {
|
|
31
33
|
buildId?: string;
|
|
34
|
+
/** Stable normalized project ID; reuse across builds. */
|
|
35
|
+
agentId?: string;
|
|
32
36
|
engine?: string;
|
|
33
37
|
optimize?: false | OptimizeOptions;
|
|
34
38
|
}
|
|
@@ -54,27 +58,82 @@ export interface AixEntry {
|
|
|
54
58
|
size: number;
|
|
55
59
|
compressed_size: number;
|
|
56
60
|
}
|
|
61
|
+
/** Inclusive archive budgets. Omitted fields are unlimited for compatibility. */
|
|
62
|
+
export interface AixReadLimits {
|
|
63
|
+
/** Maximum central-directory entries, including directories and metadata. */
|
|
64
|
+
maxEntries?: number;
|
|
65
|
+
/** Maximum declared and extracted bytes per entry. */
|
|
66
|
+
maxEntryBytes?: number;
|
|
67
|
+
/** Maximum total declared uncompressed bytes; repeated reads do not consume it. */
|
|
68
|
+
maxTotalBytes?: number;
|
|
69
|
+
}
|
|
70
|
+
/** JSON returned by the reader, including unvalidated legacy schema values. */
|
|
71
|
+
export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
|
|
72
|
+
export interface JsonObject {
|
|
73
|
+
[key: string]: JsonValue;
|
|
74
|
+
}
|
|
75
|
+
/** Schema payloads retain any JSON value; source checking validates the schema. */
|
|
76
|
+
export type JsonSchema = JsonValue;
|
|
77
|
+
export interface PageConstraint {
|
|
78
|
+
width: number;
|
|
79
|
+
height: number;
|
|
80
|
+
}
|
|
57
81
|
export interface PageInfo {
|
|
58
82
|
name: string;
|
|
59
|
-
title
|
|
60
|
-
|
|
83
|
+
title: string | null;
|
|
84
|
+
description: string | null;
|
|
85
|
+
data_schema: JsonSchema;
|
|
86
|
+
size: PageConstraint;
|
|
87
|
+
}
|
|
88
|
+
export interface MetadataDiagnostic {
|
|
89
|
+
/** Archive path of the missing, unreadable, or malformed resource. */
|
|
90
|
+
path: string;
|
|
91
|
+
message: string;
|
|
92
|
+
}
|
|
93
|
+
export interface MetadataResolution {
|
|
94
|
+
pages: PageInfo[];
|
|
95
|
+
tools: Tool[];
|
|
96
|
+
/** One failure per unresolved page, or an app.json configuration failure. */
|
|
97
|
+
diagnostics: MetadataDiagnostic[];
|
|
98
|
+
}
|
|
99
|
+
export type WidgetPlacement = 'persistent' | 'overlay';
|
|
100
|
+
export interface WidgetInfo {
|
|
101
|
+
path: string;
|
|
102
|
+
family: string;
|
|
103
|
+
placement: WidgetPlacement;
|
|
104
|
+
displayName: string | null;
|
|
105
|
+
description: string | null;
|
|
106
|
+
}
|
|
107
|
+
/** Serialized output uses the underscore-prefixed names, never input aliases. */
|
|
108
|
+
export type ToolTarget = '_current' | '_blank';
|
|
109
|
+
export interface FunctionDefinition {
|
|
110
|
+
name: string;
|
|
111
|
+
description: string | null;
|
|
112
|
+
parameters: JsonSchema;
|
|
61
113
|
}
|
|
62
114
|
export interface Tool {
|
|
115
|
+
/** The reader currently emits "function". */
|
|
63
116
|
type: string;
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
parameters: any;
|
|
68
|
-
};
|
|
117
|
+
target: ToolTarget;
|
|
118
|
+
layout: PageConstraint;
|
|
119
|
+
function: FunctionDefinition;
|
|
69
120
|
}
|
|
70
121
|
export declare class AIX {
|
|
71
122
|
private reader;
|
|
72
123
|
private constructor();
|
|
124
|
+
/** Run source structure, JS/TS syntax, schema, and permission checks in memory. */
|
|
125
|
+
static checkFromSource(files: AixInputFile[], options?: CheckOptions): Promise<CheckReport>;
|
|
126
|
+
/** Check a browser directory selection, retaining webkitRelativePath. */
|
|
127
|
+
static checkFromFiles(files: File[], options?: CheckOptions): Promise<CheckReport>;
|
|
73
128
|
/**
|
|
74
129
|
* Initialize the WASM module and create an AIX instance from the given data.
|
|
75
130
|
* @param data The .aix file content as Uint8Array or File
|
|
131
|
+
* @param limits Caller budgets; set all three when accepting untrusted archives.
|
|
132
|
+
* Values must be non-negative safe integers. Without limits, retains the
|
|
133
|
+
* historical unlimited policy. Input bytes and caller-retained copies are
|
|
134
|
+
* outside these budgets.
|
|
76
135
|
*/
|
|
77
|
-
static From(data: Uint8Array | File): Promise<AIX>;
|
|
136
|
+
static From(data: Uint8Array | File, limits?: AixReadLimits): Promise<AIX>;
|
|
78
137
|
static pack(files: AixInputFile[], options?: PackOptions): Promise<PackResult>;
|
|
79
138
|
/**
|
|
80
139
|
* Packs an in-memory application source tree.
|
|
@@ -99,6 +158,8 @@ export declare class AIX {
|
|
|
99
158
|
* Get the version metadata from the AIX package.
|
|
100
159
|
*/
|
|
101
160
|
getVersion(): string | undefined;
|
|
161
|
+
/** Stable project ID from the manifest; undefined for legacy packages. */
|
|
162
|
+
getAgentId(): string | undefined;
|
|
102
163
|
supportsEngine(currentVersion: string): boolean;
|
|
103
164
|
/**
|
|
104
165
|
* Get the title from app.json.
|
|
@@ -108,6 +169,17 @@ export declare class AIX {
|
|
|
108
169
|
* Get all pages from app.json and pages/*.json.
|
|
109
170
|
*/
|
|
110
171
|
getPages(): PageInfo[];
|
|
172
|
+
/**
|
|
173
|
+
* Resolve readable page resources and metadata, excluding failed pages/tools.
|
|
174
|
+
* Inspect diagnostics to distinguish a valid empty result from resolution errors.
|
|
175
|
+
* Widget/title fields are independent. This does not run full source checks.
|
|
176
|
+
*/
|
|
177
|
+
resolveMetadata(): MetadataResolution;
|
|
178
|
+
/**
|
|
179
|
+
* Get all widgets from app.json after validating that each .ink entry exists.
|
|
180
|
+
* When locale is provided, merge displayName and description from app.<locale>.json.
|
|
181
|
+
*/
|
|
182
|
+
getWidgets(locale?: string): WidgetInfo[];
|
|
111
183
|
/**
|
|
112
184
|
* Get all tools from app.json and pages/*.json in OpenAI format.
|
|
113
185
|
*/
|
package/index.js
CHANGED
|
@@ -1,5 +1,23 @@
|
|
|
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
|
+
}
|
|
3
21
|
function generateBuildId() {
|
|
4
22
|
const cryptoApi = globalThis.crypto;
|
|
5
23
|
if (typeof cryptoApi?.randomUUID === 'function') {
|
|
@@ -24,12 +42,35 @@ export class AIX {
|
|
|
24
42
|
constructor(reader) {
|
|
25
43
|
this.reader = reader;
|
|
26
44
|
}
|
|
45
|
+
/** Run source structure, JS/TS syntax, schema, and permission checks in memory. */
|
|
46
|
+
static async checkFromSource(files, options) {
|
|
47
|
+
options?.onProgress?.({ type: 'loading_checker' });
|
|
48
|
+
const [tooling, { checkSource }] = await Promise.all([loadTooling(), import('./check/index.js')]);
|
|
49
|
+
return checkSource(files, tooling, options);
|
|
50
|
+
}
|
|
51
|
+
/** Check a browser directory selection, retaining webkitRelativePath. */
|
|
52
|
+
static async checkFromFiles(files, options) {
|
|
53
|
+
const sources = await Promise.all(files.map(async (file) => ({
|
|
54
|
+
path: resolveWebFilePath(file),
|
|
55
|
+
data: new Uint8Array(await file.arrayBuffer()),
|
|
56
|
+
})));
|
|
57
|
+
const selectedRoot = sources[0]?.path.split('/')[0];
|
|
58
|
+
if (selectedRoot && files.every((file) => file.webkitRelativePath?.startsWith(`${selectedRoot}/`))) {
|
|
59
|
+
for (const source of sources)
|
|
60
|
+
source.path = source.path.slice(selectedRoot.length + 1);
|
|
61
|
+
}
|
|
62
|
+
return AIX.checkFromSource(sources, options);
|
|
63
|
+
}
|
|
27
64
|
/**
|
|
28
65
|
* Initialize the WASM module and create an AIX instance from the given data.
|
|
29
66
|
* @param data The .aix file content as Uint8Array or File
|
|
67
|
+
* @param limits Caller budgets; set all three when accepting untrusted archives.
|
|
68
|
+
* Values must be non-negative safe integers. Without limits, retains the
|
|
69
|
+
* historical unlimited policy. Input bytes and caller-retained copies are
|
|
70
|
+
* outside these budgets.
|
|
30
71
|
*/
|
|
31
|
-
static async From(data) {
|
|
32
|
-
await
|
|
72
|
+
static async From(data, limits) {
|
|
73
|
+
await initializeReader();
|
|
33
74
|
let buffer;
|
|
34
75
|
if (data instanceof Uint8Array) {
|
|
35
76
|
buffer = data;
|
|
@@ -38,14 +79,16 @@ export class AIX {
|
|
|
38
79
|
const arrayBuffer = await data.arrayBuffer();
|
|
39
80
|
buffer = new Uint8Array(arrayBuffer);
|
|
40
81
|
}
|
|
41
|
-
const reader =
|
|
82
|
+
const reader = limits === undefined
|
|
83
|
+
? new AixReaderWasm(buffer)
|
|
84
|
+
: AixReaderWasm.with_limits(buffer, limits);
|
|
42
85
|
return new AIX(reader);
|
|
43
86
|
}
|
|
44
87
|
static async pack(files, options) {
|
|
45
|
-
await
|
|
88
|
+
const tooling = await loadTooling();
|
|
46
89
|
const buildId = options?.buildId ?? generateBuildId();
|
|
47
90
|
const optimize = options?.optimize === false ? undefined : options?.optimize;
|
|
48
|
-
const result = pack_aix(files, buildId, options?.engine, optimize);
|
|
91
|
+
const result = tooling.pack_aix(files, buildId, options?.engine, optimize, options?.agentId);
|
|
49
92
|
return { data: result.data, report: result.report, warnings: result.warnings ?? [] };
|
|
50
93
|
}
|
|
51
94
|
/**
|
|
@@ -56,12 +99,12 @@ export class AIX {
|
|
|
56
99
|
* `.aixignore` files are honored, and the rule files are omitted.
|
|
57
100
|
*/
|
|
58
101
|
static async packFromSource(files, options) {
|
|
59
|
-
await
|
|
102
|
+
const tooling = await loadTooling();
|
|
60
103
|
const buildId = options?.buildId ?? generateBuildId();
|
|
61
104
|
const optimize = options?.optimize === false ? undefined : options?.optimize;
|
|
62
105
|
const result = options?.onProgress
|
|
63
|
-
? getPackFromSourceWithProgress()(files, buildId, options.engine, optimize, options.onProgress)
|
|
64
|
-
: getPackFromSource()(files, buildId, options?.engine, optimize);
|
|
106
|
+
? getPackFromSourceWithProgress(tooling)(files, buildId, options.engine, optimize, options.onProgress, options.agentId)
|
|
107
|
+
: getPackFromSource(tooling)(files, buildId, options?.engine, optimize, options?.agentId);
|
|
65
108
|
return { data: result.data, report: result.report, warnings: result.warnings ?? [] };
|
|
66
109
|
}
|
|
67
110
|
static async packFromFiles(files, options) {
|
|
@@ -72,11 +115,11 @@ export class AIX {
|
|
|
72
115
|
return AIX.packFromSource(sourceFiles, options);
|
|
73
116
|
}
|
|
74
117
|
static async optimize(data, options) {
|
|
75
|
-
await
|
|
118
|
+
const tooling = await loadTooling();
|
|
76
119
|
const buffer = data instanceof Uint8Array
|
|
77
120
|
? data
|
|
78
121
|
: new Uint8Array(await data.arrayBuffer());
|
|
79
|
-
const result = optimize_aix(buffer, options);
|
|
122
|
+
const result = tooling.optimize_aix(buffer, options);
|
|
80
123
|
return { data: result.data, report: result.report, warnings: result.warnings ?? [] };
|
|
81
124
|
}
|
|
82
125
|
/**
|
|
@@ -98,6 +141,10 @@ export class AIX {
|
|
|
98
141
|
getVersion() {
|
|
99
142
|
return this.reader.get_version();
|
|
100
143
|
}
|
|
144
|
+
/** Stable project ID from the manifest; undefined for legacy packages. */
|
|
145
|
+
getAgentId() {
|
|
146
|
+
return this.reader.get_agent_id();
|
|
147
|
+
}
|
|
101
148
|
supportsEngine(currentVersion) {
|
|
102
149
|
return this.reader.supports_engine(currentVersion);
|
|
103
150
|
}
|
|
@@ -113,6 +160,21 @@ export class AIX {
|
|
|
113
160
|
getPages() {
|
|
114
161
|
return this.reader.get_pages();
|
|
115
162
|
}
|
|
163
|
+
/**
|
|
164
|
+
* Resolve readable page resources and metadata, excluding failed pages/tools.
|
|
165
|
+
* Inspect diagnostics to distinguish a valid empty result from resolution errors.
|
|
166
|
+
* Widget/title fields are independent. This does not run full source checks.
|
|
167
|
+
*/
|
|
168
|
+
resolveMetadata() {
|
|
169
|
+
return this.reader.resolve_metadata();
|
|
170
|
+
}
|
|
171
|
+
/**
|
|
172
|
+
* Get all widgets from app.json after validating that each .ink entry exists.
|
|
173
|
+
* When locale is provided, merge displayName and description from app.<locale>.json.
|
|
174
|
+
*/
|
|
175
|
+
getWidgets(locale) {
|
|
176
|
+
return this.reader.get_widgets(locale);
|
|
177
|
+
}
|
|
116
178
|
/**
|
|
117
179
|
* Get all tools from app.json and pages/*.json in OpenAI format.
|
|
118
180
|
*/
|
|
@@ -124,15 +186,15 @@ function resolveWebFilePath(file) {
|
|
|
124
186
|
const candidate = file.webkitRelativePath;
|
|
125
187
|
return candidate && candidate.length > 0 ? candidate : file.name;
|
|
126
188
|
}
|
|
127
|
-
function getPackFromSource() {
|
|
128
|
-
const packFromSource =
|
|
189
|
+
function getPackFromSource(tooling) {
|
|
190
|
+
const packFromSource = tooling.pack_aix_from_source;
|
|
129
191
|
if (!packFromSource) {
|
|
130
192
|
throw new Error('pack_aix_from_source is not available in the current WASM bundle');
|
|
131
193
|
}
|
|
132
194
|
return packFromSource;
|
|
133
195
|
}
|
|
134
|
-
function getPackFromSourceWithProgress() {
|
|
135
|
-
const packFromSourceWithProgress =
|
|
196
|
+
function getPackFromSourceWithProgress(tooling) {
|
|
197
|
+
const packFromSourceWithProgress = tooling.pack_aix_from_source_with_progress;
|
|
136
198
|
if (!packFromSourceWithProgress) {
|
|
137
199
|
throw new Error('pack_aix_from_source_with_progress is not available in the current WASM bundle');
|
|
138
200
|
}
|
package/jsr.json
CHANGED