diff --git a/CHANGELOG.md b/CHANGELOG.md index 1944ab4..e57c82e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/README.md b/README.md index 8d2c9e9..37b845f 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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) diff --git a/cmd/pdd/main.go b/cmd/pdd/main.go index 830b7f6..c0b61ee 100644 --- a/cmd/pdd/main.go +++ b/cmd/pdd/main.go @@ -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())) } diff --git a/demo_files.go b/demo_files.go new file mode 100644 index 0000000..63931c6 --- /dev/null +++ b/demo_files.go @@ -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 } diff --git a/docs/browser-checks.md b/docs/browser-checks.md index 42d8301..9828f97 100644 --- a/docs/browser-checks.md +++ b/docs/browser-checks.md @@ -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) diff --git a/docs/distribution.md b/docs/distribution.md index 321d584..039cec1 100644 --- a/docs/distribution.md +++ b/docs/distribution.md @@ -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 ``` @@ -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. @@ -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 diff --git a/docs/first-project.md b/docs/first-project.md new file mode 100644 index 0000000..edd9ac2 --- /dev/null +++ b/docs/first-project.md @@ -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) diff --git a/internal/cli/cli.go b/internal/cli/cli.go index c24725a..1b68804 100644 --- a/internal/cli/cli.go +++ b/internal/cli/cli.go @@ -32,6 +32,7 @@ Usage: pdd [--cwd DIR] [--plan NAME] [--json] [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 @@ -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 @@ -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") @@ -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 == "" { diff --git a/internal/cli/demo.go b/internal/cli/demo.go new file mode 100644 index 0000000..2a313b6 --- /dev/null +++ b/internal/cli/demo.go @@ -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, "") +} diff --git a/scripts/smoke.py b/scripts/smoke.py index a16c797..8591f72 100644 --- a/scripts/smoke.py +++ b/scripts/smoke.py @@ -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")