Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (protaction) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Protaction

Protaction is a terminal-first CLI that helps developers, CI jobs, platform teams, and AI coding agents run package manager workflows with stronger supply-chain guardrails.

It can preview package manager operations before they execute, scan local projects for suspicious execution paths, and install explicit shims so familiar commands such as npm install, pnpm add, or yarn install can be routed through Protaction.

Repository: marcoabate-ck/protaction

Requirements

Node.js >=22.13.0
npm, pnpm, or Yarn for the package manager workflows you want Protaction to guard

Install

Install from npm:

npm install -g protaction

Install from Homebrew:

brew install marcoabate-ck/protaction/protaction

Install from GitHub Releases with checksum verification:

curl -fsSL https://raw.githubusercontent.com/marcoabate-ck/protaction/main/install.sh | sh

The shell installer downloads the release bundle, verifies its SHA-256 checksum, installs protaction into ~/.protaction/bin, and prints PATH instructions. It does not mutate shell profiles.

Check the installation:

protaction --help

Quickstart

Create a conservative project config:

protaction init --yes

Preview a package manager command without executing it:

protaction preview npm install
protaction preview pnpm add react
protaction preview yarn add react

Scan the current project without executing project code:

protaction detect

Diagnose package managers, shims, config, PATH, and active policy:

protaction doctor

Common Workflows

Preview Dependency Changes

Use preview before running install, add, or update commands:

protaction preview npm install
protaction preview pnpm add lodash
protaction preview yarn upgrade

Preview output includes a deterministic risk score, risk label, reason ids, dependency categories, lifecycle script changes, and policy decisions. Protaction does not execute the wrapped package manager command during preview.

Scan A Codebase

Use detect to inspect project files, package scripts, and tooling config without importing or executing project code:

protaction detect
protaction detect --json

Findings include stable rule ids, severity, confidence, evidence, and recommendations.

Install Package Manager Shims

Shims are explicit and reversible. They let Protaction guard familiar package manager commands by placing controlled wrappers earlier in your PATH.

protaction shim --npm
protaction shim --pnpm
protaction shim --yarn
protaction shim status --all

Remove shims when you no longer need them:

protaction shim remove --npm
protaction shim remove --all

Diagnose An Environment

Use doctor when you need to understand which package manager binaries are active and whether Protaction is guarding the expected paths:

protaction doctor
protaction doctor --json

Doctor reports package manager discovery, real binary paths, shim status, PATH ordering, config sources, active policy, Corepack, nvm, mise, asdf, and Volta. It reports environment state without mutating your shell, PATH, shims, or project files.

Configuration

Create a default config with:

protaction init --yes

Example:

schemaVersion: 1
mode: warn
packageManagers:
  npm:
    enabled: true
    preview: auto
  pnpm:
    enabled: true
    preview: auto
  yarn:
    enabled: true
    preview: auto
detect:
  enabled: true
  blockSeverity: high
  include:
    - .
  exclude:
    - node_modules
    - dist
    - build
    - .git
agents:
  default:
    enabled: true
    mode: strict
    requireHumanReviewForNewDependencies: true
    requireHumanReviewForNewDirectDependencies: true
    requireHumanReviewForLifecycleScripts: true
    allowDependencyAdditions: policy-only

Supported project config files:

protaction.config.json
protaction.config.yaml
protaction.config.yml
protaction.config.js
protaction.config.ts

JSON and YAML are data-only. JS and TS configs are executable code and are loaded only when explicitly allowed by the relevant command.

CI And Automation

CI must be deterministic and non-interactive. Use JSON output and treat non-zero exit codes as policy failures:

protaction preview --ci --json --actor codex npm install
protaction detect --json
protaction doctor --json

In CI, warn thresholds fail instead of prompting. Unknown AI-agent identities fall back to the default agent policy.

Security Boundaries

Protaction guarantees these baseline boundaries:

preview does not execute the wrapped package manager command.
detect does not execute project code or import JS/TS project config.
doctor reports environment state without mutating PATH, shell profiles, shims, package manager config, or project files.
init does not install shims, mutate shell profiles, install dependencies, or execute project code.
Shims are explicit, reversible, and resolve the real package manager while skipping Protaction shim paths.
CI never prompts.

Limitations

Current preview is static and offline. It uses manifest and available lockfile metadata, but it does not fetch registry metadata or fully resolve future transitive dependency graphs.

pnpm and Yarn preview support currently covers install, add, and update basics and reports limitations where full lockfile parsing is not yet available.

Detection is deterministic and intentionally conservative. False positives are expected; findings include rule ids, evidence, severity, confidence, and recommendations to make review manageable.

Contributing

This project uses Node.js, TypeScript, Vitest, and pnpm.

The repository pins pnpm through packageManager and .nvmrc. The workspace also sets:

minimumReleaseAge: 1440, delaying newly published packages by 24 hours, including transitives.
allowBuilds: { esbuild: true }, so dependency lifecycle/build scripts are not broadly pre-approved. esbuild is narrowly allowed because Protaction uses it to build the release bundle.

Set up a checkout:

pnpm install
pnpm run build
pnpm link --global

Run local checks:

pnpm test
pnpm run build
pnpm run lint
pnpm run typecheck
pnpm run pack:dry-run

Releases are tag-driven. A tag such as v0.1.0 runs .github/workflows/release.yml, which tests, builds, lints, typechecks, builds the release bundle, renders the Homebrew formula, publishes to npm with provenance through trusted publishing/OIDC, and uploads release assets to GitHub Releases.

The release jobs use the protected release environment.

protaction