safeinstall-cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 0.1.0 - 2026-03-31
+
+First public release. Open source under MIT license.
+
+### Added
+
+- Local CLI wrapper for `npm`, `pnpm`, and `bun`
+- Policy enforcement for release age, lifecycle scripts, untrusted sources, and trust downgrades
+- Lockfile-aware project installs for `pnpm install`, `npm install`, and `npm ci`
+- JSON output for CI and automation
+- `safeinstall init` starter config generation
+- Monorepo-aware package and lockfile discovery for npm and pnpm
+- End-to-end CLI regression coverage and local-repo QA against real projects
+- Configurable registry URL for private mirrors (Verdaccio, Artifactory)
+- On-disk cache for exact-version registry metadata and publish timestamps
+- Graceful SIGINT/SIGTERM shutdown with proper exit codes
+- `--help` / `-h` and `--version` / `-v` flags
+
+### Hardened
+
+- Fail-closed behavior for stale, missing, or ambiguous lockfiles
+- Explicit blocking for ambiguous workspace-targeting flags
+- Package-manager mismatch blocking when `package.json` declares a different manager
+- Local workspace and file-based project references handled as local sources instead of external supply-chain inputs
+- Abbreviated registry metadata for faster fetches
+- Concurrency-limited registry requests
+
+### Notes
+
+- Package name: `safeinstall-cli` (npm) — command: `safeinstall`
+- `bun install` remains manifest-based for project installs in this release
+- Policy checks apply to direct dependencies only in this release

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SafeInstall Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,305 @@
+<p align="center">
+  <strong>SafeInstall</strong>
+  <br />
+  <em>Stop risky package installs before they run.</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/safeinstall-cli"><img src="https://img.shields.io/npm/v/safeinstall-cli?style=flat-square&color=22c55e" alt="npm version" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e?style=flat-square" alt="license" /></a>
+  <a href="https://github.com/Mickdownunder/SafeInstall"><img src="https://img.shields.io/github/stars/Mickdownunder/SafeInstall?style=flat-square" alt="stars" /></a>
+  <a href="https://github.com/Mickdownunder/SafeInstall"><img src="https://img.shields.io/badge/TypeScript-strict-blue?style=flat-square" alt="TypeScript" /></a>
+  <a href="https://safeinstall.dev"><img src="https://img.shields.io/badge/docs-safeinstall.dev-22c55e?style=flat-square" alt="docs" /></a>
+</p>
+
+<p align="center">
+  Local-first CLI wrapper for <strong>npm</strong>, <strong>pnpm</strong>, and <strong>bun</strong>.<br />
+  Policy runs first. Then your package manager. Not the other way around.<br /><br />
+  Open source · MIT licensed · Free forever
+</p>
+
+---
+
+## Why SafeInstall
+
+AI coding tools suggest packages in seconds. They don't check publish dates. They don't read install scripts. They don't verify the source. You type "yes" and move on.
+
+SafeInstall is the gate between suggestion and execution.
+
+```
+$ safeinstall pnpm add compromised-pkg@9.9.9
+
+Install blocked.
+- compromised-pkg@9.9.9
+  Blocked: release too new (published 3 hours ago; minimum is 72 hours).
+  Blocked: install script present (has postinstall).
+```
+
+No dashboard. No account. No cloud. One command prefix — policy runs locally, blocks by default, then invokes the real tool.
+
+---
+
+## Install
+
+```bash
+npm install -g safeinstall-cli
+```
+
+> Node.js >=20 · macOS, Linux, Windows · Command: `safeinstall`
+
+## Quickstart
+
+```bash
+safeinstall init                      # create safeinstall.config.json
+safeinstall pnpm add axios            # policy runs, then pnpm
+safeinstall npm install               # lockfile-aware project install
+safeinstall check                     # audit direct deps against policy
+```
+
+---
+
+## How it works
+
+```
+┌─────────────────────┐     ┌──────────────┐     ┌─────────────────┐
+│  safeinstall pnpm   │ ──▶ │  Resolve &   │ ──▶ │  Policy check   │
+│  add axios          │     │  fetch meta  │     │  (age, scripts, │
+└─────────────────────┘     └──────────────┘     │   sources, ...)  │
+                                                  └────────┬────────┘
+                                                           │
+                                                 ┌─────────▼─────────┐
+                                          pass → │  Invoke pnpm add  │
+                                          fail → │  Exit 2 (blocked) │
+                                                 └───────────────────┘
+```
+
+1. Resolves what would be installed
+2. Fetches registry metadata (publish time, declared scripts)
+3. Evaluates policy rules
+4. Blocks (exit 2) or invokes the real package manager
+
+No registry proxy. No tarball rewriting. No cloud dependency.
+
+---
+
+## Policy defaults
+
+| Rule | Default | Block message |
+|:---|:---|:---|
+| **Release age** | 72 hours minimum | `Blocked: release too new` |
+| **Lifecycle scripts** | preinstall, install, postinstall blocked | `Blocked: install script present` |
+| **Source types** | registry, workspace, file, directory allowed | `Blocked: untrusted source` |
+| **Trust downgrade** | Detects registry→git/url or new scripts on update | `Blocked: trust level dropped` |
+
+All rules are configurable. Ambiguous or incomplete metadata **blocks instead of allowing**.
+
+---
+
+## Usage
+
+```bash
+# Ad-hoc installs
+safeinstall pnpm add axios
+safeinstall npm install react@19.2.0
+safeinstall bun add zod
+
+# Project installs (lockfile-aware for npm/pnpm)
+safeinstall pnpm install
+safeinstall npm ci
+
+# Monorepo — target one package
+safeinstall pnpm -C packages/app install
+safeinstall npm --prefix packages/app ci
+
+# Utilities
+safeinstall check                     # direct dependency audit
+safeinstall check --json              # machine-readable
+safeinstall init                      # create starter config
+safeinstall init --force              # overwrite existing config
+safeinstall --help
+safeinstall --version
+
+# JSON output (CI/automation)
+safeinstall --json pnpm add axios
+```
+
+## Project installs
+
+For `pnpm install` and `npm install` / `npm ci`, dependency versions come from the lockfile — not loose ranges in `package.json`.
+
+- `pnpm-lock.yaml` for pnpm
+- `package-lock.json` or `npm-shrinkwrap.json` for npm
+- Stale, missing, or mismatched lockfile entries **fail closed**
+- If `packageManager` is set in `package.json`, using a different CLI is blocked
+- Workspace-targeting flags (`--filter`, `--workspace`) are blocked — use `-C` or `--prefix`
+- `bun install` uses manifest-oriented analysis (full lockfile parity not yet implemented)
+
+---
+
+## Configuration
+
+Optional `safeinstall.config.json` — discovered by walking upward from the project directory.
+
+```json
+{
+  "minimumReleaseAgeHours": 72,
+  "registryUrl": "https://registry.npmjs.org",
+  "allowedScripts": {
+    "esbuild": ["postinstall"]
+  },
+  "allowedSources": ["registry", "workspace", "file", "directory"],
+  "allowedPackages": [],
+  "ciMode": false,
+  "packageManagerDefaults": {
+    "npm": { "ignoreScripts": true },
+    "pnpm": { "ignoreScripts": true },
+    "bun": { "ignoreScripts": true }
+  }
+}
+```
+
+| Field | Purpose |
+|:---|:---|
+| `minimumReleaseAgeHours` | Minimum age in hours for registry versions |
+| `registryUrl` | npm-compatible registry URL for metadata (mirrors, Artifactory, Verdaccio) |
+| `allowedScripts` | Per-package lifecycle script exceptions |
+| `allowedSources` | Permitted source types |
+| `allowedPackages` | Names that skip policy entirely (with warning) |
+| `ciMode` | Reserved for future CI-specific behavior |
+| `packageManagerDefaults` | Per-manager flags forwarded to the tool |
+
+Run `safeinstall init` to generate a starter config.
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|:---|:---|
+| `0` | Allowed / check passed |
+| `1` | Runtime or config error |
+| `2` | Blocked by policy |
+
+Use exit code 2 like any other failing step in a CI pipeline.
+
+## JSON output
+
+Pass `--json` anywhere in the command. Structured output goes to stdout.
+
+```bash
+safeinstall --json pnpm add axios
+```
+
+Fields: `command`, `commandString`, `packageManager`, `decision`, `summary`, `reasons`, `warnings`, `affectedPackages`, `exitCode`, `exitCodeMeaning`. Allowed installs include `execution.stdout` and `execution.stderr`.
+
+---
+
+## Examples
+
+<details>
+<summary><strong>Fresh release blocked</strong></summary>
+
+```
+$ safeinstall pnpm add axios
+Using config: built-in defaults
+Install blocked.
+- axios@1.14.0
+  Blocked: release too new (axios@1.14.0 is 6 hours old; minimum is 72 hours).
+  Suggestion: Retry later or lower minimumReleaseAgeHours if this package is intentionally urgent.
+```
+
+</details>
+
+<details>
+<summary><strong>Git source blocked</strong></summary>
+
+```
+$ safeinstall npm install github:axios/axios
+Using config: built-in defaults
+Install blocked.
+- github:axios/axios
+  Blocked: untrusted source (git).
+  Suggestion: Use a registry release or allow this source intentionally.
+```
+
+</details>
+
+<details>
+<summary><strong>Package manager mismatch</strong></summary>
+
+```
+$ safeinstall npm install
+Using config: built-in defaults
+Install blocked.
+- Project install blocked: package.json declares pnpm as packageManager, but this command uses npm.
+```
+
+</details>
+
+<details>
+<summary><strong>Stale lockfile</strong></summary>
+
+```
+$ safeinstall pnpm install
+Using config: built-in defaults
+Install blocked.
+- Project install blocked: axios is declared in package.json but missing from pnpm-lock.yaml.
+```
+
+</details>
+
+---
+
+## Limitations
+
+- **Not a CVE scanner** — pair with `npm audit` or Snyk for vulnerability data
+- **Transitive dependencies** not fully evaluated yet
+- **`peerDependencies`** not evaluated unless also declared as direct dependencies
+- **Trust downgrade detection** requires prior install state in `node_modules`
+- **`bun install`** uses manifest-only analysis (lockfile parity not yet implemented)
+- **`safeinstall check`** evaluates direct dependencies only
+- Ambiguous metadata blocks instead of guessing — by design
+
+## What it does not do
+
+- Vulnerability scanning or CVE databases
+- Registry proxying or tarball rewriting
+- Malware detection or provenance attestation
+- Selective lifecycle script execution (forwards `--ignore-scripts` by default)
+
+---
+
+## Works with
+
+SafeInstall works with any tool that runs package manager commands — including AI coding assistants:
+
+**Cursor** · **GitHub Copilot** · **Cline** · **Claude Code** · **Windsurf** · **Aider** · **Devin** · **Continue**
+
+Just prefix your install commands with `safeinstall`. Same workflow, one safety layer.
+
+---
+
+## Contributing
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+Issues and PRs welcome. Author merges at own discretion — this is a solo-maintained project.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Disclaimer
+
+SafeInstall is provided as-is under the MIT license. It is a policy tool that enforces configurable rules on package installs. It does not guarantee the safety of any package, does not detect all supply-chain attacks, and does not replace professional security review. Use at your own risk. The authors are not liable for any damages arising from the use of this software.
+
+---
+
+<p align="center">
+  <a href="https://safeinstall.dev">safeinstall.dev</a> · <a href="https://www.npmjs.com/package/safeinstall">npm</a> · <a href="https://github.com/Mickdownunder/SafeInstall">GitHub</a>
+</p>

package/SUPPORT.md

@@ -0,0 +1,42 @@
+# Support
+
+SafeInstall is a solo-maintained open-source project. Issues and PRs are welcome — the author reviews and merges at own discretion.
+
+SafeInstall is designed to fail closed when project metadata is stale, inconsistent, or ambiguous.
+
+## Before Reporting a Problem
+
+Run these commands in the affected project:
+
+```bash
+safeinstall --json npm install
+safeinstall --json npm ci
+safeinstall --json pnpm install
+safeinstall check --json
+```
+
+Use the command that matches the package manager and workflow you expected to use.
+
+## Include This Information
+
+- SafeInstall version (`safeinstall --version`)
+- Node.js version
+- Package manager and version
+- Exact SafeInstall command
+- Exact JSON output
+- Relevant `packageManager` field from `package.json`
+- Whether the project uses `package-lock.json`, `npm-shrinkwrap.json`, or `pnpm-lock.yaml`
+- Redacted `safeinstall.config.json` if one exists
+
+## Expected Support Boundary
+
+- SafeInstall supports direct dependency policy checks
+- SafeInstall supports lockfile-aware project installs for npm and pnpm
+- SafeInstall intentionally blocks ambiguous workspace-targeting commands
+- SafeInstall intentionally blocks when lockfile state is incomplete or conflicting
+
+## Known Limits In 0.1.0
+
+- No transitive dependency policy
+- No bun lockfile-aware project install analysis
+- No selective lifecycle-script execution even when scripts are allowlisted

package/dist/async.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapConcurrent = mapConcurrent;
+async function mapConcurrent(values, concurrency, mapper) {
+    if (!Number.isInteger(concurrency) || concurrency < 1) {
+        throw new Error(`Concurrency must be a positive integer. Received: ${concurrency}.`);
+    }
+    if (values.length === 0) {
+        return [];
+    }
+    const results = new Array(values.length);
+    let nextIndex = 0;
+    async function runWorker() {
+        while (true) {
+            const currentIndex = nextIndex;
+            nextIndex += 1;
+            if (currentIndex >= values.length) {
+                return;
+            }
+            results[currentIndex] = await mapper(values[currentIndex], currentIndex);
+        }
+    }
+    const workerCount = Math.min(concurrency, values.length);
+    await Promise.all(Array.from({ length: workerCount }, () => runWorker()));
+    return results;
+}

package/dist/check-flow.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCheckFlow = runCheckFlow;
+const config_1 = require("./config");
+const evaluations_1 = require("./evaluations");
+const output_1 = require("./output");
+const project_state_1 = require("./project-state");
+const project_discovery_1 = require("./project-discovery");
+const project_installs_1 = require("./project-installs");
+const registry_1 = require("./registry");
+const signals_1 = require("./signals");
+const specs_1 = require("./specs");
+function configLabel(configPath) {
+    return configPath ?? "built-in defaults";
+}
+function createProjectIssueReason(message) {
+    if (message.includes("both pnpm-lock.yaml and an npm lockfile exist")) {
+        return {
+            code: "ambiguous-lockfiles",
+            message,
+            suggestion: "Set packageManager in package.json or remove the stale lockfile so SafeInstall can choose one source of truth."
+        };
+    }
+    if (message.includes("required for safeinstall")) {
+        return {
+            code: "lockfile-required",
+            message,
+            suggestion: "Create or refresh the lockfile before relying on SafeInstall for project-level checks."
+        };
+    }
+    if (message.includes("specifier")) {
+        return {
+            code: "lockfile-specifier-mismatch",
+            message,
+            suggestion: "Regenerate the lockfile so package.json and the lockfile match."
+        };
+    }
+    return {
+        code: "check-blocked",
+        message,
+        suggestion: "Fix the project metadata inconsistency and run safeinstall check again."
+    };
+}
+function createAffectedPackage(evaluation) {
+    return {
+        name: evaluation.requested.name,
+        requested: evaluation.requested.raw,
+        sourceType: evaluation.requested.sourceType,
+        resolvedVersion: evaluation.resolvedRegistryPackage?.resolvedVersion,
+        reasons: evaluation.blockedReasons,
+        warnings: evaluation.warnings
+    };
+}
+async function runCheckFlow(cwd, argv, options = {}) {
+    (0, signals_1.throwIfAborted)(options.signal);
+    const invocation = await (0, project_discovery_1.resolveInvocationContext)(cwd, []);
+    const { config, path } = await (0, config_1.loadConfig)(invocation.effectiveCwd);
+    const projectTargets = await (0, project_installs_1.inferProjectInstallTargetsForCheck)(invocation.effectiveCwd, invocation.packageDir);
+    const commandString = (0, output_1.formatCommand)("safeinstall", argv);
+    if (!invocation.packageDir) {
+        return {
+            mode: "check",
+            decision: "block",
+            exitCode: 2,
+            exitCodeMeaning: "Check was blocked because the current directory does not map to a package.",
+            command: argv,
+            commandString,
+            configPath: path,
+            configLabel: configLabel(path),
+            reasons: [
+                {
+                    code: "package-root-not-found",
+                    message: "Check blocked: the current directory does not map to a package.json-backed project.",
+                    suggestion: "Run SafeInstall from a package directory."
+                }
+            ],
+            summary: "Check blocked.",
+            warnings: [],
+            affectedPackages: []
+        };
+    }
+    if (projectTargets?.issues.length) {
+        return {
+            mode: "check",
+            decision: "block",
+            exitCode: 2,
+            exitCodeMeaning: "Check was blocked because project metadata was incomplete or inconsistent.",
+            command: argv,
+            commandString,
+            configPath: path,
+            configLabel: configLabel(path),
+            reasons: projectTargets.issues.map(createProjectIssueReason),
+            summary: "Check blocked.",
+            warnings: [],
+            affectedPackages: []
+        };
+    }
+    const requestedPackages = projectTargets
+        ? projectTargets.targets.map((target) => target.requested)
+        : Object.entries(await (0, project_state_1.loadManifestDependencies)(invocation.packageDir ?? invocation.effectiveCwd)).map(([name, spec]) => (0, specs_1.parseManifestDependency)(name, spec));
+    if (requestedPackages.length === 0) {
+        return {
+            mode: "check",
+            decision: "allow",
+            exitCode: 0,
+            exitCodeMeaning: "Check passed; there were no direct dependencies to evaluate.",
+            command: argv,
+            commandString,
+            configPath: path,
+            configLabel: configLabel(path),
+            reasons: [],
+            summary: "Check skipped: package.json has no direct dependencies.",
+            warnings: [],
+            affectedPackages: []
+        };
+    }
+    const registryClient = new registry_1.RegistryClient({
+        registryUrl: config.registryUrl,
+        signal: options.signal
+    });
+    const evaluations = await (0, evaluations_1.evaluateRequestedPackages)(invocation.packageDir ?? invocation.effectiveCwd, requestedPackages, registryClient, config);
+    const blocked = evaluations.filter((evaluation) => evaluation.blockedReasons.length > 0);
+    const warnings = evaluations.flatMap((evaluation) => evaluation.warnings);
+    if (blocked.length > 0) {
+        return {
+            mode: "check",
+            decision: "block",
+            exitCode: 2,
+            exitCodeMeaning: "Check found dependencies that violate the current policy.",
+            command: argv,
+            commandString,
+            configPath: path,
+            configLabel: configLabel(path),
+            reasons: blocked.flatMap((evaluation) => evaluation.blockedReasons),
+            summary: "Check blocked.",
+            warnings,
+            affectedPackages: blocked.map(createAffectedPackage)
+        };
+    }
+    return {
+        mode: "check",
+        decision: "allow",
+        exitCode: 0,
+        exitCodeMeaning: "Check passed with no direct dependency policy violations.",
+        command: argv,
+        commandString,
+        configPath: path,
+        configLabel: configLabel(path),
+        reasons: [],
+        summary: "Check passed: no direct dependency policy violations found.",
+        warnings,
+        affectedPackages: requestedPackages.map((requested) => ({
+            name: requested.name,
+            requested: requested.raw,
+            sourceType: requested.sourceType,
+            reasons: [],
+            warnings: []
+        }))
+    };
+}

package/dist/cli-options.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCliOptions = parseCliOptions;
+function parseCliOptions(argv) {
+    let json = false;
+    const args = [];
+    for (const token of argv) {
+        if (token === "--json") {
+            json = true;
+            continue;
+        }
+        args.push(token);
+    }
+    return { args, json };
+}