Skip to content

MacHu-GWU/sqlalchemy_upsert_kit-project / .claude/skills/pywf-oss-base

pywf-oss-base

Flagged

Shared conventions, references, and scripts of the pywf-oss skills for pywf open-source Python libraries: setup, layout, code style, tests, user docs and the agent skills that hold API and maintenance knowledge, CI and hosting, release, dependencies, and secrets. Load it before ad-hoc work on modules, tests, or docs in such a repo, for a question about these conventions, or when unsure which pywf-oss skill fits a job.

FileKindSize
SKILL.mdskill md6.5 KB
assets/community-skills.tomlconfig2.4 KB
assets/notebook-page-template.ipynbother1.1 KB
assets/raw-rst-cell.jsonconfig255 B
references/00-authoring-references.mdmarkdown6.3 KB
references/01-secrets.mdmarkdown3.0 KB
references/02-machine-setup.mdmarkdown3.2 KB
references/03-mise.mdmarkdown2.1 KB
references/04-python-versions.mdmarkdown1.8 KB
references/05-uv-dependencies.mdmarkdown2.0 KB
references/06-ruff.mdmarkdown1.9 KB
references/07-repo-layout.mdmarkdown2.3 KB
references/08-package-files.mdmarkdown3.9 KB
references/09-code-style.mdmarkdown5.6 KB
references/10-test-layout.mdmarkdown4.1 KB
references/11-test-writing.mdmarkdown2.1 KB
references/12-coverage.mdmarkdown1.1 KB
references/13-sphinx.mdmarkdown5.6 KB
references/14-docfly.mdmarkdown2.2 KB
references/15-furo.mdmarkdown1.4 KB
references/16-sphinx-design.mdmarkdown5.8 KB
references/17-nbsphinx.mdmarkdown5.0 KB
references/18-knowledge-channels.mdmarkdown3.8 KB
references/19-github-actions.mdmarkdown3.7 KB
references/20-codecov.mdmarkdown1.3 KB
references/21-readthedocs.mdmarkdown1.7 KB
references/22-versioning-and-changelog.mdmarkdown3.0 KB
references/23-release.mdmarkdown1.3 KB
references/24-dependency-upgrades.mdmarkdown3.2 KB
references/25-python-release-cycle.mdmarkdown1.4 KB
references/26-community-skills.mdmarkdown5.0 KB
references/27-skill-family-workflow.mdmarkdown6.5 KB
scripts/check_doc_xrefs.pyscript3.4 KB
scripts/check_one_import_per_line.pyscript4.2 KB
scripts/check_skill_family.pyscript6.5 KB
scripts/check_test_layout.pyscript6.2 KB
scripts/install_community_skill.pyscript8.6 KB
scripts/update_skill_index.pyscript4.1 KB

references/02-machine-setup.md

View on GitHub
---
description: "One-time setup of a maintainer's Mac: global mise, uv, git and gh, shell activation, the secrets file, where and with which scopes to create each token, account settings, and token rotation. Read when setting up a new machine, rotating a token, or when a tool is missing or a token is missing or rejected (HTTP 401 or 403)."
---

# Machine Setup

Everything here is done **once per machine**, not per repo. Afterwards, every template repo works with `mise run inst`. Secrets follow `01-secrets.md`.

---

## 1. Global tools

| Tool | Install | Why it is global |
| :--- | :--- | :--- |
| mise | `brew install mise` | Installs each per-repo tool version once per machine, and runs the tasks |
| uv | `brew install uv` | `uvx` keeps one tool cache shared by all repos (for `hst`, `ruff`, ...). Each repo still pins its own uv version. |
| git, gh | `brew install git gh`, then `gh auth login` | `gh` reads CI runs and manages GitHub repos from the terminal |

Activate mise in the shell: add this line to `~/.zshrc`, then open a new terminal.

```bash
eval "$(mise activate zsh)"
```

Check with `mise --version`, `uv --version`, and `gh auth status`. In each repo, run `mise trust` once (mise asks the first time), then `mise run inst`.

---

## 2. The secrets file

Create `$HOME/home_secret.toml` with one key path per variable in `01-secrets.md` section 1, matching the `hst get <key_path>` commands in the repos' `mise.toml`. Then restrict it to the owner:

```bash
chmod 600 ~/home_secret.toml
```

- The user writes the values. An AI only says which key paths must exist.
- Never commit the file or copy it into a repo.

---

## 3. Tokens

| Variable | Where to create it | Scope |
| :--- | :--- | :--- |
| `GITHUB_TOKEN` | <https://github.com/settings/tokens> | Classic: `repo` and `workflow`. Or fine-grained, on all repos, with Administration, Contents, Secrets, and Actions set to read and write. |
| `CODECOV_TOKEN` | codecov.io → Settings → Access | An account **API** token, not a repo upload token |
| `READTHEDOCS_TOKEN` | <https://app.readthedocs.org/accounts/tokens/> | Account API token |
| `PYPI_TOKEN` | <https://pypi.org/manage/account/token/> | "Entire account". A brand-new project cannot use a project-scoped token for its first upload. |

**Account settings, once each:**

- In Read the Docs, connect GitHub in the account settings, so new projects build on every push.
- Sign in to codecov.io with GitHub, so repos appear there.

**Rotating a token:**

1. Create the new token.
2. Replace the value in `home_secret.toml` (the user does this).
3. Run the True/False check in `01-secrets.md`.

A new Codecov API token leaves the upload secrets already stored in each GitHub repo unchanged. Rerun `mise run setup-codecov` only for a repo whose CI upload fails.

---

## 4. Diagnosing a missing token

| What happens | Cause |
| :--- | :--- |
| The True/False check prints `False` | The key path is missing from `home_secret.toml`, or `mise.toml` points at the wrong path. |
| mise errors while loading the env | `hst` failed: usually the file or the key path is missing. |
| The token is present, but a task fails with HTTP 401 or 403 | The token has expired or lacks scopes (section 3). |
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall