From f33da6e8170f481a771772deaf8ce57a7d27e8a7 Mon Sep 17 00:00:00 2001 From: random block Date: Fri, 4 Sep 2026 22:31:01 +0100 Subject: [PATCH 1/2] docs: describe safe local directory verification --- docs/codex-local-workflow.md | 86 ++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 docs/codex-local-workflow.md diff --git a/docs/codex-local-workflow.md b/docs/codex-local-workflow.md new file mode 100644 index 0000000..bd8c68a --- /dev/null +++ b/docs/codex-local-workflow.md @@ -0,0 +1,86 @@ +# Safe local verification for the DACS Directory + +This workflow verifies the Directory application from a fresh Community +worktree without borrowing mutable state or credentials from another checkout. +It uses the Node version and SDK revision already pinned by the repository. + +## Keep the worktree isolated + +- Use Node 22, as required by + `reference-implementations/dacs-directory/.nvmrc` and `package.json`. +- Do not copy `.env` files, tokens, wallets, seeds, `data/`, `node_modules/`, or + `vendor/` from another worktree. +- Keep any mutable catalog state under this worktree's + `reference-implementations/dacs-directory/data/` directory. +- Do not run the indexer or live/paid browser tests as part of local static and + unit verification. They are separate, networked activities. + +## Install the pinned dependencies + +From the Community repository root, use your normally initialized version +manager to select an already-installed Node 22, then set paths from the current +worktree rather than a fixed checkout location: + +```bash +nvm use 22 + +repo_root=$(git rev-parse --show-toplevel) +app_dir="$repo_root/reference-implementations/dacs-directory" +cd "$app_dir" + +export DACS_DIRECTORY_DATA="$app_dir/data" +export NEXT_TELEMETRY_DISABLED=1 +unset RUN_LIVE_PAID_E2E LIVE_BUTLER_ORIGIN +``` + +Read the exact SDK commit from the committed setup script, then create a clean +vendor checkout in this worktree and install both dependency trees from their +lockfiles: + +```bash +sdk_rev=$(sed -n 's/^SDK_REV="\([0-9a-f]\{40\}\)"$/\1/p' scripts/setup-sdk.sh) +test "${#sdk_rev}" -eq 40 + +mkdir -p vendor +git clone --filter=blob:none https://github.com/DACS-Agent-commerce/dacs-sdk.git vendor/dacs-sdk +git -C vendor/dacs-sdk fetch --depth 1 origin "$sdk_rev" +git -C vendor/dacs-sdk checkout --detach "$sdk_rev" + +(cd vendor/dacs-sdk && npm ci --no-audit --no-fund && npm run build) +npm ci --no-audit --no-fund +``` + +If `vendor/dacs-sdk` already exists, first confirm that it is a Git checkout, +has no local changes, and is at the pinned commit. Preserve unexpected content +instead of overwriting it. Access to the SDK repository may require your normal +GitHub authentication; do not put a token in a remote URL or committed file. + +## Run deterministic checks + +The local equivalent of the Directory CI's static, unit, and production-build +checks is: + +```bash +npm run typecheck +npm test +NEXT_PUBLIC_DIRECTORY_URL=https://directory.ci.local \ + NEXT_PUBLIC_BUTLER_ORIGIN=https://agents.ci.local \ + npm run check:deploy-config +NEXT_PUBLIC_DIRECTORY_URL=https://directory.ci.local \ + NEXT_PUBLIC_BUTLER_ORIGIN=https://agents.ci.local \ + npm run build +``` + +These commands do not require the indexer, a wallet, paid commerce, or a shared +runtime data directory. Browser checks are separate from this deterministic +verification set. + +If interactive development is needed, bind only to loopback and let the OS +choose a currently free port: + +```bash +./node_modules/.bin/next dev --hostname 127.0.0.1 --port 0 +``` + +Use the URL printed by Next.js. Do not attach to a port already used by another +worktree. From 1a271dcc0504368ae80e69420de0067c3f750441 Mon Sep 17 00:00:00 2001 From: randomblocker <130692587+randomblocker@users.noreply.github.com> Date: Tue, 13 Oct 2026 16:31:14 +0200 Subject: [PATCH 2/2] docs: make the local SDK install stop on failure and link the workflow The SDK install block was meant to be pasted into an interactive shell, where a failed fetch or checkout (or an empty pin) did not stop it, so npm ci and the build ran on the SDK's default-branch HEAD instead of the pinned revision. Run it in a set -euo pipefail subshell, refuse an existing vendor path that is not a clean checkout of its own, and verify HEAD equals the pin before building. Reruns on a clean checkout no longer fail on the clone. Also: seed data/registrations.json before next dev, say the checks match CI's commands rather than its install, point at the CI env block for the placeholder origins, and link the workflow from the Directory README. Co-Authored-By: Claude Opus 5.5 --- docs/codex-local-workflow.md | 79 +++++++++++++------ .../dacs-directory/README.md | 4 +- 2 files changed, 58 insertions(+), 25 deletions(-) diff --git a/docs/codex-local-workflow.md b/docs/codex-local-workflow.md index bd8c68a..8cbe7be 100644 --- a/docs/codex-local-workflow.md +++ b/docs/codex-local-workflow.md @@ -18,12 +18,11 @@ It uses the Node version and SDK revision already pinned by the repository. ## Install the pinned dependencies From the Community repository root, use your normally initialized version -manager to select an already-installed Node 22, then set paths from the current +manager to select an already-installed Node 22 (for example `nvm use 22`) and +confirm that `node --version` prints `v22.x`. Then set paths from the current worktree rather than a fixed checkout location: ```bash -nvm use 22 - repo_root=$(git rev-parse --show-toplevel) app_dir="$repo_root/reference-implementations/dacs-directory" cd "$app_dir" @@ -33,32 +32,57 @@ export NEXT_TELEMETRY_DISABLED=1 unset RUN_LIVE_PAID_E2E LIVE_BUTLER_ORIGIN ``` -Read the exact SDK commit from the committed setup script, then create a clean -vendor checkout in this worktree and install both dependency trees from their -lockfiles: +Read the exact SDK commit from the committed setup script, then create or +reuse a clean vendor checkout in this worktree and install both dependency trees +from their lockfiles. The block runs in a subshell with `set -euo pipefail`, so +pasting it into an interactive shell stops at the first failure instead of +building whatever the SDK checkout happens to contain. It builds only after +`HEAD` is verified to be the pinned commit: ```bash -sdk_rev=$(sed -n 's/^SDK_REV="\([0-9a-f]\{40\}\)"$/\1/p' scripts/setup-sdk.sh) -test "${#sdk_rev}" -eq 40 - -mkdir -p vendor -git clone --filter=blob:none https://github.com/DACS-Agent-commerce/dacs-sdk.git vendor/dacs-sdk -git -C vendor/dacs-sdk fetch --depth 1 origin "$sdk_rev" -git -C vendor/dacs-sdk checkout --detach "$sdk_rev" - -(cd vendor/dacs-sdk && npm ci --no-audit --no-fund && npm run build) -npm ci --no-audit --no-fund +( + set -euo pipefail + die() { echo "stopped: $*" >&2; exit 1; } + + sdk_rev=$(sed -n 's/^SDK_REV="\([0-9a-f]\{40\}\)"$/\1/p' scripts/setup-sdk.sh) + [ "${#sdk_rev}" -eq 40 ] || die "no 40-hex SDK_REV found in scripts/setup-sdk.sh" + + sdk=vendor/dacs-sdk + if [ ! -e "$sdk" ]; then + mkdir -p vendor + git clone --filter=blob:none https://github.com/DACS-Agent-commerce/dacs-sdk.git "$sdk" + fi + + # An existing path must be its own Git checkout with no local changes. + [ "$(git -C "$sdk" rev-parse --show-toplevel)" = "$(cd "$sdk" && pwd -P)" ] \ + || die "$sdk is not a Git checkout of its own; inspect it, do not overwrite it" + [ -z "$(git -C "$sdk" status --porcelain)" ] \ + || die "$sdk has local changes; inspect them, do not overwrite them" + + git -C "$sdk" fetch --depth 1 origin "$sdk_rev" + git -C "$sdk" checkout --detach "$sdk_rev" + [ "$(git -C "$sdk" rev-parse HEAD)" = "$sdk_rev" ] || die "$sdk is not at $sdk_rev" + + (cd "$sdk" && npm ci --no-audit --no-fund && npm run build) + npm ci --no-audit --no-fund +) ``` -If `vendor/dacs-sdk` already exists, first confirm that it is a Git checkout, -has no local changes, and is at the pinned commit. Preserve unexpected content -instead of overwriting it. Access to the SDK repository may require your normal -GitHub authentication; do not put a token in a remote URL or committed file. +Rerunning the block on a clean checkout is safe: it re-pins the checkout and +reinstalls. If it prints `stopped: ...` or any command fails, fix that before +continuing; do not run the checks below on a partial install. Access to the SDK +repository may require your normal GitHub authentication; do not put a token in +a remote URL or committed file. ## Run deterministic checks -The local equivalent of the Directory CI's static, unit, and production-build -checks is: +These are the same check commands as the Directory CI's typecheck, test, +origin-validation, and production-build steps. The install differs: CI runs +`npm run setup` (`npm install`), while this workflow uses `npm ci`. Use the same +placeholder origins as the `env:` block of +`.github/workflows/dacs-directory-ci.yml` (today +`NEXT_PUBLIC_DIRECTORY_URL` and `NEXT_PUBLIC_BUTLER_ORIGIN`; drop any variable +the workflow no longer sets): ```bash npm run typecheck @@ -75,8 +99,15 @@ These commands do not require the indexer, a wallet, paid commerce, or a shared runtime data directory. Browser checks are separate from this deterministic verification set. -If interactive development is needed, bind only to loopback and let the OS -choose a currently free port: +If interactive development is needed, first seed the worktree-local catalog the +way `npm run setup` does. The seed is only read when the SQLite catalog is first +created, so copy it before the first `next dev`: + +```bash +[ -f data/registrations.json ] || cp data/registrations.example.json data/registrations.json +``` + +Then bind only to loopback and let the OS choose a currently free port: ```bash ./node_modules/.bin/next dev --hostname 127.0.0.1 --port 0 diff --git a/reference-implementations/dacs-directory/README.md b/reference-implementations/dacs-directory/README.md index 48b8e3a..454124b 100644 --- a/reference-implementations/dacs-directory/README.md +++ b/reference-implementations/dacs-directory/README.md @@ -36,7 +36,9 @@ npm run dev # http://localhost:3400 ``` `setup` checks out the reviewed dacs-sdk revision pinned in -`scripts/setup-sdk.sh`; no globally installed SDK is required. Tests and static checks +`scripts/setup-sdk.sh`; no globally installed SDK is required. For a fresh, isolated +worktree with lockfile installs and loopback-only development, see +[safe local verification](../../docs/codex-local-workflow.md). Tests and static checks run with `npm test` and `npm run typecheck`. The seed smoke test can be run alone with `npm run test:seed`; it uses pinned chain bytes for the shipped ReviewBot listing so CI can prove the starter seed renders at least one active listing without depending