pnpmcheker 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omar Del Rio
+
+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,125 @@
+# Bestprac
+
+Bestprac checks NPM-based projects for practical best-practice signals without relying on AI for the critical findings.
+
+The primary analyzer is deterministic. It reads local project files and reports on:
+
+- `package.json` presence and package manager pinning
+- lockfile presence, lockfile conflicts, and lockfile/package-manager mismatch
+- Node runtime support windows and upcoming expiration risk
+- committed npm token risk in `.npmrc`
+- pnpm adoption opportunities and pnpm security settings
+- test, lint, typecheck, CI, and dependency-update automation
+- developer tooling opportunities such as TypeScript, ESLint, Prettier, Vitest/Jest, lockfile-lint, and commit hooks
+
+Optional npm registry metadata checks enrich the report with package deprecation and stale package activity. These use the npm registry directly and do not use AI.
+
+For projects using pnpm, Bestprac also checks for supply-chain hardening in `pnpm-workspace.yaml`:
+
+- `minimumReleaseAge: 1440` or higher
+- `minimumReleaseAgeStrict: true`
+- `trustPolicy: no-downgrade`
+- `blockExoticSubdeps: true` or the modern pnpm default
+- build-script approvals from `pnpm approve-builds`
+
+## Run the App
+
+```bash
+pnpm install
+pnpm build
+pnpm start
+```
+
+Open `http://localhost:4174` and enter the absolute path to an npm project.
+
+For live development:
+
+```bash
+pnpm dev
+```
+
+## CLI
+
+```bash
+pnpm cli /path/to/project
+pnpm cli /path/to/project --no-registry
+pnpm cli /path/to/project --json
+pnpm cli /path/to/project --json --output /tmp/bestprac-report.json --fail-on never
+```
+
+The CLI exits with code `1` when any failing check is present, which makes it usable in CI.
+
+Use `--fail-on warn` to fail on warnings and failures, or `--fail-on never` when an agent should always receive a parseable report.
+
+## Single Executable
+
+Build a native executable for the current platform:
+
+```bash
+pnpm build:exe
+```
+
+The output is written to `dist/bin/bestprac` on macOS/Linux or `dist/bin/bestprac.exe` on Windows.
+
+The builder creates a bundled CLI first, then produces a single executable. It auto-selects the best local builder:
+
+- Node SEA when the local Node binary supports `--build-sea` and contains the SEA fuse marker
+- Bun `build --compile` when Bun is available
+
+Force a builder with:
+
+```bash
+BESTPRAC_EXECUTABLE_BUILDER=bun pnpm build:exe
+BESTPRAC_EXECUTABLE_BUILDER=node-sea pnpm build:exe
+```
+
+## Codex Skill
+
+A local Codex skill was installed at:
+
+```text
+/Users/omardelrio/.codex/skills/bestprac-check
+```
+
+Agents can invoke it with `$bestprac-check`. Its wrapper script prefers the compiled executable and falls back to the development CLI:
+
+```bash
+node /Users/omardelrio/.codex/skills/bestprac-check/scripts/run-bestprac.mjs /path/to/project --no-registry
+```
+
+## Secure npm Publishing
+
+The publish workflow lives at `.github/workflows/publish-npm.yml` and runs when a GitHub Release is published. It uses npm Trusted Publishing through GitHub Actions OIDC instead of a long-lived `NPM_TOKEN`.
+
+Required npm setup:
+
+1. On npmjs.com, open the `bestprac` package settings.
+2. Add a Trusted Publisher:
+   - Provider: GitHub Actions
+   - Owner: `omardelrio`
+   - Repository: `npmrepocheck`
+   - Workflow filename: `publish-npm.yml`
+   - Environment name: `npm-publish`
+   - Allowed action: `npm publish`
+3. After the first trusted publish works, set Publishing access to require 2FA and disallow tokens.
+4. Revoke any old npm automation tokens.
+
+Required GitHub setup:
+
+1. Create the `npm-publish` environment.
+2. Add required reviewers for that environment.
+3. Restrict who can publish releases or create release tags.
+
+Release flow:
+
+```bash
+pnpm version patch
+git push origin main --follow-tags
+gh release create "v$(node -p 'require("./package.json").version')" --generate-notes
+```
+
+The workflow validates lint, formatting, typecheck, tests, build, lockfile policy, and Bestprac before running `npm pack --dry-run` and `npm publish --access public`.
+
+## Notes
+
+Node release-line dates are embedded from the Node.js Release Working Group schedule and should be refreshed as upstream dates change.

package/dist/analyzer/index.d.ts

@@ -0,0 +1,3 @@
+import type { AnalyzeOptions, BestPracticeReport } from "./types.js";
+export declare function analyzeProject(projectPath: string, options?: AnalyzeOptions): Promise<BestPracticeReport>;
+export declare function isDirectory(filePath: string): Promise<boolean>;