strutvane 0.1.0-next.0 → 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/README.md CHANGED
@@ -1,18 +1,88 @@
1
1
  # strutvane
2
2
 
3
- The `strutvane` command. A tiny, dependency-free launcher that always runs the `@strutvane/cli` version pinned in your project, so generators and runtime match your packages.
3
+ **`npx strutvane`**: run Strutvane project commands with npx.
4
4
 
5
- ```bash
6
- npx strutvane new acme # create a project (runs create-strutvane)
7
- cd acme && npx strutvane routes # inside a project: delegates to node_modules/@strutvane/cli
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
8
14
  ```
9
15
 
10
- - Inside a project, project commands are handed to the local CLI with the same arguments and exit code. Local always wins over global.
11
- - A folder is a project only when its package.json lists `@strutvane/cli` (dependencies or devDependencies) or it contains `strutvane.config.ts`. The search walks up from the working directory but never accepts a drive or file-system root, the OS temp folder or a folder above your home directory; on macOS and Linux the folder must belong to you.
12
- - `--version`, `help`, `new` and `create` are always answered by the launcher itself, never delegated. To list a project's commands, run `pnpm exec strutvane-cli help`.
13
- - Outside a project, only `new`, `doctor --global`, `--version` and `help` run. `npx` is started as `node npx-cli.js` without a shell when npm sits next to Node.js; on Windows the fallback resolves `npx.cmd` from PATH only, never the working directory.
14
- - A version difference between launcher and local CLI is noted once on stderr (silenced by `--json`, `--quiet` or `STRUTVANE_NO_UPDATE_NOTICE=1`).
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.
15
84
 
16
- > Pre-release (`0.1.0-next.0`). Full documentation: https://github.com/vishwajit-vm/strutvane-cli#readme
85
+ ## Contributing
17
86
 
18
- MIT © 2026 The Strutvane Authors
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.