programming-agent

module
v0.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: Apache-2.0

README

programming-agent

CI OpenSSF Scorecard Go Reference

This repository holds prog, the toolchain of programming.tamnd.com. The content is in tamnd/programming.

prog reads the content tree and checks it against the specification. It runs each code example and compares the output with the recorded output. It renders the site and deploys it.

The toolchain started as a copy of algorithm-agent, the toolchain of algorithm.tamnd.com. The packages are copies. They do not import algorithm-agent, so the two projects can change at their own speed.

Install

You need Go 1.27 or later.

go install github.com/tamnd/programming-agent/cmd/prog@latest

You can also download a binary from the releases. Each binary has a build provenance attestation. To verify a binary, run gh attestation verify prog_linux_amd64.tar.gz -R tamnd/programming-agent.

Use

Run these commands in a clone of tamnd/programming.

Command What it does
prog new concept closures -area functions-and-abstraction/closures-and-scope Makes a node directory with the sections of its kind.
prog promote rust/errors/E0382 Makes a node from a card. The node keeps the tag and the facts, and the row leaves its register.
prog fmt Puts node.md, the registers and the topics in canonical form. Add -check to only report.
prog mint Gives each provisional id NEW-<slug> a permanent tag. Add -dry-run to see the tags first.
prog mv <slug> <new-slug> Renames or moves a node. The old URL redirects. The tag does not change.
prog check Runs the audit rules of spec 15. Rule X08 is a level finding when more than 10% of the code blocks of a node are norun. The limit is 40% in embedded-and-hardware, graphics-and-games-programming, mobile-and-desktop and distributed-and-cloud. A norun fragment of a group that runs does not count.
prog run closures Runs the code blocks of a page and compares the output with the output blocks. Add -update to write the output blocks from the runs. The blocks run in the sandbox, in CI, or on your computer with -unsafe-local.
prog compat probe match-statement Runs the probes of the compat entries of a node in the pinned image of each release, and writes the results to manifests/probes.jsonl. A probe must pass on the release that the entry gives and fail on the release before. It needs Docker or Podman. Add -all to run the probes that are already verified again.
prog run json -sandbox docker A block with deps=deps/rust/Cargo.lock uses the packages of a lock file of the node (spec 07.7). Rust reads Cargo.lock and Cargo.toml, Java reads pom.xml, and C++ reads vcpkg.json. C# reads a .csproj, for a test block only. In the sandbox, prog builds an image with the packages on top of the image of the language. The tag is a hash of the language image and the lock file, so the next run uses the same image. The image build is the only step with network. The block runs in the new image with no network. With -unsafe-local, Rust uses cargo with --offline and Java uses Maven with -o, so the packages must be in the local cache. C++ has no local support. A block that cannot get its packages, or a block of another language with deps=, is skipped with the reason deps. It does not fail.
prog run unit-testing A test block is a test file (spec 07.11). prog runs it with the test runner of the language and compares the report with the next output block. Python uses python3 -m unittest -v, and its report goes to stderr, so -update writes output stream=stderr. JavaScript and TypeScript use node --test. Go uses go test -v in a module with the name example. Rust uses rustc --test, or cargo test with deps=. Java uses the JUnit console launcher, from /opt/prog/junit.jar in the image or from the cache on your computer. With a pom.xml, prog leaves out the JUnit jars of the pom, because the launcher has JUnit already. C# needs deps= with a .csproj that names the test framework, such as xunit, and runs dotnet test. The packages come from /opt/nuget in the image or from the NuGet folder on your computer. C++ needs deps= with a vcpkg.json that names gtest or catch2, and runs only in the sandbox. The normalizers replace the timings with $TIME and the paths of the run with $WORK. A block passes when each test passes and the report matches. A test fails expect=test-failure block passes when at least one test fails. A language with no test runner, such as C, is skipped with the reason runner. A test framework that prog cannot get is skipped with the reason deps.
prog status closures Shows the ladders of a node and what the next level needs.
prog site serve Renders the site and serves it on your computer. It renders again when a file changes.
prog site check Renders the site and checks each internal link.
prog site deploy Renders the site, checks the limits of the host and uploads the tree as the static assets of the Cloudflare Worker programming with a pinned wrangler. With -preview, it uploads a version with a preview alias and does not change production. It reads CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID from the environment and does not print them.

prog help shows all commands. A command that is planned but not built yet exits with code 3 and names its milestone.

The exit codes are: 0 for success, 1 when a check finds a problem, 2 for a usage error and 3 for a planned command or a missing tool.

Layout

Directory Contents
cmd/prog The command.
node Reads the content tree and the card registers.
check The audit rules of spec 15.
status The ladders of a node (spec 04.9).
lang Build trees and native tests for each language.
contract The contracts and the shared cases of tasks (spec 10).
formal Builds the Lean package and checks the axiom policy.
viz Bundles the scenes with esbuild and checks them in a JavaScript runtime.
compat Reads the compat entries, the implementation register and the probe results (spec 09), and runs the probes.
examples Reads the code blocks of the pages, runs them and checks the output (spec 07).
markup Markdown, code blocks and math.
katex Renders TeX to HTML on the server.
site The templates, assets and pages of the site.
spec The specification. The site publishes it at /spec/.
testdata/corpus A small content tree for the tests.

Develop

make test     # go vet and go test
make lint     # golangci-lint
make site     # render testdata/corpus into build/site

Read CONTRIBUTING.md before you open a pull request. To report a security problem, read SECURITY.md.

To release, push a tag vX.Y.Z and run scripts/release.sh vX.Y.Z. A patch release comes every few merged pull requests. A minor release comes at the end of each milestone.

Roadmap

The work is in six milestones, M0 to M5, from November 2026 to December 2028. Spec 21 gives the goal and the exit criteria of each one. The milestones list the open issues.

Licence

The code is under the Apache License 2.0. The scene package viz/packages/core is under the MIT licence, so scenes in the content repository can use it. The parts from other projects are listed in THIRD_PARTY.md.

Directories

Path Synopsis
Package check runs the audit rules of spec 15.3 that `prog check` needs.
Package check runs the audit rules of spec 15.3 that `prog check` needs.
cmd
prog command
Command prog is the toolchain of tamnd/programming (spec 20.4).
Command prog is the toolchain of tamnd/programming (spec 20.4).
Package compat reads the compat entries of a feature (spec 09.2), the probes that prove them (09.4), and the register of the implementations of each language.
Package compat reads the compat entries of a feature (spec 09.2), the probes that prove them (09.4), and the register of the implementations of each language.
Package contract reads the contract and the shared cases of a problem node, and decides whether an output is right (spec 09.1 to 09.3).
Package contract reads the contract and the shared cases of a problem node, and decides whether an output is right (spec 09.1 to 09.3).
Package examples reads the fenced code blocks of the pages, runs them and checks their output (spec 07).
Package examples reads the fenced code blocks of the pages, runs them and checks their output (spec 07).
Package formal builds the Lean package of the content repository and reads what it proves (spec 07).
Package formal builds the Lean package of the content repository and reads what it proves (spec 07).
internal
jsonl
Package jsonl runs a child process that reads one JSON value per line on standard input and writes one per line on standard output.
Package jsonl runs a child process that reads one JSON value per line on standard input and writes one per line on standard output.
Package katex renders TeX math to HTML and MathML with KaTeX, with no browser and no Node.js.
Package katex renders TeX math to HTML and MathML with KaTeX, with no browser and no Node.js.
Package lang runs the native tests of the implementations (spec 09.9).
Package lang runs the native tests of the implementations (spec 09.9).
Package markup turns the Markdown of nodes and proofs into HTML (spec 06.2).
Package markup turns the Markdown of nodes and proofs into HTML (spec 06.2).
Package mutate makes the mutants of a source file (spec 09.6).
Package mutate makes the mutants of a source file (spec 09.6).
Package node reads the node directories of tamnd/programming (spec 04.3 and 04.4).
Package node reads the node directories of tamnd/programming (spec 04.3 and 04.4).
Package site renders the content tree to a static site (spec 14).
Package site renders the content tree to a static site (spec 14).
Package spec holds the specification of the project.
Package spec holds the specification of the project.
Package status computes the ladders of a node (spec 04.8): H for the human proof, L for Lean, I for each language, V for the visualization and W for the writing.
Package status computes the ladders of a node (spec 04.8): H for the human proof, L for Lean, I for each language, V for the visualization and W for the writing.
Package viz bundles the scenes of the nodes (spec 10) and checks their traces.
Package viz bundles the scenes of the nodes (spec 10) and checks their traces.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL