Skip to content

CLI acceptance snapshot, 2026-09-29

Executed Starter, real-site, offline, upgrade, and reproducible-archive checks for the local CLI candidate.
Historical CLI acceptance snapshot (2026-09-29)

This page records the 2026-09-29 validation of the local 0.1.0-dev CLI candidate at commit e623d93. Current CLI behavior is defined in the CLI and result contract.

Inputs and method

The CLI belongs to the independent oink-cli Go repository. The CLI and result contract defines its accepted boundary. The CLI introduction gives reproducible user steps. Hugo remains an external renderer. Generated sites contain normal Hugo inputs.

Input Observed baseline
Host macOS, darwin/arm64
Go go1.27.1
Hugo 0.166.0+extended+withdeploy
CLI 0.1.0-dev, local commit e623d93d589c49e5c58b8fae1bd5db720fc904cb
Embedded Starter Commit 137843b25bacd76ddd1f7ce71330bf2e3155b954, complete licensed Git archive
Generated theme pin Public github.com/pgsty/oink v1.1.0, with recorded Go checksums
Documentation-site theme Local theme HEAD b0af631 plus uncommitted changes

The Starter archive hash is e55bde279715f6d8d19d3d88671a2cf7561b515be46915b0f12c640d0ce1d958. Its recorded projections select an existing language profile, pin OINK v1.1.0, and set enableGitInfo: false for a new directory. An observed failure required the last projection. The original enableGitInfo: true caused a warning-strict build to fail before the site’s first Git commit. No Git repository or commit was created to hide that failure.

Checks used disposable source copies, module/render caches, and output directories. Original Starter and consumer source trees were not written by the CLI checks. Existing unrelated theme and documentation edits were retained. The counts below describe those inputs and CLI revisions on 2026-09-29.

Starter and ordinary Hugo

All six ordinary-Hugo cases passed --environment production --panicOnWarning, with provisioned modules and isolated caches:

Language profile Root URL /manual/ subpath Reported Hugo pages
en Passed Passed EN 90
en,zh Passed Passed EN 91, ZH 89
all Passed Passed EN 91, ZH 89, FR 89

The tests checked the expected language roots and representative Docs, Blog, and Book outputs. They compared generated source bytes before and after Hugo. The public CLI’s init command also passed separately for all three profiles, returning zero diagnostics and 94 generated source files per profile. The profiles select different root configurations and disable untranslated sample files while retaining them in the snapshot.

Starter package unit, race, and vet checks passed. Failure cases cover nonempty and symlink targets, validation failure, and target replacement after planning. They also cover cancellation rollback, concurrent modification/deletion, and archive path rejection. The regeneration script reproduced the fixed archive, provenance, and license exactly.

Real-site inspection snapshot

Each run below returned CLI exit 0 with zero recorded diagnostics.

Site shape and theme source Files HTML files References Machine artifacts
Three-language Starter, public v1.1.0, release check at /manual/ 316 142 7,042 6
OINK documentation/regression site, local theme HEAD b0af631 plus dirty changes 1,127 506 72,562 8
PIG project site, root Docs/Blog route rewrites, public v1.1.0 1,392 424 64,440 4
Repository documentation with generated catalog, public v1.1.0 3,287 1,635 851,535 12

The last three are local consumer repositories: PIG and the catalog site validate published-pin resolution, while the OINK documentation run validates the local theme checkout.

The inspection covered HTML links, anchors, resources, and emitted machine artifacts. The completed Hugo manifest enumerated 261, 766, 662, and 3,192 output declarations respectively. Every supported enabled machine output was required by its actual language and URL. Before/after manifests compared all tracked and non-ignored untracked source bytes, modes, and Git status. All four sites were unchanged (94, 415, 858, and 2,294 source files respectively).

Two real regressions were fixed during this work. A NAVJSON template rendered only English. This previously hid the missing Chinese output. The check now returns policy exit 1 with the missing output location. The check initially treated PIG’s intentional build.render: link sidebar entries as missing pages. Hugo’s effective build parameters now exclude them. Direct and cascaded regression cases verify this behavior. A paired build of the bilingual Starter also proved all 223 ordinary artifacts byte-identical before and after adding the isolated probe.

Offline execution and upgrade

On macOS, a full check of an initialized bilingual Starter passed under sandbox-exec with (deny network*), after dependency provisioning. The result was exit 0, zero diagnostics, 223 files, 95 HTML files, 4,461 references, and four machine artifacts. A separate English init also passed under the same OS-level network denial, returning exit 0, zero diagnostics, and the expected 94 generated files.

A cold-cache fixture requiring example.invalid/[email protected] returned CLI exit 2 and retained Hugo’s original module lookup disabled by GOPROXY=off evidence. A missing dependency was therefore reported as incomplete work, without silently enabling resolution.

A separate temporary site exercised a real public-module upgrade from v1.0.0 to v1.1.0. The original consumer was not used as a write target:

Operation Observed result
Preview Exit 0; candidate validated; applied: false; plan named only go.mod and go.sum
--write --expect-plan Exit 0; the matching plan was validated and applied
Repeat the same target version Exit 0; candidate validated; no proposed changes and applied: false

All three operations preserved unrelated dirty README.md content and untracked user-note.txt. The preview and write used the same plan ID and before/after module-file hashes. Replacement, workspace, dirty-file, rollback, and failure-protection cases passed the final focused Go tests and race run. Only go.mod and go.sum changed on write; backup manifests retained original bytes. Preview and repeat executions preserved all source bytes.

Real thin-wrapper smoke tests also passed in a disposable initialized site. build --json returned 0 and produced index.html. dev --json served HTTP 200, forwarded SIGINT to Hugo, and closed the listener. Hugo exited 0. The canceled wrapper reported 2, as specified by the cancellation contract. These runs used provisioned local caches without --network.

Final make test (all packages plus vet), make test-hugo (ordinary Hugo, workspace/config precedence, output manifest, missing-language regressions), and go test -race ./... passed. All three public init profiles were rerun under OS-denied networking; the cold dependency fixture again returned 2.

Archive and installation preparation

One frozen CLI source snapshot produced four binary archives and one source archive, plus SHA256SUMS. Rebuilding independently from the source archive produced the same SHA-256 values for all five archives. The tested packaging input hash was:

b07c5b98ef787dfe9924ce7b50c57d018c6149ec493124bb0103551a01535547

This final snapshot supersedes the intermediate archive experiments. All five archive checksums were verified and reproduced from the extracted source archive. Both source and binary archives include the versioned JSON schema, licenses, dependency pins, and Starter provenance. Local make install into a temporary prefix and the installed binary’s --version succeeded.

Target Evidence
darwin/arm64 Compiled; host binary executed; local installation path exercised
darwin/amd64 Cross compiled only; not executed on that architecture
linux/amd64 Cross compiled only; not executed on Linux
linux/arm64 Cross compiled only; not executed on Linux

The archive builder records the toolchain, flags, source-input hash, and platform targets.

Reproduce the relevant checks

From a CLI checkout with dependencies already provisioned:

make build
make test
make test-hugo
go run scripts/snapshot-starter.go --source ../oink-starter

To repeat rendered-site checks in the sibling layout, keep JSON and logs outside each consumer’s source tree:

oink_acceptance_dir="$(mktemp -d)"
mkdir "$oink_acceptance_dir/reports"
./bin/oink init "$oink_acceptance_dir/my-docs" --languages all
./bin/oink check --site "$oink_acceptance_dir/my-docs" --release \
  --base-url https://example.org/manual/ --json \
  > "$oink_acceptance_dir/reports/starter.json" \
  2> "$oink_acceptance_dir/reports/starter.log"
HUGO_MODULE_REPLACEMENTS="github.com/pgsty/oink -> $(cd ../oink && pwd)" \
  ./bin/oink check --site ../oink.pgsty.com --json \
  > "$oink_acceptance_dir/reports/docs.json" \
  2> "$oink_acceptance_dir/reports/docs.log"
./bin/oink check --site ../pig.pgsty.com --release --json \
  > "$oink_acceptance_dir/reports/pig.json" \
  2> "$oink_acceptance_dir/reports/pig.log"
./bin/oink check --site ../repo.pgsty.com --release --json \
  > "$oink_acceptance_dir/reports/catalog.json" \
  2> "$oink_acceptance_dir/reports/catalog.log"

On a macOS host providing sandbox-exec, after initializing a bilingual site:

./bin/oink init "$oink_acceptance_dir/my-bilingual-docs" --languages en,zh
sandbox-exec -p '(version 1) (allow default) (deny network*)' \
  ./bin/oink check --site "$oink_acceptance_dir/my-bilingual-docs" --json \
  > "$oink_acceptance_dir/reports/offline.json" \
  2> "$oink_acceptance_dir/reports/offline.log"
sandbox-exec -p '(version 1) (allow default) (deny network*)' \
  ./bin/oink init "$oink_acceptance_dir/offline-en" --languages en --json \
  > "$oink_acceptance_dir/reports/offline-init.json" \
  2> "$oink_acceptance_dir/reports/offline-init.log"

The command reference describes preview, plan review, and explicit application. Use a separate review copy for write-path testing. For the archive experiment, keep the same Go toolchain and release version:

make release VERSION=0.1.0-dev DIST=dist/first
mkdir -p dist/rebuild
tar -xzf dist/first/oink_0.1.0-dev_source.tar.gz -C dist/rebuild
make -C dist/rebuild/oink_0.1.0-dev_source release \
  VERSION=0.1.0-dev DIST=dist
cmp dist/first/SHA256SUMS \
  dist/rebuild/oink_0.1.0-dev_source/dist/SHA256SUMS

Limits and delivery state

State At this snapshot
Local implementation Six first-stage commands and versioned result format exist
Executed validation The runs described above passed for their recorded inputs
Owning checks and documentation-site make check Passed after implementation and bilingual-document updates
Commit, tag, push CLI committed locally as e623d93; no tag, remote, or push. Documentation changes remain local alongside existing work
Public CLI release or distribution Not performed
Consumer source adoption or production deployment Not performed by these checks
Independent-user study or adoption No measured 4-of-5 / 15-minute study, retention, or independent-team adoption data

Raw JSON, logs, source-preservation manifests, upgrade recovery evidence, and archive-verification results are stored in the CLI checkout’s ignored tmp/acceptance/ directory, with release archives in dist/first/.

This first-stage candidate focuses on existing OINK sites; Docsy assessment and later migration, theme descriptor, version lifecycle, OpenAPI, MCP, and Studio remain tracked in the CLI roadmap.