eai-supinit 0.5.0__py3-none-any.whl

eai_supinit/__init__.py

@@ -0,0 +1,3 @@
+"""eai-supinit: greenfield multi-repo / superbuild init assistant."""
+
+__version__ = "0.5.0"

eai_supinit/__main__.py

@@ -0,0 +1,6 @@
+"""Module entry: ``python -m eai_supinit``."""
+
+from eai_supinit.cli import main
+
+if __name__ == "__main__":
+    main()

eai_supinit/agent_phrases.py

@@ -0,0 +1,57 @@
+"""Copy-paste agent phrases for eai-supinit."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from eai_supinit.workflow_state import WorkflowState
+
+PHRASE_BOOTSTRAP = (
+    "Run `eai-supinit bootstrap --with-ai-rules --with-cursor --yes` for this workspace."
+)
+PHRASE_ASSESS = "Run `eai-supinit assess` for this workspace."
+PHRASE_PLAN = "Run `eai-supinit plan` for this workspace."
+PHRASE_PROMPT = "Run `eai-supinit prompt` for this workspace."
+PHRASE_DOCTOR = "Run `eai-supinit doctor` for this workspace."
+PHRASE_SIGN_OFF = (
+    "Run `eai-supinit workflow sign-off` after reviewing init deliverables "
+    "(do not edit workflow-state.yaml by hand)."
+)
+
+
+def agent_phrase_rules_markdown() -> str:
+    return """## Agent phrase rules
+
+Prefer the **Tell your agent** lines printed by `eai-supinit workflow`.
+Do not invent alternate CLI flags when a printed phrase exists.
+"""
+
+
+def format_suggested_tell_agent_line(state: WorkflowState) -> str | None:
+    if state.next_milestone is None:
+        if state.deliverables.signed_off:
+            return None
+        if state.deliverables.deliverables_complete:
+            return PHRASE_SIGN_OFF
+        return None
+    gate = state.next_milestone.gate_id
+    if gate == "layout_ready" or gate == "ai_rules_mounted":
+        return PHRASE_BOOTSTRAP
+    if gate == "prompts_ready":
+        return PHRASE_PROMPT
+    if gate == "doctor_clean":
+        return PHRASE_DOCTOR
+    if gate == "init_signed_off":
+        return PHRASE_SIGN_OFF
+    return None
+
+
+NEXT_COMMAND_PHRASE_KEYS = {
+    "bootstrap": PHRASE_BOOTSTRAP,
+    "assess": PHRASE_ASSESS,
+    "plan": PHRASE_PLAN,
+    "prompt": PHRASE_PROMPT,
+    "doctor": PHRASE_DOCTOR,
+    "sign-off": PHRASE_SIGN_OFF,
+}

eai_supinit/assess.py

@@ -0,0 +1,105 @@
+"""Inspect workspace and write greenfield workspace contract."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+
+from eai_supcore.git_ops import is_git_repository
+from eai_supcore.io_util import write_text
+from eai_supinit import __version__
+from eai_supinit.model.contract import (
+    LayoutPresence,
+    WorkspaceContract,
+    WorkspaceMetadata,
+    WorkspaceReadiness,
+)
+from eai_supinit.model.serialize import contract_to_yaml
+from eai_supinit.paths import InitPaths
+from eai_supinit.workflow_state import refresh_workflow_state
+
+
+def _layout_presence(workspace: Path) -> LayoutPresence:
+    return LayoutPresence(
+        src=(workspace / "src").is_dir(),
+        libs=(workspace / "libs").is_dir(),
+        docs_adr=(workspace / "docs" / "adr").is_dir(),
+        agents_md=(workspace / "AGENTS.md").is_file(),
+        ai_rules=(workspace / "tools" / "ai-rules").is_dir()
+        and is_git_repository(workspace / "tools" / "ai-rules"),
+        cursor_rules=(workspace / ".cursor" / "rules").is_dir(),
+        cmake_root=(workspace / "CMakeLists.txt").is_file(),
+        conan_root=(workspace / "conanfile.py").is_file() or (workspace / "conan").is_dir(),
+    )
+
+
+def render_summary(contract: WorkspaceContract) -> str:
+    layout = contract.layout
+    lines = [
+        "# Workspace summary",
+        "",
+        f"Generated by eai-supinit {contract.metadata.tool_version} at "
+        f"{contract.metadata.generated_at}.",
+        "",
+        "## Layout presence",
+        "",
+        f"- `src/`: {'yes' if layout.src else 'no'}",
+        f"- `libs/`: {'yes' if layout.libs else 'no'}",
+        f"- `docs/adr/`: {'yes' if layout.docs_adr else 'no'}",
+        f"- `AGENTS.md`: {'yes' if layout.agents_md else 'no'}",
+        f"- `tools/ai-rules/`: {'yes' if layout.ai_rules else 'no'}",
+        f"- `.cursor/rules/`: {'yes' if layout.cursor_rules else 'no'}",
+        f"- Root `CMakeLists.txt`: {'yes' if layout.cmake_root else 'no'}",
+        f"- Conan entry: {'yes' if layout.conan_root else 'no'}",
+        "",
+        f"**Readiness:** {contract.readiness.completeness}",
+        "",
+        f"**Next:** {contract.readiness.recommended_next_action}",
+        "",
+    ]
+    if contract.readiness.blockers:
+        lines.extend(["## Blockers", ""])
+        lines.extend(f"- {b}" for b in contract.readiness.blockers)
+        lines.append("")
+    if contract.notes:
+        lines.extend(["## Notes", ""])
+        lines.extend(f"- {n}" for n in contract.notes)
+        lines.append("")
+    return "\n".join(lines)
+
+
+def run_assessment(paths: InitPaths) -> WorkspaceContract:
+    paths.ensure_tool_state_dirs()
+    layout = _layout_presence(paths.workspace)
+    notes: list[str] = [
+        "Greenfield assess — no legacy Google-repo inventory.",
+        "Target steady-state layout: src/, libs/, docs/adr/, AGENTS.md, tools/ai-rules/.",
+    ]
+    blockers: list[str] = []
+    if not paths.workspace.is_dir():
+        blockers.append("Workspace directory missing")
+
+    recommended = "eai-supinit plan"
+    if not layout.src or not layout.libs or not layout.docs_adr:
+        recommended = "eai-supinit bootstrap --with-ai-rules --with-cursor --yes"
+        notes.append("Layout dirs incomplete — bootstrap will scaffold steady-state dirs.")
+
+    completeness = "good" if not blockers else "partial"
+    contract = WorkspaceContract(
+        metadata=WorkspaceMetadata(
+            generated_at=datetime.now(UTC).isoformat(),
+            tool_version=__version__,
+            workspace_path=str(paths.workspace),
+        ),
+        layout=layout,
+        notes=notes,
+        readiness=WorkspaceReadiness(
+            completeness=completeness,
+            blockers=blockers,
+            recommended_next_action=recommended,
+        ),
+    )
+    write_text(paths.contract_path, contract_to_yaml(contract))
+    write_text(paths.summary_path, render_summary(contract))
+    refresh_workflow_state(paths)
+    return contract

eai_supinit/bootstrap/runner.py

@@ -0,0 +1,201 @@
+"""Bootstrap greenfield steady-state layout via eai-supcore."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from eai_supcore.bootstrap import (
+    SharedBootstrapResult,
+    ensure_steady_state_dirs,
+    materialize_cursor_rules,
+    mount_ai_rules,
+    scaffold_consumer_dev_rails,
+    write_cursor_overlay,
+)
+from eai_supcore.io_util import write_text
+from eai_supcore.paths import DEFAULT_AI_RULES_URL
+from eai_supinit.agent_phrases import agent_phrase_rules_markdown
+from eai_supinit.paths import LOCAL_CURSOR_OVERLAY, InitPaths
+from eai_supinit.plan import load_contract
+
+
+@dataclass
+class BootstrapResult:
+    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 merge_shared(self, shared: SharedBootstrapResult) -> None:
+        self.created_dirs.extend(shared.created_dirs)
+        self.created_files.extend(shared.created_files)
+        self.submodule_added = self.submodule_added or shared.submodule_added
+        self.ai_rules_found = self.ai_rules_found or shared.ai_rules_found
+        self.cursor_rules_materialized.extend(shared.cursor_rules_materialized)
+        self.warnings.extend(shared.warnings)
+        self.errors.extend(shared.errors)
+
+
+def _scaffold_agents(paths: InitPaths, result: BootstrapResult) -> None:
+    if paths.agents_path.exists():
+        return
+    content = f"""# AGENTS.md
+
+Local superbuild workspace. Read this file first, then `tools/ai-rules/AGENTS.md`.
+
+## Workspace role
+
+Greenfield multi-repo / superbuild. Steady-state layout:
+
+- `src/` — first-party member repositories
+- `libs/` — third-party or patched deps not from Conan
+- `docs/adr/` — workspace ADRs
+- `tools/ai-rules/` — shared superbuild-workflow policy (submodule)
+
+## Init artifacts
+
+Journey state: `.tools/esys/eai-supinit/` (committed tool state).
+Prompts: `prompts/` — commit after `eai-supinit prompt`.
+
+## Tell your agent
+
+Use phrases in `prompts/` or run `eai-supinit workflow`.
+
+{agent_phrase_rules_markdown()}
+
+See `tools/ai-rules/docs/init-assistant.md` when mounted.
+"""
+    write_text(paths.agents_path, content)
+    result.created_files.append("AGENTS.md")
+
+
+def _write_init_overlay(paths: InitPaths, shared: SharedBootstrapResult) -> None:
+    content = f"""---
+description: Local init overlay — workspace-specific exceptions
+alwaysApply: true
+---
+
+# Local init overlay
+
+Read `.tools/esys/eai-supinit/workspace-contract.yaml` and root `AGENTS.md`.
+Shared policy: `tools/ai-rules/AGENTS.md`.
+
+Document exceptions here; do not fork shared policy under `tools/ai-rules/`.
+
+{agent_phrase_rules_markdown()}
+
+## Version control at checkpoints
+
+When `eai-supinit` prints **Commit checkpoint**, remind the user to commit (or confirm
+auto-commit ran). Commit **`prompts/`** with **`.tools/esys/eai-supinit/`**.
+"""
+    write_cursor_overlay(
+        paths.workspace,
+        shared,
+        overlay_name=LOCAL_CURSOR_OVERLAY,
+        content=content,
+    )
+
+
+def run_bootstrap(
+    paths: InitPaths,
+    *,
+    with_ai_rules: bool = False,
+    ai_rules_url: str = DEFAULT_AI_RULES_URL,
+    with_cursor: bool = False,
+    with_dev_hooks: bool = True,
+    with_esysrepo_manifest: bool = True,
+    install_hooks: bool = False,
+    dry_run: bool = False,
+) -> BootstrapResult:
+    result = BootstrapResult()
+    paths.ensure_tool_state_dirs()
+    result.created_dirs.append(".tools/esys/eai-supinit")
+    result.created_dirs.append("prompts")
+
+    if dry_run:
+        result.warnings.append("Dry run — no files or submodules modified")
+        return result
+
+    try:
+        load_contract(paths)
+    except FileNotFoundError:
+        result.warnings.append(
+            "No workspace contract; run `eai-supinit assess` for richer bootstrap"
+        )
+
+    shared = SharedBootstrapResult()
+    ensure_steady_state_dirs(paths.workspace, shared)
+    scaffold_consumer_dev_rails(
+        paths.workspace,
+        shared,
+        with_hooks=with_dev_hooks,
+        with_manifest=with_esysrepo_manifest,
+        install_hooks=install_hooks,
+    )
+    result.merge_shared(shared)
+
+    _scaffold_agents(paths, result)
+
+    shared2 = SharedBootstrapResult()
+    if with_ai_rules:
+        mount_ai_rules(paths.workspace, shared2, ai_rules_url=ai_rules_url)
+    if with_cursor:
+        materialize_cursor_rules(paths.workspace, shared2)
+        _write_init_overlay(paths, shared2)
+    result.merge_shared(shared2)
+
+    next_steps = ["# Next steps", ""]
+    step = 1
+    if not paths.contract_path.is_file():
+        next_steps.append(f"{step}. Run `eai-supinit assess`")
+        step += 1
+    else:
+        next_steps.append(f"{step}. Review `.tools/esys/eai-supinit/workspace-summary.md`")
+        step += 1
+    if not paths.plan_path.is_file():
+        next_steps.append(f"{step}. Run `eai-supinit plan`")
+        step += 1
+    next_steps.append(f"{step}. Run `eai-supinit prompt` for AI handoff")
+    step += 1
+    if result.submodule_added:
+        next_steps.append(f"{step}. `git submodule update --init tools/ai-rules`")
+        step += 1
+    if with_dev_hooks and not install_hooks:
+        next_steps.append(f"{step}. `python scripts/setup-dev.py` (pre-commit + gitlint)")
+        step += 1
+    next_steps.append(
+        f"{step}. Optional: `eai-supinit extension add cmake` when using CMake builds"
+    )
+    step += 1
+    next_steps.append(f"{step}. Run `eai-supinit doctor` then `eai-supinit workflow sign-off`")
+    next_steps.append("")
+    write_text(paths.next_steps_path, "\n".join(next_steps))
+    result.created_files.append(".tools/esys/eai-supinit/next-steps.md")
+
+    summary_lines = [
+        "# Bootstrap summary",
+        "",
+        f"- AI rules checkout found: {result.ai_rules_found}",
+        f"- Submodule added: {result.submodule_added}",
+        f"- Cursor rules materialized: {len(result.cursor_rules_materialized)}",
+        f"- Dev hooks scaffolded: {with_dev_hooks}",
+        f"- esysrepo manifest scaffolded: {with_esysrepo_manifest}",
+        "",
+        "## Created directories",
+        "",
+    ]
+    summary_lines.extend(f"- `{d}`" for d in result.created_dirs)
+    summary_lines.extend(["", "## Created files", ""])
+    summary_lines.extend(f"- `{f}`" for f in result.created_files)
+    if result.warnings:
+        summary_lines.extend(["", "## Warnings", ""])
+        summary_lines.extend(f"- {w}" for w in result.warnings)
+    if result.errors:
+        summary_lines.extend(["", "## Errors", ""])
+        summary_lines.extend(f"- {e}" for e in result.errors)
+    write_text(paths.bootstrap_summary_path, "\n".join(summary_lines))
+    return result