strutvane 0.0.0-stage → 0.2.0-next.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/CHANGELOG.md ADDED
@@ -0,0 +1,15 @@
1
+ # strutvane
2
+
3
+ ## 0.2.0-next.0
4
+
5
+ ### Minor Changes
6
+
7
+ - `npx strutvane`, the v2 npx guard. Inside a Strutvane project (the nearest folder whose
8
+ package.json lists `@strutvane/framework`) it runs exactly what `node strut <args>` runs: the
9
+ project's own `strut.js`, or without one the `strutvane` program of the project's installed
10
+ `@strutvane/framework`, with the same Node, no shell, and the exit code or signal passed back.
11
+ Outside a project it only prints: help and `--version` exit 0, `new`/`create`/`init` point to
12
+ `npm create strutvane`, anything else exits 2. It never installs or downloads anything, refuses a
13
+ `strut.js` without the framework in package.json, a project root that is a link, and a framework,
14
+ `strut.js` or bin whose real location is outside the project, and never looks above your home
15
+ folder. Zero dependencies; Node 24.3 or newer.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 The Strutvane Authors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,88 @@
1
- # Temporary Holding Version
1
+ # strutvane
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **`npx strutvane`**: run Strutvane project commands with npx.
4
+
5
+ **Package:** `strutvane` · **Part of:** [Strutvane](https://github.com/vishwajit-vm/strutvane) · **Docs:** https://vishwajit-vm.github.io/strutvane-docs/ · **License:** MIT
6
+
7
+ ## What it does
8
+
9
+ Inside a Strutvane app, these two commands do exactly the same thing:
10
+
11
+ ```text
12
+ node strut migrate
13
+ npx strutvane migrate
14
+ ```
15
+
16
+ `npx strutvane <command>` finds your project and runs its own `strut.js` with your arguments, using
17
+ the `@strutvane/framework` version your project has installed. It never runs a second copy of the
18
+ framework, so what you get always matches your `package.json`.
19
+
20
+ Outside a project there is nothing to run, so it tells you how to make one:
21
+
22
+ ```text
23
+ $ npx strutvane
24
+ No Strutvane project was found in /home/ana or the folders above it.
25
+
26
+ Create a new app:
27
+ npm create strutvane@latest my-app
28
+ ```
29
+
30
+ (While Strutvane is in pre-release, it says `@next` instead of `@latest`.)
31
+
32
+ ## Commands outside a project
33
+
34
+ | You type | What happens | Exit code |
35
+ |---|---|---|
36
+ | `npx strutvane`, `help`, `--help`, `-h` | Prints help and how to create a project | 0 |
37
+ | `npx strutvane --version`, `-v` | Prints this package's version | 0 |
38
+ | `npx strutvane new my-app` (or `create`, `init`) | Prints the `npm create strutvane` command to run | 2 |
39
+ | Anything else | Explains that the command needs a project | 2 |
40
+
41
+ Inside a project, **every** argument goes to the project, `--version` and `help` included, just like
42
+ `node strut`.
43
+
44
+ ## How it finds your project
45
+
46
+ From the folder you are in, it looks upwards for the nearest folder that has a `strut.js` or a
47
+ `package.json` listing `@strutvane/framework`. That folder is your project when its `package.json`
48
+ lists `@strutvane/framework`. The command then runs from the project folder, as `node strut` does.
49
+
50
+ In a project without a `strut.js`, it runs the `strutvane` program of the installed
51
+ `@strutvane/framework` instead (what `strut.js` itself runs for framework commands).
52
+
53
+ ## Safe by design
54
+
55
+ `strutvane` is a guard: it runs only your project's own code, and only after checking it.
56
+
57
+ - **Never installs or downloads anything.** It has no dependencies, and outside a project it only
58
+ prints.
59
+ - **Never looks too far up.** The search stops at your home folder, the temp folder and drive
60
+ roots, so a `strut.js` someone left in a shared folder above you is never run. On Linux and macOS
61
+ the project folder must also belong to you.
62
+ - **A `strut.js` alone is not enough.** If the nearest one sits in a folder whose `package.json`
63
+ does not list `@strutvane/framework`, nothing runs and you are told why.
64
+ - **Nothing outside the project runs.** It refuses a project folder that is a link (it shows you the
65
+ real folder to open instead), a `strut.js` that is a link, and a
66
+ `node_modules/@strutvane/framework` (or its program) whose real location is outside the project.
67
+ - **No shell.** Your arguments go to Node as a list, so `a&b`, `$(x)` or `%PATH%` arrive as plain
68
+ text on every platform, and `--import=...` is an argument for your command, never a Node option.
69
+ - **Exit codes and signals pass through.** Your command's exit code comes back unchanged. If it is
70
+ stopped by a signal, `strutvane` stops with the same signal (on Windows, with exit code 128 + n).
71
+ A `kill` sent to `strutvane` reaches your command; Ctrl+C at a terminal is not sent twice.
72
+
73
+ When it refuses, it exits with code 1 and says how to fix it.
74
+
75
+ ## Do not add it to your project
76
+
77
+ Use it through `npx` only. A Strutvane app already has the `strutvane` program, from
78
+ `@strutvane/framework`; adding this package as a dependency would put two owners on the same
79
+ command, and `node strut doctor` reports it.
80
+
81
+ ## Requirements
82
+
83
+ Node.js 24.3 or newer.
84
+
85
+ ## Contributing
86
+
87
+ npm only. `npm ci`, then `npm run ci` (lint, type check, tests with coverage, build). See the
88
+ [Strutvane hub](https://github.com/vishwajit-vm/strutvane) for the ecosystem rules.
package/dist/bin.mjs ADDED
@@ -0,0 +1,780 @@
1
+ #!/usr/bin/env node
2
+ import { lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
3
+ import { constants, homedir, tmpdir } from "node:os";
4
+ import { dirname, isAbsolute, join, posix, relative, resolve, win32 } from "node:path";
5
+ import { spawn } from "node:child_process";
6
+ import { fileURLToPath } from "node:url";
7
+ // src/boundary.ts
8
+ /**
9
+ * Which folders may ever be treated as a Strutvane project.
10
+ *
11
+ * Treating a folder as the project means running code from it (`strut.js`, or the framework in
12
+ * its `node_modules`). So, walking up from the working directory, the search stops (with no
13
+ * project) at a folder that:
14
+ * - is a file-system or drive root,
15
+ * - is the OS temp directory itself,
16
+ * - is above the user's home directory,
17
+ * because anyone able to write there (other users, an extracted archive) could otherwise plant a
18
+ * project that applies to every folder below it. On POSIX the project folder must also belong to
19
+ * the current user.
20
+ *
21
+ * These are the same rules as `@strutvane/framework`'s `console/project/boundary.ts`. This
22
+ * package has no dependencies (it must work before anything is installed), so the rules are
23
+ * mirrored here rather than imported. Keep the two in step.
24
+ *
25
+ * @module
26
+ */
27
+ /**
28
+ * The boundary facts of this process.
29
+ *
30
+ * @example
31
+ * isForbiddenProjectDir('/tmp', processBoundary()) // true
32
+ */
33
+ function processBoundary() {
34
+ return {
35
+ home: homedir(),
36
+ temp: tmpdir(),
37
+ uid: typeof process.getuid === "function" ? process.getuid() : void 0
38
+ };
39
+ }
40
+ /** Every spelling of a path worth comparing: as given, and with links resolved. */
41
+ function spellings(path) {
42
+ const out = [resolve(path)];
43
+ try {
44
+ out.push(realpathSync.native(path));
45
+ } catch {}
46
+ return out;
47
+ }
48
+ /** Path equality; case-insensitive on Windows and macOS, whose file systems usually are. */
49
+ function samePath(a, b) {
50
+ const fold = process.platform === "win32" || process.platform === "darwin";
51
+ const norm = (p) => fold ? resolve(p).toLowerCase() : resolve(p);
52
+ return norm(a) === norm(b);
53
+ }
54
+ /**
55
+ * Whether `child` is `parent` itself or lies inside it. Both should already be real paths (links
56
+ * resolved), or a link inside `parent` could point anywhere.
57
+ *
58
+ * Why not `startsWith`: `/srv/app-evil` starts with `/srv/app`. `path.relative` compares whole
59
+ * segments, and on Windows it ignores case and reports another drive as an absolute path.
60
+ *
61
+ * @example
62
+ * isInside('/srv/app', '/srv/app/strut.js') // true
63
+ * isInside('/srv/app', '/srv/app-evil/strut.js') // false
64
+ */
65
+ function isInside(parent, child) {
66
+ const rel = relative(parent, child);
67
+ if (rel === "") return true;
68
+ if (isAbsolute(rel)) return false;
69
+ return rel.split(/[\\/]/)[0] !== "..";
70
+ }
71
+ /** Whether `ancestor` is a strict ancestor of `path`. */
72
+ function isStrictAncestor(ancestor, path) {
73
+ return !samePath(ancestor, path) && isInside(ancestor, path);
74
+ }
75
+ /**
76
+ * A file-system or drive root, the temp directory itself, or a folder above home: never a
77
+ * project, and the upward search stops there.
78
+ *
79
+ * @example
80
+ * isForbiddenProjectDir('C:\\', facts) // true
81
+ */
82
+ function isForbiddenProjectDir(dir, facts) {
83
+ for (const d of spellings(dir)) {
84
+ if (dirname(d) === d) return true;
85
+ for (const temp of spellings(facts.temp)) if (samePath(d, temp)) return true;
86
+ for (const home of spellings(facts.home)) if (isStrictAncestor(d, home)) return true;
87
+ }
88
+ return false;
89
+ }
90
+ /**
91
+ * POSIX only: whether `dir` belongs to the current user (always `true` without a uid, i.e. on
92
+ * Windows). A missing folder is not owned by anyone: `false`.
93
+ */
94
+ function isOwnedByCurrentUser(dir, facts) {
95
+ if (facts.uid === void 0) return true;
96
+ try {
97
+ return statSync(dir).uid === facts.uid;
98
+ } catch {
99
+ return false;
100
+ }
101
+ }
102
+ // src/child.ts
103
+ /**
104
+ * Running the project's script as a child process, and passing its result back.
105
+ *
106
+ * - **No shell, ever.** The program is the running Node (`process.execPath`) and the arguments go
107
+ * in an array, so `a&b`, `$(x)`, `; rm -rf ~` or `%PATH%` reach `strut.js` as plain text on
108
+ * every platform. Arguments come after the script path, so `--import=x.mjs` or `--require x`
109
+ * are the script's arguments, never Node options.
110
+ * - **Exit codes** come back unchanged. When the child is killed by a signal, the caller re-raises
111
+ * that signal on itself (see `bin.ts`), so a parent shell or CI sees what really happened;
112
+ * where that is not possible (Windows) the exit code is the shell convention 128 + signal.
113
+ * - **Signals** sent to this process are forwarded to the child, so `kill <pid>` or a supervisor
114
+ * stopping the guard stops the command too, and the guard never exits before the child: see
115
+ * {@link shouldForward} for which ones and why.
116
+ *
117
+ * @module
118
+ */
119
+ /** Signals the guard listens for while a child runs. */
120
+ const HANDLED_SIGNALS = Object.freeze([
121
+ "SIGINT",
122
+ "SIGTERM",
123
+ "SIGHUP",
124
+ "SIGBREAK"
125
+ ]);
126
+ /**
127
+ * Whether a signal received by the guard is passed on to the child.
128
+ *
129
+ * - **Windows: never.** A console Ctrl+C or Ctrl+Break already reaches every process attached to
130
+ * the console, the child included, and "sending" a signal to a Windows process terminates it
131
+ * outright, which would deny `strut.js` its own clean-up. The guard only keeps a listener so it
132
+ * is not the one to die first.
133
+ * - **Ctrl+C at a terminal (POSIX, `SIGINT` with stdin a TTY): not forwarded.** The terminal
134
+ * sends it to the whole foreground process group, so the child already has it; a second copy
135
+ * can turn "stop gracefully" into "force quit" in commands that count presses (a dev server).
136
+ * - **Everything else is forwarded** (`SIGTERM`, `SIGHUP`, and `SIGINT` without a terminal, e.g.
137
+ * from a supervisor or `kill -INT`), since only the guard received it.
138
+ *
139
+ * @example
140
+ * shouldForward('SIGTERM', 'linux', true) // true
141
+ * shouldForward('SIGINT', 'linux', true) // false
142
+ */
143
+ function shouldForward(signal, platform, stdinIsTTY) {
144
+ if (platform === "win32") return false;
145
+ if (signal === "SIGINT" && stdinIsTTY) return false;
146
+ return true;
147
+ }
148
+ /** The exit code that stands for death by `signal` (128 + its number; 1 when unknown). */
149
+ function signalExitCode(signal) {
150
+ const number = constants.signals[signal];
151
+ return typeof number === "number" ? 128 + number : 1;
152
+ }
153
+ /**
154
+ * Run `node <script> <args...>` with no shell, forward signals while it runs, and resolve with
155
+ * how it ended. Never rejects: a child that cannot start resolves as `{ kind: 'error' }`.
156
+ *
157
+ * @example
158
+ * await runChild({ execPath: process.execPath, script: '/srv/blog/strut.js', args: ['migrate'], ... })
159
+ * // { kind: 'exit', code: 0 }
160
+ */
161
+ const runChild = (request) => new Promise((resolvePromise) => {
162
+ const signals = request.signals ?? process;
163
+ let settled = false;
164
+ const child = spawn(request.execPath, [request.script, ...request.args], {
165
+ cwd: request.cwd,
166
+ env: request.env,
167
+ stdio: request.stdio ?? "inherit",
168
+ shell: false,
169
+ windowsHide: true
170
+ });
171
+ const onSignal = (signal) => {
172
+ if (child.exitCode !== null || child.signalCode !== null) return;
173
+ if (shouldForward(signal, request.platform, request.stdinIsTTY)) child.kill(signal);
174
+ };
175
+ for (const signal of HANDLED_SIGNALS) signals.on(signal, onSignal);
176
+ const finish = (outcome) => {
177
+ if (settled) return;
178
+ settled = true;
179
+ for (const signal of HANDLED_SIGNALS) signals.off(signal, onSignal);
180
+ resolvePromise(outcome);
181
+ };
182
+ child.once("error", (error) => finish({
183
+ kind: "error",
184
+ message: error.message
185
+ }));
186
+ child.once("exit", (code, signal) => {
187
+ if (signal !== null) finish({
188
+ kind: "signal",
189
+ signal
190
+ });
191
+ else finish({
192
+ kind: "exit",
193
+ code: code ?? 1
194
+ });
195
+ });
196
+ });
197
+ // src/messages.ts
198
+ const CONTROL = /[\u0000-\u001f\u007f-\u009f]/g;
199
+ /**
200
+ * Text from outside the guard (a path, an argument, a version from a file it does not control),
201
+ * made safe for a terminal: control characters (ANSI escapes, line breaks) removed and the length
202
+ * capped, so a crafted folder or argument can't rewrite the screen or fake a message.
203
+ *
204
+ * @example
205
+ * printable('a\u001b[2Jb') // 'a[2Jb'
206
+ */
207
+ function printable(text, max = 200) {
208
+ const clean = text.replace(CONTROL, "");
209
+ return clean.length > max ? `${clean.slice(0, max - 1)}…` : clean;
210
+ }
211
+ /**
212
+ * The dist-tag to name in `npm create strutvane@<tag>`: `next` while this package is a
213
+ * pre-release (before 1.0 the core train is published under `next`, decision #128), `latest`
214
+ * otherwise. The same rule as create-strutvane's `releaseTag()`.
215
+ *
216
+ * @example
217
+ * releaseTag('0.2.0-next.0') // 'next'
218
+ * releaseTag('1.0.0') // 'latest'
219
+ */
220
+ function releaseTag(version) {
221
+ return version.includes("-") ? "next" : "latest";
222
+ }
223
+ /** `npm create strutvane@<tag> <name>`, the one command that makes a project. */
224
+ function createCommand(version, name = "my-app") {
225
+ return `npm create strutvane@${releaseTag(version)} ${name}`;
226
+ }
227
+ /** A project name worth echoing back in a suggestion (otherwise the placeholder is shown). */
228
+ const SIMPLE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
229
+ /** Commands people type to make a new project. */
230
+ const CREATE_WORDS = /* @__PURE__ */ new Set([
231
+ "new",
232
+ "create",
233
+ "init"
234
+ ]);
235
+ /** `strutvane <version>`. */
236
+ function versionText(version) {
237
+ return `strutvane ${printable(version, 64)}`;
238
+ }
239
+ /** What `npx strutvane` does, and how to make a project. Printed for `help` outside a project. */
240
+ function helpText(version, start) {
241
+ return [
242
+ `${versionText(version)}: run Strutvane project commands with npx.`,
243
+ "",
244
+ `No Strutvane project was found in ${printable(start)} or the folders above it.`,
245
+ "",
246
+ "Create a new app:",
247
+ ` ${createCommand(version)}`,
248
+ "",
249
+ "Inside a project, `npx strutvane <command>` runs exactly what `node strut <command>` runs,",
250
+ "with the project's own @strutvane/framework (try `node strut list` there). A project is a",
251
+ "folder whose package.json lists @strutvane/framework.",
252
+ "",
253
+ "This command never installs or downloads anything."
254
+ ].join("\n");
255
+ }
256
+ /** A project command was typed outside a project. */
257
+ function noProjectText(version, command, start) {
258
+ return [
259
+ `strutvane: "${printable(command, 60)}" needs a Strutvane project, and none was found in ${printable(start)}`,
260
+ " or the folders above it (a project is a folder whose package.json lists",
261
+ " @strutvane/framework; the search never goes above your home folder).",
262
+ "",
263
+ ` Create one with: ${createCommand(version)}`,
264
+ " Then run commands inside it: node strut list"
265
+ ].join("\n");
266
+ }
267
+ /** `new`, `create` or `init` was typed: point to the installer instead of running anything. */
268
+ function createText(version, name) {
269
+ return [
270
+ "strutvane: new projects are made by the installer, which asks how you want the app set up:",
271
+ "",
272
+ ` ${createCommand(version, name !== void 0 && SIMPLE_NAME.test(name) ? name : "<name>")}`
273
+ ].join("\n");
274
+ }
275
+ /** A candidate project folder was found but is not trusted. */
276
+ function untrustedText(dir, reason) {
277
+ const where = printable(dir);
278
+ if (reason === "not-owned") return [`strutvane: ${where} looks like a Strutvane project, but it belongs to another user.`, " Refusing to run code from it. Run the command as the folder owner, or fix its ownership."].join("\n");
279
+ return [
280
+ `strutvane: ${where} has a strut.js, but its package.json does not list @strutvane/framework,`,
281
+ " so it is not a Strutvane project and its strut.js was not run.",
282
+ " If it is your project, add the framework (npm install @strutvane/framework) and try again;",
283
+ " otherwise run the command from your project folder."
284
+ ].join("\n");
285
+ }
286
+ /** Why a trusted project still can't be run, and the fix. */
287
+ function refusalText(reason, path, realPath) {
288
+ const where = printable(path);
289
+ switch (reason) {
290
+ case "root-unreadable": return `strutvane: the project folder ${where} can no longer be read. Check it exists and try again.`;
291
+ case "root-is-link": return [`strutvane: the project folder ${where} is a link${realPath === void 0 ? "" : ` to ${printable(realPath)}`}.`, " Refusing to run code through a link: open the real folder and run the command there."].join("\n");
292
+ case "strut-not-file": return [`strutvane: ${where} is a link or not a regular file, so it was not run.`, " Restore strut.js from git (or from a new project made with npm create strutvane)."].join("\n");
293
+ case "strut-outside-root": return `strutvane: ${where} really lives outside the project folder, so it was not run.`;
294
+ case "framework-missing": return [`strutvane: the project's dependencies are not installed (${where} is missing).`, " Run: npm install (or npm run setup in a project made by create-strutvane)"].join("\n");
295
+ case "framework-outside-root": return [`strutvane: ${where} points outside the project folder (a link or junction), so it was not run.`, " Install the framework into the project instead: npm install"].join("\n");
296
+ case "framework-invalid": return [`strutvane: ${where} is not a usable @strutvane/framework (wrong name, or no safe "strutvane" program).`, " Reinstall it: npm install"].join("\n");
297
+ }
298
+ }
299
+ /** The guard was started again by the project it started (a `strut.js` calling `npx strutvane`). */
300
+ function loopText() {
301
+ return ["strutvane: npx strutvane was started again from inside the command it ran, so it stopped", " instead of looping. Call `node strut` (not `npx strutvane`) from strut.js and project scripts."].join("\n");
302
+ }
303
+ /** Node is older than the minimum. */
304
+ function nodeTooOldText(found, minimum) {
305
+ return [`strutvane: Node.js ${printable(found, 32)} is too old; Strutvane needs Node.js ${minimum} or newer.`, " Install a current LTS from https://nodejs.org and try again."].join("\n");
306
+ }
307
+ /** The child could not be started at all. */
308
+ function startFailedText(script, message) {
309
+ return `strutvane: could not start ${printable(script)}: ${printable(message)}`;
310
+ }
311
+ // src/manifest.ts
312
+ /**
313
+ * Reading `package.json` files the guard does not control.
314
+ *
315
+ * Every manifest read here is untrusted input (it may be in a folder someone else wrote), so the
316
+ * reader is lenient (any problem means "no manifest") and bounded (a huge file is not read).
317
+ * Nothing in a manifest is ever executed; it only decides what is trusted.
318
+ *
319
+ * @module
320
+ */
321
+ /** The package that marks a Strutvane project, and whose `strutvane` program runs commands. */
322
+ const FRAMEWORK_PACKAGE = "@strutvane/framework";
323
+ /**
324
+ * Read a JSON object file. Returns `undefined` when it is missing, not a regular file, larger than
325
+ * {@link MAX_MANIFEST_BYTES}, not valid JSON, or not an object.
326
+ *
327
+ * @example
328
+ * readJsonObject('/srv/app/package.json')?.['name'] // 'my-app'
329
+ */
330
+ function readJsonObject(path) {
331
+ try {
332
+ const stats = statSync(path);
333
+ if (!stats.isFile() || stats.size > 1048576) return void 0;
334
+ const text = readFileSync(path, "utf8");
335
+ const parsed = JSON.parse(text.charCodeAt(0) === 65279 ? text.slice(1) : text);
336
+ return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : void 0;
337
+ } catch {
338
+ return;
339
+ }
340
+ }
341
+ /** `<dir>/package.json`, read with {@link readJsonObject}. */
342
+ function readManifest(dir) {
343
+ return readJsonObject(join(dir, "package.json"));
344
+ }
345
+ /**
346
+ * Whether a manifest lists `@strutvane/framework` in `dependencies` or `devDependencies` (as an
347
+ * own property with a string range). That is what makes a folder a Strutvane project.
348
+ *
349
+ * Why only those two fields: an optional or peer dependency is not installed for the app itself,
350
+ * and the framework's own project detection uses the same two.
351
+ *
352
+ * @example
353
+ * declaresFramework({ dependencies: { '@strutvane/framework': '^0.2.0-next.0' } }) // true
354
+ */
355
+ function declaresFramework(manifest) {
356
+ if (manifest === void 0) return false;
357
+ return ["dependencies", "devDependencies"].some((field) => {
358
+ const deps = manifest[field];
359
+ return typeof deps === "object" && deps !== null && !Array.isArray(deps) && Object.hasOwn(deps, "@strutvane/framework") && typeof deps["@strutvane/framework"] === "string";
360
+ });
361
+ }
362
+ // src/project.ts
363
+ /**
364
+ * Finding the Strutvane project for a working directory.
365
+ *
366
+ * From the working directory upwards, the **nearest** folder that holds a `strut.js` or whose
367
+ * package.json lists `@strutvane/framework` is the candidate, and the search ends there (an
368
+ * ancestor further up is never considered, so a project can't be hijacked from above). The
369
+ * candidate is trusted only when:
370
+ * - its package.json lists `@strutvane/framework` (a `strut.js` on its own is not enough: anyone
371
+ * can drop a file called `strut.js` into a folder);
372
+ * - it passes the boundary rules of `boundary.ts` (never a root, the temp directory or a folder
373
+ * above home; owned by the current user on POSIX).
374
+ *
375
+ * Only files are read here; nothing is run.
376
+ *
377
+ * @module
378
+ */
379
+ /** The file that `node strut` runs, in the project root. */
380
+ const STRUT_FILE = "strut.js";
381
+ /** Whether `path` exists in any form (a file, a folder, a link, even a broken link). */
382
+ function exists(path) {
383
+ try {
384
+ lstatSync(path);
385
+ return true;
386
+ } catch {
387
+ return false;
388
+ }
389
+ }
390
+ /**
391
+ * Find the project for `start` (see the module documentation for the rules).
392
+ *
393
+ * @example
394
+ * findProject('/home/ana/blog/app/models', facts) // { kind: 'project', root: '/home/ana/blog' }
395
+ */
396
+ function findProject(start, facts) {
397
+ const from = resolve(start);
398
+ let dir = from;
399
+ for (;;) {
400
+ if (isForbiddenProjectDir(dir, facts)) return {
401
+ kind: "none",
402
+ start: from
403
+ };
404
+ const declares = declaresFramework(readManifest(dir));
405
+ if (declares || exists(join(dir, "strut.js"))) {
406
+ if (!declares) return {
407
+ kind: "untrusted",
408
+ dir,
409
+ reason: "strut-without-framework"
410
+ };
411
+ if (!isOwnedByCurrentUser(dir, facts)) return {
412
+ kind: "untrusted",
413
+ dir,
414
+ reason: "not-owned"
415
+ };
416
+ return {
417
+ kind: "project",
418
+ root: dir
419
+ };
420
+ }
421
+ const parent = dirname(dir);
422
+ if (parent === dir) return {
423
+ kind: "none",
424
+ start: from
425
+ };
426
+ dir = parent;
427
+ }
428
+ }
429
+ // src/target.ts
430
+ /**
431
+ * What to run for a trusted project root, and the checks that keep it inside that root.
432
+ *
433
+ * `node strut <args>` runs the project's `strut.js`. So the guard runs that same file, with the
434
+ * same Node, when it is there. Without a `strut.js` (a project made by hand, or one whose
435
+ * `strut.js` was deleted) it runs what `strut.js` would run for a framework command: the
436
+ * `strutvane` program of the project's own installed `@strutvane/framework`. Never a second copy,
437
+ * and never anything fetched.
438
+ *
439
+ * Every path is checked on its **real** location (links resolved), and must stay inside the
440
+ * project root:
441
+ * - the root itself must not be a link (a link can make an innocent-looking folder run code from
442
+ * anywhere); the user is told the real folder to open instead;
443
+ * - `strut.js` must be a regular file, not a link;
444
+ * - `node_modules/@strutvane/framework` must really be inside the root (an `npm link` or a
445
+ * planted junction pointing elsewhere is refused), must be named `@strutvane/framework`, and its
446
+ * `bin` must be a plain relative `.js`/`.mjs`/`.cjs` path that stays inside the package.
447
+ *
448
+ * The file that runs is handed to Node by its real path, so what was checked is what runs.
449
+ *
450
+ * @module
451
+ */
452
+ /** The name of the framework's program in its package.json `bin`. */
453
+ const FRAMEWORK_BIN = "strutvane";
454
+ /** Scripts the guard may hand to Node. */
455
+ const SCRIPT_EXTENSION = /\.[cm]?js$/;
456
+ /**
457
+ * Whether a package.json `bin` value is a plain relative path to a script: not empty, no NUL, not
458
+ * absolute on any platform (`/x`, `C:\x`, `\\server\share\x`), not drive-relative (`C:x`), no `..`
459
+ * segment, and ending in `.js`, `.mjs` or `.cjs`.
460
+ *
461
+ * Why so strict: the value comes from a file inside `node_modules`, and becomes a path Node runs.
462
+ *
463
+ * @example
464
+ * isSafeBinPath('dist/console/bin.mjs') // true
465
+ * isSafeBinPath('..\\..\\evil.js') // false
466
+ */
467
+ function isSafeBinPath(bin) {
468
+ if (bin === "" || bin.length > 512 || bin.includes("\0")) return false;
469
+ if (posix.isAbsolute(bin) || win32.isAbsolute(bin) || /^[A-Za-z]:/.test(bin)) return false;
470
+ if (bin.split(/[\\/]/).includes("..")) return false;
471
+ return SCRIPT_EXTENSION.test(bin);
472
+ }
473
+ /** The `strutvane` entry of a manifest's `bin` (a string `bin` counts as the package's only one). */
474
+ function frameworkBin(manifest) {
475
+ const bin = manifest["bin"];
476
+ if (typeof bin === "string") return bin;
477
+ if (typeof bin !== "object" || bin === null || Array.isArray(bin)) return void 0;
478
+ if (!Object.hasOwn(bin, "strutvane")) return void 0;
479
+ const entry = bin[FRAMEWORK_BIN];
480
+ return typeof entry === "string" ? entry : void 0;
481
+ }
482
+ /** `lstat`, or `undefined` when the path does not exist (or cannot be read). */
483
+ function lstatOrUndefined(path) {
484
+ try {
485
+ return lstatSync(path);
486
+ } catch {
487
+ return;
488
+ }
489
+ }
490
+ /** The real path, or `undefined` when it cannot be resolved (missing, broken link, no access). */
491
+ function realOrUndefined(path) {
492
+ try {
493
+ return realpathSync.native(path);
494
+ } catch {
495
+ return;
496
+ }
497
+ }
498
+ /**
499
+ * Decide what to run for the trusted project root `root` (see the module documentation).
500
+ *
501
+ * @example
502
+ * resolveTarget('/srv/blog') // { kind: 'run', root: '/srv/blog', script: '/srv/blog/strut.js', via: 'strut.js' }
503
+ */
504
+ function resolveTarget(root) {
505
+ const rootStats = lstatOrUndefined(root);
506
+ const realRoot = realOrUndefined(root);
507
+ if (rootStats === void 0 || realRoot === void 0) return {
508
+ kind: "refused",
509
+ reason: "root-unreadable",
510
+ path: root
511
+ };
512
+ if (rootStats.isSymbolicLink()) return {
513
+ kind: "refused",
514
+ reason: "root-is-link",
515
+ path: root,
516
+ realPath: realRoot
517
+ };
518
+ const strut = join(root, STRUT_FILE);
519
+ const strutStats = lstatOrUndefined(strut);
520
+ if (strutStats !== void 0) {
521
+ if (strutStats.isSymbolicLink() || !strutStats.isFile()) return {
522
+ kind: "refused",
523
+ reason: "strut-not-file",
524
+ path: strut
525
+ };
526
+ const real = realOrUndefined(strut);
527
+ if (real === void 0 || !isInside(realRoot, real)) return {
528
+ kind: "refused",
529
+ reason: "strut-outside-root",
530
+ path: strut
531
+ };
532
+ return {
533
+ kind: "run",
534
+ root,
535
+ script: real,
536
+ via: "strut.js"
537
+ };
538
+ }
539
+ return frameworkTarget(root, realRoot);
540
+ }
541
+ /** The framework's own `strutvane` program, for a project without `strut.js`. */
542
+ function frameworkTarget(root, realRoot) {
543
+ const dir = join(root, "node_modules", ...FRAMEWORK_PACKAGE.split("/"));
544
+ if (lstatOrUndefined(dir) === void 0) return {
545
+ kind: "refused",
546
+ reason: "framework-missing",
547
+ path: dir
548
+ };
549
+ const realDir = realOrUndefined(dir);
550
+ if (realDir === void 0 || !isInside(realRoot, realDir)) return {
551
+ kind: "refused",
552
+ reason: "framework-outside-root",
553
+ path: dir
554
+ };
555
+ const manifest = readJsonObject(join(realDir, "package.json"));
556
+ const bin = manifest === void 0 ? void 0 : frameworkBin(manifest);
557
+ if (manifest?.["name"] !== "@strutvane/framework" || bin === void 0 || !isSafeBinPath(bin)) return {
558
+ kind: "refused",
559
+ reason: "framework-invalid",
560
+ path: dir
561
+ };
562
+ const real = realOrUndefined(resolve(realDir, bin));
563
+ if (real === void 0 || !isInside(realDir, real) || !isRegularFile(real)) return {
564
+ kind: "refused",
565
+ reason: "framework-invalid",
566
+ path: dir
567
+ };
568
+ return {
569
+ kind: "run",
570
+ root,
571
+ script: real,
572
+ via: "framework"
573
+ };
574
+ }
575
+ /** Whether `path` is a regular file (following links). */
576
+ function isRegularFile(path) {
577
+ try {
578
+ return statSync(path).isFile();
579
+ } catch {
580
+ return false;
581
+ }
582
+ }
583
+ // src/version.ts
584
+ /**
585
+ * This package's own version, and the Node.js versions it supports.
586
+ *
587
+ * @module
588
+ */
589
+ /** The oldest Node.js the guard (and the framework it starts) supports: package.json `engines`. */
590
+ const MIN_NODE = "24.3.0";
591
+ /**
592
+ * This package's version, read from its own package.json (one folder up from both `src/` and
593
+ * `dist/`), so it can never drift from what was published. `0.0.0` if it cannot be read.
594
+ *
595
+ * @example
596
+ * ownVersion() // '0.2.0-next.0'
597
+ */
598
+ function ownVersion(manifestUrl = new URL("../package.json", import.meta.url)) {
599
+ const version = readJsonObject(fileURLToPath(manifestUrl))?.["version"];
600
+ return typeof version === "string" ? version : "0.0.0";
601
+ }
602
+ /**
603
+ * Whether `version` (`process.versions.node`, e.g. `24.3.0`) is at least `minimum`. Anything that
604
+ * is not `major.minor.patch` counts as too old (fail closed).
605
+ *
606
+ * @example
607
+ * isNodeSupported('24.3.0', '24.3.0') // true
608
+ * isNodeSupported('22.12.0', '24.3.0') // false
609
+ */
610
+ function isNodeSupported(version, minimum = MIN_NODE) {
611
+ const parse = (v) => {
612
+ const match = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
613
+ return match === null ? void 0 : [
614
+ Number(match[1]),
615
+ Number(match[2]),
616
+ Number(match[3])
617
+ ];
618
+ };
619
+ const have = parse(version);
620
+ const need = parse(minimum);
621
+ if (have === void 0 || need === void 0) return false;
622
+ for (let i = 0; i < 3; i++) {
623
+ const a = have[i] ?? 0;
624
+ const b = need[i] ?? 0;
625
+ if (a !== b) return a > b;
626
+ }
627
+ return true;
628
+ }
629
+ // src/main.ts
630
+ /**
631
+ * `npx strutvane <args>`: the whole decision, with every process fact injected so it can be
632
+ * tested without touching the real process.
633
+ *
634
+ * 1. Node older than {@link MIN_NODE}: say so, exit 1.
635
+ * 2. Started again by the command it started (`STRUTVANE_NPX_DEPTH`): stop, exit 1, no loop.
636
+ * 3. Find the project (`project.ts`) and what to run in it (`target.ts`).
637
+ * - Found and trusted: run it with the user's arguments exactly as typed, and hand back its
638
+ * exit code or signal. Every argument goes to the project, `--version` and `help` included,
639
+ * because that is what `node strut` does.
640
+ * - Found but untrusted or refused: say why and how to fix it, exit 1. Nothing runs.
641
+ * - Not found: `help` / `--help` / no command prints help (exit 0), `--version` prints this
642
+ * package's version (exit 0), `new` / `create` / `init` prints the installer command, and
643
+ * anything else explains that it needs a project. Those last two exit 2: nothing was done.
644
+ *
645
+ * Nothing is ever installed or downloaded; outside a project the guard only prints.
646
+ *
647
+ * @module
648
+ */
649
+ /** Exit codes of the guard itself (the project's own codes pass through unchanged). */
650
+ const EXIT = Object.freeze({
651
+ OK: 0,
652
+ /** Refused to run (untrusted folder, link, missing or invalid framework, loop, old Node). */
653
+ FAILURE: 1,
654
+ /** Outside a project: the command needs one (or is `new`), so nothing was done. */
655
+ USAGE: 2
656
+ });
657
+ /** Counts how deep `npx strutvane` is nested inside itself (guards against loops). */
658
+ const DEPTH_ENV = "STRUTVANE_NPX_DEPTH";
659
+ /** Flags that ask for this package's version outside a project. */
660
+ const VERSION_FLAGS = /* @__PURE__ */ new Set([
661
+ "--version",
662
+ "-v",
663
+ "-V"
664
+ ]);
665
+ /** Words and flags that ask for help outside a project. */
666
+ const HELP_WORDS = /* @__PURE__ */ new Set([
667
+ "help",
668
+ "--help",
669
+ "-h"
670
+ ]);
671
+ /**
672
+ * The child's environment: the user's, plus the nesting depth and, on Windows,
673
+ * `NoDefaultCurrentDirectoryInExePath`, so a `.cmd` the project starts through cmd.exe can't pick
674
+ * up a program planted in the working directory before PATH.
675
+ */
676
+ function childEnvironment(env, platform, depth) {
677
+ return {
678
+ ...env,
679
+ ...platform === "win32" ? { NoDefaultCurrentDirectoryInExePath: "1" } : {},
680
+ [DEPTH_ENV]: String(depth + 1)
681
+ };
682
+ }
683
+ /** The nesting depth from the environment (anything unexpected counts as 0). */
684
+ function depthOf(env) {
685
+ const value = env[DEPTH_ENV];
686
+ return value !== void 0 && /^\d{1,3}$/.test(value) ? Number(value) : 0;
687
+ }
688
+ /**
689
+ * Run the guard for `argv` (the arguments after `strutvane`). Never throws for expected
690
+ * situations; returns how to end.
691
+ *
692
+ * @example
693
+ * await main(['migrate'], environment) // { exitCode: 0 } after `node strut migrate` succeeded
694
+ */
695
+ async function main(argv, env) {
696
+ if (!isNodeSupported(env.nodeVersion)) {
697
+ env.stderr(nodeTooOldText(env.nodeVersion, MIN_NODE));
698
+ return { exitCode: EXIT.FAILURE };
699
+ }
700
+ const depth = depthOf(env.env);
701
+ if (depth >= 1) {
702
+ env.stderr(loopText());
703
+ return { exitCode: EXIT.FAILURE };
704
+ }
705
+ const search = findProject(env.cwd, env.boundary ?? processBoundary());
706
+ if (search.kind === "untrusted") {
707
+ env.stderr(untrustedText(search.dir, search.reason));
708
+ return { exitCode: EXIT.FAILURE };
709
+ }
710
+ if (search.kind === "none") return outside(argv, search.start, env);
711
+ const target = resolveTarget(search.root);
712
+ if (target.kind === "refused") {
713
+ env.stderr(refusalText(target.reason, target.path, target.realPath));
714
+ return { exitCode: EXIT.FAILURE };
715
+ }
716
+ const outcome = await (env.run ?? runChild)({
717
+ execPath: env.execPath,
718
+ script: target.script,
719
+ args: argv,
720
+ cwd: target.root,
721
+ env: childEnvironment(env.env, env.platform, depth),
722
+ platform: env.platform,
723
+ stdinIsTTY: env.stdinIsTTY
724
+ });
725
+ switch (outcome.kind) {
726
+ case "exit": return { exitCode: outcome.code };
727
+ case "signal": return {
728
+ signal: outcome.signal,
729
+ exitCode: signalExitCode(outcome.signal)
730
+ };
731
+ case "error":
732
+ env.stderr(startFailedText(target.script, outcome.message));
733
+ return { exitCode: EXIT.FAILURE };
734
+ }
735
+ }
736
+ /** Outside a project: only print (help, version, the installer command, or why not). */
737
+ function outside(argv, start, env) {
738
+ const [first, second] = argv;
739
+ if (first === void 0 || HELP_WORDS.has(first)) {
740
+ env.stdout(helpText(env.version, start));
741
+ return { exitCode: EXIT.OK };
742
+ }
743
+ if (VERSION_FLAGS.has(first)) {
744
+ env.stdout(versionText(env.version));
745
+ return { exitCode: EXIT.OK };
746
+ }
747
+ if (CREATE_WORDS.has(first)) {
748
+ env.stderr(createText(env.version, second));
749
+ return { exitCode: EXIT.USAGE };
750
+ }
751
+ env.stderr(noProjectText(env.version, first, start));
752
+ return { exitCode: EXIT.USAGE };
753
+ }
754
+ // src/bin.ts
755
+ /**
756
+ * The `strutvane` executable (`npx strutvane <command>`). All decisions live in `main.ts`
757
+ * (tested); this file only connects them to the real process: arguments, output, the exit code,
758
+ * and re-raising a signal the child died of.
759
+ *
760
+ * It is the one file in this package allowed to print with `console` (package.json
761
+ * `strutvane.allowConsole`).
762
+ *
763
+ * @module
764
+ */
765
+ const outcome = await main(process.argv.slice(2), {
766
+ cwd: process.cwd(),
767
+ env: process.env,
768
+ execPath: process.execPath,
769
+ platform: process.platform,
770
+ nodeVersion: process.versions.node,
771
+ version: ownVersion(),
772
+ stdinIsTTY: process.stdin.isTTY === true,
773
+ stdout: (text) => console.log(text),
774
+ stderr: (text) => console.error(text)
775
+ });
776
+ process.exitCode = outcome.exitCode;
777
+ if ("signal" in outcome && process.platform !== "win32") process.kill(process.pid, outcome.signal);
778
+ export {};
779
+
780
+ //# sourceMappingURL=bin.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bin.mjs","names":[],"sources":["../src/boundary.ts","../src/child.ts","../src/messages.ts","../src/manifest.ts","../src/project.ts","../src/target.ts","../src/version.ts","../src/main.ts","../src/bin.ts"],"sourcesContent":["/**\n * Which folders may ever be treated as a Strutvane project.\n *\n * Treating a folder as the project means running code from it (`strut.js`, or the framework in\n * its `node_modules`). So, walking up from the working directory, the search stops (with no\n * project) at a folder that:\n * - is a file-system or drive root,\n * - is the OS temp directory itself,\n * - is above the user's home directory,\n * because anyone able to write there (other users, an extracted archive) could otherwise plant a\n * project that applies to every folder below it. On POSIX the project folder must also belong to\n * the current user.\n *\n * These are the same rules as `@strutvane/framework`'s `console/project/boundary.ts`. This\n * package has no dependencies (it must work before anything is installed), so the rules are\n * mirrored here rather than imported. Keep the two in step.\n *\n * @module\n */\nimport { realpathSync, statSync } from 'node:fs'\nimport { homedir, tmpdir } from 'node:os'\nimport { dirname, isAbsolute, relative, resolve } from 'node:path'\n\n/** Facts the rules depend on (injectable, so tests can place \"home\" and \"temp\" anywhere). */\nexport interface BoundaryFacts {\n /** The user's home directory. */\n readonly home: string\n /** The OS temp directory. */\n readonly temp: string\n /** The current uid on POSIX; `undefined` where ownership is not checked (Windows). */\n readonly uid: number | undefined\n}\n\n/**\n * The boundary facts of this process.\n *\n * @example\n * isForbiddenProjectDir('/tmp', processBoundary()) // true\n */\nexport function processBoundary(): BoundaryFacts {\n return {\n home: homedir(),\n temp: tmpdir(),\n uid: typeof process.getuid === 'function' ? process.getuid() : undefined,\n }\n}\n\n/** Every spelling of a path worth comparing: as given, and with links resolved. */\nfunction spellings(path: string): string[] {\n const out = [resolve(path)]\n try {\n out.push(realpathSync.native(path))\n } catch {\n // A path that does not exist has only its given spelling.\n }\n return out\n}\n\n/** Path equality; case-insensitive on Windows and macOS, whose file systems usually are. */\nfunction samePath(a: string, b: string): boolean {\n const fold = process.platform === 'win32' || process.platform === 'darwin'\n const norm = (p: string): string => (fold ? resolve(p).toLowerCase() : resolve(p))\n return norm(a) === norm(b)\n}\n\n/**\n * Whether `child` is `parent` itself or lies inside it. Both should already be real paths (links\n * resolved), or a link inside `parent` could point anywhere.\n *\n * Why not `startsWith`: `/srv/app-evil` starts with `/srv/app`. `path.relative` compares whole\n * segments, and on Windows it ignores case and reports another drive as an absolute path.\n *\n * @example\n * isInside('/srv/app', '/srv/app/strut.js') // true\n * isInside('/srv/app', '/srv/app-evil/strut.js') // false\n */\nexport function isInside(parent: string, child: string): boolean {\n const rel = relative(parent, child)\n if (rel === '') return true\n if (isAbsolute(rel)) return false\n const first = rel.split(/[\\\\/]/)[0]\n return first !== '..'\n}\n\n/** Whether `ancestor` is a strict ancestor of `path`. */\nfunction isStrictAncestor(ancestor: string, path: string): boolean {\n return !samePath(ancestor, path) && isInside(ancestor, path)\n}\n\n/**\n * A file-system or drive root, the temp directory itself, or a folder above home: never a\n * project, and the upward search stops there.\n *\n * @example\n * isForbiddenProjectDir('C:\\\\', facts) // true\n */\nexport function isForbiddenProjectDir(dir: string, facts: BoundaryFacts): boolean {\n for (const d of spellings(dir)) {\n if (dirname(d) === d) return true\n for (const temp of spellings(facts.temp)) if (samePath(d, temp)) return true\n for (const home of spellings(facts.home)) if (isStrictAncestor(d, home)) return true\n }\n return false\n}\n\n/**\n * POSIX only: whether `dir` belongs to the current user (always `true` without a uid, i.e. on\n * Windows). A missing folder is not owned by anyone: `false`.\n */\nexport function isOwnedByCurrentUser(dir: string, facts: BoundaryFacts): boolean {\n if (facts.uid === undefined) return true\n try {\n return statSync(dir).uid === facts.uid\n } catch {\n return false\n }\n}\n","/**\n * Running the project's script as a child process, and passing its result back.\n *\n * - **No shell, ever.** The program is the running Node (`process.execPath`) and the arguments go\n * in an array, so `a&b`, `$(x)`, `; rm -rf ~` or `%PATH%` reach `strut.js` as plain text on\n * every platform. Arguments come after the script path, so `--import=x.mjs` or `--require x`\n * are the script's arguments, never Node options.\n * - **Exit codes** come back unchanged. When the child is killed by a signal, the caller re-raises\n * that signal on itself (see `bin.ts`), so a parent shell or CI sees what really happened;\n * where that is not possible (Windows) the exit code is the shell convention 128 + signal.\n * - **Signals** sent to this process are forwarded to the child, so `kill <pid>` or a supervisor\n * stopping the guard stops the command too, and the guard never exits before the child: see\n * {@link shouldForward} for which ones and why.\n *\n * @module\n */\nimport { spawn } from 'node:child_process'\nimport { constants } from 'node:os'\n\n/** Signals the guard listens for while a child runs. */\nexport const HANDLED_SIGNALS: readonly NodeJS.Signals[] = Object.freeze([\n 'SIGINT',\n 'SIGTERM',\n 'SIGHUP',\n 'SIGBREAK',\n])\n\n/**\n * Whether a signal received by the guard is passed on to the child.\n *\n * - **Windows: never.** A console Ctrl+C or Ctrl+Break already reaches every process attached to\n * the console, the child included, and \"sending\" a signal to a Windows process terminates it\n * outright, which would deny `strut.js` its own clean-up. The guard only keeps a listener so it\n * is not the one to die first.\n * - **Ctrl+C at a terminal (POSIX, `SIGINT` with stdin a TTY): not forwarded.** The terminal\n * sends it to the whole foreground process group, so the child already has it; a second copy\n * can turn \"stop gracefully\" into \"force quit\" in commands that count presses (a dev server).\n * - **Everything else is forwarded** (`SIGTERM`, `SIGHUP`, and `SIGINT` without a terminal, e.g.\n * from a supervisor or `kill -INT`), since only the guard received it.\n *\n * @example\n * shouldForward('SIGTERM', 'linux', true) // true\n * shouldForward('SIGINT', 'linux', true) // false\n */\nexport function shouldForward(\n signal: NodeJS.Signals,\n platform: NodeJS.Platform,\n stdinIsTTY: boolean,\n): boolean {\n if (platform === 'win32') return false\n if (signal === 'SIGINT' && stdinIsTTY) return false\n return true\n}\n\n/** The exit code that stands for death by `signal` (128 + its number; 1 when unknown). */\nexport function signalExitCode(signal: NodeJS.Signals): number {\n const number = constants.signals[signal]\n return typeof number === 'number' ? 128 + number : 1\n}\n\n/** How a child process ended. */\nexport type ChildOutcome =\n | { readonly kind: 'exit'; readonly code: number }\n | { readonly kind: 'signal'; readonly signal: NodeJS.Signals }\n | { readonly kind: 'error'; readonly message: string }\n\n/** Where signals come from (the real `process`, or a test's event emitter). */\nexport interface SignalSource {\n on(event: NodeJS.Signals, listener: (signal: NodeJS.Signals) => void): unknown\n off(event: NodeJS.Signals, listener: (signal: NodeJS.Signals) => void): unknown\n}\n\n/** What {@link runChild} needs to start the child. */\nexport interface ChildRequest {\n /** The Node executable (normally `process.execPath`). */\n readonly execPath: string\n /** The script to run (a real path, checked by `target.ts`). */\n readonly script: string\n /** The user's arguments, passed through exactly. */\n readonly args: readonly string[]\n /** The child's working directory (the project root). */\n readonly cwd: string\n /** The child's environment. */\n readonly env: NodeJS.ProcessEnv\n /** The platform, for {@link shouldForward}. */\n readonly platform: NodeJS.Platform\n /** Whether stdin is a terminal, for {@link shouldForward}. */\n readonly stdinIsTTY: boolean\n /** Where signals arrive (default: `process`). */\n readonly signals?: SignalSource\n /** The child's stdio (default `inherit`: the child talks to the user's terminal directly). */\n readonly stdio?: 'inherit' | 'pipe' | 'ignore'\n}\n\n/** Starts the child and resolves with how it ended. Injectable so tests can stand in. */\nexport type ChildRunner = (request: ChildRequest) => Promise<ChildOutcome>\n\n/**\n * Run `node <script> <args...>` with no shell, forward signals while it runs, and resolve with\n * how it ended. Never rejects: a child that cannot start resolves as `{ kind: 'error' }`.\n *\n * @example\n * await runChild({ execPath: process.execPath, script: '/srv/blog/strut.js', args: ['migrate'], ... })\n * // { kind: 'exit', code: 0 }\n */\nexport const runChild: ChildRunner = (request) =>\n new Promise((resolvePromise) => {\n const signals = request.signals ?? process\n let settled = false\n const child = spawn(request.execPath, [request.script, ...request.args], {\n cwd: request.cwd,\n env: request.env,\n stdio: request.stdio ?? 'inherit',\n shell: false,\n windowsHide: true,\n })\n const onSignal = (signal: NodeJS.Signals): void => {\n if (child.exitCode !== null || child.signalCode !== null) return\n if (shouldForward(signal, request.platform, request.stdinIsTTY)) child.kill(signal)\n }\n for (const signal of HANDLED_SIGNALS) signals.on(signal, onSignal)\n const finish = (outcome: ChildOutcome): void => {\n if (settled) return\n settled = true\n for (const signal of HANDLED_SIGNALS) signals.off(signal, onSignal)\n resolvePromise(outcome)\n }\n child.once('error', (error) => finish({ kind: 'error', message: error.message }))\n child.once('exit', (code, signal) => {\n if (signal !== null) finish({ kind: 'signal', signal })\n else finish({ kind: 'exit', code: code ?? 1 })\n })\n })\n","/**\n * Everything the guard says. One place, so the wording stays consistent and every value from\n * outside (paths, arguments, versions) is made safe to print first.\n *\n * Messages say what happened and how to fix it (ecosystem standard), in plain words.\n *\n * @module\n */\nimport type { UntrustedReason } from './project.ts'\nimport type { RefusalReason } from './target.ts'\n\n// biome-ignore lint/suspicious/noControlCharactersInRegex: matching control characters is the point\nconst CONTROL = /[\\u0000-\\u001f\\u007f-\\u009f]/g\n\n/**\n * Text from outside the guard (a path, an argument, a version from a file it does not control),\n * made safe for a terminal: control characters (ANSI escapes, line breaks) removed and the length\n * capped, so a crafted folder or argument can't rewrite the screen or fake a message.\n *\n * @example\n * printable('a\\u001b[2Jb') // 'a[2Jb'\n */\nexport function printable(text: string, max = 200): string {\n const clean = text.replace(CONTROL, '')\n return clean.length > max ? `${clean.slice(0, max - 1)}…` : clean\n}\n\n/**\n * The dist-tag to name in `npm create strutvane@<tag>`: `next` while this package is a\n * pre-release (before 1.0 the core train is published under `next`, decision #128), `latest`\n * otherwise. The same rule as create-strutvane's `releaseTag()`.\n *\n * @example\n * releaseTag('0.2.0-next.0') // 'next'\n * releaseTag('1.0.0') // 'latest'\n */\nexport function releaseTag(version: string): 'next' | 'latest' {\n return version.includes('-') ? 'next' : 'latest'\n}\n\n/** `npm create strutvane@<tag> <name>`, the one command that makes a project. */\nexport function createCommand(version: string, name = 'my-app'): string {\n return `npm create strutvane@${releaseTag(version)} ${name}`\n}\n\n/** A project name worth echoing back in a suggestion (otherwise the placeholder is shown). */\nconst SIMPLE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/\n\n/** Commands people type to make a new project. */\nexport const CREATE_WORDS: ReadonlySet<string> = new Set(['new', 'create', 'init'])\n\n/** `strutvane <version>`. */\nexport function versionText(version: string): string {\n return `strutvane ${printable(version, 64)}`\n}\n\n/** What `npx strutvane` does, and how to make a project. Printed for `help` outside a project. */\nexport function helpText(version: string, start: string): string {\n return [\n `${versionText(version)}: run Strutvane project commands with npx.`,\n '',\n `No Strutvane project was found in ${printable(start)} or the folders above it.`,\n '',\n 'Create a new app:',\n ` ${createCommand(version)}`,\n '',\n 'Inside a project, `npx strutvane <command>` runs exactly what `node strut <command>` runs,',\n \"with the project's own @strutvane/framework (try `node strut list` there). A project is a\",\n 'folder whose package.json lists @strutvane/framework.',\n '',\n 'This command never installs or downloads anything.',\n ].join('\\n')\n}\n\n/** A project command was typed outside a project. */\nexport function noProjectText(version: string, command: string, start: string): string {\n const word = printable(command, 60)\n return [\n `strutvane: \"${word}\" needs a Strutvane project, and none was found in ${printable(start)}`,\n ' or the folders above it (a project is a folder whose package.json lists',\n ' @strutvane/framework; the search never goes above your home folder).',\n '',\n ` Create one with: ${createCommand(version)}`,\n ' Then run commands inside it: node strut list',\n ].join('\\n')\n}\n\n/** `new`, `create` or `init` was typed: point to the installer instead of running anything. */\nexport function createText(version: string, name: string | undefined): string {\n const shown = name !== undefined && SIMPLE_NAME.test(name) ? name : '<name>'\n return [\n 'strutvane: new projects are made by the installer, which asks how you want the app set up:',\n '',\n ` ${createCommand(version, shown)}`,\n ].join('\\n')\n}\n\n/** A candidate project folder was found but is not trusted. */\nexport function untrustedText(dir: string, reason: UntrustedReason): string {\n const where = printable(dir)\n if (reason === 'not-owned') {\n return [\n `strutvane: ${where} looks like a Strutvane project, but it belongs to another user.`,\n ' Refusing to run code from it. Run the command as the folder owner, or fix its ownership.',\n ].join('\\n')\n }\n return [\n `strutvane: ${where} has a strut.js, but its package.json does not list @strutvane/framework,`,\n ' so it is not a Strutvane project and its strut.js was not run.',\n ' If it is your project, add the framework (npm install @strutvane/framework) and try again;',\n ' otherwise run the command from your project folder.',\n ].join('\\n')\n}\n\n/** Why a trusted project still can't be run, and the fix. */\nexport function refusalText(reason: RefusalReason, path: string, realPath?: string): string {\n const where = printable(path)\n switch (reason) {\n case 'root-unreadable':\n return `strutvane: the project folder ${where} can no longer be read. Check it exists and try again.`\n case 'root-is-link':\n return [\n `strutvane: the project folder ${where} is a link${realPath === undefined ? '' : ` to ${printable(realPath)}`}.`,\n ' Refusing to run code through a link: open the real folder and run the command there.',\n ].join('\\n')\n case 'strut-not-file':\n return [\n `strutvane: ${where} is a link or not a regular file, so it was not run.`,\n ' Restore strut.js from git (or from a new project made with npm create strutvane).',\n ].join('\\n')\n case 'strut-outside-root':\n return `strutvane: ${where} really lives outside the project folder, so it was not run.`\n case 'framework-missing':\n return [\n `strutvane: the project's dependencies are not installed (${where} is missing).`,\n ' Run: npm install (or npm run setup in a project made by create-strutvane)',\n ].join('\\n')\n case 'framework-outside-root':\n return [\n `strutvane: ${where} points outside the project folder (a link or junction), so it was not run.`,\n ' Install the framework into the project instead: npm install',\n ].join('\\n')\n case 'framework-invalid':\n return [\n `strutvane: ${where} is not a usable @strutvane/framework (wrong name, or no safe \"strutvane\" program).`,\n ' Reinstall it: npm install',\n ].join('\\n')\n }\n}\n\n/** The guard was started again by the project it started (a `strut.js` calling `npx strutvane`). */\nexport function loopText(): string {\n return [\n 'strutvane: npx strutvane was started again from inside the command it ran, so it stopped',\n ' instead of looping. Call `node strut` (not `npx strutvane`) from strut.js and project scripts.',\n ].join('\\n')\n}\n\n/** Node is older than the minimum. */\nexport function nodeTooOldText(found: string, minimum: string): string {\n return [\n `strutvane: Node.js ${printable(found, 32)} is too old; Strutvane needs Node.js ${minimum} or newer.`,\n ' Install a current LTS from https://nodejs.org and try again.',\n ].join('\\n')\n}\n\n/** The child could not be started at all. */\nexport function startFailedText(script: string, message: string): string {\n return `strutvane: could not start ${printable(script)}: ${printable(message)}`\n}\n","/**\n * Reading `package.json` files the guard does not control.\n *\n * Every manifest read here is untrusted input (it may be in a folder someone else wrote), so the\n * reader is lenient (any problem means \"no manifest\") and bounded (a huge file is not read).\n * Nothing in a manifest is ever executed; it only decides what is trusted.\n *\n * @module\n */\nimport { readFileSync, statSync } from 'node:fs'\nimport { join } from 'node:path'\n\n/** The package that marks a Strutvane project, and whose `strutvane` program runs commands. */\nexport const FRAMEWORK_PACKAGE = '@strutvane/framework'\n\n/** Manifests larger than this are not read (1 MiB; real ones are a few KiB). */\nexport const MAX_MANIFEST_BYTES: number = 1024 * 1024\n\n/** A parsed JSON object. */\nexport type JsonObject = Readonly<Record<string, unknown>>\n\n/**\n * Read a JSON object file. Returns `undefined` when it is missing, not a regular file, larger than\n * {@link MAX_MANIFEST_BYTES}, not valid JSON, or not an object.\n *\n * @example\n * readJsonObject('/srv/app/package.json')?.['name'] // 'my-app'\n */\nexport function readJsonObject(path: string): JsonObject | undefined {\n try {\n const stats = statSync(path)\n if (!stats.isFile() || stats.size > MAX_MANIFEST_BYTES) return undefined\n const text = readFileSync(path, 'utf8')\n const parsed: unknown = JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text)\n return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)\n ? (parsed as JsonObject)\n : undefined\n } catch {\n return undefined\n }\n}\n\n/** `<dir>/package.json`, read with {@link readJsonObject}. */\nexport function readManifest(dir: string): JsonObject | undefined {\n return readJsonObject(join(dir, 'package.json'))\n}\n\n/**\n * Whether a manifest lists `@strutvane/framework` in `dependencies` or `devDependencies` (as an\n * own property with a string range). That is what makes a folder a Strutvane project.\n *\n * Why only those two fields: an optional or peer dependency is not installed for the app itself,\n * and the framework's own project detection uses the same two.\n *\n * @example\n * declaresFramework({ dependencies: { '@strutvane/framework': '^0.2.0-next.0' } }) // true\n */\nexport function declaresFramework(manifest: JsonObject | undefined): boolean {\n if (manifest === undefined) return false\n return ['dependencies', 'devDependencies'].some((field) => {\n const deps = manifest[field]\n return (\n typeof deps === 'object' &&\n deps !== null &&\n !Array.isArray(deps) &&\n Object.hasOwn(deps, FRAMEWORK_PACKAGE) &&\n typeof (deps as Record<string, unknown>)[FRAMEWORK_PACKAGE] === 'string'\n )\n })\n}\n","/**\n * Finding the Strutvane project for a working directory.\n *\n * From the working directory upwards, the **nearest** folder that holds a `strut.js` or whose\n * package.json lists `@strutvane/framework` is the candidate, and the search ends there (an\n * ancestor further up is never considered, so a project can't be hijacked from above). The\n * candidate is trusted only when:\n * - its package.json lists `@strutvane/framework` (a `strut.js` on its own is not enough: anyone\n * can drop a file called `strut.js` into a folder);\n * - it passes the boundary rules of `boundary.ts` (never a root, the temp directory or a folder\n * above home; owned by the current user on POSIX).\n *\n * Only files are read here; nothing is run.\n *\n * @module\n */\nimport { lstatSync } from 'node:fs'\nimport { dirname, join, resolve } from 'node:path'\nimport { type BoundaryFacts, isForbiddenProjectDir, isOwnedByCurrentUser } from './boundary.ts'\nimport { declaresFramework, readManifest } from './manifest.ts'\n\n/** The file that `node strut` runs, in the project root. */\nexport const STRUT_FILE = 'strut.js'\n\n/** Why a candidate folder was found but not trusted. */\nexport type UntrustedReason =\n /** It has a `strut.js` but its package.json does not list `@strutvane/framework`. */\n | 'strut-without-framework'\n /** POSIX: the folder belongs to another user. */\n | 'not-owned'\n\n/** The outcome of the search. */\nexport type ProjectSearch =\n /** A trusted project root (not yet checked for links; see `target.ts`). */\n | { readonly kind: 'project'; readonly root: string }\n /** A candidate was found and refused. */\n | { readonly kind: 'untrusted'; readonly dir: string; readonly reason: UntrustedReason }\n /** No candidate between `start` and the first boundary. */\n | { readonly kind: 'none'; readonly start: string }\n\n/** Whether `path` exists in any form (a file, a folder, a link, even a broken link). */\nfunction exists(path: string): boolean {\n try {\n lstatSync(path)\n return true\n } catch {\n return false\n }\n}\n\n/**\n * Find the project for `start` (see the module documentation for the rules).\n *\n * @example\n * findProject('/home/ana/blog/app/models', facts) // { kind: 'project', root: '/home/ana/blog' }\n */\nexport function findProject(start: string, facts: BoundaryFacts): ProjectSearch {\n const from = resolve(start)\n let dir = from\n for (;;) {\n if (isForbiddenProjectDir(dir, facts)) return { kind: 'none', start: from }\n const declares = declaresFramework(readManifest(dir))\n if (declares || exists(join(dir, STRUT_FILE))) {\n if (!declares) return { kind: 'untrusted', dir, reason: 'strut-without-framework' }\n if (!isOwnedByCurrentUser(dir, facts)) return { kind: 'untrusted', dir, reason: 'not-owned' }\n return { kind: 'project', root: dir }\n }\n const parent = dirname(dir)\n if (parent === dir) return { kind: 'none', start: from }\n dir = parent\n }\n}\n","/**\n * What to run for a trusted project root, and the checks that keep it inside that root.\n *\n * `node strut <args>` runs the project's `strut.js`. So the guard runs that same file, with the\n * same Node, when it is there. Without a `strut.js` (a project made by hand, or one whose\n * `strut.js` was deleted) it runs what `strut.js` would run for a framework command: the\n * `strutvane` program of the project's own installed `@strutvane/framework`. Never a second copy,\n * and never anything fetched.\n *\n * Every path is checked on its **real** location (links resolved), and must stay inside the\n * project root:\n * - the root itself must not be a link (a link can make an innocent-looking folder run code from\n * anywhere); the user is told the real folder to open instead;\n * - `strut.js` must be a regular file, not a link;\n * - `node_modules/@strutvane/framework` must really be inside the root (an `npm link` or a\n * planted junction pointing elsewhere is refused), must be named `@strutvane/framework`, and its\n * `bin` must be a plain relative `.js`/`.mjs`/`.cjs` path that stays inside the package.\n *\n * The file that runs is handed to Node by its real path, so what was checked is what runs.\n *\n * @module\n */\nimport { lstatSync, realpathSync, statSync } from 'node:fs'\nimport { join, posix, resolve, win32 } from 'node:path'\nimport { isInside } from './boundary.ts'\nimport { FRAMEWORK_PACKAGE, readJsonObject } from './manifest.ts'\nimport { STRUT_FILE } from './project.ts'\n\n/** The name of the framework's program in its package.json `bin`. */\nexport const FRAMEWORK_BIN = 'strutvane'\n\n/** Why a trusted project root still cannot be run. */\nexport type RefusalReason =\n /** The project root disappeared or cannot be read since it was found. */\n | 'root-unreadable'\n /** The project root is a symbolic link or junction. */\n | 'root-is-link'\n /** `strut.js` is a link, or not a regular file. */\n | 'strut-not-file'\n /** `strut.js`'s real location is outside the project root. */\n | 'strut-outside-root'\n /** No `strut.js`, and `@strutvane/framework` is not installed in the project. */\n | 'framework-missing'\n /** `node_modules/@strutvane/framework` really lives outside the project root. */\n | 'framework-outside-root'\n /** The installed package is not `@strutvane/framework`, or has no usable `strutvane` bin. */\n | 'framework-invalid'\n\n/** The outcome of resolving what to run. */\nexport type Target =\n | {\n readonly kind: 'run'\n /** The project root (as found; the child's working directory). */\n readonly root: string\n /** Real path of the script Node runs. */\n readonly script: string\n /** Which of the two kinds of script it is. */\n readonly via: 'strut.js' | 'framework'\n }\n | {\n readonly kind: 'refused'\n readonly reason: RefusalReason\n /** The path the refusal is about (printed in the message). */\n readonly path: string\n /** The real location, when it helps the user (for `root-is-link`). */\n readonly realPath?: string\n }\n\n/** Scripts the guard may hand to Node. */\nconst SCRIPT_EXTENSION = /\\.[cm]?js$/\n\n/**\n * Whether a package.json `bin` value is a plain relative path to a script: not empty, no NUL, not\n * absolute on any platform (`/x`, `C:\\x`, `\\\\server\\share\\x`), not drive-relative (`C:x`), no `..`\n * segment, and ending in `.js`, `.mjs` or `.cjs`.\n *\n * Why so strict: the value comes from a file inside `node_modules`, and becomes a path Node runs.\n *\n * @example\n * isSafeBinPath('dist/console/bin.mjs') // true\n * isSafeBinPath('..\\\\..\\\\evil.js') // false\n */\nexport function isSafeBinPath(bin: string): boolean {\n if (bin === '' || bin.length > 512 || bin.includes('\\0')) return false\n if (posix.isAbsolute(bin) || win32.isAbsolute(bin) || /^[A-Za-z]:/.test(bin)) return false\n if (bin.split(/[\\\\/]/).includes('..')) return false\n return SCRIPT_EXTENSION.test(bin)\n}\n\n/** The `strutvane` entry of a manifest's `bin` (a string `bin` counts as the package's only one). */\nexport function frameworkBin(manifest: Readonly<Record<string, unknown>>): string | undefined {\n const bin = manifest['bin']\n if (typeof bin === 'string') return bin\n if (typeof bin !== 'object' || bin === null || Array.isArray(bin)) return undefined\n if (!Object.hasOwn(bin, FRAMEWORK_BIN)) return undefined\n const entry = (bin as Record<string, unknown>)[FRAMEWORK_BIN]\n return typeof entry === 'string' ? entry : undefined\n}\n\n/** `lstat`, or `undefined` when the path does not exist (or cannot be read). */\nfunction lstatOrUndefined(path: string): ReturnType<typeof lstatSync> | undefined {\n try {\n return lstatSync(path)\n } catch {\n return undefined\n }\n}\n\n/** The real path, or `undefined` when it cannot be resolved (missing, broken link, no access). */\nfunction realOrUndefined(path: string): string | undefined {\n try {\n return realpathSync.native(path)\n } catch {\n return undefined\n }\n}\n\n/**\n * Decide what to run for the trusted project root `root` (see the module documentation).\n *\n * @example\n * resolveTarget('/srv/blog') // { kind: 'run', root: '/srv/blog', script: '/srv/blog/strut.js', via: 'strut.js' }\n */\nexport function resolveTarget(root: string): Target {\n const rootStats = lstatOrUndefined(root)\n const realRoot = realOrUndefined(root)\n if (rootStats === undefined || realRoot === undefined) {\n return { kind: 'refused', reason: 'root-unreadable', path: root }\n }\n if (rootStats.isSymbolicLink()) {\n return { kind: 'refused', reason: 'root-is-link', path: root, realPath: realRoot }\n }\n\n const strut = join(root, STRUT_FILE)\n const strutStats = lstatOrUndefined(strut)\n if (strutStats !== undefined) {\n if (strutStats.isSymbolicLink() || !strutStats.isFile()) {\n return { kind: 'refused', reason: 'strut-not-file', path: strut }\n }\n const real = realOrUndefined(strut)\n if (real === undefined || !isInside(realRoot, real)) {\n return { kind: 'refused', reason: 'strut-outside-root', path: strut }\n }\n return { kind: 'run', root, script: real, via: 'strut.js' }\n }\n\n return frameworkTarget(root, realRoot)\n}\n\n/** The framework's own `strutvane` program, for a project without `strut.js`. */\nfunction frameworkTarget(root: string, realRoot: string): Target {\n const dir = join(root, 'node_modules', ...FRAMEWORK_PACKAGE.split('/'))\n if (lstatOrUndefined(dir) === undefined) {\n return { kind: 'refused', reason: 'framework-missing', path: dir }\n }\n const realDir = realOrUndefined(dir)\n if (realDir === undefined || !isInside(realRoot, realDir)) {\n return { kind: 'refused', reason: 'framework-outside-root', path: dir }\n }\n const manifest = readJsonObject(join(realDir, 'package.json'))\n const bin = manifest === undefined ? undefined : frameworkBin(manifest)\n if (manifest?.['name'] !== FRAMEWORK_PACKAGE || bin === undefined || !isSafeBinPath(bin)) {\n return { kind: 'refused', reason: 'framework-invalid', path: dir }\n }\n const real = realOrUndefined(resolve(realDir, bin))\n if (real === undefined || !isInside(realDir, real) || !isRegularFile(real)) {\n return { kind: 'refused', reason: 'framework-invalid', path: dir }\n }\n return { kind: 'run', root, script: real, via: 'framework' }\n}\n\n/** Whether `path` is a regular file (following links). */\nfunction isRegularFile(path: string): boolean {\n try {\n return statSync(path).isFile()\n } catch {\n return false\n }\n}\n","/**\n * This package's own version, and the Node.js versions it supports.\n *\n * @module\n */\nimport { fileURLToPath } from 'node:url'\nimport { readJsonObject } from './manifest.ts'\n\n/** The oldest Node.js the guard (and the framework it starts) supports: package.json `engines`. */\nexport const MIN_NODE = '24.3.0'\n\n/**\n * This package's version, read from its own package.json (one folder up from both `src/` and\n * `dist/`), so it can never drift from what was published. `0.0.0` if it cannot be read.\n *\n * @example\n * ownVersion() // '0.2.0-next.0'\n */\nexport function ownVersion(manifestUrl: URL = new URL('../package.json', import.meta.url)): string {\n const version = readJsonObject(fileURLToPath(manifestUrl))?.['version']\n return typeof version === 'string' ? version : '0.0.0'\n}\n\n/**\n * Whether `version` (`process.versions.node`, e.g. `24.3.0`) is at least `minimum`. Anything that\n * is not `major.minor.patch` counts as too old (fail closed).\n *\n * @example\n * isNodeSupported('24.3.0', '24.3.0') // true\n * isNodeSupported('22.12.0', '24.3.0') // false\n */\nexport function isNodeSupported(version: string, minimum: string = MIN_NODE): boolean {\n const parse = (v: string): number[] | undefined => {\n const match = /^(\\d+)\\.(\\d+)\\.(\\d+)/.exec(v)\n return match === null ? undefined : [Number(match[1]), Number(match[2]), Number(match[3])]\n }\n const have = parse(version)\n const need = parse(minimum)\n if (have === undefined || need === undefined) return false\n for (let i = 0; i < 3; i++) {\n const a = have[i] ?? 0\n const b = need[i] ?? 0\n if (a !== b) return a > b\n }\n return true\n}\n","/**\n * `npx strutvane <args>`: the whole decision, with every process fact injected so it can be\n * tested without touching the real process.\n *\n * 1. Node older than {@link MIN_NODE}: say so, exit 1.\n * 2. Started again by the command it started (`STRUTVANE_NPX_DEPTH`): stop, exit 1, no loop.\n * 3. Find the project (`project.ts`) and what to run in it (`target.ts`).\n * - Found and trusted: run it with the user's arguments exactly as typed, and hand back its\n * exit code or signal. Every argument goes to the project, `--version` and `help` included,\n * because that is what `node strut` does.\n * - Found but untrusted or refused: say why and how to fix it, exit 1. Nothing runs.\n * - Not found: `help` / `--help` / no command prints help (exit 0), `--version` prints this\n * package's version (exit 0), `new` / `create` / `init` prints the installer command, and\n * anything else explains that it needs a project. Those last two exit 2: nothing was done.\n *\n * Nothing is ever installed or downloaded; outside a project the guard only prints.\n *\n * @module\n */\nimport { type BoundaryFacts, processBoundary } from './boundary.ts'\nimport { type ChildRunner, runChild, signalExitCode } from './child.ts'\nimport {\n CREATE_WORDS,\n createText,\n helpText,\n loopText,\n nodeTooOldText,\n noProjectText,\n refusalText,\n startFailedText,\n untrustedText,\n versionText,\n} from './messages.ts'\nimport { findProject } from './project.ts'\nimport { resolveTarget } from './target.ts'\nimport { isNodeSupported, MIN_NODE } from './version.ts'\n\n/** Exit codes of the guard itself (the project's own codes pass through unchanged). */\nexport const EXIT: Readonly<{ OK: 0; FAILURE: 1; USAGE: 2 }> = Object.freeze({\n OK: 0,\n /** Refused to run (untrusted folder, link, missing or invalid framework, loop, old Node). */\n FAILURE: 1,\n /** Outside a project: the command needs one (or is `new`), so nothing was done. */\n USAGE: 2,\n})\n\n/** Counts how deep `npx strutvane` is nested inside itself (guards against loops). */\nexport const DEPTH_ENV = 'STRUTVANE_NPX_DEPTH'\n\n/** How the guard should end. */\nexport type Outcome =\n | { readonly exitCode: number }\n /** The child died of `signal`: re-raise it (or exit with `exitCode` where that is impossible). */\n | { readonly signal: NodeJS.Signals; readonly exitCode: number }\n\n/** Process facts the guard needs (injectable for tests). */\nexport interface GuardEnvironment {\n readonly cwd: string\n readonly env: NodeJS.ProcessEnv\n readonly execPath: string\n readonly platform: NodeJS.Platform\n /** `process.versions.node`. */\n readonly nodeVersion: string\n /** This package's version. */\n readonly version: string\n readonly stdinIsTTY: boolean\n readonly stdout: (text: string) => void\n readonly stderr: (text: string) => void\n /** Project boundary facts. Default: this process's. */\n readonly boundary?: BoundaryFacts\n /** Starts the child. Default: {@link runChild}. */\n readonly run?: ChildRunner\n}\n\n/** Flags that ask for this package's version outside a project. */\nconst VERSION_FLAGS: ReadonlySet<string> = new Set(['--version', '-v', '-V'])\n/** Words and flags that ask for help outside a project. */\nconst HELP_WORDS: ReadonlySet<string> = new Set(['help', '--help', '-h'])\n\n/**\n * The child's environment: the user's, plus the nesting depth and, on Windows,\n * `NoDefaultCurrentDirectoryInExePath`, so a `.cmd` the project starts through cmd.exe can't pick\n * up a program planted in the working directory before PATH.\n */\nexport function childEnvironment(\n env: NodeJS.ProcessEnv,\n platform: NodeJS.Platform,\n depth: number,\n): NodeJS.ProcessEnv {\n return {\n ...env,\n ...(platform === 'win32' ? { NoDefaultCurrentDirectoryInExePath: '1' } : {}),\n [DEPTH_ENV]: String(depth + 1),\n }\n}\n\n/** The nesting depth from the environment (anything unexpected counts as 0). */\nexport function depthOf(env: NodeJS.ProcessEnv): number {\n const value = env[DEPTH_ENV]\n return value !== undefined && /^\\d{1,3}$/.test(value) ? Number(value) : 0\n}\n\n/**\n * Run the guard for `argv` (the arguments after `strutvane`). Never throws for expected\n * situations; returns how to end.\n *\n * @example\n * await main(['migrate'], environment) // { exitCode: 0 } after `node strut migrate` succeeded\n */\nexport async function main(argv: readonly string[], env: GuardEnvironment): Promise<Outcome> {\n if (!isNodeSupported(env.nodeVersion)) {\n env.stderr(nodeTooOldText(env.nodeVersion, MIN_NODE))\n return { exitCode: EXIT.FAILURE }\n }\n const depth = depthOf(env.env)\n if (depth >= 1) {\n env.stderr(loopText())\n return { exitCode: EXIT.FAILURE }\n }\n\n const search = findProject(env.cwd, env.boundary ?? processBoundary())\n if (search.kind === 'untrusted') {\n env.stderr(untrustedText(search.dir, search.reason))\n return { exitCode: EXIT.FAILURE }\n }\n if (search.kind === 'none') return outside(argv, search.start, env)\n\n const target = resolveTarget(search.root)\n if (target.kind === 'refused') {\n env.stderr(refusalText(target.reason, target.path, target.realPath))\n return { exitCode: EXIT.FAILURE }\n }\n\n const run = env.run ?? runChild\n const outcome = await run({\n execPath: env.execPath,\n script: target.script,\n args: argv,\n cwd: target.root,\n env: childEnvironment(env.env, env.platform, depth),\n platform: env.platform,\n stdinIsTTY: env.stdinIsTTY,\n })\n switch (outcome.kind) {\n case 'exit':\n return { exitCode: outcome.code }\n case 'signal':\n return { signal: outcome.signal, exitCode: signalExitCode(outcome.signal) }\n case 'error':\n env.stderr(startFailedText(target.script, outcome.message))\n return { exitCode: EXIT.FAILURE }\n }\n}\n\n/** Outside a project: only print (help, version, the installer command, or why not). */\nfunction outside(argv: readonly string[], start: string, env: GuardEnvironment): Outcome {\n const [first, second] = argv\n if (first === undefined || HELP_WORDS.has(first)) {\n env.stdout(helpText(env.version, start))\n return { exitCode: EXIT.OK }\n }\n if (VERSION_FLAGS.has(first)) {\n env.stdout(versionText(env.version))\n return { exitCode: EXIT.OK }\n }\n if (CREATE_WORDS.has(first)) {\n env.stderr(createText(env.version, second))\n return { exitCode: EXIT.USAGE }\n }\n env.stderr(noProjectText(env.version, first, start))\n return { exitCode: EXIT.USAGE }\n}\n","#!/usr/bin/env node\n/**\n * The `strutvane` executable (`npx strutvane <command>`). All decisions live in `main.ts`\n * (tested); this file only connects them to the real process: arguments, output, the exit code,\n * and re-raising a signal the child died of.\n *\n * It is the one file in this package allowed to print with `console` (package.json\n * `strutvane.allowConsole`).\n *\n * @module\n */\nimport { main } from './main.ts'\nimport { ownVersion } from './version.ts'\n\nconst outcome = await main(process.argv.slice(2), {\n cwd: process.cwd(),\n env: process.env,\n execPath: process.execPath,\n platform: process.platform,\n nodeVersion: process.versions.node,\n version: ownVersion(),\n stdinIsTTY: process.stdin.isTTY === true,\n // biome-ignore lint/suspicious/noConsole: the bin entry prints help and the version to stdout\n stdout: (text) => console.log(text),\n stderr: (text) => console.error(text),\n})\n\nprocess.exitCode = outcome.exitCode\n// The child was killed by a signal: die of the same signal, so the shell (or CI) that started us\n// sees exactly that. Windows has no such thing; there the exit code (128 + signal) stands.\nif ('signal' in outcome && process.platform !== 'win32') process.kill(process.pid, outcome.signal)\n"],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,80 @@
1
1
  {
2
2
  "name": "strutvane",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0-next.0",
4
+ "description": "npx strutvane: inside a Strutvane project it runs exactly what `node strut` runs, with the project's own @strutvane/framework; outside one it points you to `npm create strutvane`. A guard: never installs or downloads anything, zero dependencies.",
5
+ "keywords": [
6
+ "strutvane",
7
+ "cli",
8
+ "npx",
9
+ "framework",
10
+ "typescript"
11
+ ],
12
+ "homepage": "https://github.com/vishwajit-vm/strutvane-npx#readme",
13
+ "bugs": {
14
+ "url": "https://github.com/vishwajit-vm/strutvane-npx/issues"
15
+ },
16
+ "repository": {
17
+ "type": "git",
18
+ "url": "git+https://github.com/vishwajit-vm/strutvane-npx.git"
19
+ },
20
+ "license": "MIT",
21
+ "author": "The Strutvane Authors",
22
+ "type": "module",
23
+ "sideEffects": false,
24
+ "bin": {
25
+ "strutvane": "dist/bin.mjs"
26
+ },
27
+ "exports": {
28
+ "./package.json": "./package.json"
29
+ },
30
+ "files": [
31
+ "dist",
32
+ "README.md",
33
+ "CHANGELOG.md",
34
+ "LICENSE"
35
+ ],
36
+ "engines": {
37
+ "node": ">=24.3"
38
+ },
39
+ "devEngines": {
40
+ "packageManager": {
41
+ "name": "npm",
42
+ "version": ">=11.19.0",
43
+ "onFail": "error"
44
+ }
45
+ },
46
+ "publishConfig": {
47
+ "access": "public",
48
+ "provenance": true
49
+ },
50
+ "scripts": {
51
+ "lint": "biome check .",
52
+ "format": "biome check --write .",
53
+ "typecheck": "tsc --noEmit",
54
+ "test": "vitest run",
55
+ "test:coverage": "vitest run --coverage",
56
+ "build": "tsdown",
57
+ "ci": "biome check . && tsc --noEmit && vitest run --coverage && tsdown",
58
+ "changeset": "changeset",
59
+ "version-packages": "changeset version",
60
+ "release": "changeset publish",
61
+ "test:perf": "vitest run --config vitest.perf.config.ts"
62
+ },
63
+ "devDependencies": {
64
+ "@biomejs/biome": "2.6.7",
65
+ "@changesets/cli": "3.0.3",
66
+ "@types/node": "24.19.2",
67
+ "@vitest/coverage-v8": "5.1.0",
68
+ "tsdown": "0.23.7",
69
+ "typescript": "6.0.3",
70
+ "vitest": "5.1.0"
71
+ },
72
+ "strutvane": {
73
+ "allowConsole": [
74
+ "src/bin.ts"
75
+ ]
76
+ },
77
+ "allowScripts": {
78
+ "fsevents@2.3.3": false
79
+ }
80
+ }