oct.scaffold.oct_scaffold module

oct.scaffold.oct_scaffold module#

Purpose#

OI-512 / FS-518 — project scaffolding. Lifts the scaffold body out of oct/cli.py so the CLI becomes a thin dispatcher and so the venv integration (FS-503 / FS-504) can layer on a single include_venv parameter rather than a second 135-line rewrite.

The public entry point is run_scaffold(), which returns a ScaffoldResult describing what was created, skipped, or warned about. Callers are expected to render the result themselves — this module never touches click.echo directly.

Responsibilities#

  • Materialise the standard Option C directory layout under a target path.

  • Write bundled templates: .octrc.json, Sphinx conf.py / index.rst, the debug-config skeleton, stub READMEs.

  • Optionally create a .venv/ via venv (include_venv).

  • Run in dry-run mode where no filesystem state changes.

Diagnostics#

Domain: SCAFFOLD Levels:

L2 — lifecycle: start / end / target path L3 — semantic details: per-template decisions L4 — deep tracing: per-file / per-dir outcomes

Contracts#

  • run_scaffold must be side-effect-free when dry_run=True.

  • Venv creation must never shell out — uses venv.EnvBuilder.

  • The Sphinx template directory is resolved at import time to keep run_scaffold self-contained.

Dependencies#

  • oct.core.diagnostics (_dbg structured logger)

  • oct.core.option_c_dir (OcStatus, write_oc_status)

class oct.scaffold.oct_scaffold.ScaffoldResult(created: list[Path] = <factory>, skipped: list[Path] = <factory>, messages: list[str] = <factory>, venv_path: Path | None = None)[source]#

Bases: object

Structured output from run_scaffold().

created#

Paths (directories + files) that were created.

Type:

list[pathlib.Path]

skipped#

Paths that already existed and were not overwritten.

Type:

list[pathlib.Path]

messages#

Informational strings the caller may render — warnings, tips, or dry-run descriptions.

Type:

list[str]

venv_path#

The .venv/ that was created, or None when include_venv=False.

Type:

pathlib.Path | None

created: list[Path]#
messages: list[str]#
skipped: list[Path]#
venv_path: Path | None = None#
oct.scaffold.oct_scaffold.run_scaffold(name: str, base_dir: Path, *, dry_run: bool = False, include_venv: bool = True) → ScaffoldResult[source]#

Create a new Option C project under base_dir / name.

Parameters:

  • name – Project name (becomes the top-level directory).

  • base_dir – Parent directory — the project is created at base_dir / name.

  • dry_run – When True, describe what would happen without touching the filesystem.

  • include_venv – When True, create a .venv/ at the project root using the stdlib venv module.

Returns:

Structured result. Always returns; never raises for existing files (they are recorded in skipped).

Return type:

ScaffoldResult