wads.project_setup

Project setup utilities: name checking, GitHub operations, and orchestration.

This module provides the building blocks for AI-assisted project creation. Each function is independently useful — they can be called from Python, CLI, or a Claude skill.

Key capabilities:

• Check package name availability on PyPI and GitHub

• Manage name candidate files (pools of potential names)

• Create GitHub repositories via the gh CLI

• Orchestrate full project creation (repo → populate → commit/push)

Functions

check_name_availability(name, *[, org, npm, ...])	Check a package name's validity and availability on PyPI (and optionally npm, GitHub).
check_names(names, *[, org])	Check multiple names for availability (kwargs: npm, github, see check_name_availability).
create_github_repo(name, *[, org, ...])	Create a GitHub repository via the gh CLI.
create_misc_docs(pkg_dir, *[, sections])	Create misc/docs/ directory with template markdown files.
detect_github_username()	Detect the current GitHub username.
github_repo_url(name, *[, org])	Return the GitHub repository URL for org/name.
is_available_on_github(name, *[, org])	Check if a repository name is available on GitHub.
is_available_on_npm(name, *[, timeout])	Check if a package name is unclaimed on the npm registry (HTTP 404 = free).
is_available_on_pypi(name)	Check if a package name is unclaimed on PyPI.
list_name_candidate_files()	List all name candidate files in the name_candidates directory.
load_name_candidates([filepath])	Load name candidates from a file or all files in the name_candidates directory.
pypi_project_url(name)	Return the PyPI project page URL for a package name.
repo_exists(name, *[, org])	Check if a GitHub repository exists at org/name.
setup_opsward_for_project(pkg_dir)	Set up AI agent configuration using opsward, if available.
setup_project(name, *[, description, org, ...])	Orchestrate full project creation.

wads.project_setup.check_name_availability(name, *, org=None, npm=False, github=False)

Check a package name’s validity and availability on PyPI (and optionally npm, GitHub).

PyPI is always checked. Pass npm=True when the project also publishes to npm. GitHub is checked only with github=True (explicit user request): GitHub calls are rate limited, and PyPI/npm are what decide a package name.

Return type:

dict

Returns a dict with keys:

name, valid_pep508, pypi_available, pypi_url, npm_available, npm_url, github_available, github_url

(keys of checks that were not run are None)

>>> result = check_name_availability("wads")
>>> result["valid_pep508"]
True

wads.project_setup.check_names(names, *, org=None, **kwargs)

Check multiple names for availability (kwargs: npm, github, see check_name_availability). Returns a list of result dicts.

Return type:

list[dict]

wads.project_setup.create_github_repo(name, *, org=None, description='', public=True, clone=True, clone_dir=None)

Create a GitHub repository via the gh CLI.

Parameters:

• name (str) – Repository name.

• org (str | None) – GitHub org or username. Detected if not provided.

• description (str) – Repository description.

• public (bool) – If True, create a public repo. If False, private.

• clone (bool) – If True, clone the repo after creation.

• clone_dir (str | None) – Directory to clone into. Defaults to current dir.

Return type:

str

Returns:

The local path to the cloned/created repository.

Raises:

• EnvironmentError – If gh CLI is not available.

• CalledProcessError – If repo creation fails.

wads.project_setup.create_misc_docs(pkg_dir, *, sections=None)

Create misc/docs/ directory with template markdown files.

Parameters:

• pkg_dir (str) – Project root directory.

• sections (list[str] | None) – List of section names to create. Defaults to [“research”, “design”, “roadmap”].

Return type:

list[str]

Returns:

List of created file paths.

wads.project_setup.detect_github_username()

Detect the current GitHub username.

Tries gh auth status first, then falls back to git config user.name. Returns None if detection fails.

Return type:

str | None

wads.project_setup.github_repo_url(name, *, org=None)

Return the GitHub repository URL for org/name.

Return type:

str

wads.project_setup.is_available_on_github(name, *, org=None)

Check if a repository name is available on GitHub.

Requires the gh CLI to be installed and authenticated. Returns True if no repo exists at org/name.

Return type:

bool

wads.project_setup.is_available_on_npm(name, *, timeout=10)

Check if a package name is unclaimed on the npm registry (HTTP 404 = free).

Returns None when the registry could not give a definite answer.

Return type:

bool | None

>>> is_available_on_npm("zzz-nonexistent-pkg-12345")
True

wads.project_setup.is_available_on_pypi(name)

Check if a package name is unclaimed on PyPI.

Returns True if the name is available (no package exists with that name).

Return type:

bool

>>> is_available_on_pypi("wads")
False
>>> is_available_on_pypi("zzz_nonexistent_pkg_12345")
True

wads.project_setup.list_name_candidate_files()

List all name candidate files in the name_candidates directory.

Name candidate files are plain text files (one name per line). Lines starting with # are comments; blank lines are ignored.

Return type:

list[Path]

wads.project_setup.load_name_candidates(filepath=None)

Load name candidates from a file or all files in the name_candidates directory.

Parameters:

filepath (Path | None) – Specific file to load from. If None, loads from all files in the name_candidates directory.

Return type:

list[str]

Returns:

List of candidate names (deduplicated, preserving order).

wads.project_setup.pypi_project_url(name)

Return the PyPI project page URL for a package name.

Return type:

str

wads.project_setup.repo_exists(name, *, org=None)

Check if a GitHub repository exists at org/name.

Return type:

bool

wads.project_setup.setup_opsward_for_project(pkg_dir)

Set up AI agent configuration using opsward, if available.

Returns True if opsward ran successfully, False if not available.

Return type:

bool

wads.project_setup.setup_project(name, *, description='', org=None, author=None, license='mit', root_url=None, proj_rootdir=None, create_repo=True, populate=True, create_devdocs=False, setup_opsward=False, verbose=True)

Orchestrate full project creation.

Steps (each independently skippable via keyword args):

1. Validate name

2. Create GitHub repo (if create_repo)

3. Populate project files (if populate)

4. Create misc/docs/ (if create_devdocs)

5. Run opsward generate (if setup_opsward and opsward is available)

Returns a summary dict with keys: path, steps_completed, warnings.

Return type:

dict