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
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
# Changelog

## v0.4.0

- Bundle the reviewed login example in `pdd demo` for first-time users.
- Show current check verdicts, negative examples and log links in HTML reports.
- Run named Playwright tests and record first-attempt results, screenshots and traces.
- Add a Chromium wallet example and a walkthrough for a separate Go module.

## v0.3.0

- Add request-driven planning, contextual decision cards and original-intent mappings.
Expand Down
31 changes: 14 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ When a change touches who can sign in, what can be authorized, or when a balance

Start with one decision in an existing Go project. The core workflow works without an LLM account.

[Try the login example](#try-it) · [Use it in your project](#use-it-in-your-project) · [Download pdd](https://github.com/cruskell/pdd-kit-go/releases/tag/v0.3.0)
[View live report examples](https://pdd-kit-go-demo.cruskell.chatgpt.site) · [Try the login example](#try-it) · [Use it in your project](#use-it-in-your-project) · [Download pdd](https://github.com/cruskell/pdd-kit-go/releases/tag/v0.4.0)

## What a proof catches

Expand All @@ -23,36 +23,33 @@ An implementation that always returns `false` satisfies a rejection-only rule. I

## Try it

Use Go 1.20 or newer and Docker on a 64-bit host. Put the Go install directory on your `PATH`, or use the [checksummed binaries](https://github.com/cruskell/pdd-kit-go/releases/tag/v0.3.0). To use a local Gobra JAR, see [troubleshooting](docs/troubleshooting.md).
Use Go 1.20 or newer and Docker on a 64-bit host. Put the Go install directory on your `PATH`, or use the [checksummed binaries](https://github.com/cruskell/pdd-kit-go/releases/tag/v0.4.0). To use a local Gobra JAR, see [troubleshooting](docs/troubleshooting.md).

```sh
go install github.com/cruskell/pdd-kit-go/cmd/pdd@v0.3.0
git clone https://github.com/cruskell/pdd-kit-go.git
cd pdd-kit-go
pdd plan
go install github.com/cruskell/pdd-kit-go/cmd/pdd@v0.4.0
pdd demo
```

`pdd plan` lets you inspect the rule, checks, proposed mutations and caller assumptions before you run the verifier. The following commands reuse the repository's demonstration approval. For your own rules, record your team's review as shown below.
`pdd demo` writes the bundled login example into a new `pdd-demo` directory,
imports its demonstration approval, and runs the real Gobra and Go checks.
Docker pulls the pinned Gobra image on the first run. The command prints the
HTML report and receipt paths. Choose another empty name with `--out DIR`.

```sh
docker pull ghcr.io/viperproject/gobra@sha256:5e96431b06c2e6209aa767df9153bb4cf8b2620598598f1d7d3f3a74c09c14f9
pdd import-approval --from .pdd/reviews/default.json
pdd prove
pdd status
```

Look for these two lines in `pdd prove` output. Each shows what the corresponding check established.
The report shows the same two requirement results that `pdd prove` prints.

```text
login-decision: proved (formal)
login-boundary: evidenced (empirical)
```

Open the `receipt.md` path printed by `pdd prove` to see the checks, rejected mutations, trusted assumptions, and proof limits. `pdd status` checks that the latest receipt still matches the current source and approval. For the requirements, test results, rejected mutations, and links to logs on one page, run `pdd report --out .pdd/results/login.html` and open the HTML file.
Open the report path to see the two results, three rejected mutations, and links
to the saved logs. Explore the source and review with `pdd --cwd pdd-demo plan`.
After edits, rerun `pdd --cwd pdd-demo prove` and regenerate the HTML with
`pdd --cwd pdd-demo report --out .pdd/results/demo.html`.

## Use it in your project

Pick a production function that makes an important decision. Keep the rule in the Go core and use named Go tests where the application connects it to HTTP, storage, or external libraries.
Pick a production function that makes an important decision. For a runnable walkthrough in a separate Go module, see [prove one function](docs/first-project.md). Keep the rule in the Go core and use named Go tests where the application connects it to HTTP, storage, or external libraries.

1. Run `pdd init` in your repository. Add `// @ ensures` contracts to the production `.go` files and fill in `.pdd/plan.json` with the rule, checks, trust assumptions, and a deliberate negative mutation for each formal clause. [Plan format](docs/plan-format.md)
2. Run `pdd lint` and `pdd plan`. Use `pdd plan --diff` when revisiting an approved contract. Record which guarantees and assumptions a reviewer accepts with `pdd approve --reviewer "$REVIEWER" --accept-tcb "$TRUST_IDS" --expect-digest "$REVIEWED_DIGEST"`, substituting your reviewer, comma-separated trust IDs, and the digest from the plan they inspected. [Signed reviews](docs/signed-reviews.md)
Expand Down
2 changes: 1 addition & 1 deletion cmd/pdd/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ func buildVersion() string {
if info, ok := debug.ReadBuildInfo(); ok && info.Main.Version != "" && info.Main.Version != "(devel)" {
return info.Main.Version
}
return "0.3.0-dev"
return "0.4.0-dev"
}

func main() { os.Exit(cli.Run(os.Args[1:], os.Stdout, os.Stderr, buildVersion())) }
15 changes: 15 additions & 0 deletions demo_files.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
package pddkit

import (
"embed"
"io/fs"
)

// Explicit file patterns keep the bundled demo identical to the reviewed
// repository example and exclude workspace state from installed binaries.
//
//go:embed go.mod .pdd/plan.json .pdd/reviews/default.json examples/login/login.go examples/login/login_test.go
var demoFiles embed.FS

// DemoFiles returns the login example and its portable demonstration approval.
func DemoFiles() fs.FS { return demoFiles }
3 changes: 1 addition & 2 deletions docs/browser-checks.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,7 @@ execution log, the Playwright JSON, and any saved failure screenshots and traces

Use a Go toolchain, the pinned Gobra image, and Node.js 20 or newer for this
example. Install Playwright and Chromium once on the machine running the check.
Run these commands from the repository root with a `pdd` binary built from this
checkout.
Run these commands from the repository root with `pdd` v0.4.0 or newer.

```sh
browser_tools=$(mktemp -d)
Expand Down
8 changes: 4 additions & 4 deletions docs/distribution.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Versioned binaries and checksums are published on [GitHub Releases](https://gith
Go users can install the tagged CLI directly:

```sh
go install github.com/cruskell/pdd-kit-go/cmd/pdd@v0.3.0
go install github.com/cruskell/pdd-kit-go/cmd/pdd@v0.4.0
pdd --version
```

Expand All @@ -24,10 +24,10 @@ Release builds use the exact Go 1.27.4 toolchain. Fetch it from
From a clean checkout of the release commit, with Python 3 available:

```sh
GO=/path/to/go1.27.4/bin/go python3 scripts/release.py v0.3.0
GO=/path/to/go1.27.4/bin/go python3 scripts/release.py v0.4.0
```

The script produces five archives under `dist/v0.3.0`: Linux amd64/arm64,
The script produces five archives under `dist/v0.4.0`: Linux amd64/arm64,
macOS amd64/arm64 and Windows amd64, plus `BUILD.json` and `SHA256SUMS`.
It disables CGO, VCS stamping and local file paths, embeds the requested CLI
version, records the commit/toolchain/flags, and normalizes archive metadata.
Expand Down Expand Up @@ -67,7 +67,7 @@ example reviews, run actual proofs and HTTP tests, kill mutants and check stale
source handling. It needs Go and Docker with the pinned image already pulled:

```sh
python3 scripts/smoke.py --pdd /absolute/path/to/pdd --version v0.3.0
python3 scripts/smoke.py --pdd /absolute/path/to/pdd --version v0.4.0
```

The [release workflow](../.github/workflows/release.yml) builds and validates
Expand Down
96 changes: 96 additions & 0 deletions docs/first-project.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
# Prove one function in your Go project

Start with a small production decision. This example proves that an inventory
reservation is accepted exactly when the amount is positive and stock is
sufficient. It also runs a named Go test for representative cases.

## Create the example module

Use `pdd` v0.4.0, Go and Docker. Run this block in a new scratch directory.

```sh
go mod init example.com/inventory
cat > stock.go <<'GO'
package inventory

// @ ensures allowed == (requested > 0 && requested <= available)
func CanReserve(available, requested int) (allowed bool) {
return requested > 0 && requested <= available
}
GO
cat > stock_test.go <<'GO'
package inventory

import "testing"

func TestReservationBoundary(t *testing.T) {
if !CanReserve(3, 3) || CanReserve(3, 4) || CanReserve(3, 0) {
t.Fatal("incorrect reservation decision")
}
}
GO
mkdir .pdd
cat > .pdd/plan.json <<'JSON'
{
"schema": 1,
"name": "Inventory reservation",
"intent": "Allow exactly positive reservations within available stock",
"non_goals": ["Correctness of storage, concurrency and callers"],
"requirements": [
{"id":"reservation-policy","kind":"formal","text":"Allow exactly quantities within stock","check":"proof","file":"stock.go","function":"CanReserve","ensures":"allowed == (requested > 0 && requested <= available)"},
{"id":"boundary-cases","kind":"empirical","text":"Exercise zero, exact stock and overstock cases","check":"tests"}
],
"checks": [
{"id":"proof","kind":"gobra","files":["stock.go"]},
{"id":"tests","kind":"go-test","package":".","tests":["TestReservationBoundary"]}
],
"trusted_boundary": [],
"mutations": [
{"id":"deny-everyone","kind":"last-return","requirement":"reservation-policy","check":"proof","file":"stock.go","find":"","replace":"return false"}
]
}
JSON
pdd lint
pdd plan
```

The `ensures` clause captures both directions, so a function that always denies
reservations fails the contract. Review the plan and copy its printed `Digest`
into the next command.

```sh
pdd approve --reviewer YOUR_NAME --expect-digest REVIEWED_DIGEST
pdd prove
pdd status
pdd report --out .pdd/results/inventory.html
```

`reservation-policy` should be `proved` and `boundary-cases` should be
`evidenced`. The HTML links to the negative example and test logs. For your own
project, model caller obligations as explicit trust assumptions with named tests.

## Move the same check into CI

Export the approval after a reviewer has inspected the concrete contract. Commit
it alongside `.pdd/plan.json` and the annotated source.

```sh
pdd export-approval --to .pdd/reviewed-inventory.json
```

A GitHub Actions job can run these steps after checkout and Go setup:

```yaml
- name: Install PDD
run: go install github.com/cruskell/pdd-kit-go/cmd/pdd@v0.4.0
- name: Verify reviewed inventory policy
run: |
pdd import-approval --from .pdd/reviewed-inventory.json
pdd prove
pdd status
```

The runner needs Go and Docker. When the contract changes, have the reviewer
inspect `pdd plan --diff` and record a new approval. Use an independently
provisioned policy and signed records when CI must check reviewer authority.
[CI integration](ci.md) · [Signed reviews](signed-reviews.md)
14 changes: 13 additions & 1 deletion internal/cli/cli.go
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ Usage: pdd [--cwd DIR] [--plan NAME] [--json] <command> [options]
prove Run approved proofs, Go and Playwright checks, and negative mutations
status Check whether this plan's latest receipt is current and successful
doctor Check Go and Docker/Java prerequisites
demo Verify the bundled login example in a new directory
draft Generate a plan from --request-file; --apply installs an unapproved draft
decisions Inspect decision cards, including unresolved drafts
decide Answer a card: --id ID --option ID --reason TEXT --expect-draft HASH
Expand All @@ -50,6 +51,7 @@ Global: --policy PATH (or PDD_REVIEW_POLICY) enforces authorized, unexpired sign
Global: --cwd DIR, --plan NAME (default: default), --json, --version, --help
Named plans: .pdd/plans/NAME.json; state: .pdd/state/NAME/
The default plan keeps .pdd/plan.json and .pdd/approval.json.
demo: --out DIR (default: pdd-demo); accepts the prove tool options
init: --from PATH (optional; imports a plan without executing it)
plan: --diff
approve: --reviewer NAME --accept-tcb ID[,ID...] --expect-digest SHA256
Expand Down Expand Up @@ -142,7 +144,10 @@ func Run(args []string, out, errOut io.Writer, version string) (exitCode int) {
fs.StringVar(&expected, "expect-digest", "", "Digest of the intent and contracts reviewed")
case "plan":
fs.BoolVar(&diff, "diff", false, "Show changes since recorded review")
case "prove", "doctor":
case "prove", "doctor", "demo":
if command == "demo" {
fs.StringVar(&to, "out", "pdd-demo", "New directory for the bundled login example")
}
fs.StringVar(&goExe, "go", "go", "Go executable")
fs.StringVar(&jar, "gobra-jar", "", "Local Gobra jar instead of Docker")
fs.DurationVar(&timeout, "timeout", 2*time.Minute, "Timeout per check")
Expand Down Expand Up @@ -209,6 +214,13 @@ func Run(args []string, out, errOut io.Writer, version string) (exitCode int) {
return path
}
global.policy = resolve(global.policy)
if command == "demo" {
if paths.Name != "default" || global.policy != "" || strings.TrimSpace(to) == "" || timeout <= 0 {
return printer.finish(2, nil, "usage", fmt.Errorf("demo needs a new --out directory, positive timeout, default plan and no review policy"), "The bundled example uses its shipped local approval. Use prove for a project with a review policy.")
}
jar = resolve(jar)
return runDemo(ctx, printer, resolve(to), pdd.Options{Version: version, Runner: pdd.ToolRunner{Go: goExe, GobraJar: jar, Timeout: timeout}, Tools: pdd.ToolInfo(ctx, goExe, jar), Progress: func(line string) { fmt.Fprintln(errOut, line) }})
}
signingKey = resolve(signingKey)
if command == "keygen" {
if privateKey == "" || publicKey == "" {
Expand Down
74 changes: 74 additions & 0 deletions internal/cli/demo.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
package cli

import (
"context"
"fmt"
"io/fs"
"os"
"path/filepath"

pddkit "github.com/cruskell/pdd-kit-go"
"github.com/cruskell/pdd-kit-go/internal/pdd"
)

type demoResult struct {
Directory string `json:"directory"`
Report string `json:"report,omitempty"`
Receipt string `json:"receipt,omitempty"`
}

func runDemo(ctx context.Context, printer output, destination string, options pdd.Options) int {
result := demoResult{Directory: destination}
fail := func(err error) int { return printer.finish(1, result, "demo", err, "") }
if err := pdd.NoSymlinks(destination); err != nil {
return fail(err)
}
if err := os.Mkdir(destination, 0755); err != nil {
return fail(fmt.Errorf("create a new demo directory: %w", err))
}
files := pddkit.DemoFiles()
if err := fs.WalkDir(files, ".", func(name string, entry fs.DirEntry, err error) error {
if err != nil || entry.IsDir() {
return err
}
data, err := fs.ReadFile(files, name)
if err != nil {
return err
}
return pdd.AtomicWrite(filepath.Join(destination, filepath.FromSlash(name)), data)
}); err != nil {
return fail(err)
}
plan, err := pdd.Load(destination)
if err != nil {
return fail(err)
}
if _, err := pdd.ImportApproval(destination, plan, ".pdd/reviews/default.json"); err != nil {
return fail(err)
}
receipt, dir, err := pdd.Prove(ctx, destination, plan, options)
if err != nil {
return fail(err)
}
result.Receipt = filepath.Join(dir, "receipt.md")
report := filepath.Join(destination, ".pdd", "results", "demo.html")
if err := pdd.WriteDashboard(ctx, destination, plan.ID(), "", report); err != nil {
return fail(err)
}
result.Report = report
if !printer.json {
fmt.Fprintln(printer.out, "Report:", result.Report)
fmt.Fprintln(printer.out, "Receipt:", result.Receipt)
}
if !receipt.Success {
return fail(fmt.Errorf("demo verification did not pass; inspect the report"))
}
_, latest, err := pdd.StatusContext(ctx, destination, plan, "")
if err != nil {
return fail(err)
}
if latest != dir {
return fail(fmt.Errorf("a newer run replaced the demo receipt"))
}
return printer.finish(0, result, "", nil, "")
}
7 changes: 7 additions & 0 deletions scripts/smoke.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,13 @@ def cli(*command, success=True):

assert cli("--version")["version"] == args.version
cli("doctor")
demo_dir = Path(directory) / "demo"
demo = cli("demo", "--out", str(demo_dir))
assert demo["directory"] == str(demo_dir)
assert "deny-everyone" in Path(demo["report"]).read_text()
assert "| login-decision | formal | proved |" in Path(demo["receipt"]).read_text()
cli("demo", "--out", str(demo_dir), success=False)
print("bundled demo: clean install, proof, report and no-overwrite check passed", flush=True)
for plan in ("default", "httpwallet"):
if plan == "httpwallet":
cli("--plan", plan, "init", "--from", "examples/httpwallet/plan.json")
Expand Down
Loading