Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
name: CI

on:
push:
branches: [main]
pull_request:

permissions:
contents: read

jobs:
check:
name: Node ${{ matrix.node }} on ${{ matrix.os }}
runs-on: ${{ matrix.os }}
timeout-minutes: 20
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest]
node: [22, 24]

steps:
- name: Check out
uses: actions/checkout@v4

- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
cache: npm

- name: Set up Terraform
uses: hashicorp/setup-terraform@v3
with:
terraform_version: 1.15.8
terraform_wrapper: false

- name: Install dependencies
run: npm ci

- name: Typecheck, build and test
run: npm run check

- name: Audit production dependencies
run: npm audit --omit=dev

- name: Inspect package contents
run: npm pack --dry-run
42 changes: 42 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Changelog

All notable changes to this project are documented in this file.

## [0.1.1] - 2026-11-04

### Added

- Repeatable data-loss demo with real Terraform plans and local AWS mocks. It shows
the same destructive rename leaving 0 orders and 0 invoices without PlanSentry,
versus 25 orders and 3 invoices with PlanSentry.
- Live-agent demo fixture pinned to the local mock.
- Installation warning when the `plansentry` executable is not on the agent's PATH.
- CI coverage for Node.js 22 and 24 on Linux and macOS.

### Changed

- Node.js 22 or newer is now required.
- Release checks build before running tests and fail if the Terraform end-to-end
prerequisites are missing.
- Dependency updates resolve the previously reported audit findings.

### Fixed

- Hook timeouts and unexpected errors now deny infrastructure commands instead of
failing open.
- Applies behind `bash` options that take a value, and behind `time -p`, are now
detected.
- Terragrunt applies are held for approval regardless of option order.
- Nested CloudFormation stack changes now require approval because their contents
are not diffed.
- Held resources remain visible when report output is truncated by tools such as
`tail`.

### Documentation

- Added the demo recording guide and publishing checklist.
- Documented nested-stack behaviour and shell forms that are not detected.

## [0.1.0] - 2026-09-26

Initial npm release.
11 changes: 6 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
[![Codex Hook](https://img.shields.io/badge/Codex-Hook-10A37F)](#-2-min-quickstart)
[![Terraform | OpenTofu | CDK](https://img.shields.io/badge/Terraform_|_OpenTofu_|_CDK-supported-844FBA)](#-what-it-catches)
[![npm](https://img.shields.io/npm/v/plansentry.svg)](https://www.npmjs.com/package/plansentry)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/RobeyBeswick/plansentry/blob/main/LICENSE)

</div>

Expand Down Expand Up @@ -38,7 +38,7 @@ ask you to run it yourself.

## ⚡ 2 min Quickstart

Requires Node.js 20+.
Requires Node.js 22+.

```bash
npm install -g plansentry
Expand All @@ -63,7 +63,7 @@ does to a shop with **25 paid orders and three invoices**:
| Without plansentry: apply succeeds, resources are replaced | 0 | 0 |
| With plansentry: replacement blocked before apply | 25 | 3 |

Run it from a checkout with Node.js 20+, Terraform 1.5+ and `uv`:
Run it from a checkout with Node.js 22+, Terraform 1.5+ and `uv`:

```sh
npm ci
Expand All @@ -78,7 +78,8 @@ The bucket deliberately has `force_destroy` enabled to make the data-loss case v
No model, cloud account or global hook installation is needed.

The first run downloads the demo dependencies. See the [recording guide and spoken
script](docs/DEMO.md), or the optional [live-agent setup](examples/agent-demo/README.md).
script](https://github.com/RobeyBeswick/plansentry/blob/main/docs/DEMO.md), or the optional
[live-agent setup](https://github.com/RobeyBeswick/plansentry/blob/main/examples/agent-demo/README.md).

## 🔎 How It Works

Expand Down Expand Up @@ -155,7 +156,7 @@ plansentry explain "make deploy"

This project is under the **MIT** license.

Maintainers: follow the [publishing checklist](docs/PUBLISHING.md) for the demo
Maintainers: follow the [publishing checklist](https://github.com/RobeyBeswick/plansentry/blob/main/docs/PUBLISHING.md) for the demo
video, release verification and public launch.

---
Expand Down
26 changes: 26 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Security policy

## Supported versions

| Version | Supported |
| --- | --- |
| 0.1.x | Yes |
| Older | No |

## Reporting a vulnerability

Report suspected vulnerabilities privately through GitHub's private vulnerability
reporting:

https://github.com/RobeyBeswick/plansentry/security/advisories/new

Please do not open a public issue for a suspected vulnerability. Include the
affected version, a description of the impact, and reproduction steps or a proof
of concept. Do not include real credentials, customer data or production state.

Reports will be acknowledged and investigated on a best-effort basis. A fix and
coordinated disclosure will be arranged according to severity and impact.

PlanSentry guards against accidental destructive changes. It is not a sandbox
against a malicious agent, and bypasses of its intended protections are still
security-relevant.
46 changes: 46 additions & 0 deletions docs/COMPATIBILITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Compatibility and release validation

Last updated: **2026-11-04**.

This record covers the local checks performed for the 0.1.1 release candidate.
It is not a substitute for live-client testing.

## Local release candidate

| Area | Result |
| --- | --- |
| Platform | macOS ARM64 |
| Node.js | 22.23.4 |
| npm | 10.9.9 |
| Terraform | 1.15.8 |
| uv | 0.13.7 (Python 3.12 downloaded by the demo) |
| Test runner | Vitest 5.1.0 |
| Typecheck and build | Passed |
| Test suite | 145 passed, including both real Terraform end-to-end tests |
| Dependency audit | 0 vulnerabilities, including production dependencies |
| Packed package | 30 files, 41.6 kB compressed, version `0.1.1` |
| Packed-package smoke test | Passed outside the source tree: version, `explain`, project hook install/uninstall for Claude and Codex, and destructive-plan exit `3` |
| Deterministic demo | `npm run demo -- --auto` passed; the unguarded shop lost its data and the guarded shop retained 25 orders and 3 invoices |

## Integration coverage

| Integration | Status |
| --- | --- |
| Terraform | Real end-to-end tests pass locally |
| Claude Code | Hook protocol and install/uninstall are covered by tests and the packed-package smoke test. A live client permission prompt has not been verified for this release. |
| Codex | Hook protocol and install/uninstall are covered by tests and the packed-package smoke test. Live hook loading/trust has not been verified for this release. |
| OpenTofu | Not validated for this release. |
| AWS CDK | Analysis tests pass; a live `cdk deploy` against a real account was not performed. |
| AWS production deployment | Not tested. The demo uses local AWS mocks and is not evidence of production behaviour. |

## Known limits

- Terragrunt plans are not analysed; Terragrunt applies ask for approval.
- Nested CloudFormation stack contents are not diffed; changes require approval.
- Commands built at runtime and less common shell constructs are not detected.
- PlanSentry guards against accidental destructive changes. It is not a sandbox
against a malicious agent.

Live-client testing should be repeated when the advertised client versions or
permission modes change, and the results recorded here with the date, client
version and observed outcome.
4 changes: 2 additions & 2 deletions docs/DEMO.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,14 @@ are scripted; this is a reproducible guard walkthrough, not an agent recording.

## Prepare

Requires Node.js 20+, Terraform 1.5+, and `uv` on your PATH.
Requires Node.js 22+, Terraform 1.5+, and `uv` on your PATH.

```sh
npm ci
npm run demo -- --auto
```

The first run downloads Moto 5.2.2 and Terraform's AWS provider 5.100.0.
The first run downloads Python 3.12, Moto 5.2.2 and Terraform's AWS provider 5.100.0.
The provider cache is in the checkout's ignored `.demo-cache/terraform/`;
Python dependencies use uv's cache. Rehearse with network access before the
presentation. A cached run can still need the package registries for resolution.
Expand Down
71 changes: 31 additions & 40 deletions docs/PUBLISHING.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Publishing checklist

Prepared **2026-10-30**, using the same handoff format as NoMeatProxy.
Prepared **2026-10-30**, updated **2026-11-04** for the 0.1.1 release, using the same
handoff format as NoMeatProxy.
Work through the numbered steps in order: record the demo, prepare and verify
the release, make the source public, publish the package, then announce it.

Expand All @@ -10,36 +11,38 @@ registry before release. Do not try to publish `0.1.0` again.

## Current state

| Area | Verified state on 2026-10-30 |
| Area | Verified state on 2026-11-04 |
| --- | --- |
| Source | `main` at `4096830`; working tree clean before this documentation handoff |
| npm | `0.1.0` is `latest`, published 2026-09-26; registry `gitHead` is `f8d10af`, nine commits behind this checkout |
| Package metadata | Both manifests still say `0.1.0`; no `"private": true` flag |
| GitHub | Private repository; no tags, releases, Actions workflows or runs found |
| Source | Release branch `chore/public-launch` based on `main` at `3806ee7` |
| npm | `0.1.0` is `latest`, published 2026-09-26; registry `gitHead` is `f8d10af` |
| Package metadata | Both manifests say `0.1.1`; Node.js `>=22`; no `"private": true` flag |
| GitHub | Public repository; no tags or releases yet; CI workflow added and private vulnerability reporting enabled |
| Video preparation | [Three-minute spoken script and recording guide](DEMO.md), automated rehearsal and optional live-agent fixture exist |
| Finished video | No tracked video found; recording, editing, captions and upload remain |
| Release documentation | No `CHANGELOG.md`, `SECURITY.md` or dated live-client compatibility record found |
| Dependency audit | Six affected packages: two moderate, two high and two critical; production-only audit reports one moderate package (`fast-uri`) |
| Public-content review | History-aware secret scan, commit-metadata review and media review remain |
| Release documentation | `CHANGELOG.md`, `SECURITY.md` and `docs/COMPATIBILITY.md` added |
| Dependency audit | 0 vulnerabilities, including production dependencies |
| Public-content review | Gitleaks found no leaks; commit metadata reviewed; media review deferred until the video is produced |

The published package predates fixes for hook failures, shell-wrapper detection,
Terragrunt approval handling, nested stack changes and approval-report visibility,
as well as the new demo. An installation of `0.1.0` does not validate this checkout.

Local verification for source commit `4096830`:
Local verification for the `0.1.1` release candidate:

- `npm ci`, typecheck, build and **all 145 tests passed**, including both real
Terraform end-to-end tests.
- Packed-package smoke check passed: **30 files, about 41 KiB compressed**,
- Packed-package smoke check passed: **32 files, about 43 KiB compressed**,
installed outside the source tree. Version reporting, read-only allow, apply
redirect, destructive-plan exit `3`, and both agents' project hook
install/uninstall worked.
- `npm run demo -- --auto` passed: safe update applied, the unguarded shop lost
its data, the guarded shop preserved every order and invoice, the approval
responses matched expectations, and both mocks and temporary shops cleaned up.
- Runtime: Node.js `22.22.2`, npm `10.9.7`, Terraform `1.5.7`, macOS ARM64.
- Dependency audit is **not clear**; see step 3. These checks do not establish
live agent compatibility or production deployment coverage.
- Runtime: Node.js `22.23.4`, npm `10.9.9`, Terraform `1.15.8`, uv `0.13.7`,
macOS ARM64.
- Dependency audit is clear. These checks do not establish live agent
compatibility or production deployment coverage; see
[COMPATIBILITY.md](COMPATIBILITY.md).

Rerun verification after release changes. Local passes do not complete the
unchecked release tasks below.
Expand Down Expand Up @@ -123,30 +126,21 @@ produce nonzero exit codes.
- [ ] Review targeted dependency updates and the lockfile diff. Some current
audit fixes propose a Vitest major upgrade; do not apply `npm audit fix
--force` blindly. Record any remaining finding's applicability and disposition.
- [ ] Decide the supported Node versions. The package currently advertises
`>=20`, but Node 20 reached end of life on 2026-04-30 according to the
[official release schedule](https://github.com/nodejs/Release/blob/main/schedule.json).
Align `engines`, README, demo prerequisites, Node types and CI with the chosen
support policy; use maintained runtimes for launch validation.
- [ ] Ensure builds happen **before tests** in the release check. The current
`prepublishOnly` runs tests before building; Terraform end-to-end tests skip
without `dist/cli.js` or Terraform, and can otherwise exercise an old build.
Change it to `npm run typecheck && npm run build && npm test`, or use a shared
check script with that order.
- [ ] Add CI for the supported Node/platform combinations, installing Terraform
before running the checks. Node 22 and 24 on Linux and macOS are a reasonable
initial matrix; broaden advertised support only with evidence.
- [ ] Make missing end-to-end prerequisites fail the release check instead of
accepting a run with those tests skipped.
- [x] Supported Node versions are now 22 and 24. `engines`, README, demo
prerequisites, Node types and CI are aligned with that policy.
- [x] `npm run check` builds before tests, and `prepublishOnly` uses it.
- [x] CI covers Node 22 and 24 on Linux and macOS, installing Terraform before
running the checks.
- [x] Missing end-to-end prerequisites fail the release check via
`PLANSENTRY_REQUIRE_E2E=1`.
- [ ] Confirm both manifests have the release version and review
`git diff -- package.json package-lock.json`.

## 4. Finish public documentation and content review

- [ ] Add `CHANGELOG.md` covering changes since the published `0.1.0`, including
the safety fixes and reproducible demo.
- [ ] Add `SECURITY.md` with a working private reporting route; configure the
route before advertising it.
- [x] Added `CHANGELOG.md` covering changes since the published `0.1.0`.
- [x] Added `SECURITY.md`; GitHub private vulnerability reporting is enabled and
verified.
- [ ] Check the README quickstart against the release candidate. Retain the
restart/trust instructions, the need for the executable on the agent's PATH,
and the distinction between client permission modes.
Expand All @@ -156,11 +150,9 @@ produce nonzero exit codes.
- [ ] Verify AWS feature claims against current official documentation before
adding them to the launch copy. Do not present the local mock demonstration
as a production deployment test.
- [ ] Run a history-aware secret scan, such as `gitleaks git --redact .` after
installing Gitleaks, and inspect the results privately.
- [ ] Review tracked content and commit metadata for secrets, internal domains,
account identifiers, personal paths and customer information. Use synthetic
examples such as `123456789012`, `jsmith`, `Acme Corp` and `~/project`.
- [x] `gitleaks git --redact .` found no leaks across the repository history.
- [x] Tracked content and commit metadata reviewed; commit authors use GitHub
noreply addresses and examples are synthetic.
- [ ] Review any Actions logs and artifacts created during preparation before
changing visibility. GitHub makes Actions history and logs public when the
repository becomes public.
Expand Down Expand Up @@ -256,8 +248,7 @@ synthetic replacement plan with `plansentry check` to verify exit `3`; the

## 7. Make the source public and prepare the final assets

- [ ] After the content review, change GitHub visibility using repository
**Settings → General → Danger Zone → Change visibility → Public**.
- [x] Repository visibility changed to public after the content review.
- [ ] In a signed-out browser, check the repository, license, README and guides.
Resolve inaccessible or private links before announcing them.
- [ ] From the verified, merged commit on `main`, build the final package:
Expand Down
Loading
Loading