eai-supcore 0.5.0__py3-none-any.whl

eai_supcore/__init__.py

@@ -0,0 +1,3 @@
+"""Shared steady-state bootstrap APIs for the eai-sup* CLI family."""
+
+__version__ = "0.5.0"

eai_supcore/bootstrap.py

@@ -0,0 +1,269 @@
+"""Shared steady-state bootstrap steps for eai-supinit and eai-supmig."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from eai_supcore.git_ops import GitError, add_submodule, is_git_repository, submodule_exists
+from eai_supcore.io_util import read_text, write_text
+from eai_supcore.paths import (
+    AI_RULES_SUBMODULE,
+    CURSOR_RULES_DIR,
+    DEFAULT_AI_RULES_URL,
+    ESYSREPO_MANIFEST_NAME,
+    STEADY_STATE_DIRS,
+    TOOLS_LOCAL_GITIGNORE_ENTRY,
+)
+from eai_supcore.templates import resolve_consumer_templates, resolve_template_file
+
+CONSUMER_GITIGNORE_ENTRIES = (
+    TOOLS_LOCAL_GITIGNORE_ENTRY,
+    ".venv/",
+    "venv/",
+    "build/",
+    "cmake-build-*/",
+    "out/",
+    ".idea/",
+    ".vscode/",
+    "*.swp",
+    ".DS_Store",
+    "Thumbs.db",
+)
+
+
+@dataclass
+class SharedBootstrapResult:
+    created_dirs: list[str] = field(default_factory=list)
+    created_files: list[str] = field(default_factory=list)
+    submodule_added: bool = False
+    ai_rules_found: bool = False
+    cursor_rules_materialized: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+
+def ensure_steady_state_dirs(workspace: Path, result: SharedBootstrapResult) -> None:
+    """Create steady-state layout dirs (src/, libs/, docs/adr/, prompts/)."""
+    for rel in STEADY_STATE_DIRS:
+        target = workspace / rel
+        if not target.exists():
+            target.mkdir(parents=True, exist_ok=True)
+            result.created_dirs.append(rel.as_posix())
+
+
+def _merge_gitignore_entries(
+    workspace: Path, entries: tuple[str, ...], result: SharedBootstrapResult
+) -> None:
+    gitignore = workspace / ".gitignore"
+    existing_lines: list[str] = []
+    if gitignore.is_file():
+        content = read_text(gitignore)
+        existing_lines = content.splitlines()
+        present = {line.strip() for line in existing_lines}
+    else:
+        content = ""
+        present = set()
+
+    missing = [e for e in entries if e not in present and e.rstrip("/") not in present]
+    if not missing:
+        return
+
+    blocks: list[str] = []
+    if not gitignore.is_file():
+        blocks.append("# Generated / updated by eai-sup* bootstrap")
+    elif content and not content.endswith("\n"):
+        existing_lines.append("")
+
+    # Keep tools_local comment when adding that entry
+    for entry in missing:
+        if entry == TOOLS_LOCAL_GITIGNORE_ENTRY and "# eai-sup* local installs" not in "\n".join(
+            existing_lines
+        ):
+            blocks.append("# eai-sup* local installs (ADR-0024)")
+        blocks.append(entry)
+
+    new_body = "\n".join([*existing_lines, *blocks]).rstrip() + "\n"
+    write_text(gitignore, new_body)
+    if ".gitignore" not in result.created_files:
+        result.created_files.append(".gitignore")
+
+
+def ensure_tools_local_gitignore(workspace: Path, result: SharedBootstrapResult) -> None:
+    """Ensure ``.tools_local/`` is listed in consumer ``.gitignore``."""
+    _merge_gitignore_entries(workspace, (TOOLS_LOCAL_GITIGNORE_ENTRY,), result)
+
+
+def ensure_consumer_gitignore(workspace: Path, result: SharedBootstrapResult) -> None:
+    """Merge language-agnostic consumer ``.gitignore`` entries."""
+    _merge_gitignore_entries(workspace, CONSUMER_GITIGNORE_ENTRIES, result)
+
+
+def _write_new_from_template(
+    workspace: Path,
+    dest_rel: str,
+    template_root: Path,
+    result: SharedBootstrapResult,
+) -> None:
+    dest = workspace / dest_rel
+    if dest.exists():
+        return
+    src = resolve_template_file(template_root, dest_rel)
+    if src is None:
+        result.warnings.append(f"Template missing: {dest_rel}")
+        return
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(src, dest)
+    result.created_files.append(dest_rel.replace("\\", "/"))
+
+
+def ensure_esysrepo_manifest(
+    workspace: Path, result: SharedBootstrapResult, *, template_root: Path
+) -> None:
+    """Scaffold basic ``.esysrepo.manifest.xml`` once if missing."""
+    _write_new_from_template(workspace, ESYSREPO_MANIFEST_NAME, template_root, result)
+
+
+def install_dev_hooks(workspace: Path, result: SharedBootstrapResult) -> None:
+    """Run consumer ``scripts/setup-dev.py`` when Python + git are available (warnings on fail)."""
+    script = workspace / "scripts" / "setup-dev.py"
+    if not script.is_file():
+        result.warnings.append("scripts/setup-dev.py missing — skipped hook install")
+        return
+    if shutil.which("git") is None:
+        result.warnings.append("git not on PATH — skipped hook install")
+        return
+    py = Path(sys.executable) if sys.executable else None
+    if py is None or not py.is_file():
+        result.warnings.append("Python not available — skipped hook install")
+        return
+    try:
+        proc = subprocess.run(
+            [str(py), str(script)],
+            cwd=workspace,
+            capture_output=True,
+            text=True,
+            check=False,
+            env={**os.environ},
+        )
+        if proc.returncode != 0:
+            detail = (proc.stderr or proc.stdout or "").strip()
+            result.warnings.append(
+                f"setup-dev.py failed (exit {proc.returncode})" + (f": {detail}" if detail else "")
+            )
+    except OSError as exc:
+        result.warnings.append(f"setup-dev.py failed: {exc}")
+
+
+def scaffold_consumer_dev_rails(
+    workspace: Path,
+    result: SharedBootstrapResult | None = None,
+    *,
+    with_hooks: bool = True,
+    with_manifest: bool = True,
+    install_hooks: bool = False,
+) -> SharedBootstrapResult:
+    """Materialize language-agnostic consumer rails (hooks, gitignore, setup-dev, manifest)."""
+    if result is None:
+        result = SharedBootstrapResult()
+    try:
+        template_root = resolve_consumer_templates(workspace)
+    except FileNotFoundError as exc:
+        result.errors.append(str(exc))
+        return result
+
+    ensure_consumer_gitignore(workspace, result)
+
+    if with_hooks:
+        _write_new_from_template(workspace, ".pre-commit-config.yaml", template_root, result)
+        _write_new_from_template(workspace, ".gitlint", template_root, result)
+        scripts_dir = workspace / "scripts"
+        if not scripts_dir.exists():
+            scripts_dir.mkdir(parents=True, exist_ok=True)
+            result.created_dirs.append("scripts")
+        _write_new_from_template(workspace, "scripts/setup-dev.py", template_root, result)
+
+    if with_manifest:
+        ensure_esysrepo_manifest(workspace, result, template_root=template_root)
+
+    if install_hooks and with_hooks:
+        install_dev_hooks(workspace, result)
+
+    return result
+
+
+def mount_ai_rules(
+    workspace: Path,
+    result: SharedBootstrapResult,
+    *,
+    ai_rules_url: str = DEFAULT_AI_RULES_URL,
+) -> None:
+    """Mount ``tools/ai-rules`` as submodule or reuse an existing git checkout."""
+    ai_rules_path = workspace / AI_RULES_SUBMODULE
+    if ai_rules_path.is_dir() and is_git_repository(ai_rules_path):
+        result.ai_rules_found = True
+        return
+    if submodule_exists(workspace, AI_RULES_SUBMODULE):
+        result.warnings.append("tools/ai-rules submodule already configured")
+        return
+    if ai_rules_path.exists():
+        result.warnings.append(
+            "tools/ai-rules exists but is not a git repository; skipping submodule add"
+        )
+        return
+    try:
+        add_submodule(workspace, ai_rules_url, AI_RULES_SUBMODULE)
+        result.submodule_added = True
+    except GitError as exc:
+        result.errors.append(str(exc))
+
+
+def materialize_cursor_rules(
+    workspace: Path,
+    result: SharedBootstrapResult,
+) -> None:
+    """Copy shared Cursor ``.mdc`` rules from ``tools/ai-rules/cursor/rules``."""
+    ai_rules_path = workspace / AI_RULES_SUBMODULE
+    shared_rules = ai_rules_path / "cursor" / "rules"
+    cursor_dir = workspace / CURSOR_RULES_DIR
+    if not shared_rules.is_dir():
+        result.warnings.append(
+            f"Shared Cursor rules not found at {shared_rules}; run with --with-ai-rules first"
+        )
+        return
+    cursor_dir.mkdir(parents=True, exist_ok=True)
+    for src in sorted(shared_rules.glob("*.mdc")):
+        dest = cursor_dir / src.name
+        if dest.exists():
+            result.warnings.append(f"Skipped existing Cursor rule: {dest.name}")
+            continue
+        shutil.copy2(src, dest)
+        result.cursor_rules_materialized.append(dest.name)
+
+
+def write_cursor_overlay(
+    workspace: Path,
+    result: SharedBootstrapResult,
+    *,
+    overlay_name: str,
+    content: str,
+) -> None:
+    """Write a local Cursor overlay if missing."""
+    cursor_dir = workspace / CURSOR_RULES_DIR
+    cursor_dir.mkdir(parents=True, exist_ok=True)
+    overlay = cursor_dir / overlay_name
+    if overlay.exists():
+        return
+    write_text(overlay, content)
+    result.created_files.append(str(overlay.relative_to(workspace)).replace("\\", "/"))
+
+
+def materialized_cursor_rule_names(workspace: Path) -> list[str]:
+    shared_rules = workspace / AI_RULES_SUBMODULE / "cursor" / "rules"
+    if not shared_rules.is_dir():
+        return []
+    return sorted(item.name for item in shared_rules.glob("*.mdc") if item.is_file())

eai_supcore/data/__init__.py

@@ -0,0 +1 @@
+"""Package data marker for bundled consumer / extension templates."""

eai_supcore/data/consumer/esysrepo.manifest.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<esysrepo_manifest kind="embedded" schema-version="1.1">
+  <default revision="refs/heads/develop" sync-j="4" />
+  <location name="origin" addr="ssh://git@gitlab.com/YOUR_GROUP" alt_addr="https://gitlab.com/YOUR_GROUP">
+    <!-- Add repositories under src/ and libs/ as members are added -->
+  </location>
+</esysrepo_manifest>

eai_supcore/data/consumer/gitignore

@@ -0,0 +1,18 @@
+# eai-sup* local installs (ADR-0024)
+.tools_local/
+
+# Local Python environment (created by scripts/setup-dev.py)
+.venv/
+venv/
+
+# Build artifacts
+build/
+cmake-build-*/
+out/
+
+# Editor / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db

eai_supcore/data/consumer/gitlint

@@ -0,0 +1,11 @@
+[general]
+ignore=body-is-missing
+
+[title-max-length]
+line-length=72
+
+[title-match-regex]
+regex=^(WIP: )?((adr|build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9._/-]+\))?(!)?): [A-Z0-9].+$
+
+[body-max-line-length]
+line-length=100

eai_supcore/data/consumer/pre-commit-config.yaml

@@ -0,0 +1,30 @@
+ci:
+  autoupdate_commit_msg: "chore: Update pre-commit hooks"
+  autofix_commit_msg: "style: Apply pre-commit fixes"
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-yaml
+      - id: end-of-file-fixer
+        exclude: ^\.cursor/
+      - id: mixed-line-ending
+        args: [--fix=lf]
+      - id: trailing-whitespace
+        exclude: ^\.cursor/
+
+  - repo: https://github.com/Lucas-C/pre-commit-hooks
+    rev: v1.5.5
+    hooks:
+      - id: remove-tabs
+        files: "\\.(md|mdc|ya?ml)$"
+
+  - repo: https://github.com/jorisroovers/gitlint
+    rev: v0.19.1
+    hooks:
+      - id: gitlint
+        stages: [commit-msg]
+        args: ["--msg-filename"]

eai_supcore/data/consumer/scripts/setup-dev.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Create/use .venv, install pre-commit, register pre-commit + commit-msg hooks.
+
+Usage (from repository root):
+  python scripts/setup-dev.py
+  python3 scripts/setup-dev.py
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+VENV_DIR = ROOT / ".venv"
+
+
+def log(msg: str) -> None:
+    print(f"[setup-dev] {msg}")
+
+
+def die(msg: str) -> None:
+    print(f"[setup-dev] ERROR: {msg}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+def venv_python(venv_dir: Path) -> Path:
+    if sys.platform == "win32":
+        return venv_dir / "Scripts" / "python.exe"
+    return venv_dir / "bin" / "python"
+
+
+def resolve_python() -> Path:
+    active = os.environ.get("VIRTUAL_ENV")
+    if active:
+        candidate = venv_python(Path(active))
+        if candidate.is_file():
+            return candidate
+    existing = venv_python(VENV_DIR)
+    if existing.is_file():
+        return existing
+    host = Path(sys.executable) if sys.executable else None
+    if host is None or not host.is_file():
+        for name in ("python3", "python"):
+            found = shutil.which(name)
+            if found:
+                host = Path(found)
+                break
+    if host is None or not host.is_file():
+        die("Python 3.11+ required")
+    log(f"Creating {VENV_DIR.name}/ ...")
+    subprocess.run([str(host), "-m", "venv", str(VENV_DIR)], cwd=ROOT, check=True)
+    py = venv_python(VENV_DIR)
+    if not py.is_file():
+        die(f"venv created but python missing at {py}")
+    return py
+
+
+def main() -> None:
+    os.chdir(ROOT)
+    if not (ROOT / ".pre-commit-config.yaml").is_file():
+        die(".pre-commit-config.yaml missing — run eai-supinit/eai-supmig bootstrap first")
+    if shutil.which("git") is None:
+        die("git required on PATH")
+    py = resolve_python()
+    log(f"Using {py}")
+    log("Installing pre-commit ...")
+    subprocess.run([str(py), "-m", "pip", "install", "--upgrade", "pip"], cwd=ROOT, check=False)
+    subprocess.run([str(py), "-m", "pip", "install", "pre-commit"], cwd=ROOT, check=True)
+    log("Installing pre-commit hooks (pre-commit + commit-msg/gitlint) ...")
+    subprocess.run([str(py), "-m", "pre_commit", "install"], cwd=ROOT, check=True)
+    subprocess.run(
+        [str(py), "-m", "pre_commit", "install", "--hook-type", "commit-msg"],
+        cwd=ROOT,
+        check=True,
+    )
+    log("Done. Re-run after clone or when .pre-commit-config.yaml changes.")
+
+
+if __name__ == "__main__":
+    main()

eai_supcore/data/extensions/cmake/cmake-format.yaml

@@ -0,0 +1,11 @@
+# cmake-format defaults for eai multi-repo workspaces (extension: cmake)
+# See https://cmake-format.readthedocs.io/
+format:
+  line_width: 100
+  tab_size: 2
+  max_subgroups_hwrap: 2
+  max_pargs_hwrap: 6
+  dangle_parens: false
+  separate_ctrl_name_with_space: false
+  separate_fn_name_with_space: false
+  raise_body_indent: false

eai_supcore/data/extensions/cmake/pre-commit-snippet.yaml

@@ -0,0 +1,7 @@
+# BEGIN eai-sup extension: cmake
+  - repo: https://github.com/cheshirekow/cmake-format-precommit
+    rev: v0.6.13
+    hooks:
+      - id: cmake-format
+      - id: cmake-lint
+# END eai-sup extension: cmake

eai_supcore/doctor_rails.py

@@ -0,0 +1,64 @@
+"""Doctor checks shared across eai-sup* for consumer rails and extensions."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from eai_supcore.extensions import status_extensions
+from eai_supcore.io_util import read_text
+from eai_supcore.paths import ESYSREPO_MANIFEST_NAME, TOOLS_LOCAL_GITIGNORE_ENTRY
+
+
+def add_rails_doctor_checks(report, workspace: Path) -> None:
+    """Append language-agnostic rails checks to a doctor report (``add`` method)."""
+    pre_commit = workspace / ".pre-commit-config.yaml"
+    gitlint = workspace / ".gitlint"
+    setup_dev = workspace / "scripts" / "setup-dev.py"
+    manifest = workspace / ESYSREPO_MANIFEST_NAME
+    gitignore = workspace / ".gitignore"
+
+    report.add(
+        ".pre-commit-config.yaml",
+        pre_commit.is_file(),
+        "run bootstrap (default --with-dev-hooks)" if not pre_commit.is_file() else str(pre_commit),
+    )
+    report.add(
+        ".gitlint",
+        gitlint.is_file(),
+        "run bootstrap (default --with-dev-hooks)" if not gitlint.is_file() else str(gitlint),
+    )
+    report.add(
+        "scripts/setup-dev.py",
+        setup_dev.is_file(),
+        "run bootstrap" if not setup_dev.is_file() else str(setup_dev),
+    )
+    report.add(
+        ESYSREPO_MANIFEST_NAME,
+        manifest.is_file(),
+        "run bootstrap (default --with-esysrepo-manifest)"
+        if not manifest.is_file()
+        else str(manifest),
+    )
+
+    tools_local_ok = False
+    detail = f"add {TOOLS_LOCAL_GITIGNORE_ENTRY} via bootstrap"
+    if gitignore.is_file():
+        lines = {line.strip() for line in read_text(gitignore).splitlines()}
+        tools_local_ok = (
+            TOOLS_LOCAL_GITIGNORE_ENTRY in lines or TOOLS_LOCAL_GITIGNORE_ENTRY.rstrip("/") in lines
+        )
+        detail = str(gitignore) if tools_local_ok else detail
+    report.add(".tools_local/ in .gitignore", tools_local_ok, detail)
+
+    for status in status_extensions(workspace):
+        if not status.recorded and not status.pre_commit_block_present:
+            continue
+        name = f"extension:{status.extension_id}"
+        if status.drift:
+            report.add(name, False, "; ".join(status.notes) or "drift detected")
+        else:
+            report.add(
+                name,
+                True,
+                "applied" if status.recorded else "hooks present (unrecorded)",
+            )

eai_supcore/extension_cli.py

@@ -0,0 +1,161 @@
+"""Typer command group for workspace extensions (shared wiring)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from eai_supcore.extensions import add_extension, list_extensions, status_extensions
+
+
+def attach_extension_commands(parent: typer.Typer, *, resolve_workspace) -> None:
+    """Register both ``extension`` and ``ext`` groups on ``parent``.
+
+    ``resolve_workspace`` is a callable ``(Path | None) -> Path``.
+    """
+    console = Console(stderr=True)
+
+    def _make_group() -> typer.Typer:
+        group = typer.Typer(
+            help="Workspace extensions (e.g. cmake)",
+            no_args_is_help=True,
+        )
+
+        @group.command("list")
+        def list_cmd(
+            workspace: Annotated[
+                Path | None,
+                typer.Option("--workspace", "-C", help="Workspace root"),
+            ] = None,
+            json_output: Annotated[bool, typer.Option("--json")] = False,
+        ) -> None:
+            """List available extensions and whether each is applied."""
+            root = resolve_workspace(workspace)
+            items = list_extensions(root)
+            if json_output:
+                typer.echo(
+                    json.dumps(
+                        [
+                            {
+                                "id": i.id,
+                                "description": i.description,
+                                "applied": i.applied,
+                            }
+                            for i in items
+                        ],
+                        indent=2,
+                    )
+                )
+                return
+            table = Table(title="Workspace extensions")
+            table.add_column("id")
+            table.add_column("applied")
+            table.add_column("description")
+            for item in items:
+                table.add_row(item.id, "yes" if item.applied else "no", item.description)
+            console.print(table)
+
+        @group.command("add")
+        def add_cmd(
+            extension_id: Annotated[str, typer.Argument(help="Extension id (e.g. cmake)")],
+            workspace: Annotated[
+                Path | None,
+                typer.Option("--workspace", "-C", help="Workspace root"),
+            ] = None,
+            force: Annotated[
+                bool, typer.Option("--force", help="Refresh managed snippets / config")
+            ] = False,
+            json_output: Annotated[bool, typer.Option("--json")] = False,
+        ) -> None:
+            """Apply one workspace extension."""
+            root = resolve_workspace(workspace)
+            result = add_extension(root, extension_id, force=force)
+            if json_output:
+                typer.echo(
+                    json.dumps(
+                        {
+                            "extension_id": result.extension_id,
+                            "ok": result.ok,
+                            "already_applied": result.already_applied,
+                            "created_files": result.created_files,
+                            "updated_files": result.updated_files,
+                            "warnings": result.warnings,
+                            "errors": result.errors,
+                        },
+                        indent=2,
+                    )
+                )
+            else:
+                if result.already_applied:
+                    console.print(
+                        f"[green]Extension `{extension_id}` already applied[/green] "
+                        "(use --force to refresh)"
+                    )
+                elif result.ok:
+                    console.print(f"[green]Applied extension[/green] `{extension_id}`")
+                    for path in result.created_files:
+                        console.print(f"  created: {path}")
+                    for path in result.updated_files:
+                        console.print(f"  updated: {path}")
+                for warning in result.warnings:
+                    console.print(f"[yellow]Warning:[/yellow] {warning}")
+                for error in result.errors:
+                    console.print(f"[red]Error:[/red] {error}")
+            if not result.ok:
+                raise typer.Exit(code=1)
+
+        @group.command("status")
+        def status_cmd(
+            workspace: Annotated[
+                Path | None,
+                typer.Option("--workspace", "-C", help="Workspace root"),
+            ] = None,
+            json_output: Annotated[bool, typer.Option("--json")] = False,
+        ) -> None:
+            """Show applied extensions and drift."""
+            root = resolve_workspace(workspace)
+            rows = status_extensions(root)
+            if json_output:
+                typer.echo(
+                    json.dumps(
+                        [
+                            {
+                                "extension_id": r.extension_id,
+                                "recorded": r.recorded,
+                                "pre_commit_block_present": r.pre_commit_block_present,
+                                "config_files_present": r.config_files_present,
+                                "config_files_missing": r.config_files_missing,
+                                "drift": r.drift,
+                                "notes": r.notes,
+                            }
+                            for r in rows
+                        ],
+                        indent=2,
+                    )
+                )
+                return
+            table = Table(title="Extension status")
+            table.add_column("id")
+            table.add_column("recorded")
+            table.add_column("hooks")
+            table.add_column("drift")
+            table.add_column("notes")
+            for row in rows:
+                table.add_row(
+                    row.extension_id,
+                    "yes" if row.recorded else "no",
+                    "yes" if row.pre_commit_block_present else "no",
+                    "yes" if row.drift else "no",
+                    "; ".join(row.notes) if row.notes else "—",
+                )
+            console.print(table)
+
+        return group
+
+    parent.add_typer(_make_group(), name="extension")
+    parent.add_typer(_make_group(), name="ext")

eai_supcore/extensions.py

@@ -0,0 +1,267 @@
+"""Workspace extension registry (cmake, …) shared by eai-sup* CLIs."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+
+import yaml
+
+from eai_supcore.io_util import read_text, write_text
+from eai_supcore.paths import EXTENSIONS_STATE_PATH
+from eai_supcore.templates import resolve_extension_templates
+
+BEGIN_MARK = "# BEGIN eai-sup extension: {id}"
+END_MARK = "# END eai-sup extension: {id}"
+
+
+@dataclass
+class ExtensionInfo:
+    id: str
+    description: str
+    applied: bool = False
+
+
+@dataclass
+class ExtensionApplyResult:
+    extension_id: str
+    created_files: list[str] = field(default_factory=list)
+    updated_files: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    already_applied: bool = False
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+
+@dataclass
+class ExtensionStatus:
+    extension_id: str
+    recorded: bool
+    pre_commit_block_present: bool
+    config_files_present: list[str] = field(default_factory=list)
+    config_files_missing: list[str] = field(default_factory=list)
+    drift: bool = False
+    notes: list[str] = field(default_factory=list)
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def extensions_state_path(workspace: Path) -> Path:
+    return workspace / EXTENSIONS_STATE_PATH
+
+
+def load_extensions_state(workspace: Path) -> dict:
+    path = extensions_state_path(workspace)
+    if not path.is_file():
+        return {"version": 1, "applied": {}}
+    data = yaml.safe_load(read_text(path)) or {}
+    if not isinstance(data, dict):
+        return {"version": 1, "applied": {}}
+    data.setdefault("version", 1)
+    data.setdefault("applied", {})
+    if not isinstance(data["applied"], dict):
+        data["applied"] = {}
+    return data
+
+
+def save_extensions_state(workspace: Path, state: dict) -> None:
+    path = extensions_state_path(workspace)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    write_text(path, yaml.safe_dump(state, sort_keys=False))
+
+
+def record_extension_applied(workspace: Path, extension_id: str) -> None:
+    state = load_extensions_state(workspace)
+    state["applied"][extension_id] = {"applied_at": _now_iso()}
+    save_extensions_state(workspace, state)
+
+
+def is_extension_recorded(workspace: Path, extension_id: str) -> bool:
+    return extension_id in load_extensions_state(workspace).get("applied", {})
+
+
+def baseline_hooks_present(workspace: Path) -> bool:
+    return (workspace / ".pre-commit-config.yaml").is_file()
+
+
+def _managed_block_present(pre_commit_text: str, extension_id: str) -> bool:
+    begin = BEGIN_MARK.format(id=extension_id)
+    end = END_MARK.format(id=extension_id)
+    return begin in pre_commit_text and end in pre_commit_text
+
+
+def _merge_pre_commit_snippet(
+    workspace: Path,
+    extension_id: str,
+    snippet: str,
+    *,
+    force: bool,
+) -> tuple[bool, str | None]:
+    """Return ``(changed, error)``."""
+    path = workspace / ".pre-commit-config.yaml"
+    if not path.is_file():
+        return False, "`.pre-commit-config.yaml` missing — run bootstrap first"
+    text = read_text(path)
+    begin = BEGIN_MARK.format(id=extension_id)
+    end = END_MARK.format(id=extension_id)
+    if _managed_block_present(text, extension_id):
+        if not force:
+            return False, None
+        start = text.index(begin)
+        stop = text.index(end) + len(end)
+        if stop < len(text) and text[stop] == "\n":
+            stop += 1
+        text = text[:start] + snippet.rstrip() + "\n" + text[stop:]
+        write_text(path, text if text.endswith("\n") else text + "\n")
+        return True, None
+
+    body = text.rstrip() + "\n\n" + snippet.rstrip() + "\n"
+    write_text(path, body)
+    return True, None
+
+
+def _apply_cmake(workspace: Path, *, force: bool = False) -> ExtensionApplyResult:
+    result = ExtensionApplyResult(extension_id="cmake")
+    if not baseline_hooks_present(workspace):
+        result.errors.append(
+            "Baseline rails missing (`.pre-commit-config.yaml`) — run "
+            "`eai-supinit bootstrap` or `eai-supmig bootstrap` first"
+        )
+        return result
+
+    try:
+        templates = resolve_extension_templates(workspace, "cmake")
+    except FileNotFoundError as exc:
+        result.errors.append(str(exc))
+        return result
+
+    snippet_path = templates / "pre-commit-snippet.yaml"
+    config_src = templates / "cmake-format.yaml"
+    if not config_src.is_file():
+        config_src = templates / ".cmake-format.yaml"
+    if not snippet_path.is_file():
+        result.errors.append(f"Missing snippet template: {snippet_path}")
+        return result
+
+    snippet = read_text(snippet_path)
+    begin = BEGIN_MARK.format(id="cmake")
+    end = END_MARK.format(id="cmake")
+    if begin not in snippet:
+        snippet = f"{begin}\n{snippet.rstrip()}\n{end}\n"
+
+    recorded = is_extension_recorded(workspace, "cmake")
+    pre_commit = workspace / ".pre-commit-config.yaml"
+    block_already = _managed_block_present(read_text(pre_commit), "cmake")
+    config_dest = workspace / ".cmake-format.yaml"
+    config_exists = config_dest.is_file()
+
+    if recorded and block_already and config_exists and not force:
+        result.already_applied = True
+        return result
+
+    changed, err = _merge_pre_commit_snippet(workspace, "cmake", snippet, force=force)
+    if err:
+        result.errors.append(err)
+        return result
+    if changed:
+        result.updated_files.append(".pre-commit-config.yaml")
+
+    if config_src.is_file() and (not config_exists or force):
+        write_text(config_dest, read_text(config_src))
+        if not config_exists:
+            result.created_files.append(".cmake-format.yaml")
+        else:
+            result.updated_files.append(".cmake-format.yaml")
+
+    state_path = extensions_state_path(workspace)
+    state_existed = state_path.is_file()
+    record_extension_applied(workspace, "cmake")
+    rel_state = EXTENSIONS_STATE_PATH.as_posix()
+    if state_existed:
+        result.updated_files.append(rel_state)
+    else:
+        result.created_files.append(rel_state)
+    return result
+
+
+def _status_cmake(workspace: Path) -> ExtensionStatus:
+    recorded = is_extension_recorded(workspace, "cmake")
+    pre_commit = workspace / ".pre-commit-config.yaml"
+    block = False
+    if pre_commit.is_file():
+        block = _managed_block_present(read_text(pre_commit), "cmake")
+    config = workspace / ".cmake-format.yaml"
+    present = [".cmake-format.yaml"] if config.is_file() else []
+    missing = [] if config.is_file() else [".cmake-format.yaml"]
+    notes: list[str] = []
+    if recorded and not block:
+        notes.append("managed pre-commit block missing")
+    if recorded and missing:
+        notes.append("config file(s) missing: " + ", ".join(missing))
+    if block and not recorded:
+        notes.append("pre-commit block present but not recorded in extensions.yaml")
+    drift = bool(notes)
+    return ExtensionStatus(
+        extension_id="cmake",
+        recorded=recorded,
+        pre_commit_block_present=block,
+        config_files_present=present,
+        config_files_missing=missing,
+        drift=drift,
+        notes=notes,
+    )
+
+
+@dataclass(frozen=True)
+class _ExtensionSpec:
+    id: str
+    description: str
+    apply_force: Callable[[Path, bool], ExtensionApplyResult]
+    status: Callable[[Path], ExtensionStatus]
+
+
+REGISTRY: dict[str, _ExtensionSpec] = {
+    "cmake": _ExtensionSpec(
+        id="cmake",
+        description="CMake builds — cmake-format + cmake-lint pre-commit hooks",
+        apply_force=lambda ws, force: _apply_cmake(ws, force=force),
+        status=_status_cmake,
+    ),
+}
+
+
+def list_extensions(workspace: Path | None = None) -> list[ExtensionInfo]:
+    applied: dict = {}
+    if workspace is not None:
+        applied = load_extensions_state(workspace).get("applied", {})
+    return [
+        ExtensionInfo(
+            id=spec.id,
+            description=spec.description,
+            applied=spec.id in applied,
+        )
+        for spec in REGISTRY.values()
+    ]
+
+
+def add_extension(
+    workspace: Path, extension_id: str, *, force: bool = False
+) -> ExtensionApplyResult:
+    spec = REGISTRY.get(extension_id)
+    if spec is None:
+        result = ExtensionApplyResult(extension_id=extension_id)
+        known = ", ".join(sorted(REGISTRY)) or "(none)"
+        result.errors.append(f"Unknown extension {extension_id!r}. Known: {known}")
+        return result
+    return spec.apply_force(workspace, force)
+
+
+def status_extensions(workspace: Path) -> list[ExtensionStatus]:
+    return [spec.status(workspace) for spec in REGISTRY.values()]

eai_supcore/git_ops.py

@@ -0,0 +1,107 @@
+"""Cross-platform Git subprocess helpers."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from eai_supcore.paths import AI_RULES_SUBMODULE
+
+AI_RULES_CHECKOUT_MANUAL = "manual_clone"
+AI_RULES_CHECKOUT_SUBMODULE = "submodule"
+AI_RULES_CHECKOUT_MISSING = "missing"
+AI_RULES_CHECKOUT_NON_GIT = "non_git"
+
+
+class GitError(RuntimeError):
+    pass
+
+
+def run_git(args: list[str], *, cwd: Path, check: bool = True) -> subprocess.CompletedProcess[str]:
+    cmd = ["git", *args]
+    try:
+        result = subprocess.run(
+            cmd,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        raise GitError("git executable not found on PATH") from exc
+    if check and result.returncode != 0:
+        stderr = (result.stderr or "").strip()
+        raise GitError(f"git {' '.join(args)} failed: {stderr}")
+    return result
+
+
+def git_output(args: list[str], *, cwd: Path) -> str:
+    result = run_git(args, cwd=cwd)
+    return (result.stdout or "").strip()
+
+
+def submodule_exists(workspace: Path, path: Path) -> bool:
+    gitmodules = workspace / ".gitmodules"
+    if not gitmodules.is_file():
+        return False
+    rel = path.as_posix()
+    content = gitmodules.read_text(encoding="utf-8", errors="replace")
+    return f"path = {rel}" in content or f"path = {path}" in content
+
+
+def is_git_repository(path: Path) -> bool:
+    if not path.is_dir():
+        return False
+    try:
+        git_output(["rev-parse", "--git-dir"], cwd=path)
+    except GitError:
+        return False
+    return True
+
+
+def paths_with_pending_changes(workspace: Path, rel_paths: list[str]) -> list[str]:
+    """Return workspace-relative paths with staged, modified, or untracked changes."""
+    if not rel_paths or not is_git_repository(workspace):
+        return []
+    try:
+        porcelain = git_output(["status", "--porcelain", "--", *rel_paths], cwd=workspace)
+    except GitError:
+        return []
+    if not porcelain:
+        return []
+    pending: set[str] = set()
+    for line in porcelain.splitlines():
+        if len(line) < 4:
+            continue
+        rel = line[3:].strip().replace("\\", "/")
+        if rel:
+            pending.add(rel)
+    return sorted(pending)
+
+
+def commit_paths(workspace: Path, rel_paths: list[str], message: str) -> str:
+    """Stage ``rel_paths`` and create a commit; return the new commit SHA."""
+    if not rel_paths:
+        raise GitError("no paths to commit")
+    run_git(["add", "--", *rel_paths], cwd=workspace)
+    run_git(["commit", "-m", message], cwd=workspace)
+    return git_output(["rev-parse", "HEAD"], cwd=workspace)
+
+
+def classify_ai_rules_checkout(workspace: Path, ai_rules_path: Path) -> str:
+    """Classify ``tools/ai-rules`` for reset and bootstrap messaging."""
+    if not ai_rules_path.exists():
+        return AI_RULES_CHECKOUT_MISSING
+    if submodule_exists(workspace, AI_RULES_SUBMODULE):
+        return AI_RULES_CHECKOUT_SUBMODULE
+    if is_git_repository(ai_rules_path):
+        return AI_RULES_CHECKOUT_MANUAL
+    return AI_RULES_CHECKOUT_NON_GIT
+
+
+def add_submodule(workspace: Path, url: str, path: Path) -> None:
+    rel = path.as_posix()
+    if submodule_exists(workspace, path):
+        return
+    run_git(["submodule", "add", url, rel], cwd=workspace)

eai_supcore/io_util.py

@@ -0,0 +1,14 @@
+"""UTF-8 file I/O helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def read_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def write_text(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8", newline="\n")

eai_supcore/paths.py

@@ -0,0 +1,22 @@
+"""Shared path constants for the eai-sup* family."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+AI_RULES_SUBMODULE = Path("tools") / "ai-rules"
+CURSOR_RULES_DIR = Path(".cursor") / "rules"
+DEFAULT_AI_RULES_URL = "ssh://git@gitlab.com/libesys/ai-workflows/superbuild-workflow.git"
+
+# Steady-state layout roles (repository-layout.md)
+STEADY_STATE_DIRS = (
+    Path("src"),
+    Path("libs"),
+    Path("docs") / "adr",
+    Path("prompts"),
+)
+
+TOOLS_LOCAL_GITIGNORE_ENTRY = ".tools_local/"
+ESYSREPO_MANIFEST_NAME = ".esysrepo.manifest.xml"
+# Shared eai-supcore tool state (extensions apply to the whole workspace)
+EXTENSIONS_STATE_PATH = Path(".tools") / "esys" / "eai-supcore" / "extensions.yaml"

eai_supcore/templates.py

@@ -0,0 +1,70 @@
+"""Resolve consumer / extension template roots (method mount vs bundled)."""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+from eai_supcore.paths import AI_RULES_SUBMODULE
+
+# Dest path in workspace → template filename (no leading dots — setuptools package-data)
+CONSUMER_TEMPLATE_FILES: dict[str, str] = {
+    ".pre-commit-config.yaml": "pre-commit-config.yaml",
+    ".gitlint": "gitlint",
+    ".esysrepo.manifest.xml": "esysrepo.manifest.xml",
+    "scripts/setup-dev.py": "scripts/setup-dev.py",
+}
+
+
+def bundled_data_root() -> Path:
+    """Return the filesystem path to ``eai_supcore.data``."""
+    root = resources.files("eai_supcore") / "data"
+    return Path(str(root))
+
+
+def resolve_template_file(template_root: Path, dest_rel: str) -> Path | None:
+    """Locate a template file by destination name or undotted package-data name."""
+    dest_rel = dest_rel.replace("\\", "/")
+    candidates = [dest_rel]
+    mapped = CONSUMER_TEMPLATE_FILES.get(dest_rel)
+    if mapped and mapped not in candidates:
+        candidates.append(mapped)
+    name = Path(dest_rel).name
+    if name.startswith("."):
+        parent = Path(dest_rel).parent
+        undotted = name[1:] if str(parent) == "." else f"{parent.as_posix()}/{name[1:]}"
+        if undotted not in candidates:
+            candidates.append(undotted)
+    for rel in candidates:
+        path = template_root / rel
+        if path.is_file():
+            return path
+    return None
+
+
+def _has_consumer_hooks_template(root: Path) -> bool:
+    return resolve_template_file(root, ".pre-commit-config.yaml") is not None
+
+
+def resolve_consumer_templates(workspace: Path) -> Path:
+    """Prefer ``tools/ai-rules/templates/consumer``; else bundled package data."""
+    mounted = workspace / AI_RULES_SUBMODULE / "templates" / "consumer"
+    if mounted.is_dir() and _has_consumer_hooks_template(mounted):
+        return mounted
+    bundled = bundled_data_root() / "consumer"
+    if not _has_consumer_hooks_template(bundled):
+        raise FileNotFoundError(
+            "Consumer templates not found (mount tools/ai-rules or reinstall eai-supcore)"
+        )
+    return bundled
+
+
+def resolve_extension_templates(workspace: Path, extension_id: str) -> Path:
+    """Prefer method-tree extension templates; else bundled package data."""
+    mounted = workspace / AI_RULES_SUBMODULE / "templates" / "extensions" / extension_id
+    if mounted.is_dir():
+        return mounted
+    bundled = bundled_data_root() / "extensions" / extension_id
+    if not bundled.is_dir():
+        raise FileNotFoundError(f"Extension templates missing for id={extension_id!r}")
+    return bundled

eai_supcore-0.5.0.dist-info/METADATA

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: eai-supcore
+Version: 0.5.0
+Summary: Shared steady-state bootstrap APIs for the eai-sup* CLI family
+Author-email: Michel Gillet <michel.gillet@libesys.org>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.com/libesys/ai-workflows/superbuild-workflow
+Project-URL: Repository, https://gitlab.com/libesys/ai-workflows/superbuild-workflow.git
+Keywords: superbuild,cmake,conan,bootstrap,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.7
+
+# eai-supcore
+
+Shared steady-state bootstrap and consumer-rails APIs for **`eai-supinit`** and **`eai-supmig`**.
+
+Includes:
+
+- Layout / AI-rules / Cursor helpers
+- Language-agnostic consumer rails (`scaffold_consumer_dev_rails`)
+- Workspace extensions registry (`cmake`, …) and shared `extension`/`ext` CLI wiring
+
+See [docs/init-assistant.md](../../docs/init-assistant.md) and
+[ADR-0002](../../docs/adr/0002-consumer-rails-and-workspace-extensions.md).

eai_supcore-0.5.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+eai_supcore/__init__.py,sha256=rSY1dlFbovl2W61BBPRUaJm05iarvtxkUPVfV2wnVyk,93
+eai_supcore/bootstrap.py,sha256=CpqQwXNhkWRKCWzQUUZ__QlhQImIMddGFcczreCwOSM,9267
+eai_supcore/doctor_rails.py,sha256=Geu4rP_bhIQBGbsoDityFZUsOD9dzmz72fLobIFlqaY,2357
+eai_supcore/extension_cli.py,sha256=lnVP7YKPktDdGYWh7uutesNUAtkAoZlERHyNQn37JjE,6324
+eai_supcore/extensions.py,sha256=8FuRrjsm1Wd9L-SccLiIXVfv6H3T0KgASgAu94Kh_pM,8812
+eai_supcore/git_ops.py,sha256=srLGT3KlptAcVpB9q7u-HMfbSqPGEDG2hfL6CQjqdgo,3369
+eai_supcore/io_util.py,sha256=9d96omb8fo9eDPBIxFRW5O6q8lPIYi81t0uVt2IrxGE,336
+eai_supcore/paths.py,sha256=K2MUabor9Fw_AwiNNXZn-VT6TYQeP2ruZ23U9L6oGdk,713
+eai_supcore/templates.py,sha256=8dI_KXwRpWdAQAIceK0bOoQzgTGkFVt9zn-M0l8AJEQ,2668
+eai_supcore/data/__init__.py,sha256=CpPVFhqXLUUTQCA2G_zMrGeSAukMvZ8mRjiitXi2pAU,70
+eai_supcore/data/consumer/esysrepo.manifest.xml,sha256=G5D64XqJWVRJA8baguh3zYzkh5z_npbYL9VTmK4609s,365
+eai_supcore/data/consumer/gitignore,sha256=FhawrDyGw_CPPBgRn6wNdvzmL4Bh_P4drVRkJOu9bCc,229
+eai_supcore/data/consumer/gitlint,sha256=_sKCZZyGat1Ne01MDRNG77PXnowtGj5zoPcpZZrJfmc,250
+eai_supcore/data/consumer/pre-commit-config.yaml,sha256=0snq0YPUsCJpMsLvpWoWFtYc6V9JTY3DJ2iHGkSYpcI,772
+eai_supcore/data/consumer/scripts/setup-dev.py,sha256=Uybtbf8gjlAsD64BXJhbBEDrmyJuamVNejVDpV2S1z8,2560
+eai_supcore/data/extensions/cmake/cmake-format.yaml,sha256=-ri3N82xbfnPjFgNk02qiKECwNKTx-AkJGtaCcciYEI,328
+eai_supcore/data/extensions/cmake/pre-commit-snippet.yaml,sha256=z1uxU9p4YPu7wJLIK-CAhUsXTUNnSldXFLsxYnGbGHY,204
+eai_supcore-0.5.0.dist-info/METADATA,sha256=_Gk-f7ARjMbqvjm9dmUAhbUBoMmQ9Kl_PFmHOWlI1zE,1368
+eai_supcore-0.5.0.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
+eai_supcore-0.5.0.dist-info/top_level.txt,sha256=Pfm5UJULDM0tne4404L5azsrkC_BV2YfF0NHCKi0RrU,12
+eai_supcore-0.5.0.dist-info/RECORD,,

eai_supcore-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (79.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

eai_supcore-0.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+eai_supcore