Public release preparation (issue #42)

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,26 @@
+---
+name: Bug report
+about: Report a bug or unexpected behavior
+title: ''
+labels: bug
+assignees: ''
+---
+
+**Describe the bug**
+A clear description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Run command '...'
+2. See error
+
+**Expected behavior**
+What you expected to happen.
+
+**Environment**
+- OS: [e.g., macOS 14, Ubuntu 22.04]
+- Shell: [e.g., bash 5.2, zsh 5.9]
+- jq version: [e.g., 1.7]
+
+**Additional context**
+Any other relevant information.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest a new feature or enhancement
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+**Problem**
+What problem does this feature solve?
+
+**Proposed solution**
+How would you like it to work?
+
+**Alternatives considered**
+Other approaches you've thought about.
+
+**Additional context**
+Any other relevant information.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## Summary
+
+Brief description of changes.
+
+## Changes
+
+- Change 1
+- Change 2
+
+## Testing
+
+How were these changes tested?
+
+## Checklist
+
+- [ ] Scripts work from any directory
+- [ ] Documentation updated (if applicable)
+- [ ] No hardcoded paths or credentials

.github/workflows/release.yml

@@ -0,0 +1,19 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          generate_release_notes: true

.gitignore

@@ -30,6 +30,7 @@ npm-install-log.json
 # IDE files
 .vscode/
 .idea/
+.cursor/
 *.sublime-project
 *.sublime-workspace
 

CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Added
+
+- Unified CLI entry point (`npm-scanner.sh`) with `scan` and `validate` commands
+- Project and package scanning with risk assessment
+- Pre-installation package validation with typosquatting detection
+- Shared caching library for npm API responses
+- HTML and JSON report generation
+- Scheduled audit capabilities with alerting
+- Credential rotation guidance for incident response
+- Comprehensive documentation
+
+### Security
+
+- Zero npm dependencies policy to prevent supply chain attacks
+- All scripts use bash and system tools only

CLAUDE.md

@@ -29,19 +29,13 @@ Security toolkit protecting Node.js developers from npm supply chain attacks (Ph
 - **generate-summary-report.sh** - Report aggregation
 - **npmrc-security-config.sh** - Secure configuration template
 
-### Deprecated
-
-- **deprecated/recursive-audit-script.sh** - Replaced by `npm-scanner.sh scan --project`
-- **deprecated/package-validator.js** - Replaced by `package-validator.sh`
-- **deprecated/npm-install-monitor.js** - Not integrated, limited value over scan commands
-
 ## Constraints
 
 ### Documentation Sync
 
 - ALWAYS update the corresponding `docs/` file when modifying any script
 - NEVER commit script changes without corresponding documentation updates
-- WHEN adding new features that affect architecture, update `docs/overview.md`
+- WHEN adding new features that affect architecture, update `docs/contributors/reference/architecture.md`
 - WHEN adding new command-line options, update the script's documentation file
 
 ### Code Quality
@@ -71,10 +65,9 @@ Security toolkit protecting Node.js developers from npm supply chain attacks (Ph
 - `docs/` - Script documentation and reference materials
 - `templates/` - Report templates (common, packages, projects)
 - `reports/` - Output directory for scan results
-- `deprecated/` - Scripts replaced by newer unified tools
 
 ## References
 
-- Script documentation: `docs/`
-- Development guide: `docs/development-guide.md`
-- Integration examples: `docs/integration-guidelines.md`
+- Documentation: `docs/README.md`
+- Contributing: `docs/contributors/how-to/contributing.md`
+- CI/CD integration: `docs/users/how-to/integrate-with-ci.md`

CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# No Code of Conduct
+
+We are all adults. We accept anyone's contributions. Nothing combative or disrespectful will be tolerated.
+
+---
+
+[NCoC](https://github.com/domgetter/NCoC)

CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing to npm-scanner
+
+Thanks for your interest in contributing!
+
+## Quick Start
+
+1. Fork and clone the repository
+2. Create a branch: `git checkout -b <issue-number>-<description>`
+3. Make your changes
+4. Run `shellcheck scripts/*.sh npm-scanner.sh`
+5. Test your changes
+6. Submit a PR
+
+## Full Guide
+
+See [docs/contributors/how-to/contributing.md](docs/contributors/how-to/contributing.md) for detailed instructions including:
+
+- Development environment setup
+- Testing procedures
+- How to add new IOCs and typosquatting targets
+- Documentation requirements
+
+## Code of Conduct
+
+This project follows the [No Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Questions?
+
+Open an issue or start a discussion.

LICENSE

@@ -1,24 +1,15 @@
-This is free and unencumbered software released into the public domain.
+ISC License
 
-Anyone is free to copy, modify, publish, use, compile, sell, or
-distribute this software, either in source code form or as a compiled
-binary, for any purpose, commercial or non-commercial, and by any
-means.
+Copyright (c) 2025
 
-In jurisdictions that recognize copyright laws, the author or authors
-of this software dedicate any and all copyright interest in the
-software to the public domain. We make this dedication for the benefit
-of the public at large and to the detriment of our heirs and
-successors. We intend this dedication to be an overt act of
-relinquishment in perpetuity of all present and future rights to this
-software under copyright law.
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
 
-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 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.
-
-For more information, please refer to <https://unlicense.org>
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

README.md

@@ -1,23 +1,19 @@
 # npm-scanner
 
-Security toolkit protecting Node.js developers from npm supply chain attacks.
+[![CI](https://github.com/virtualian/npm-scanner/actions/workflows/ci.yml/badge.svg)](https://github.com/virtualian/npm-scanner/actions/workflows/ci.yml)
+[![License: ISC](https://img.shields.io/badge/license-ISC-blue.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-1.1.0-green.svg)](VERSION)
 
-## What This Is
+Security auditing toolkit for detecting npm supply chain attacks. Detects threats that `npm audit` misses—URL dependencies (PhantomRaven-style attacks), malicious lifecycle scripts, typosquatting, and suspicious package metadata.
 
-npm-scanner detects supply chain attacks that `npm audit` misses:
-
-- **URL dependencies** - Packages fetched from HTTP URLs instead of the registry (PhantomRaven attack)
-- **Malicious lifecycle scripts** - Code that runs automatically during `npm install`
-- **Typosquatting** - Packages with names similar to popular packages
-- **Suspicious metadata** - New packages, single maintainers, low downloads
-
-It complements `npm audit` (which checks for known CVEs) by catching attacks that haven't been reported yet.
-
-See [How It Works](docs/how-it-works.md) for details.
+Zero npm dependencies by design: a security tool that depends on npm packages would be vulnerable to the same attacks it's trying to detect.
 
 ## Quick Start
 
 ```bash
+git clone https://github.com/virtualian/npm-scanner.git
+cd npm-scanner
+
 # Scan globally installed packages
 ./npm-scanner.sh scan --global
 
@@ -28,73 +24,15 @@ See [How It Works](docs/how-it-works.md) for details.
 ./npm-scanner.sh validate lodash
 ```
 
-## Commands
-
-### scan
-
-Scan installed packages or project dependencies.
-
-```bash
-./npm-scanner.sh scan --global                 # Global packages
-./npm-scanner.sh scan --local ~/projects       # node_modules directories
-./npm-scanner.sh scan --project ~/code         # Project package.json files
-./npm-scanner.sh scan --project -n 10 ~/code   # Limit to 10 packages
-```
-
-### validate
-
-Check a package before installation.
-
-```bash
-./npm-scanner.sh validate <package-name>
-```
-
-## Reports
-
-Scan results are saved to `reports/packages-TIMESTAMP/`:
-
-```
-reports/packages-2025-01-15-10h30m00s+0000-UTC/
-├── audit-report.md          # Summary with findings
-├── .work-files/
-│   └── maintainer-data.tsv  # Maintainer analytics
-└── node-<package>-*.md      # Per-package details
-```
-
-## If Issues Found
-
-**HTTP Dependencies (CRITICAL):**
-1. Do NOT run `npm install`
-2. Remove the suspicious package
-3. Run `scripts/credential-rotation-script.sh`
-4. Report to npm: security@npmjs.com
-
-**Lifecycle Scripts (WARNING):**
-Review if the package is new, has low downloads, or is single-maintainer.
-
 ## Documentation
 
-- [Full Documentation](docs/README.md)
-- [Security Indicators](docs/security-indicators.md)
-- [Integration Guidelines](docs/integration-guidelines.md)
-
-## Additional Tools
-
-Located in `scripts/`:
-
-| Script | Purpose |
-|--------|---------|
-| `credential-rotation-script.sh` | Post-compromise incident response |
-| `npm-install-monitor.js` | Network monitoring during install |
-| `scheduled-audit-script.sh` | Automated scheduled scanning |
-| `npmrc-security-config.sh` | Secure npm configuration |
+Full documentation: **[virtualian.github.io/npm-scanner](https://virtualian.github.io/npm-scanner)**
 
 ## Requirements
 
-- Bash
+- Bash, jq, curl
 - Node.js (no npm dependencies)
-- jq, curl (system tools)
 
 ## License
 
-See LICENSE file.
+ISC

SECURITY.md

@@ -0,0 +1,24 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in npm-scanner, please report it by opening a GitHub issue.
+
+For sensitive issues that shouldn't be publicly disclosed, contact the maintainers directly through GitHub.
+
+## Scope
+
+npm-scanner is a security auditing tool that analyzes npm packages. The tool itself:
+
+- Runs locally on your machine
+- Does not collect or transmit data
+- Has no external dependencies (zero npm packages)
+- Uses only system tools (bash, curl, jq)
+
+## Security Considerations
+
+When using npm-scanner:
+
+- Review flagged packages before installation
+- Keep your local tools (curl, jq, bash) updated
+- Run scans in isolated environments when analyzing untrusted packages