dc-up 0.1.2__tar.gz → 0.3.0__tar.gz

{dc_up-0.1.2 → dc_up-0.3.0}/.gitignore

@@ -1,14 +1,13 @@
 # ============================================================
 # .gitignore (ALL-REPOS)
 # ============================================================
-# Updated: 2026-06-06
+# Updated: 2026-06-27
 #
 # REQ: All professional GitHub project repositories MUST include .gitignore.
 # WHY: Keep generated artifacts, local state, secrets, and OS-specific files
 # out of the repository.
 # ALT: Repository may customize ignores, but MUST preserve universal safety rules.
-# CUSTOM: Logs may be committed for verification; keep ignored for
-# production use and security.
+
 
 # === Logs and generated runtime output ===
 
@@ -31,6 +30,10 @@ PRIVATE_NOTES.md
 .env
 .env.*
 
+# WHY: Commit .env.example as a template showing which variables to set.
+# Copy this file to .env and customize.
+!.env.example
+
 
 # === Operating-system files ===
 

{dc_up-0.1.2 → dc_up-0.3.0}/CHANGELOG.md

@@ -13,6 +13,25 @@ and this project adheres to **[Semantic Versioning](https://semver.org/spec/v2.0
 
 ---
 
+## [0.3.0] - 2026-06-27
+
+### Changed
+
+- ALL-PY-SRC docs/api.md fills in template package name to default the docs/api.md page.
+
+---
+
+## [0.2.0] - 2026-06-27
+
+### Changed
+
+- Data-driven course prefixes
+- And a more flexible course repo detection if repo is named like this:
+  `prefix-NN-post`
+- better logic for ALL-PY (just tooling) vs ALL-PY-SRC with Ruff and Pyright
+
+---
+
 ## [0.1.2] - 2026-06-10
 
 ### Changed
@@ -128,7 +147,9 @@ git push origin :refs/tags/vX.Z.Y
 
 ## Links
 
-[Unreleased]: https://github.com/denisecase/dc-up/compare/v0.1.2...HEAD
+[Unreleased]: https://github.com/denisecase/dc-up/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/denisecase/dc-up/releases/tag/v0.3.0
+[0.2.0]: https://github.com/denisecase/dc-up/releases/tag/v0.2.0
 [0.1.2]: https://github.com/denisecase/dc-up/releases/tag/v0.1.2
 [0.1.1]: https://github.com/denisecase/dc-up/releases/tag/v0.1.1
 [0.1.0]: https://github.com/denisecase/dc-up/releases/tag/v0.1.0

{dc_up-0.1.2 → dc_up-0.3.0}/CITATION.cff

@@ -10,8 +10,8 @@ type: software
 
 title: "dc-up"
 # Set version and date-released to match latest git tag or release.
-version: "0.1.2"
-date-released: "2026-06-10"
+version: "0.3.0"
+date-released: "2026-06-27"
 
 authors:
   - family-names: Case

{dc_up-0.1.2 → dc_up-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dc-up
-Version: 0.1.2
+Version: 0.3.0
 Summary: Command-line tool for bringing repositories up to a managed baseline using layered canonical templates.
 Project-URL: Homepage, https://github.com/denisecase/dc-up
 Project-URL: Repository, https://github.com/denisecase/dc-up
@@ -82,7 +82,11 @@ Description-Content-Type: text/markdown
 ## Update a Repo based on Templates
 
 ```shell
+# see what files the command would update (optional, force latest)
 uvx dc-up
+uvx dc-up@latest
+
+# actually add and overwrite the files listed (CAUTION: DESTRUCTIVE)
 uvx dc-up --write
 ```
 

{dc_up-0.1.2 → dc_up-0.3.0}/README.md

@@ -23,7 +23,11 @@
 ## Update a Repo based on Templates
 
 ```shell
+# see what files the command would update (optional, force latest)
 uvx dc-up
+uvx dc-up@latest
+
+# actually add and overwrite the files listed (CAUTION: DESTRUCTIVE)
 uvx dc-up --write
 ```
 

{dc_up-0.1.2 → dc_up-0.3.0}/pyproject.toml

@@ -222,11 +222,12 @@ include = [
 packages = ["src/dc_up"]
 
 [tool.hatch.build.targets.wheel.force-include]
+"src/dc_up/data/defaults.toml" = "dc_up/data/defaults.toml"
 "src/dc_up/data/todo-surfaces.toml" = "dc_up/data/todo-surfaces.toml"
 
 [tool.hatch.version]
 # Used when no git tags are present. Keep in sync with CITATION.cff.
-fallback-version = "0.1.2"
+fallback-version = "0.3.0"
 # WHY: Version is derived from git tags at build time.
 source = "vcs"
 # WHY: Allow hatch-vcs to find the Git root from isolated build contexts.

{dc_up-0.1.2 → dc_up-0.3.0}/src/dc_up/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.2'
-__version_tuple__ = version_tuple = (0, 1, 2)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
 __commit_id__ = commit_id = None

dc_up-0.3.0/src/dc_up/baseline.py

@@ -0,0 +1,50 @@
+"""Baseline layer inference and managed file declarations."""
+
+from pathlib import Path
+
+from .baseline_utils import load_package_defaults, looks_like_course_repo
+
+__all__ = ["PRESERVE_PATTERNS", "infer_layers"]
+
+PRESERVE_PATTERNS: tuple[str, ...] = (
+    "README.md",
+    "artifacts/**",
+    "data/**",
+    "docs/**",
+    "notebooks/**",
+    "sql/**",
+    "src/**",
+    "tests/**",
+)
+
+
+def infer_layers(*, repo_root: Path, repo_name: str, files: set[str]) -> list[str]:
+    """Infer additive template layers based strictly on file existence."""
+    # 1. Identify physical markers
+    has_py = "pyproject.toml" in files
+    has_src = (repo_root / "src").is_dir()
+    is_ts = "package.json" in files
+
+    # 2. Build Layers (Ordered by specificity)
+    layers: list[str] = ["ALL"]
+
+    # Base Tooling
+    if has_py:
+        layers.append("ALL-PY")
+    elif is_ts:
+        layers.append("ALL-TS")
+
+    # Structural Overlays
+    if has_py and has_src:
+        layers.append("ALL-PY-SRC")
+
+    # 3. Course Overlays (Highest precedence)
+    rules = load_package_defaults()
+    if looks_like_course_repo(repo_name_only=repo_name, files=files, rules=rules):
+        layers.append("ALL-COURSE")
+
+        # Only add the source course layer if it's a src-layout
+        if has_py and has_src:
+            layers.append("ALL-COURSE-PY-SRC")
+
+    return layers

dc_up-0.3.0/src/dc_up/baseline_utils.py

@@ -0,0 +1,136 @@
+"""Internal utilities, type-casters, and metadata parsers for layout inference."""
+
+import importlib.resources
+from pathlib import Path
+import re
+import tomllib
+from typing import BinaryIO, cast
+
+__all__ = ["looks_like_course_repo", "looks_like_pypi_package", "load_package_defaults"]
+
+TomlTable = dict[str, object]
+
+
+def load_package_defaults() -> dict[str, object]:
+    """Read the data properties packaged inside this tool's installation wheel."""
+    try:
+        ref = importlib.resources.files("dc_up").joinpath("data/defaults.toml")
+        with ref.open("rb") as f:
+            config = tomllib.load(cast(BinaryIO, f))
+        classification = config.get("classification")
+        if isinstance(classification, dict):
+            return cast(dict[str, object], classification)
+    except OSError:
+        return {}
+    except tomllib.TOMLDecodeError:
+        return {}
+    return {}
+
+
+def looks_like_course_repo(
+    *, repo_name_only: str, files: set[str], rules: dict[str, object]
+) -> bool:
+    """Return whether a repository matches course layouts using data-driven patterns."""
+    normalized_slug = repo_name_only.lower()
+
+    # Guard admin/maintenance surfaces
+    if normalized_slug.endswith(("-00-admin", "-admin")):
+        return False
+
+    # Safely extract regex string from configuration
+    pattern_str = rules.get("course_pattern")
+    if not isinstance(pattern_str, str):
+        pattern_str = ""
+
+    # WHY: Use our existing type-caster to safely extract and cast the list of objects to strings.
+    prefixes = tuple(_as_string_list(rules.get("course_prefixes")))
+
+    # 1. Match regex pattern (enforces the pre-NN-post structure using dashes)
+    is_pattern_match = False
+    if pattern_str:
+        is_pattern_match = bool(re.match(pattern_str, normalized_slug))
+
+    # 2. Match legacy prefixes (fallback)
+    is_prefix_match = False
+    if prefixes and normalized_slug.startswith(prefixes):
+        is_prefix_match = True
+
+    # 3. Must match one of the naming rules, and must contain a pyproject.toml
+    return bool(is_pattern_match or is_prefix_match)
+
+
+def looks_like_pypi_package(repo_root: Path) -> bool:
+    """Return whether pyproject.toml looks like a publishable package."""
+    pyproject_path = repo_root / "pyproject.toml"
+    if not pyproject_path.exists():
+        return False
+
+    try:
+        data = _read_toml(pyproject_path)
+    except OSError:
+        return False
+    except tomllib.TOMLDecodeError:
+        return False
+
+    project = _as_table(data.get("project"))
+    if not project:
+        return False
+
+    if _has_console_scripts(project):
+        return True
+
+    classifiers = _as_string_list(project.get("classifiers"))
+    if any("PyPI" in item for item in classifiers):
+        return True
+
+    tool = _as_table(data.get("tool"))
+    uv = _as_table(tool.get("uv"))
+
+    return _as_bool(uv.get("package"))
+
+
+def _has_console_scripts(project: TomlTable) -> bool:
+    """Return whether project metadata declares console scripts."""
+    scripts = _as_string_dict(project.get("scripts"))
+    if scripts:
+        return True
+
+    entry_points = _as_table(project.get("entry-points"))
+    console_scripts = _as_string_dict(entry_points.get("console_scripts"))
+
+    return bool(console_scripts)
+
+
+def _read_toml(path: Path) -> TomlTable:
+    """Read a TOML file as typed object data."""
+    with path.open("rb") as file:
+        return cast(TomlTable, tomllib.load(file))
+
+
+def _as_table(value: object) -> TomlTable:
+    """Return value as a TOML table or an empty table."""
+    if isinstance(value, dict):
+        return cast(TomlTable, value)
+    return {}
+
+
+def _as_string_list(value: object) -> list[str]:
+    """Return value as a list of strings."""
+    if not isinstance(value, list):
+        return []
+    return [str(item) for item in cast(list[object], value)]
+
+
+def _as_string_dict(value: object) -> dict[str, str]:
+    """Return value as a string-to-string dictionary."""
+    if not isinstance(value, dict):
+        return {}
+    table = cast(dict[object, object], value)
+    return {str(key): str(item) for key, item in table.items()}
+
+
+def _as_bool(value: object) -> bool:
+    """Return value as a boolean."""
+    if isinstance(value, bool):
+        return value
+    return False

{dc_up-0.1.2 → dc_up-0.3.0}/src/dc_up/cli.py

@@ -10,6 +10,7 @@ uv run dc-up todo
 
 Equivalent uvx usage after release:
 uvx dc-up
+uvx dc-up@latest
 uvx dc-up --write
 uvx dc-up todo
 """

{dc_up-0.1.2 → dc_up-0.3.0}/src/dc_up/commands/update.py

@@ -40,6 +40,7 @@ def run(
     plan = build_update_plan(
         target=repository,
         source=source,
+        protected_paths=frozenset({"docs/api.md", "README.md"}),
     )
 
     print_update_plan(plan, write=write)

dc_up-0.3.0/src/dc_up/data/defaults.toml

@@ -0,0 +1,13 @@
+# src/dc_up/data/defaults.toml
+
+[classification]
+course_prefixes = [
+    "cintel-",
+    "datafun-",
+    "insights-",
+    "ml-",
+    "nlp-",
+    "streaming-"
+]
+
+course_pattern = "^[a-zA-Z]+-\\d{2}-.+$"

{dc_up-0.1.2 → dc_up-0.3.0}/src/dc_up/data/todo-surfaces.toml

@@ -1,4 +1,4 @@
-# dc-up-todo.toml
+# src/dc_up/data/todo-surfaces.toml
 
 [review_paths]
 default = [
@@ -8,6 +8,7 @@ default = [
 pyproject = [
   "pyproject.toml",
   "uv.lock",
+  "docs/index.md",
 ]
 
 python_src = [
@@ -15,9 +16,7 @@ python_src = [
   "tests/**",
 ]
 
-zensical = [
-  "docs/index.md",
-]
+zensical = []
 
 course_python_src = [
   "docs/project-instructions.md",

{dc_up-0.1.2 → dc_up-0.3.0}/src/dc_up/detect.py

@@ -38,6 +38,7 @@ def detect_repository(root: Path | None = None) -> RepositoryContext:
 
     repo_url = f"https://github.com/{github_handle}/{repo_name}"
     site_url = f"https://{github_handle}.github.io/{repo_name}/"
+    src_package = _detect_src_package(local_repo_root_directory)
 
     layers = tuple(
         infer_layers(
@@ -53,6 +54,7 @@ def detect_repository(root: Path | None = None) -> RepositoryContext:
         repo_name=repo_name,
         repo_url=repo_url,
         site_url=site_url,
+        src_package=src_package,
         files=frozenset(files),
         layers=layers,
     )
@@ -157,3 +159,14 @@ def _detect_github_handle(root: Path) -> str | None:
         return None
 
     return match.group("owner")
+
+
+def _detect_src_package(root: Path) -> str:
+    """Infer the primary package name from src/."""
+    src = root / "src"
+    if not src.exists():
+        return ""
+    for candidate in sorted(src.iterdir()):
+        if candidate.is_dir() and (candidate / "__init__.py").exists():
+            return candidate.name
+    return ""

{dc_up-0.1.2 → dc_up-0.3.0}/src/dc_up/plan.py

@@ -23,6 +23,7 @@ def build_update_plan(
     *,
     target: RepositoryContext,
     source: TemplateSource,
+    protected_paths: frozenset[str] = frozenset(),
 ) -> UpdatePlan:
     """Build an update plan from discovered template files."""
     planned_files: list[PlannedFile] = []
@@ -71,7 +72,8 @@ def print_update_plan(plan: UpdatePlan, *, write: bool) -> None:
         f"{counts['current']} current, "
         f"{counts['changed']} changed, "
         f"{counts['missing']} missing, "
-        f"{counts['no-template']} no-template"
+        f"{counts['no-template']} no-template, "
+        f"{counts['protected']} protected"
     )
 
     if not write:
@@ -183,6 +185,7 @@ def _status_counts(plan: UpdatePlan) -> dict[FileStatus, int]:
         "changed": 0,
         "missing": 0,
         "no-template": 0,
+        "protected": 0,
     }
 
     for file in plan.files:
@@ -202,3 +205,5 @@ def _status_label(status: FileStatus, *, write: bool) -> str:
             return "ADDED" if write else "WOULD ADD"
         case "no-template":
             return "NO TEMPLATE"
+        case "protected":
+            return "PROTECTED"

{dc_up-0.1.2 → dc_up-0.3.0}/src/dc_up/render.py

@@ -22,6 +22,7 @@ def render_template(text: str, target: RepositoryContext) -> str:
         "github_handle": target.github_handle,
         "repo_url": target.repo_url,
         "site_url": target.site_url,
+        "src_package": target.src_package,
     }
 
     rendered = text

{dc_up-0.1.2 → dc_up-0.3.0}/src/dc_up/types.py

@@ -17,6 +17,7 @@ FileStatus = Literal[
     "changed",
     "missing",
     "no-template",
+    "protected",
 ]
 
 
@@ -29,6 +30,7 @@ class RepositoryContext:
     repo_name: str
     repo_url: str
     site_url: str
+    src_package: str
     files: frozenset[str]
     layers: tuple[str, ...]
 

dc_up-0.1.2/src/dc_up/baseline.py

@@ -1,205 +0,0 @@
-"""Baseline layer inference and managed file declarations."""
-
-from pathlib import Path
-import tomllib
-from typing import Literal, cast
-
-__all__ = [
-    "PRESERVE_PATTERNS",
-    "infer_layers",
-]
-
-TomlTable = dict[str, object]
-
-# Single base stack classification per repo (first match wins, see _classify_stack).
-StackKind = Literal["ts", "notebook", "kafka", "pypi", "src"]
-
-COURSE_PREFIXES: tuple[str, ...] = (
-    "cintel-",
-    "datafun-",
-    "insights-",
-    "ml-",
-    "nlp-",
-    "streaming-",
-)
-
-
-PRESERVE_PATTERNS: tuple[str, ...] = (
-    "README.md",
-    "artifacts/**",
-    "data/**",
-    "docs/**",
-    "notebooks/**",
-    "sql/**",
-    "src/**",
-    "tests/**",
-)
-
-
-# WHY: Base layers describe the repo's stack. Indexed by StackKind so the
-# classification and the layer list can't drift apart, and so the prefix
-# duplication (ALL, ALL-PY, ...) is declared once per kind, not per branch.
-BASE_LAYERS: dict[StackKind, tuple[str, ...]] = {
-    "kafka": ("ALL", "ALL-PY", "ALL-PY-KAFKA"),
-    "notebook": ("ALL", "ALL-PY", "ALL-PY-NB"),
-    "pypi": ("ALL", "ALL-PY", "ALL-PY-SRC", "ALL-PY-SRC-PYPI"),
-    "src": ("ALL", "ALL-PY", "ALL-PY-SRC"),
-    "ts": ("ALL", "ALL-TS"),
-}
-
-# WHY: Educational ("ALL-COURSE*") overrides, appended AFTER the base so the
-# ed versions win (last layer wins). ALL-COURSE is always first because it
-# overrides ALL; deeper course layers follow parent-first.
-# OBS: "ts" is unreachable for courses (course repos require pyproject.toml,
-#   which the "ts" classification excludes) - it's defensive.
-# OBS: "notebook" gets ALL-COURSE only; there is no ALL-COURSE-PY-NB defined.
-COURSE_OVERLAYS: dict[StackKind, tuple[str, ...]] = {
-    "kafka": ("ALL-COURSE", "ALL-COURSE-PY-SRC", "ALL-COURSE-PY-SRC-KAFKA"),
-    "notebook": ("ALL-COURSE",),
-    "pypi": ("ALL-COURSE", "ALL-COURSE-PY-SRC"),
-    "src": ("ALL-COURSE", "ALL-COURSE-PY-SRC"),
-    "ts": ("ALL-COURSE",),
-}
-
-
-def infer_layers(
-    *,
-    repo_root: Path,
-    repo_name: str,
-    files: set[str],
-) -> list[str]:
-    """Infer additive template layers for a repository.
-
-    The base layers describe the repo's stack. If the repo is a course repo,
-    the matching course overlay is appended AFTER the base so the educational
-    files override their ALL / ALL-PY counterparts (last layer wins).
-    """
-    slug = repo_name.lower()
-    kind = _classify_stack(repo_root=repo_root, slug=slug, files=files)
-
-    layers: list[str] = list(BASE_LAYERS[kind])
-
-    if _looks_like_course_repo(repo_name_only=repo_name, files=files):
-        layers.extend(COURSE_OVERLAYS[kind])
-
-    return layers
-
-
-def _classify_stack(
-    *,
-    repo_root: Path,
-    slug: str,
-    files: set[str],
-) -> StackKind:
-    """Classify a repository into one base stack kind (first match wins).
-
-    Precedence is preserved from the original if/elif chain. This is the one
-    place to special-case 'insights-' or 'ml-' later if they need it.
-    """
-    if "package.json" in files and "pyproject.toml" not in files:
-        return "ts"
-    if "notebook" in slug or slug.endswith("-notebooks"):
-        return "notebook"
-    if "kafka" in slug:
-        return "kafka"
-    if slug == "dc-up" or _looks_like_pypi_package(repo_root):
-        return "pypi"
-    return "src"
-
-
-def _has_console_scripts(project: TomlTable) -> bool:
-    """Return whether project metadata declares console scripts."""
-    scripts = _as_string_dict(project.get("scripts"))
-    if scripts:
-        return True
-
-    entry_points = _as_table(project.get("entry-points"))
-    console_scripts = _as_string_dict(entry_points.get("console_scripts"))
-
-    return bool(console_scripts)
-
-
-def _read_toml(path: Path) -> TomlTable:
-    """Read a TOML file as typed object data."""
-    with path.open("rb") as file:
-        return cast(TomlTable, tomllib.load(file))
-
-
-def _as_table(value: object) -> TomlTable:
-    """Return value as a TOML table or an empty table."""
-    if isinstance(value, dict):
-        return cast(TomlTable, value)
-    return {}
-
-
-def _as_string_list(value: object) -> list[str]:
-    """Return value as a list of strings."""
-    if not isinstance(value, list):
-        return []
-
-    return [str(item) for item in cast(list[object], value)]
-
-
-def _as_string_dict(value: object) -> dict[str, str]:
-    """Return value as a string-to-string dictionary."""
-    if not isinstance(value, dict):
-        return {}
-
-    table = cast(dict[object, object], value)
-    return {str(key): str(item) for key, item in table.items()}
-
-
-def _as_bool(value: object) -> bool:
-    """Return value as a boolean."""
-    if isinstance(value, bool):
-        return value
-    return False
-
-
-def _looks_like_course_repo(*, repo_name_only: str, files: set[str]) -> bool:
-    """Return whether a repository looks like a course project repo."""
-    normalized_slug = repo_name_only.lower()
-
-    if not normalized_slug.startswith(COURSE_PREFIXES):
-        return False
-
-    # Avoid admin/maintenance repos unless you decide they should get course docs.
-    if normalized_slug.endswith("-00-admin") or normalized_slug.endswith("-admin"):
-        return False
-
-    # Require project repo shape, not just matching name.
-    return "pyproject.toml" in files
-
-
-def _looks_like_pypi_package(repo_root: Path) -> bool:
-    """Return whether pyproject.toml looks like a publishable package.
-
-    This is intentionally stricter than "has pyproject + src" so ordinary
-    course repos do not accidentally receive PyPI release surfaces.
-    """
-    pyproject_path = repo_root / "pyproject.toml"
-    if not pyproject_path.exists():
-        return False
-
-    try:
-        data = _read_toml(pyproject_path)
-    except OSError:
-        return False
-    except tomllib.TOMLDecodeError:
-        return False
-
-    project = _as_table(data.get("project"))
-    if not project:
-        return False
-
-    if _has_console_scripts(project):
-        return True
-
-    classifiers = _as_string_list(project.get("classifiers"))
-    if any("PyPI" in item for item in classifiers):
-        return True
-
-    tool = _as_table(data.get("tool"))
-    uv = _as_table(tool.get("uv"))
-
-    return _as_bool(uv.get("package"))