@skathi-native/cli 0.1.0-beta.3 → 0.1.0-beta.4

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/effects.ts ADDED
@@ -0,0 +1,162 @@
1
+ // An app's own `--shading` effects in the sk commands: its shaders/*.slang compiled for every renderer
2
+ // (HLSL, WGSL, MSL), so a build made on one OS runs on all three. `sk build` puts them into the payload
3
+ // as `sk/effects/*` entries; `sk dev` writes them to dist/.sk-dev/effects and points the dev host there.
4
+
5
+ import { watch, writeFileSync, type FSWatcher } from "node:fs";
6
+ import { join } from "node:path";
7
+ import {
8
+ appShadersDir,
9
+ compileAppEffects,
10
+ EffectsError,
11
+ formatProblems,
12
+ hasAppEffects,
13
+ writeEffectFiles,
14
+ type AppEffects,
15
+ } from "../effects/compile";
16
+ import { resolveCompiler, type ShaderCompiler } from "../effects/redslangc";
17
+ import { ConfigError } from "./config";
18
+ import { KIND, NAMES, type SkpkInput } from "./skpk";
19
+ import type { Progress } from "./term";
20
+
21
+ export interface BuiltEffects {
22
+ effects: AppEffects;
23
+ compiler: ShaderCompiler;
24
+ /// The SKPK entries: effects.json and one file per effect and target.
25
+ inputs: SkpkInput[];
26
+ }
27
+
28
+ const enc = new TextEncoder();
29
+
30
+ const effectInputs = (effects: AppEffects): SkpkInput[] =>
31
+ effects.files.map((f) => ({ name: `${NAMES.EFFECTS_DIR}${f.name}`, kind: KIND.EFFECT, data: enc.encode(f.text) }));
32
+
33
+ export function effectsFailure(e: EffectsError): ConfigError {
34
+ const errors = e.problems.filter((p) => p.severity === "error");
35
+ return new ConfigError(
36
+ `the app's effect shaders do not compile (${errors.length} error${errors.length === 1 ? "" : "s"}):\n` +
37
+ formatProblems(e.problems),
38
+ );
39
+ }
40
+
41
+ /// Compiles the app's shaders into `out` and the payload entries; null for an app without any.
42
+ export async function buildAppEffects(options: {
43
+ appRoot: string;
44
+ out: string;
45
+ compiler?: string | undefined;
46
+ progress: Progress;
47
+ }): Promise<BuiltEffects | null> {
48
+ const { appRoot, out, progress } = options;
49
+ if (!hasAppEffects(appRoot)) return null;
50
+ progress.step("effects");
51
+ const compiler = await resolveCompiler({
52
+ named: options.compiler,
53
+ log: (line) => progress.info(line),
54
+ onBytes: (done, total) => progress.bytes(done, total),
55
+ });
56
+ let effects: AppEffects;
57
+ try {
58
+ effects = await compileAppEffects(appRoot, compiler.path);
59
+ } catch (e) {
60
+ throw e instanceof EffectsError ? effectsFailure(e) : e;
61
+ }
62
+ for (const line of formatProblems(effects.warnings).split("\n").filter(Boolean)) progress.warn(line);
63
+ writeEffectFiles(out, effects.files);
64
+ progress.detail(`${effects.compiled.map((c) => c.effect.name).join(", ")} · hlsl, wgsl, metal`);
65
+ return { effects, compiler, inputs: effectInputs(effects) };
66
+ }
67
+
68
+ export interface EffectsWatch {
69
+ close(): void;
70
+ }
71
+
72
+ /// Recompiles into `out` when a `.slang` under shaders/ changes, debounced. A failed compile keeps the
73
+ /// last good files and reports through `onError`.
74
+ export function watchAppEffects(options: {
75
+ appRoot: string;
76
+ out: string;
77
+ compiler: string;
78
+ onBuilt: (effects: AppEffects) => void;
79
+ onError: (message: string) => void;
80
+ debounceMs?: number;
81
+ }): EffectsWatch {
82
+ const dir = appShadersDir(options.appRoot);
83
+ let timer: ReturnType<typeof setTimeout> | null = null;
84
+ let running = false;
85
+ let again = false;
86
+ const rebuild = async () => {
87
+ if (running) {
88
+ again = true;
89
+ return;
90
+ }
91
+ running = true;
92
+ try {
93
+ const effects = await compileAppEffects(options.appRoot, options.compiler);
94
+ writeEffectFiles(options.out, effects.files);
95
+ options.onBuilt(effects);
96
+ } catch (e) {
97
+ options.onError(
98
+ e instanceof EffectsError ? formatProblems(e.problems) : e instanceof Error ? e.message : String(e),
99
+ );
100
+ } finally {
101
+ running = false;
102
+ if (again) {
103
+ again = false;
104
+ void rebuild();
105
+ }
106
+ }
107
+ };
108
+ let watcher: FSWatcher | null = null;
109
+ try {
110
+ watcher = watch(dir, { recursive: true }, (_event, file) => {
111
+ if (file && !String(file).endsWith(".slang")) return;
112
+ if (timer) clearTimeout(timer);
113
+ timer = setTimeout(() => {
114
+ timer = null;
115
+ void rebuild();
116
+ }, options.debounceMs ?? 120);
117
+ });
118
+ } catch (e) {
119
+ options.onError(`cannot watch ${dir}: ${e instanceof Error ? e.message : String(e)}`);
120
+ }
121
+ return {
122
+ close() {
123
+ if (timer) clearTimeout(timer);
124
+ watcher?.close();
125
+ },
126
+ };
127
+ }
128
+
129
+ /// The dev host polls this beside the HMR changes.json: `{"dir": "<compiled effects>"}`.
130
+ export const EFFECTS_CHANGED = "effects-changed.json";
131
+
132
+ /// `sk dev`'s shader watch. A good rebuild goes to a host that reloads effects in place as the
133
+ /// [`EFFECTS_CHANGED`] message, written after the files; a host older than that is restarted.
134
+ export function devEffectsWatch(options: {
135
+ appRoot: string;
136
+ dist: string;
137
+ out: string;
138
+ compiler: string;
139
+ inPlace: boolean;
140
+ restart: () => void;
141
+ log: (line: string) => void;
142
+ onError: (message: string) => void;
143
+ debounceMs?: number;
144
+ }): EffectsWatch {
145
+ return watchAppEffects({
146
+ appRoot: options.appRoot,
147
+ out: options.out,
148
+ compiler: options.compiler,
149
+ ...(options.debounceMs === undefined ? {} : { debounceMs: options.debounceMs }),
150
+ onBuilt: (effects) => {
151
+ const names = effects.compiled.map((e) => e.effect.name).join(", ");
152
+ if (options.inPlace) {
153
+ writeFileSync(join(options.dist, EFFECTS_CHANGED), `${JSON.stringify({ dir: options.out })}\n`);
154
+ options.log(`effects rebuilt (${names}) — reloaded in the running app`);
155
+ } else {
156
+ options.log(`effects rebuilt (${names}) — restarting the app`);
157
+ options.restart();
158
+ }
159
+ },
160
+ onError: options.onError,
161
+ });
162
+ }
package/cli/elf.ts CHANGED
@@ -104,9 +104,10 @@ export function stampElf(options: ElfStampOptions): ElfStampResult {
104
104
  const t0 = performance.now();
105
105
  const host = new Uint8Array(readFileSync(options.host));
106
106
  const machine = elfMachine(host);
107
- if (!machine) throw new Error(`${options.host} is not a 64-bit ELF executable — a Linux build needs a Linux sk-app`);
107
+ if (!machine)
108
+ throw new Error(`${options.host} is not a 64-bit ELF executable — a Linux build needs a Linux workload (sk-app)`);
108
109
  if (appendedPayload(host, host.length)) {
109
- throw new Error(`${options.host} is a packaged app, not a bare host (it already carries a payload)`);
110
+ throw new Error(`${options.host} is a packaged app, not a bare workload (it already carries a payload)`);
110
111
  }
111
112
  const offset = Math.ceil(host.length / PAGE) * PAGE;
112
113
  const unskewed = options.payload(0);
package/cli/help.ts CHANGED
@@ -1,159 +1,68 @@
1
- import { CLI_VERSION } from "./host";
1
+ // `sk --help` and `sk <command> --help`, laid out from the commander declarations in sk.ts: usage,
2
+ // what the command does, its subcommands, and its options under their group headings.
3
+
4
+ import type { Argument, CommandUnknownOpts, Help } from "@commander-js/extra-typings";
2
5
  import { paint, type Paint } from "./term";
3
6
 
4
- type Row = [string, string];
5
- type Section = { title: string; rows: Row[] };
7
+ export type Row = [string, string];
6
8
 
7
- const COMMANDS: Row[] = [
8
- ["create [dir]", "Start a new app"],
9
- ["dev [app]", "Run the app with hot reload"],
10
- ["build [app]", "Debug build: devtools on, not minified"],
11
- ["publish [app]", "Release build to ship"],
12
- ["run [app]", "Build, then start the app"],
13
- ["check [app]", "What breaks under AOT, and how well the code is typed"],
14
- ["explain <code>", "What a check code means and how to fix it"],
15
- ["host <command>", "Manage the prebuilt engine hosts"],
16
- ];
9
+ export function table(p: Paint, rows: Row[]): string[] {
10
+ const width = Math.max(...rows.map(([term]) => term.length));
11
+ return rows.map(([term, text]) => ` ${p.cyan(term.padEnd(width))} ${text}`);
12
+ }
17
13
 
18
- const BUILD: Section[] = [
19
- {
20
- title: "Options",
21
- rows: [
22
- ["--platform <os>", "windows, macos or linux (default: this OS)"],
23
- ["--out <dir>", "Output directory (default: <app>/dist/debug or dist/release)"],
24
- ["--define K=V", "A Vite-style define; repeatable"],
25
- ["--config <path>", "An sk.config.json outside the app"],
26
- ["--sign <identity>", "macOS: codesign identity (- for ad hoc)"],
27
- ["--no-sign", "macOS: leave the bundle unsigned"],
28
- ["--console", "Windows: keep the console window"],
29
- ["--aot", "Windows x64: compile the app to a native image (--no-aot: don't)"],
30
- ["--json", "Print the result as JSON"],
31
- ],
32
- },
33
- {
34
- title: "Advanced",
35
- rows: [
36
- ["--host <exe>", "Stamp this host instead of the cached one"],
37
- ["--payload-only", "Write dist/.sk/app.skpk and stop"],
38
- ["--aot-inputs", "Keep the typed sources for a later AOT compile"],
39
- ["--aot-compiler <exe>", "Compile native images with this sk-aot.exe (or SK_AOT_COMPILER)"],
40
- ],
41
- },
42
- ];
14
+ export const section = (p: Paint, title: string, rows: Row[]): string[] =>
15
+ rows.length ? ["", p.bold(title), ...table(p, rows)] : [];
43
16
 
44
- const HELP: Record<string, { usage: string; about: string; sections: Section[] }> = {
45
- create: {
46
- usage: "sk create [dir] [options]",
47
- about: "Start a new app. In a terminal it asks for whatever the options leave open.",
48
- sections: [
49
- {
50
- title: "Options",
51
- rows: [
52
- ["--name <name>", "The app's name (default: the directory's)"],
53
- ["--template <name>", "showcase (every feature) or minimal"],
54
- ["--os <list>", "What to package for: windows, macos, linux"],
55
- ["--devtools", "Keep devtools (F12) in published builds"],
56
- ["--pm <name>", "bun, npm, pnpm or yarn"],
57
- ["-y, --yes", "Ask nothing, take the defaults"],
58
- ],
59
- },
60
- ],
61
- },
62
- dev: {
63
- usage: "sk dev [app] [options]",
64
- about: "Run the app with hot reload: edits to .vue, .ts and .css apply without a restart.",
65
- sections: [{ title: "Options", rows: [["--exe <host>", "Run this dev host instead of the cached one"]] }],
66
- },
67
- build: {
68
- usage: "sk build [app] [options]",
69
- about: "A debug build in <app>/dist/debug: devtools (F12) on, the bundle not minified.",
70
- sections: BUILD,
71
- },
72
- publish: {
73
- usage: "sk publish [app] [options]",
74
- about:
75
- 'The release build in <app>/dist/release: minified, devtools only with "publishDevtools": true in sk.config.json.',
76
- sections: BUILD,
77
- },
78
- run: {
79
- usage: "sk run [app] [options] [-- app args]",
80
- about: "sk build, then start the app with its output in this terminal.",
81
- sections: BUILD,
82
- },
83
- check: {
84
- usage: "sk check [app] [options]",
85
- about: "What in the bundle, app code and node_modules, breaks or slows down under AOT, and how well it is typed.",
86
- sections: [
87
- {
88
- title: "Options",
89
- rows: [
90
- ["--format json", "One JSON report on stdout (schema skathi.check)"],
91
- ["--deny-warnings", "Fail on warnings too"],
92
- ["--no-deps", "Only the app's own code"],
93
- ["--config <path>", "An sk.config.json outside the app"],
94
- ],
95
- },
96
- {
97
- title: "Exit codes",
98
- rows: [
99
- ["0", "Clean"],
100
- ["1", "Errors (or warnings with --deny-warnings)"],
101
- ["2", "Bad usage or config, or the check failed"],
102
- ],
103
- },
104
- ],
105
- },
106
- explain: {
107
- usage: "sk explain <code> | --list",
108
- about: "What a check code means, an example, and how to fix it.",
109
- sections: [{ title: "Options", rows: [["--list", "Every code"]] }],
110
- },
111
- host: {
112
- usage: "sk host <command>",
113
- about: "The engine host is the prebuilt executable an app is packed into. sk build fetches it on demand.",
114
- sections: [
115
- {
116
- title: "Commands",
117
- rows: [
118
- ["fetch", "Download this version's hosts into the local cache"],
119
- ["path", "Which host sk build would use"],
120
- ["info [exe]", "What a host says about itself"],
121
- ["add <exe>", "Verify a host and add it to the cache"],
122
- ["build", "In a Skathi checkout: build the hosts with cargo"],
123
- ],
124
- },
125
- ],
126
- },
17
+ const argTerm = (a: Argument) => {
18
+ const name = `${a.name()}${a.variadic ? "..." : ""}`;
19
+ return a.required ? `<${name}>` : `[${name}]`;
127
20
  };
128
21
 
129
- function rows(p: Paint, list: Row[]): string[] {
130
- const width = Math.max(...list.map(([name]) => name.length));
131
- return list.map(([name, text]) => ` ${p.cyan(name.padEnd(width))} ${text}`);
132
- }
133
-
134
- function sections(p: Paint, list: Section[]): string[] {
135
- return list.flatMap((s) => ["", p.bold(s.title), ...rows(p, s.rows)]);
22
+ function path(cmd: CommandUnknownOpts): string {
23
+ const names: string[] = [];
24
+ for (let c: CommandUnknownOpts | null = cmd; c; c = c.parent) names.unshift(c.name());
25
+ return names.join(" ");
136
26
  }
137
27
 
138
- const head = (p: Paint) => `${p.bold("sk")} ${p.dim(CLI_VERSION)} Skathi apps for Windows, macOS and Linux`;
139
-
140
- export function topHelp(color: boolean): string {
141
- const p = paint(color);
142
- return [
143
- head(p),
144
- "",
145
- `${p.bold("Usage")} sk <command> [app] [options]`,
146
- "",
147
- p.bold("Commands"),
148
- ...rows(p, COMMANDS),
149
- "",
150
- p.dim("Run sk <command> --help for its options. [app] is a directory (default: .)."),
151
- ].join("\n");
152
- }
28
+ const visible = (helper: Help, cmd: CommandUnknownOpts) =>
29
+ helper.visibleCommands(cmd).filter((c) => c.name() !== "help");
153
30
 
154
- export function commandHelp(command: string, color: boolean): string | null {
155
- const help = HELP[command];
156
- if (!help) return null;
31
+ export function helpFormat(color: boolean): Partial<Help> {
157
32
  const p = paint(color);
158
- return [`${p.bold("Usage")} ${help.usage}`, "", help.about, ...sections(p, help.sections)].join("\n");
33
+ return {
34
+ formatHelp(cmd, helper) {
35
+ const commands = visible(helper, cmd);
36
+ const options = helper.visibleOptions(cmd);
37
+ const usage = [
38
+ path(cmd),
39
+ ...cmd.registeredArguments.map(argTerm),
40
+ ...(commands.length ? ["<command>"] : []),
41
+ ...(options.length ? ["[options]"] : []),
42
+ ].join(" ");
43
+ const lines: string[] = [];
44
+ if (!cmd.parent) lines.push(`${p.bold(cmd.name())} ${p.dim(cmd.version() ?? "")} ${cmd.description()}`, "");
45
+ lines.push(`${p.bold("Usage")} ${usage}`);
46
+ if (cmd.parent && cmd.description()) lines.push("", cmd.description());
47
+ lines.push(
48
+ ...section(
49
+ p,
50
+ "Commands",
51
+ commands.map((c) => [
52
+ [c.name(), ...c.registeredArguments.map(argTerm), ...(visible(helper, c).length ? ["<command>"] : [])].join(
53
+ " ",
54
+ ),
55
+ c.summary() || c.description(),
56
+ ]),
57
+ ),
58
+ );
59
+ const groups = new Map<string, Row[]>();
60
+ for (const o of options) {
61
+ const title = (o.helpGroupHeading ?? "Options").replace(/:$/, "");
62
+ groups.set(title, [...(groups.get(title) ?? []), [o.flags, o.description]]);
63
+ }
64
+ for (const [title, rows] of groups) lines.push(...section(p, title, rows));
65
+ return `${lines.join("\n")}\n`;
66
+ },
67
+ };
159
68
  }
package/cli/host-fetch.ts CHANGED
@@ -77,6 +77,7 @@ export interface FetchOptions {
77
77
  platform?: Platform;
78
78
  arch?: string;
79
79
  log?: (line: string) => void;
80
+ onBytes?: OnBytes | undefined;
80
81
  }
81
82
 
82
83
  function source() {
@@ -88,10 +89,31 @@ function source() {
88
89
  return { repo, api, headers };
89
90
  }
90
91
 
91
- async function download(asset: ReleaseAsset, headers: Record<string, string>): Promise<Uint8Array<ArrayBuffer>> {
92
+ export type OnBytes = (done: number, total: number) => void;
93
+
94
+ async function download(
95
+ asset: ReleaseAsset,
96
+ headers: Record<string, string>,
97
+ onBytes?: OnBytes,
98
+ ): Promise<Uint8Array<ArrayBuffer>> {
92
99
  const res = await fetch(asset.url, { headers: { ...headers, Accept: "application/octet-stream" } });
93
100
  if (!res.ok) throw new HostError(`downloading ${asset.name}: HTTP ${res.status}`);
94
- return new Uint8Array(await res.arrayBuffer());
101
+ if (!onBytes || !res.body) return new Uint8Array(await res.arrayBuffer());
102
+ const total = Number(res.headers.get("content-length")) || asset.size;
103
+ const chunks: Uint8Array[] = [];
104
+ let done = 0;
105
+ for await (const chunk of res.body) {
106
+ chunks.push(chunk);
107
+ done += chunk.length;
108
+ onBytes(done, total);
109
+ }
110
+ const bytes = new Uint8Array(done);
111
+ let at = 0;
112
+ for (const chunk of chunks) {
113
+ bytes.set(chunk, at);
114
+ at += chunk.length;
115
+ }
116
+ return bytes;
95
117
  }
96
118
 
97
119
  interface Release {
@@ -132,11 +154,12 @@ async function cacheAsset(
132
154
  digest: string,
133
155
  dest: string,
134
156
  log: (line: string) => void,
157
+ onBytes?: OnBytes,
135
158
  ): Promise<void> {
136
159
  const asset = release.asset(name);
137
160
  if (!asset) throw new HostError(`release ${release.tag} lists ${name} in ${MANIFEST_NAME} but does not carry it`);
138
161
  log(`downloading ${name} (${(asset.size / 1048576).toFixed(1)} MB) from github.com/${release.repo} ${release.tag}`);
139
- const bytes = Bun.gunzipSync(await download(asset, release.headers));
162
+ const bytes = Bun.gunzipSync(await download(asset, release.headers, onBytes));
140
163
  if (bytes.length !== size || sha256(bytes) !== digest) {
141
164
  throw new HostError(`${name} does not match the sha256 in ${MANIFEST_NAME}; nothing was cached`);
142
165
  }
@@ -148,7 +171,7 @@ async function cacheAsset(
148
171
  renameSync(tmp, dest);
149
172
  }
150
173
 
151
- /** Downloads the host for `variant` from the release of `version` into the local cache, checked against `hosts.json`. */
174
+ /** Downloads the workload for `variant` from the release of `version` into the local cache, checked against `hosts.json`. */
152
175
  export async function fetchHost(options: FetchOptions): Promise<{ path: string; info: HostInfo }> {
153
176
  const version = options.version ?? CLI_VERSION;
154
177
  const platform = options.platform ?? currentPlatform();
@@ -163,14 +186,14 @@ export async function fetchHost(options: FetchOptions): Promise<{ path: string;
163
186
  .map((h) => h.variant)
164
187
  .join(", ");
165
188
  throw new HostError(
166
- `release ${tag} has no ${options.variant} host for ${platform}-${arch}` +
167
- (offered ? ` (it has: ${offered}); other variants are built from a checkout with sk host build` : ""),
189
+ `release ${tag} has no ${options.variant} workload for ${platform}-${arch}` +
190
+ (offered ? ` (it has: ${offered}); other variants are built from a checkout with sk workload build` : ""),
168
191
  );
169
192
  }
170
193
  const dest = cachedHost(version, options.variant, platform);
171
- await cacheAsset(release, entry.file, entry.size, entry.sha256, dest, log);
194
+ await cacheAsset(release, entry.file, entry.size, entry.sha256, dest, log, options.onBytes);
172
195
  writeFileSync(join(dirname(dest), "host.json"), JSON.stringify(entry.info, null, 2) + "\n");
173
- log(`cached ${options.variant} host ${version} → ${dest}`);
196
+ log(`cached ${options.variant} workload ${version} → ${dest}`);
174
197
  return { path: dest, info: entry.info };
175
198
  }
176
199
 
@@ -190,7 +213,7 @@ export async function fetchAotCompiler(
190
213
  const entry = release.manifest.aot?.find((c) => c.platform === platform && c.arch === arch);
191
214
  if (!entry) throw new HostError(`release ${release.tag} has no sk-aot for ${platform}-${arch}`);
192
215
  const dest = cachedAotCompiler(version, platform);
193
- await cacheAsset(release, entry.file, entry.size, entry.sha256, dest, log);
216
+ await cacheAsset(release, entry.file, entry.size, entry.sha256, dest, log, options.onBytes);
194
217
  writeFileSync(join(dirname(dest), "compiler.json"), JSON.stringify(entry.info, null, 2) + "\n");
195
218
  log(`cached sk-aot ${version} → ${dest}`);
196
219
  return { path: dest, info: entry.info };
@@ -208,7 +231,7 @@ export async function resolveOrFetchHost(options: ResolveOptions): Promise<Resol
208
231
  const cross = (options.platform ?? currentPlatform()) !== currentPlatform();
209
232
  if (!(e instanceof HostError) || named || cross || process.env.SK_HOST_OFFLINE === "1") throw e;
210
233
  try {
211
- await fetchHost({ variant: options.variant, ...(options.log && { log: options.log }) });
234
+ await fetchHost({ variant: options.variant, onBytes: options.onBytes, ...(options.log && { log: options.log }) });
212
235
  } catch (f) {
213
236
  throw new HostError(`${e.message}\n(downloading it failed too: ${(f as Error).message})`);
214
237
  }