# Command catalog

Run commands from `/Users/shazi/Projects/SandboxedJs` unless stated otherwise.
Use focused commands first. Keep long logs out of model context:

```sh
some-command > /tmp/sbx-native-build.log 2>&1
tail -n 120 /tmp/sbx-native-build.log
```

Do not use the redirection form when editing source files; it is for disposable
logs only.

## Cheap inspection

```sh
git status --short
git diff --cached --check
git diff --cached --stat
python3 -m json.tool python-runtime/abi/extension-abi.json >/dev/null
```

## Build prerequisites and runtime

```sh
make -C python-runtime doctor
make -C python-runtime python PROFILE=dynamic
make -C python-runtime package PROFILE=dynamic
npm run build
```

Do not rebuild CPython when the runtime and ABI inputs have not changed and the
required output already exists.

## Extension fixtures and index

```sh
python3 python-runtime/scripts/build_extension.py \
  python-runtime/fixtures/sbx_setuptools_probe/recipe.json
python3 python-runtime/scripts/build_extension.py \
  python-runtime/fixtures/sbx_cython_probe/recipe.json
python3 python-runtime/scripts/build_extension.py \
  python-runtime/fixtures/sbx_rust_probe/recipe.json
python3 python-runtime/scripts/build_index.py
```

If a wheel changes, rebuild `index.json` before runtime tests or its digest will
correctly be stale.

## Focused tests

```sh
npx vitest run test/python-runtime/extensions.test.ts
npx vitest run test/python-runtime/resolver.test.ts
npx vitest run test/python-runtime/extension-abi.test.ts
npm run typecheck
```

Run `npm run check` only at milestone gates. Network-enabled suites are not a
default native-package check.

## Wheel inspection

```sh
python3 -m zipfile -l path/to/package.whl
python3 python-runtime/scripts/build_index.py --wheels path/to/wheel-directory
```

Prefer adding a small reusable inspection script over repeatedly embedding
complex Python in shell commands.

## Logs

Use one log per active failure under `/tmp`, named with the task and package.
Keep only:

- the exact command;
- toolchain versions when relevant;
- first causal error;
- final 80-150 lines;
- exit code.

Warnings are not tasks unless they identify incorrect output or a future
failure covered by the current milestone.