@pirafrank/poof 0.0.1-bootstrap.0 → 0.6.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/LICENSE.md ADDED
@@ -0,0 +1,72 @@
1
+ # License
2
+
3
+ ## Rust Source Code License
4
+
5
+ `SPDX-License-Identifier: MIT`
6
+
7
+ This Rust source code of this software is licensed under the terms of MIT License.
8
+
9
+ Any third-party libraries or dependencies included in this software may be licensed under different terms. You are responsible for complying with the terms of those licenses.
10
+
11
+ ### MIT License (MIT)
12
+
13
+ The MIT License (MIT)
14
+
15
+ Copyright (c) 2024 Francesco Pira (pirafrank)
16
+
17
+ Permission is hereby granted, free of charge, to any person obtaining a copy
18
+ of this software and associated documentation files (the "Software"), to deal
19
+ in the Software without restriction, including without limitation the rights
20
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
21
+ copies of the Software, and to permit persons to whom the Software is
22
+ furnished to do so, subject to the following conditions:
23
+
24
+ The above copyright notice and this permission notice shall be included in
25
+ all copies or substantial portions of the Software.
26
+
27
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
28
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
29
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
30
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
31
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
32
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
33
+ THE SOFTWARE.
34
+
35
+ ## Documentation License
36
+
37
+ The documentation for this software is licensed under the terms of the
38
+ [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/).
39
+
40
+ You are free to share and adapt the documentation, provided that you give appropriate credit to the authors and license your contributions under the same terms.
41
+
42
+ You may not use the material for commercial purposes without permission from the authors.
43
+
44
+ The documentation may include images, diagrams, or other content that is licensed under different terms. You are responsible for complying with the terms of those licenses.
45
+
46
+ ## Logo License
47
+
48
+ The assets included in this software, such as images, icons, or other media files, are licensed under the terms of the [Creative Commons Attribution-NonDerivatives 4.0 International License](https://creativecommons.org/licenses/by-nd/4.0/).
49
+
50
+ You are free to use the logo for personal or commercial purposes, provided that you give appropriate credit to the authors and do not create derivative works based on the logo without permission.
51
+
52
+ ## Additional Terms
53
+
54
+ ### 1. Attribution
55
+
56
+ If you use this software in a project, please provide appropriate credit to the author and any contributors. You should also provide a link to the original repository.
57
+
58
+ ### 2. Contribution Policy
59
+
60
+ If you wish to contribute to this software, please submit a pull request or open an issue in the repository. By submitting a contribution, you agree to license your contributions under the same terms as this software.
61
+
62
+ ### 3. Contact Information
63
+
64
+ For any questions or concerns regarding this license, please contact the authors at the email address provided in the repository or website.
65
+
66
+ ### 4. Language
67
+
68
+ This license is written in English. If this license is translated into another language, the English version shall prevail in case of any conflict or ambiguity.
69
+
70
+ ### 5. Acceptance
71
+
72
+ By using this software, you acknowledge that you have read this license, understand it, and agree to be bound by its terms. If you do not agree to the terms of this license, you may not use this software.
package/README.md CHANGED
@@ -1,3 +1,87 @@
1
- # npm trusted-publishing bootstrap
1
+ # poof
2
2
 
3
- This is a deliberately non-functional placeholder package published only to create the package record for configuring npm Trusted Publishing. It contains no poof executable or runtime code. Do not use this version. The real package is published from a signed poof release.
3
+ Easy to use zero-config, zero-install, zero-dependencies manager of pre-built software that
4
+ works like magic.
5
+
6
+ `poof` downloads pre-built binaries from GitHub Releases and manages them entirely in user
7
+ space: no root, no system package manager, no daemon, no configuration files.
8
+
9
+ This npm package is a **thin launcher**. It installs the native `poof` executable for your
10
+ platform through an optional platform package and forwards every argument to it unchanged.
11
+
12
+ ## Requirements
13
+
14
+ - Node.js **>= 18**
15
+ - One of the supported platforms below
16
+
17
+ | Operating system | Architecture | npm package |
18
+ | ---------------- | ------------ | ---------------------------------- |
19
+ | Linux (static musl) | x64 | `@pirafrank/poof-linux-x64` |
20
+ | Linux (static musl) | arm64 | `@pirafrank/poof-linux-arm64` |
21
+ | macOS | x64 (Intel) | `@pirafrank/poof-darwin-x64` |
22
+ | macOS | arm64 (Apple silicon) | `@pirafrank/poof-darwin-arm64` |
23
+
24
+ Windows is **not** supported. Linux binaries are statically linked against musl, so they run
25
+ on glibc and musl distributions alike, including Alpine and scratch-based containers.
26
+
27
+ ## Install
28
+
29
+ ```sh
30
+ # Global install: puts `poof` on your PATH
31
+ npm install --global @pirafrank/poof
32
+
33
+ # One-off use without installing
34
+ npx --yes @pirafrank/poof --help
35
+
36
+ # Project-local install
37
+ npm install --save-dev @pirafrank/poof
38
+ ```
39
+
40
+ Then use it like the native CLI:
41
+
42
+ ```sh
43
+ poof install pirafrank/poof
44
+ poof list
45
+ poof which rg
46
+ ```
47
+
48
+ ## Verifying what you installed
49
+
50
+ Every release is built by GitHub Actions from a tagged commit, signed with Sigstore, and
51
+ published with npm provenance. You can inspect the provenance of an installed version with:
52
+
53
+ ```sh
54
+ npm audit signatures
55
+ ```
56
+
57
+ Native release archives, checksums, SPDX inventories, and attestations are published on the
58
+ [GitHub Releases page](https://github.com/pirafrank/poof/releases).
59
+
60
+ ## How it works
61
+
62
+ The launcher resolves the native executable with Node module resolution and spawns it with
63
+ `stdio: 'inherit'` and `shell: false`. Arguments, exit codes, and signals are passed through
64
+ unchanged, so `poof` behaves exactly like the native binary.
65
+
66
+ The launcher performs **no network access at runtime**. It never downloads, extracts, or
67
+ updates anything: the executable is already installed by npm. All download and update
68
+ behavior belongs to `poof` itself and is unchanged by this packaging.
69
+
70
+ ## Documentation
71
+
72
+ Full CLI documentation, shell integration, and more is available at [poof.fpira.com](https://poof.fpira.com).
73
+
74
+ ## Troubleshooting
75
+
76
+ See the [npm troubleshooting guide](https://poof.fpira.com/docs/npm-troubleshooting)
77
+ for help with missing native packages, unsupported platforms, and executable launch errors.
78
+
79
+ ## Repository
80
+
81
+ The source code is available on GitHub: <https://github.com/pirafrank/poof>.
82
+
83
+ ## License
84
+
85
+ MIT
86
+
87
+ See [LICENSE.md](https://github.com/pirafrank/poof/blob/main/LICENSE.md).
package/bin/poof.js ADDED
@@ -0,0 +1,226 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ /**
5
+ * poof launcher for npm/npx.
6
+ *
7
+ * Resolves the native executable shipped by the matching optional platform
8
+ * package and spawns it. This file performs no network access, no downloads,
9
+ * no extraction, and no shell interpolation: the native binary is already
10
+ * installed by npm alongside this package.
11
+ */
12
+
13
+ const { spawn } = require('node:child_process');
14
+
15
+ /** The only supported (platform, arch) pairs. No Windows, no other Linux CPUs. */
16
+ const SUPPORTED_TARGETS = Object.freeze([
17
+ Object.freeze({ platform: 'linux', arch: 'x64', package: '@pirafrank/poof-linux-x64' }),
18
+ Object.freeze({ platform: 'linux', arch: 'arm64', package: '@pirafrank/poof-linux-arm64' }),
19
+ Object.freeze({ platform: 'darwin', arch: 'x64', package: '@pirafrank/poof-darwin-x64' }),
20
+ Object.freeze({ platform: 'darwin', arch: 'arm64', package: '@pirafrank/poof-darwin-arm64' }),
21
+ ]);
22
+
23
+ /** Signals forwarded to the child so Ctrl-C and termination behave natively. */
24
+ const FORWARDED_SIGNALS = Object.freeze(['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT']);
25
+
26
+ const INSTALL_HINT = 'npm install --global @pirafrank/poof';
27
+
28
+ /**
29
+ * Select the platform package for a (platform, arch) pair.
30
+ * @param {string} platform process.platform value.
31
+ * @param {string} arch process.arch value.
32
+ * @returns {{platform: string, arch: string, package: string}|null} target or null.
33
+ */
34
+ function selectTarget(platform, arch) {
35
+ return SUPPORTED_TARGETS.find((t) => t.platform === platform && t.arch === arch) || null;
36
+ }
37
+
38
+ /**
39
+ * Render the supported target list for diagnostics.
40
+ * @returns {string} multi-line list of supported platforms.
41
+ */
42
+ function supportedTargetsText() {
43
+ return SUPPORTED_TARGETS.map((t) => ` - ${t.platform}/${t.arch} (${t.package})`).join('\n');
44
+ }
45
+
46
+ /**
47
+ * Build the actionable error for an unsupported operating system or CPU.
48
+ * @param {string} platform detected process.platform.
49
+ * @param {string} arch detected process.arch.
50
+ * @returns {string} diagnostic text.
51
+ */
52
+ function unsupportedMessage(platform, arch) {
53
+ return [
54
+ 'poof: unsupported platform.',
55
+ `Detected: platform=${platform} arch=${arch}`,
56
+ 'Supported targets:',
57
+ supportedTargetsText(),
58
+ '',
59
+ 'poof publishes native binaries for Linux (x64, arm64) and macOS (x64, arm64) only.',
60
+ 'Windows is not supported. On other systems, build from source or use a native',
61
+ `release archive: https://github.com/pirafrank/poof/releases`,
62
+ '',
63
+ ].join('\n');
64
+ }
65
+
66
+ /**
67
+ * Build the actionable error for a missing optional native package.
68
+ * @param {{platform: string, arch: string, package: string}} target expected package.
69
+ * @param {Error} error resolution failure.
70
+ * @returns {string} diagnostic text.
71
+ */
72
+ function missingPackageMessage(target, error) {
73
+ return [
74
+ `poof: native package ${target.package} is not installed.`,
75
+ `Detected: platform=${target.platform} arch=${target.arch}`,
76
+ 'Supported targets:',
77
+ supportedTargetsText(),
78
+ '',
79
+ 'Likely causes:',
80
+ ' - optional dependencies were skipped (npm --omit=optional, --no-optional,',
81
+ ' or a package manager configured to ignore optionalDependencies)',
82
+ ' - an incomplete or interrupted install, or a pruned node_modules tree',
83
+ ' - a package-manager layout that does not place sibling scoped packages',
84
+ ' where Node can resolve them (for example some pnpm/Yarn PnP setups)',
85
+ '',
86
+ 'Fix: reinstall with optional dependencies enabled, for example',
87
+ ` ${INSTALL_HINT}`,
88
+ 'or, for a local project:',
89
+ ' npm install --include=optional @pirafrank/poof',
90
+ '',
91
+ `Resolution error: ${error && error.message ? error.message : String(error)}`,
92
+ '',
93
+ ].join('\n');
94
+ }
95
+
96
+ /**
97
+ * Build the actionable error when the resolved binary cannot be executed.
98
+ * @param {string} binaryPath resolved native executable path.
99
+ * @param {Error} error spawn failure.
100
+ * @returns {string} diagnostic text.
101
+ */
102
+ function spawnFailureMessage(binaryPath, error) {
103
+ const code = error && error.code ? error.code : 'unknown';
104
+ return [
105
+ `poof: failed to execute ${binaryPath} (${code}).`,
106
+ 'The native package is installed but its executable could not be started.',
107
+ 'Check that the file exists, is a regular file, and has the executable bit set',
108
+ '(expected mode 0755), and that your antivirus or mount options (noexec) are',
109
+ 'not blocking it. Reinstalling usually repairs a damaged installation:',
110
+ ` ${INSTALL_HINT}`,
111
+ '',
112
+ ].join('\n');
113
+ }
114
+
115
+ /**
116
+ * Resolve the packaged native executable relative to this launcher's package.
117
+ * @param {{package: string}} target platform package descriptor.
118
+ * @param {string} fromDir directory to start Node resolution from.
119
+ * @returns {string} absolute path to the native executable.
120
+ */
121
+ function resolveBinaryPath(target, fromDir) {
122
+ return require.resolve(`${target.package}/bin/poof`, { paths: [fromDir] });
123
+ }
124
+
125
+ /**
126
+ * Spawn the native binary, forwarding arguments, stdio, and signals.
127
+ * @param {string} binaryPath absolute path to the native executable.
128
+ * @param {string[]} args arguments to forward unchanged.
129
+ * @returns {Promise<{code: number|null, signal: string|null}>} child outcome.
130
+ */
131
+ function runBinary(binaryPath, args) {
132
+ return new Promise((resolve, reject) => {
133
+ const child = spawn(binaryPath, args, { stdio: 'inherit', shell: false });
134
+ const forward = (signal) => {
135
+ try {
136
+ child.kill(signal);
137
+ } catch {
138
+ // The child may already have exited; nothing to forward.
139
+ }
140
+ };
141
+ for (const signal of FORWARDED_SIGNALS) {
142
+ process.on(signal, forward);
143
+ }
144
+ const cleanup = () => {
145
+ for (const signal of FORWARDED_SIGNALS) {
146
+ process.removeListener(signal, forward);
147
+ }
148
+ };
149
+ child.once('error', (error) => {
150
+ cleanup();
151
+ reject(error);
152
+ });
153
+ child.once('close', (code, signal) => {
154
+ cleanup();
155
+ resolve({ code, signal });
156
+ });
157
+ });
158
+ }
159
+
160
+ /**
161
+ * Launcher entry point.
162
+ * @param {string[]} [argv] full argv (defaults to process.argv).
163
+ * @param {string} [platform] detected platform (defaults to process.platform).
164
+ * @param {string} [arch] detected architecture (defaults to process.arch).
165
+ * @param {string} [fromDir] resolution root (defaults to this file's directory).
166
+ * @returns {Promise<number>} process exit code.
167
+ */
168
+ async function main(argv, platform, arch, fromDir) {
169
+ const fullArgv = argv || process.argv;
170
+ const detectedPlatform = platform || process.platform;
171
+ const detectedArch = arch || process.arch;
172
+ const resolutionRoot = fromDir || __dirname;
173
+
174
+ const target = selectTarget(detectedPlatform, detectedArch);
175
+ if (!target) {
176
+ process.stderr.write(unsupportedMessage(detectedPlatform, detectedArch));
177
+ return 1;
178
+ }
179
+
180
+ let binaryPath;
181
+ try {
182
+ binaryPath = resolveBinaryPath(target, resolutionRoot);
183
+ } catch (error) {
184
+ process.stderr.write(missingPackageMessage(target, error));
185
+ return 1;
186
+ }
187
+
188
+ let outcome;
189
+ try {
190
+ outcome = await runBinary(binaryPath, fullArgv.slice(2));
191
+ } catch (error) {
192
+ process.stderr.write(spawnFailureMessage(binaryPath, error));
193
+ return 1;
194
+ }
195
+
196
+ if (outcome.signal) {
197
+ // Die by the same signal so shells and supervisors observe native behavior.
198
+ process.kill(process.pid, outcome.signal);
199
+ return 1;
200
+ }
201
+ return outcome.code === null ? 1 : outcome.code;
202
+ }
203
+
204
+ if (require.main === module) {
205
+ main()
206
+ .then((code) => {
207
+ process.exitCode = code;
208
+ })
209
+ .catch((error) => {
210
+ process.stderr.write(`poof: unexpected launcher failure: ${error && error.stack ? error.stack : error}\n`);
211
+ process.exitCode = 1;
212
+ });
213
+ }
214
+
215
+ module.exports = {
216
+ SUPPORTED_TARGETS,
217
+ FORWARDED_SIGNALS,
218
+ selectTarget,
219
+ supportedTargetsText,
220
+ unsupportedMessage,
221
+ missingPackageMessage,
222
+ spawnFailureMessage,
223
+ resolveBinaryPath,
224
+ runBinary,
225
+ main,
226
+ };
package/package.json CHANGED
@@ -1,16 +1,43 @@
1
1
  {
2
- "name": "@pirafrank/poof",
3
- "version": "0.0.1-bootstrap.0",
4
- "description": "Non-functional bootstrap placeholder; not a poof release.",
2
+ "bin": {
3
+ "poof": "bin/poof.js"
4
+ },
5
+ "bugs": {
6
+ "url": "https://github.com/pirafrank/poof/issues"
7
+ },
8
+ "description": "Easy to use zero-config, zero-install, zero-dependencies manager of pre-built software that works like magic",
9
+ "engines": {
10
+ "node": ">=18"
11
+ },
12
+ "files": [
13
+ "bin/poof.js",
14
+ "README.md",
15
+ "LICENSE.md"
16
+ ],
17
+ "homepage": "https://github.com/pirafrank/poof#readme",
18
+ "keywords": [
19
+ "binary-manager",
20
+ "portable-tools",
21
+ "zero-config",
22
+ "no-install",
23
+ "userspace",
24
+ "cli"
25
+ ],
5
26
  "license": "MIT",
6
- "repository": {
7
- "type": "git",
8
- "url": "git+https://github.com/pirafrank/poof.git"
27
+ "name": "@pirafrank/poof",
28
+ "optionalDependencies": {
29
+ "@pirafrank/poof-darwin-arm64": "0.6.4",
30
+ "@pirafrank/poof-darwin-x64": "0.6.4",
31
+ "@pirafrank/poof-linux-arm64": "0.6.4",
32
+ "@pirafrank/poof-linux-x64": "0.6.4"
9
33
  },
34
+ "private": false,
10
35
  "publishConfig": {
11
36
  "access": "public"
12
37
  },
13
- "files": [
14
- "README.md"
15
- ]
38
+ "repository": {
39
+ "type": "git",
40
+ "url": "git+https://github.com/pirafrank/poof.git"
41
+ },
42
+ "version": "0.6.4"
16
43
  }