nigig-org/workflow.md

Nigig-org implementation workflow

This document records the reproducible workflow used in this session from repository acquisition through validation and Gitdab push. It deliberately excludes credentials, access tokens, and any other secret material.

1. Obtain and inspect the repository

git clone https://gitdab.com/andodeki/nigig-org.git
cd nigig-org
git log -1 --format='%H %cs %s'
git status --short

Initial review inputs were read from REVIEWS/, especially:

• REVIEWS/NIGIG_PAY_CONSOLIDATED_REVIEW.md
• REVIEWS/PAY_CAD_IMPLEMENTATION_STATUS.md
• the map, spreadsheet, CAD, and cost-estimator review documents.

The implementation work started from the review priority order: contain unsafe payment behavior first, establish a pure domain and durable storage boundary, then migrate legacy paths incrementally.

2. Preserve local work while pulling upstream changes

Do not pull over uncommitted implementation work directly. Fetch first, inspect changes, then use rebase/autostash only after confirming the target branch.

git fetch origin
git log --oneline HEAD..origin/main
git pull --rebase --autostash origin main
git status --short

This session pulled upstream commit e9616c3 (added missing crates) and preserved local changes through Git’s autostash mechanism.

3. Repair vendored crate paths after upstream import

Upstream added Robius crates under crates/, while dependent manifests still pointed to old sibling-repository paths.

The local crate paths were repaired for:

• robius-sms
• robius-ussd
• robius-fingerprinting
• robius-contacts
• robius-trigger

The root workspace list was also repaired to add commas, remove a duplicate member, and include each imported crate once.

Validation used Python’s TOML parser and direct path checks:

python3 - <<'PY'
import tomllib
from pathlib import Path
for manifest in [Path('Cargo.toml'), *Path('crates').rglob('Cargo.toml')]:
    tomllib.loads(manifest.read_text())
print('all Cargo manifests parse')
PY

The full workspace is not claimed buildable in a standalone checkout until all external Makepad and remaining Robius sibling dependencies are available or vendored.

4. Use isolated, self-cleaning Rust tests

The repository contains:

tools/test-rust-clean.sh

It creates a temporary directory containing:

• isolated RUSTUP_HOME;
• isolated CARGO_HOME;
• isolated build target;
• copied pure crate(s), outside the incomplete workspace dependency graph;
• a minimal Rust toolchain and rustfmt.

It removes the entire environment through a shell trap on success, failure, interruption, or termination.

Run pure domain tests:

TEST_TARGET=domain ./tools/test-rust-clean.sh

Run storage tests:

TEST_TARGET=storage ./tools/test-rust-clean.sh

To inspect a failed temporary environment only:

KEEP_TEST_ENV=1 TEST_TARGET=storage ./tools/test-rust-clean.sh

Then delete the retained temporary path manually after diagnosis. Do not retain toolchains/caches inside the repository or user home directory.

5. Validate each implementation tranche

Before committing each feature:

git diff --check
TEST_TARGET=domain ./tools/test-rust-clean.sh
TEST_TARGET=storage ./tools/test-rust-clean.sh

Use only relevant isolated tests when a feature changes one pure crate. Be explicit if full application compilation cannot run because external GUI/platform dependencies are absent.

6. Commit focused changes

Use one focused commit for one tested implementation tranche:

git add <specific files>
git commit -m '<type>(pay): concise description'
git log -1 --format='%H %s'

Repository-local identity used in this session:

git config user.name 'andodeki'
git config user.email 'andodeki@noreply.gitdab.com'

Do not set a global identity unless the developer explicitly wants that behavior.

7. Push to Gitdab

Push only after validation and a successful focused commit:

git push origin main

If HTTPS credentials are unavailable in a non-interactive environment, configure authentication through a secure credential helper, SSH deploy key, or an access token supplied through a secure mechanism. Never commit, log, store, or copy a token into repository files, workflow documents, shell history, or Git remote configuration.

After pushing:

git status --short
git log -1 --format='%H %s'

The expected result is a clean working tree and the pushed commit at origin/main.

8. Current payment migration order

The current safe migration sequence is:

1. Keep default builds tracker-only.
2. Block legacy PIN UI, PIN request creation, USSD dispatch, automatic retry, and bulk dispatch outside explicit demo mode.
3. Use exact-domain PaymentIntent, Money, validation and fee calculation.
4. Persist payment intent transitions through SQLite and a single storage worker.
5. Import legacy JSON pending records conservatively as reconciliation-required where outcome is ambiguous.
6. Wire startup migration once, then move authoritative UI reads from legacy JSON to SQLite.
7. Only then replace the legacy thread-local PayFlowHandler with the coordinator/application-service path.
8. Add SQLCipher/Keystore integration and provider-authorized gateway before enabling production payment dispatch.

9. Non-negotiable rules

• No production default path may collect or retain an M-Pesa PIN.
• No ambiguous session/SMS outcome may be called a known payment failure or success.
• No automatic replay of a financial dispatch after an ambiguous outcome.
• No silent unknown fee fallback to zero.
• No git push before test/check results are known.
• No access token or credential in committed files or workflow documentation.