@skathi-native/cli 0.0.0-stage → 0.1.0-beta.1

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/cli/sk.ts ADDED
@@ -0,0 +1,356 @@
1
+ #!/usr/bin/env bun
2
+ // sk — create, develop and package a Skathi app for Windows, macOS or Linux, without a
3
+ // Rust toolchain.
4
+
5
+ import { spawn } from "node:child_process";
6
+ import { buildApp, summary } from "./build-app";
7
+ import {
8
+ ConfigError,
9
+ OPTIONAL,
10
+ parseParts,
11
+ partsLeftOut,
12
+ selectVariant,
13
+ VARIANTS,
14
+ variantFor,
15
+ type Variant,
16
+ } from "./config";
17
+ import { dev } from "./dev";
18
+ import { addHost, buildHost, CLI_VERSION, DEV_HOST, HostError, hostInfo, resolveHost } from "./host";
19
+ import { fetchHost } from "./host-fetch";
20
+ import { colorEnabled, colorFlag, lineProgress, logTo, paint, progressFor } from "./term";
21
+ import { createCommand } from "./create";
22
+ import { currentPlatform, parsePlatform } from "./platform";
23
+
24
+ const USAGE = `sk ${CLI_VERSION} — package a Skathi app for Windows, macOS or Linux
25
+
26
+ usage
27
+ sk dev [app] [--exe <h>] the dev loop: build.ts --watch + a dev host (hot reload); the
28
+ host is the checkout's debug sk-app, else this version's,
29
+ cached or downloaded from its release
30
+ sk build [app] [options] a debug exe in <app>/dist/debug: devtools (F12) in, the bundle
31
+ not minified
32
+ sk publish [app] [options] the release exe in <app>/dist/release: the engine parts
33
+ sk.config.json selects, and without a selection no devtools;
34
+ minified (macOS: <exeName>.app, signed per macos.sign)
35
+ sk run [app] [options] sk build, then start the exe with its stderr in this terminal
36
+ sk host info [exe] what a host exe says about itself (--sk-host-info)
37
+ sk host path [selection] which host \`sk build\` would stamp
38
+ sk host fetch [selection | --variant both | --variant dev]
39
+ download prebuilt hosts of this version from its GitHub
40
+ release into the local cache (no selection: every published
41
+ one and the dev host; sk build and sk dev do it on demand)
42
+ sk host add <exe> verify a prod host and copy it into the local cache
43
+ sk host build [selection | --variant both]
44
+ maintainers, in a checkout: cargo-build the bare host(s)
45
+ (no selection: standard and no-devtools)
46
+ sk check [app] [options] what in the bundle (app code and node_modules) breaks or slows
47
+ down under native AOT, and how well it is typed
48
+ --format pretty|json json: one versioned report on stdout (schema skathi.check)
49
+ --deny-warnings warnings fail the check too
50
+ --no-deps the app's own code only
51
+ --config <path> external config, as for sk build
52
+ --color | --no-color colours on or off (default: a terminal, unless NO_COLOR is set)
53
+ exit 0: clean; 1: errors; 2: usage, config or internal failure
54
+ sk.config.json "check": { "allow": { "SK2001": ["pkg", "src/legacy/**"] } }
55
+ sk explain <CODE> | --list what a check code means and how to fix it
56
+ sk create [dir] [options] a new app; in a terminal it asks for what the options leave open
57
+ --name <n> the app's name (default: the directory's)
58
+ --os windows,macos what sk publish packages for (default: this OS)
59
+ --without audio,… engine parts to leave out (${OPTIONAL.filter((p) => p !== "devtools").join(", ")})
60
+ --devtools | --no-devtools whether sk publish keeps devtools (default: no)
61
+ --router | --no-router vue-router and pinia (asked: yes; with --yes: no)
62
+ --pm bun|npm|pnpm|yarn the package manager (default: the one running this, else bun)
63
+ --yes, -y ask nothing; defaults for the rest
64
+
65
+ [app] is an app directory (default: .), its entry module, or its sk.config.json.
66
+
67
+ build and publish options
68
+ --out <dir> output directory (default <app>/dist/debug or dist/release)
69
+ --config <path> external config; entry and relative assets stay under [app]
70
+ --host <exe> the bare host to stamp (default: SK_HOST, the checkout's
71
+ target/…/release/sk-app.exe, the local cache, then a
72
+ download from the release; SK_HOST_OFFLINE=1 skips that)
73
+ selection — which engine parts the host carries (default: sk.config.json
74
+ "windows": "without" / "features" / "host", else every part; sk build always keeps
75
+ devtools, sk publish drops them unless the config selects them). One of:
76
+ --without audio,clipboard leave these parts out
77
+ --features audio,storages take only these parts
78
+ --variant no-devtools+no-audio
79
+ a host variant by name ("standard" = every part)
80
+ parts: ${OPTIONAL.join(", ")}
81
+ --console keep the console subsystem (a console window opens with it)
82
+ --platform windows|macos|linux what to package for (default: this OS). Another OS's
83
+ build needs --host <its sk-app>, and is not signed
84
+ --sign <identity> macOS: codesign with this identity, hardened runtime and
85
+ entitlements ("-" = ad hoc; over sk.config.json macos.sign)
86
+ --no-sign macOS: leave the bundle unsigned (default: ad hoc)
87
+ --payload-only write dist/.sk/app.skpk and stop; no host needed
88
+ --aot-inputs retain typed TS/Vue source inputs in dist/.sk/aot-inputs/
89
+ (preparation archive; does not enable native AOT)
90
+ --allow-host-mismatch stamp a host from another Skathi version (maintainers)
91
+ --define K=V a Vite-style define on top of sk.config.json "define"
92
+ (V is an expression: --define __FLAG__=true,
93
+ --define 'APP_NAME="argon"'); repeatable
94
+ --json one JSON line instead of the summary (build, host path)
95
+
96
+ sk.config.json "packs" splits the assets into <name>.skpk files beside the payload
97
+ (or the exe), e.g. [{ "name": "fonts", "match": ["**/*.woff2"] }, { "name": "assets" }].
98
+ `;
99
+
100
+ type Flags = Record<string, string | boolean>;
101
+ const BOOLEAN = new Set([
102
+ "deny-warnings",
103
+ "no-deps",
104
+ "list",
105
+ "console",
106
+ "payload-only",
107
+ "allow-host-mismatch",
108
+ "aot-inputs",
109
+ "help",
110
+ "json",
111
+ "no-sign",
112
+ "yes",
113
+ "devtools",
114
+ "no-devtools",
115
+ "router",
116
+ "no-router",
117
+ "color",
118
+ "no-color",
119
+ ]);
120
+ const REPEATABLE = new Set(["define"]);
121
+
122
+ function parse(argv: string[]): {
123
+ positional: string[];
124
+ flags: Flags;
125
+ repeated: Record<string, string[]>;
126
+ rest: string[];
127
+ } {
128
+ const positional: string[] = [];
129
+ const flags: Flags = {};
130
+ const repeated: Record<string, string[]> = {};
131
+ let rest: string[] = [];
132
+ for (let i = 0; i < argv.length; i++) {
133
+ const a = argv[i]!;
134
+ if (a === "--") {
135
+ rest = argv.slice(i + 1);
136
+ break;
137
+ }
138
+ if (a === "-h") flags.help = true;
139
+ else if (a === "-y") flags.yes = true;
140
+ else if (a.startsWith("--")) {
141
+ // Split at the FIRST "=" only: `--define=K=V` keeps its own "=".
142
+ const body = a.slice(2);
143
+ const eq = body.indexOf("=");
144
+ const name = eq < 0 ? body : body.slice(0, eq);
145
+ const inline = eq < 0 ? undefined : body.slice(eq + 1);
146
+ if (BOOLEAN.has(name)) flags[name] = true;
147
+ else if (REPEATABLE.has(name)) (repeated[name] ??= []).push(inline ?? argv[++i] ?? "");
148
+ else flags[name] = inline ?? argv[++i] ?? "";
149
+ } else positional.push(a);
150
+ }
151
+ return { positional, flags, repeated, rest };
152
+ }
153
+
154
+ function variantOf(flags: Flags): Variant | undefined {
155
+ const list = (name: string) => {
156
+ const v = flags[name];
157
+ if (v === undefined) return undefined;
158
+ if (typeof v !== "string" || !v.trim())
159
+ throw new ConfigError(`--${name} needs a list of parts (${OPTIONAL.join(", ")})`);
160
+ return parseParts(v, `--${name}`);
161
+ };
162
+ const host = flags.variant;
163
+ if (host !== undefined && (typeof host !== "string" || !host.trim()))
164
+ throw new ConfigError("--variant needs a variant name");
165
+ const sel = { features: list("features"), without: list("without"), host: host as string | undefined };
166
+ if (!sel.features && !sel.without && !sel.host) return undefined;
167
+ // Normalised: `no-audio+no-devtools` and `no-devtools+no-audio` are one host.
168
+ return variantFor(partsLeftOut(selectVariant(sel, "the command line")));
169
+ }
170
+
171
+ async function main(argv: string[]): Promise<number> {
172
+ const { positional, flags, repeated, rest } = parse(argv);
173
+ const [command, ...args] = positional;
174
+ if (!command || flags.help || command === "help") {
175
+ console.log(USAGE);
176
+ return command || flags.help ? 0 : 1;
177
+ }
178
+ if (command === "version" || command === "--version") {
179
+ console.log(CLI_VERSION);
180
+ return 0;
181
+ }
182
+
183
+ if (command === "build" || command === "publish" || command === "run") {
184
+ const platform = flags.platform === undefined ? undefined : parsePlatform(flags.platform);
185
+ if (command === "run" && platform && platform !== currentPlatform()) {
186
+ throw new ConfigError(
187
+ `sk run starts the app here; a ${platform} build cannot run on ${process.platform} — use sk build`,
188
+ );
189
+ }
190
+ if (flags.sign !== undefined && (typeof flags.sign !== "string" || !flags.sign.trim())) {
191
+ throw new ConfigError('--sign needs a codesign identity ("-" for ad hoc)');
192
+ }
193
+ if (flags.sign !== undefined && flags["no-sign"])
194
+ throw new ConfigError("--sign and --no-sign contradict each other");
195
+ const progress = progressFor(process.stderr, colorEnabled(process.stderr, colorFlag(flags)));
196
+ const result = await buildApp({
197
+ progress,
198
+ target: args[0] ?? ".",
199
+ configPath: typeof flags.config === "string" ? flags.config : undefined,
200
+ out: typeof flags.out === "string" ? flags.out : undefined,
201
+ host: typeof flags.host === "string" ? flags.host : undefined,
202
+ variant: variantOf(flags),
203
+ console: flags.console === true,
204
+ payloadOnly: flags["payload-only"] === true,
205
+ allowHostMismatch: flags["allow-host-mismatch"] === true,
206
+ defines: repeated.define,
207
+ aotInputs: flags["aot-inputs"] === true,
208
+ platform,
209
+ sign: flags["no-sign"] ? false : typeof flags.sign === "string" ? flags.sign.trim() : undefined,
210
+ mode: command === "publish" ? "release" : "debug",
211
+ }).finally(() => progress.end());
212
+ if (flags.json) {
213
+ const s = result.stamp;
214
+ console.log(
215
+ JSON.stringify({
216
+ exe: result.exe,
217
+ skpk: result.skpk,
218
+ aotInputs: result.aotInputs,
219
+ name: result.config.name,
220
+ productName: result.config.productName,
221
+ version: result.config.version,
222
+ variant: result.variant,
223
+ host: result.host && { exe: result.host.exe, source: result.host.source, profile: result.host.info.profile },
224
+ assets: result.assets.length,
225
+ bundleBytes: result.bundleBytes,
226
+ payloadBytes: result.payloadBytes,
227
+ ...(result.packs.length ? { packs: result.packs } : {}),
228
+ stamp: s && {
229
+ bytes: s.bytes,
230
+ skew: s.skew,
231
+ dataAligned: s.dataAligned,
232
+ passes: s.passes,
233
+ subsystem: s.subsystem,
234
+ iconCount: s.iconCount,
235
+ ms: s.ms,
236
+ },
237
+ ...(result.bundle && {
238
+ platform: result.platform,
239
+ app: result.bundle.app,
240
+ bundle: {
241
+ bundleId: result.bundle.bundleId,
242
+ bytes: result.bundle.bytes,
243
+ iconSizes: result.bundle.iconSizes,
244
+ signed: result.bundle.signed,
245
+ signNote: result.bundle.signNote,
246
+ entitlements: result.bundle.entitlements,
247
+ ms: result.bundle.ms,
248
+ },
249
+ }),
250
+ warnings: result.warnings,
251
+ ms: result.ms,
252
+ }),
253
+ );
254
+ } else {
255
+ console.log(summary(result, colorEnabled(process.stdout, colorFlag(flags))));
256
+ }
257
+ if (command !== "run" || !result.exe) return 0;
258
+ // `run`: inherited handles, so a GUI-subsystem exe's stderr still lands in this terminal.
259
+ const child = spawn(result.exe, rest, { stdio: "inherit" });
260
+ return await new Promise<number>((done) => child.on("exit", (c) => done(c ?? 0)));
261
+ }
262
+
263
+ if (command === "check") return await (await import("../check/command")).checkCommand(args[0], flags, CLI_VERSION);
264
+ if (command === "explain")
265
+ return (await import("../check/command")).explainCommand(args[0], flags.list === true, flags);
266
+
267
+ if (command === "dev") {
268
+ return await dev(args[0] ?? ".", { exe: typeof flags.exe === "string" ? flags.exe : undefined });
269
+ }
270
+
271
+ if (command === "host") {
272
+ const [sub, arg] = args;
273
+ if (sub === "info") {
274
+ const exe = arg ?? resolveHost({ variant: variantOf(flags) ?? "standard", allowMismatch: true }).exe;
275
+ // `hostInfo` refuses a stamped exe itself: asking one for host info would launch the app inside it.
276
+ console.log(JSON.stringify(hostInfo(exe), null, 2));
277
+ return 0;
278
+ }
279
+ if (sub === "path") {
280
+ const h = resolveHost({
281
+ variant: variantOf(flags) ?? "standard",
282
+ host: typeof flags.host === "string" ? flags.host : undefined,
283
+ platform: flags.platform === undefined ? undefined : parsePlatform(flags.platform),
284
+ });
285
+ console.log(flags.json ? JSON.stringify({ exe: h.exe, source: h.source, info: h.info }, null, 2) : h.exe);
286
+ return 0;
287
+ }
288
+ if (sub === "add") {
289
+ if (!arg) throw new HostError("sk host add <exe>");
290
+ addHost(arg, (line) => console.log(line));
291
+ return 0;
292
+ }
293
+ const color = colorEnabled(process.stderr, colorFlag(flags));
294
+ if (sub === "fetch") {
295
+ const named = flags.variant === "both" || flags.variant === DEV_HOST ? flags.variant : variantOf(flags);
296
+ const variants = named === undefined ? [...VARIANTS, DEV_HOST] : named === "both" ? VARIANTS : [named];
297
+ const progress = progressFor(process.stderr, color);
298
+ try {
299
+ for (const variant of variants) {
300
+ progress.step(`${variant} host`);
301
+ await fetchHost({ variant, log: (line) => progress.detail(line) });
302
+ }
303
+ } finally {
304
+ progress.end();
305
+ }
306
+ return 0;
307
+ }
308
+ if (sub === "build") {
309
+ // cargo draws its own progress on the terminal: plain lines around it.
310
+ const lines = lineProgress((line) => console.error(line), color);
311
+ const v = flags.variant === "both" ? "both" : (variantOf(flags) ?? "both");
312
+ for (const variant of v === "both" ? VARIANTS : [v]) {
313
+ lines.step(`${variant} host`);
314
+ const built = buildHost(variant, logTo(lines));
315
+ lines.detail(built.path);
316
+ }
317
+ lines.end();
318
+ return 0;
319
+ }
320
+ throw new HostError("sk host info|path|fetch|add|build");
321
+ }
322
+
323
+ if (command === "create") {
324
+ const str = (k: string) => (typeof flags[k] === "string" ? (flags[k] as string) : undefined);
325
+ const yesNo = (k: string) => (flags[k] ? true : flags[`no-${k}`] ? false : undefined);
326
+ return await createCommand(args[0], {
327
+ name: str("name"),
328
+ os: str("os"),
329
+ without: str("without"),
330
+ devtools: yesNo("devtools"),
331
+ router: yesNo("router"),
332
+ pm: str("pm"),
333
+ yes: flags.yes === true,
334
+ });
335
+ }
336
+
337
+ console.error(
338
+ `${paint(colorEnabled(process.stderr)).red("error")}: unknown command ${JSON.stringify(command)}\n\n${USAGE}`,
339
+ );
340
+ return 1;
341
+ }
342
+
343
+ if (import.meta.main) {
344
+ main(process.argv.slice(2)).then(
345
+ (code) => process.exit(code),
346
+ (e) => {
347
+ const known = e instanceof ConfigError || e instanceof HostError;
348
+ const red = paint(colorEnabled(process.stderr)).red;
349
+ if (known || (e instanceof Error && !process.env.SK_DEBUG)) console.error(`${red("error")}: ${e.message}`);
350
+ else console.error(e);
351
+ process.exit(1);
352
+ },
353
+ );
354
+ }
355
+
356
+ export { main };
package/cli/skpk.ts ADDED
@@ -0,0 +1,268 @@
1
+ // SKPK v1: the one blob a packaged exe carries. The writer is here; the reader that matters is in
2
+ // Rust (`crates/sk-payload`), and both are held to `test/fixtures/golden.skpk`.
3
+ //
4
+ // header (64 bytes, little-endian, read BYTE-WISE: the blob is only 4-byte aligned in the image)
5
+ // 0 "SKPK" | 4 u16 format = 1 (a host refuses > 1) | 6 u16 flags (bit 0: has BYTECODE)
6
+ // 8 u32 entry_count | 12 u32 toc_off (= 64) | 16 u32 names_off | 20 u32 names_len
7
+ // 24 u32 skew: zero bytes between names and data, chosen so data_off lands on a page boundary
8
+ // IN THE MAPPED IMAGE | 28 u32 reserved | 32 u64 data_off (= names_off + names_len + skew)
9
+ // 40 u64 blob_len | 48 [16] reserved
10
+ // toc: entry_count x 32 bytes sorted by (kind, name bytes): u32 name_off (rel. names_off),
11
+ // u32 name_len, u64 off (rel. data_off), u64 len, u16 kind, u8 align_log2, u8 reserved, u32 crc32
12
+ // names: UTF-8, no terminators. data: each entry aligned to 2^align_log2 relative to data_off.
13
+ //
14
+ // No timestamps, so two builds of the same inputs are byte-identical. No compression: demand
15
+ // paging matters more than size.
16
+
17
+ export const MAGIC = "SKPK";
18
+ export const FORMAT = 1;
19
+ export const HEADER_SIZE = 64;
20
+ export const TOC_ENTRY_SIZE = 32;
21
+ export const PAGE = 4096;
22
+
23
+ export const KIND = {
24
+ META: 1,
25
+ WINDOW: 2,
26
+ SCRIPT: 3,
27
+ BYTECODE: 4,
28
+ ASSET: 16,
29
+ } as const;
30
+
31
+ export const NAMES = {
32
+ META: "sk/app.json",
33
+ WINDOW: "sk/window.json",
34
+ SCRIPT: "sk/app.js",
35
+ BYTECODE: "sk/app.bc",
36
+ } as const;
37
+
38
+ export const FLAG_HAS_BYTECODE = 1;
39
+
40
+ export interface SkpkInput {
41
+ name: string;
42
+ kind: number;
43
+ data: Uint8Array;
44
+ alignLog2?: number;
45
+ }
46
+
47
+ export interface SkpkEntry {
48
+ name: string;
49
+ kind: number;
50
+ start: number;
51
+ len: number;
52
+ alignLog2: number;
53
+ crc32: number;
54
+ }
55
+
56
+ export interface SkpkHeader {
57
+ format: number;
58
+ flags: number;
59
+ entryCount: number;
60
+ tocOff: number;
61
+ namesOff: number;
62
+ namesLen: number;
63
+ skew: number;
64
+ dataOff: number;
65
+ blobLen: number;
66
+ }
67
+
68
+ // crc32 (IEEE), for `sk verify` and the tests; the host never checks it at boot (it would fault in every page).
69
+
70
+ const CRC_TABLE = (() => {
71
+ const t = new Uint32Array(256);
72
+ for (let n = 0; n < 256; n++) {
73
+ let c = n;
74
+ for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
75
+ t[n] = c >>> 0;
76
+ }
77
+ return t;
78
+ })();
79
+
80
+ export function crc32(bytes: Uint8Array, seed = 0): number {
81
+ let c = (seed ^ 0xffffffff) >>> 0;
82
+ for (let i = 0; i < bytes.length; i++) c = CRC_TABLE[(c ^ bytes[i]!) & 0xff]! ^ (c >>> 8);
83
+ return (c ^ 0xffffffff) >>> 0;
84
+ }
85
+
86
+ const utf8 = new TextEncoder();
87
+
88
+ export function compareBytes(a: Uint8Array, b: Uint8Array): number {
89
+ const n = Math.min(a.length, b.length);
90
+ for (let i = 0; i < n; i++) {
91
+ if (a[i] !== b[i]) return a[i]! - b[i]!;
92
+ }
93
+ return a.length - b.length;
94
+ }
95
+
96
+ const alignUp = (n: number, to: number) => Math.ceil(n / to) * to;
97
+
98
+ function defaultAlign(kind: number): number {
99
+ return kind === KIND.BYTECODE ? 12 : 4;
100
+ }
101
+
102
+ /** Lays the entries out and returns the blob. `skew: 0` is a valid payload, just not page-aligned. */
103
+ export function writeSkpk(inputs: SkpkInput[], options: { skew?: number } = {}): Uint8Array {
104
+ const skew = options.skew ?? 0;
105
+ if (!Number.isInteger(skew) || skew < 0 || skew >= PAGE) {
106
+ throw new Error(`skpk: skew must be an integer in [0, ${PAGE}), got ${skew}`);
107
+ }
108
+ const items = inputs.map((e) => ({
109
+ ...e,
110
+ nameBytes: utf8.encode(e.name),
111
+ alignLog2: e.alignLog2 ?? defaultAlign(e.kind),
112
+ }));
113
+ for (const e of items) {
114
+ if (!e.name) throw new Error("skpk: an entry has an empty name");
115
+ if (!Number.isInteger(e.kind) || e.kind < 1 || e.kind > 0xffff) {
116
+ throw new Error(`skpk: ${e.name}: kind ${e.kind} is not a u16`);
117
+ }
118
+ if (e.alignLog2 < 0 || e.alignLog2 > 16) throw new Error(`skpk: ${e.name}: align 2^${e.alignLog2}`);
119
+ }
120
+ items.sort((a, b) => a.kind - b.kind || compareBytes(a.nameBytes, b.nameBytes));
121
+ for (let i = 1; i < items.length; i++) {
122
+ const a = items[i - 1]!;
123
+ const b = items[i]!;
124
+ if (a.kind === b.kind && compareBytes(a.nameBytes, b.nameBytes) === 0) {
125
+ throw new Error(`skpk: duplicate entry ${JSON.stringify(b.name)} (kind ${b.kind})`);
126
+ }
127
+ }
128
+
129
+ const tocOff = HEADER_SIZE;
130
+ const namesOff = tocOff + items.length * TOC_ENTRY_SIZE;
131
+ const namesLen = items.reduce((n, e) => n + e.nameBytes.length, 0);
132
+ const dataOff = namesOff + namesLen + skew;
133
+
134
+ let cursor = 0;
135
+ const placed = items.map((e) => {
136
+ const off = alignUp(cursor, 1 << e.alignLog2);
137
+ cursor = off + e.data.length;
138
+ return off;
139
+ });
140
+ const blobLen = dataOff + cursor;
141
+ if (blobLen > 0xffff_ffff) {
142
+ throw new Error(`skpk: ${blobLen} bytes — a PE resource is limited to 4 GiB`);
143
+ }
144
+
145
+ const out = new Uint8Array(blobLen);
146
+ const dv = new DataView(out.buffer);
147
+ out.set(utf8.encode(MAGIC), 0);
148
+ dv.setUint16(4, FORMAT, true);
149
+ let flags = 0;
150
+ if (items.some((e) => e.kind === KIND.BYTECODE)) flags |= FLAG_HAS_BYTECODE;
151
+ dv.setUint16(6, flags, true);
152
+ dv.setUint32(8, items.length, true);
153
+ dv.setUint32(12, tocOff, true);
154
+ dv.setUint32(16, namesOff, true);
155
+ dv.setUint32(20, namesLen, true);
156
+ dv.setUint32(24, skew, true);
157
+ dv.setUint32(28, 0, true);
158
+ dv.setBigUint64(32, BigInt(dataOff), true);
159
+ dv.setBigUint64(40, BigInt(blobLen), true);
160
+
161
+ let nameCursor = 0;
162
+ items.forEach((e, i) => {
163
+ const t = tocOff + i * TOC_ENTRY_SIZE;
164
+ dv.setUint32(t + 0, nameCursor, true);
165
+ dv.setUint32(t + 4, e.nameBytes.length, true);
166
+ dv.setBigUint64(t + 8, BigInt(placed[i]!), true);
167
+ dv.setBigUint64(t + 16, BigInt(e.data.length), true);
168
+ dv.setUint16(t + 24, e.kind, true);
169
+ out[t + 26] = e.alignLog2;
170
+ out[t + 27] = 0;
171
+ dv.setUint32(t + 28, crc32(e.data), true);
172
+ out.set(e.nameBytes, namesOff + nameCursor);
173
+ nameCursor += e.nameBytes.length;
174
+ out.set(e.data, dataOff + placed[i]!);
175
+ });
176
+ return out;
177
+ }
178
+
179
+ /** The skew that puts `data_off` on a page boundary once the blob sits at image RVA `rva`. */
180
+ export function skewFor(rva: number, header: Pick<SkpkHeader, "namesOff" | "namesLen">): number {
181
+ const namesEnd = header.namesOff + header.namesLen;
182
+ return (PAGE - ((rva + namesEnd) % PAGE)) % PAGE;
183
+ }
184
+
185
+ export class SkpkError extends Error {}
186
+
187
+ export function readHeader(blob: Uint8Array): SkpkHeader {
188
+ if (blob.length < HEADER_SIZE) throw new SkpkError(`skpk: ${blob.length} bytes is shorter than a header`);
189
+ const magic = new TextDecoder().decode(blob.subarray(0, 4));
190
+ if (magic !== MAGIC) throw new SkpkError(`skpk: bad magic ${JSON.stringify(magic)}`);
191
+ const dv = new DataView(blob.buffer, blob.byteOffset, blob.byteLength);
192
+ const format = dv.getUint16(4, true);
193
+ if (format > FORMAT) {
194
+ throw new SkpkError(`skpk: format ${format} — this payload was built by a newer sk`);
195
+ }
196
+ return {
197
+ format,
198
+ flags: dv.getUint16(6, true),
199
+ entryCount: dv.getUint32(8, true),
200
+ tocOff: dv.getUint32(12, true),
201
+ namesOff: dv.getUint32(16, true),
202
+ namesLen: dv.getUint32(20, true),
203
+ skew: dv.getUint32(24, true),
204
+ dataOff: Number(dv.getBigUint64(32, true)),
205
+ blobLen: Number(dv.getBigUint64(40, true)),
206
+ };
207
+ }
208
+
209
+ export interface Skpk {
210
+ header: SkpkHeader;
211
+ entries: SkpkEntry[];
212
+ bytes(e: SkpkEntry): Uint8Array;
213
+ find(kind: number, name: string): SkpkEntry | undefined;
214
+ }
215
+
216
+ export function readSkpk(blob: Uint8Array): Skpk {
217
+ const header = readHeader(blob);
218
+ const dv = new DataView(blob.buffer, blob.byteOffset, blob.byteLength);
219
+ const within = (what: string, start: number, len: number) => {
220
+ if (start < 0 || len < 0 || start + len > blob.length) {
221
+ throw new SkpkError(`skpk: ${what} [${start}, +${len}) is outside the ${blob.length}-byte blob`);
222
+ }
223
+ };
224
+ within("toc", header.tocOff, header.entryCount * TOC_ENTRY_SIZE);
225
+ within("names", header.namesOff, header.namesLen);
226
+ within("data", header.dataOff, 0);
227
+ if (header.blobLen > blob.length) within("blob_len", 0, header.blobLen);
228
+ const decoder = new TextDecoder("utf-8", { fatal: true });
229
+ const entries: SkpkEntry[] = [];
230
+ for (let i = 0; i < header.entryCount; i++) {
231
+ const t = header.tocOff + i * TOC_ENTRY_SIZE;
232
+ const nameOff = dv.getUint32(t, true);
233
+ const nameLen = dv.getUint32(t + 4, true);
234
+ within(`entry ${i} name`, header.namesOff + nameOff, nameLen);
235
+ if (nameOff + nameLen > header.namesLen) throw new SkpkError(`skpk: entry ${i} name overruns names`);
236
+ const nameBytes = blob.subarray(header.namesOff + nameOff, header.namesOff + nameOff + nameLen);
237
+ let name: string;
238
+ try {
239
+ name = decoder.decode(nameBytes);
240
+ } catch {
241
+ throw new SkpkError(`skpk: entry ${i} name is not UTF-8`);
242
+ }
243
+ const off = Number(dv.getBigUint64(t + 8, true));
244
+ const len = Number(dv.getBigUint64(t + 16, true));
245
+ within(`entry ${i} (${name}) data`, header.dataOff + off, len);
246
+ entries.push({
247
+ name,
248
+ kind: dv.getUint16(t + 24, true),
249
+ alignLog2: blob[t + 26]!,
250
+ start: header.dataOff + off,
251
+ len,
252
+ crc32: dv.getUint32(t + 28, true),
253
+ });
254
+ }
255
+ const encoded = entries.map((e) => utf8.encode(e.name));
256
+ for (let i = 1; i < entries.length; i++) {
257
+ const a = entries[i - 1]!;
258
+ const b = entries[i]!;
259
+ const order = a.kind - b.kind || compareBytes(encoded[i - 1]!, encoded[i]!);
260
+ if (order >= 0) throw new SkpkError(`skpk: the toc is not sorted at entry ${i} (${b.name})`);
261
+ }
262
+ return {
263
+ header,
264
+ entries,
265
+ bytes: (e) => blob.subarray(e.start, e.start + e.len),
266
+ find: (kind, name) => entries.find((e) => e.kind === kind && e.name === name),
267
+ };
268
+ }