hexaswarm-core 0.1.1__tar.gz

hexaswarm_core-0.1.1/.gitignore

@@ -0,0 +1,63 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Pytest / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.nox/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# Secrets
+.env
+.env.*
+!.env.example
+.secrets/
+*.key
+*.pem
+
+# Hexa runtime (never committed — these are generated per-clone)
+.hexa/session.uuid
+.ai-sync/locks/*.lock
+.ai-sync/locks/*.lock.hb
+.ai-sync/KILL
+.ai-sync/logs/

hexaswarm_core-0.1.1/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: hexaswarm-core
+Version: 0.1.1
+Summary: Universal primitives for Claude-native multi-agent software delivery — orchestrator, cost tracker, safety, stack adapters, and the `hexa` CLI.
+Project-URL: Homepage, https://github.com/pna03100/hexa-swarm-template
+Project-URL: Issues, https://github.com/pna03100/hexa-swarm-template/issues
+Author-email: PNA Company <taemin@pnamarketing.co.kr>
+License: MIT
+Keywords: agentic,anthropic,claude,claude-code,enterprise-ai,hexa-swarm,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: structlog<26,>=24.4
+Requires-Dist: typer<0.20,>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy<2,>=1.12; extra == 'dev'
+Requires-Dist: pytest-cov<7,>=5; extra == 'dev'
+Requires-Dist: pytest<9,>=8.3; extra == 'dev'
+Requires-Dist: ruff<0.12,>=0.8; extra == 'dev'
+Requires-Dist: types-pyyaml<7,>=6.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# hexa-swarm-core
+
+Universal primitives for Claude-native multi-agent software delivery.
+Provides the `hexa` CLI plus a Python library used by `hexa-swarm-template` and any project adopted via `hexa adopt .`.
+
+## What lives here
+
+- **`hexa` CLI** — `hexa adopt`, `hexa quality-gate`, `hexa lock`, `hexa session`, `hexa cost-track`
+- **StackAdapter protocol** — pluggable language/framework support (py-fastapi, node-next, go-chi, …)
+- **Orchestrator primitives** — atomic file locks, session UUID, heartbeat, contract writer queue
+- **Telemetry** — JSONL cost tracker, structured logging, trace IDs
+- **Safety** — KillSwitch, CostCeiling, CircuitBreaker, stochastic delay
+- **Exceptions** — `SafetyViolationError(invariant=...)` hierarchy
+- **Config** — Pydantic nested settings
+
+## Install
+
+```bash
+pipx install hexa-swarm-core
+hexa --help
+```
+
+## Adopt an existing repo (non-destructive)
+
+```bash
+cd my-existing-project
+hexa adopt . --dry-run   # show what would change
+hexa adopt .             # install Tier A only
+```
+
+See the parent repo's [README](../README.md) and [ARCHITECTURE.md](../ARCHITECTURE.md) for the full picture.

hexaswarm_core-0.1.1/README.md

@@ -0,0 +1,31 @@
+# hexa-swarm-core
+
+Universal primitives for Claude-native multi-agent software delivery.
+Provides the `hexa` CLI plus a Python library used by `hexa-swarm-template` and any project adopted via `hexa adopt .`.
+
+## What lives here
+
+- **`hexa` CLI** — `hexa adopt`, `hexa quality-gate`, `hexa lock`, `hexa session`, `hexa cost-track`
+- **StackAdapter protocol** — pluggable language/framework support (py-fastapi, node-next, go-chi, …)
+- **Orchestrator primitives** — atomic file locks, session UUID, heartbeat, contract writer queue
+- **Telemetry** — JSONL cost tracker, structured logging, trace IDs
+- **Safety** — KillSwitch, CostCeiling, CircuitBreaker, stochastic delay
+- **Exceptions** — `SafetyViolationError(invariant=...)` hierarchy
+- **Config** — Pydantic nested settings
+
+## Install
+
+```bash
+pipx install hexa-swarm-core
+hexa --help
+```
+
+## Adopt an existing repo (non-destructive)
+
+```bash
+cd my-existing-project
+hexa adopt . --dry-run   # show what would change
+hexa adopt .             # install Tier A only
+```
+
+See the parent repo's [README](../README.md) and [ARCHITECTURE.md](../ARCHITECTURE.md) for the full picture.

hexaswarm_core-0.1.1/hexa_swarm_core/__init__.py

@@ -0,0 +1,7 @@
+"""hexa_swarm_core — Universal primitives for Claude-native multi-agent delivery."""
+
+from __future__ import annotations
+
+from hexa_swarm_core._version import __version__
+
+__all__ = ["__version__"]

hexaswarm_core-0.1.1/hexa_swarm_core/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

hexaswarm_core-0.1.1/hexa_swarm_core/adapters/__init__.py

@@ -0,0 +1,12 @@
+from hexa_swarm_core.adapters.base import BaseAdapter
+from hexa_swarm_core.adapters.protocol import InvariantEnforcer, StackAdapter
+from hexa_swarm_core.adapters.registry import ADAPTERS, detect_adapters, get_adapter
+
+__all__ = [
+    "ADAPTERS",
+    "BaseAdapter",
+    "InvariantEnforcer",
+    "StackAdapter",
+    "detect_adapters",
+    "get_adapter",
+]

hexaswarm_core-0.1.1/hexa_swarm_core/adapters/_node_base.py

@@ -0,0 +1,66 @@
+"""Shared plumbing for Node-family adapters (next, nest, express)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from hexa_swarm_core.adapters.base import BaseAdapter
+from hexa_swarm_core.adapters.protocol import CommandSpec
+
+
+class NodeAdapterBase(BaseAdapter):
+    """Base for Node/TS adapters - handles pnpm/yarn/npm dispatch uniformly."""
+
+    language = "typescript"
+
+    @staticmethod
+    def _pm(project_root: Path) -> str:
+        if (project_root / "pnpm-lock.yaml").exists():
+            return "pnpm"
+        if (project_root / "yarn.lock").exists():
+            return "yarn"
+        return "npm"
+
+    def _run(self, project_root: Path, script: str) -> list[CommandSpec]:
+        pm = self._pm(project_root)
+        if pm == "pnpm":
+            return [CommandSpec(["pnpm", "run", script], description=f"pnpm run {script}")]
+        if pm == "yarn":
+            return [CommandSpec(["yarn", script], description=f"yarn {script}")]
+        return [CommandSpec(["npm", "run", script, "--if-present"], description=f"npm run {script}")]
+
+    def lint_cmd(self, project_root: Path) -> list[CommandSpec]:
+        return self._run(project_root, "lint")
+
+    def test_cmd(self, project_root: Path) -> list[CommandSpec]:
+        return self._run(project_root, "test")
+
+    def build_cmd(self, project_root: Path) -> list[CommandSpec]:
+        return self._run(project_root, "build")
+
+    def format_check_cmd(self, project_root: Path) -> list[CommandSpec]:
+        pm = self._pm(project_root)
+        if pm == "pnpm":
+            return [CommandSpec(["pnpm", "exec", "prettier", "--check", "."], description="prettier --check")]
+        if pm == "yarn":
+            return [CommandSpec(["yarn", "prettier", "--check", "."], description="yarn prettier --check")]
+        return [CommandSpec(["npx", "--yes", "prettier", "--check", "."], description="npx prettier --check")]
+
+    def typecheck_cmd(self, project_root: Path) -> list[CommandSpec]:
+        pm = self._pm(project_root)
+        if pm == "pnpm":
+            return [CommandSpec(["pnpm", "exec", "tsc", "--noEmit"], description="tsc --noEmit")]
+        if pm == "yarn":
+            return [CommandSpec(["yarn", "tsc", "--noEmit"], description="yarn tsc --noEmit")]
+        return [CommandSpec(["npx", "--yes", "tsc", "--noEmit"], description="npx tsc --noEmit")]
+
+    def dep_audit_cmd(self, project_root: Path) -> list[CommandSpec]:
+        pm = self._pm(project_root)
+        if pm == "pnpm":
+            return [CommandSpec(["pnpm", "audit", "--audit-level=high"], description="pnpm audit")]
+        if pm == "yarn":
+            return [CommandSpec(["yarn", "npm", "audit", "--severity", "high"], description="yarn npm audit")]
+        return [CommandSpec(["npm", "audit", "--audit-level=high"], description="npm audit")]
+
+
+__all__ = ["NodeAdapterBase"]

hexaswarm_core-0.1.1/hexa_swarm_core/adapters/base.py

@@ -0,0 +1,70 @@
+"""BaseAdapter — a default skeleton most adapters can subclass."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from hexa_swarm_core.adapters.protocol import CommandSpec, InvariantEnforcer
+
+
+class BaseAdapter:
+    """Common adapter plumbing.
+
+    Subclasses override attributes (name, language, detect_files, detect_imports,
+    priority) and `_*_cmd()` methods as needed. Default implementations return
+    empty lists — "no-op" is a valid adapter stance for a stage it doesn't own.
+    """
+
+    name: str = "base"
+    language: str = "unknown"
+    detect_files: list[str] = []
+    detect_imports: list[str] = []
+    priority: int = 0
+
+    # -- detection --------------------------------------------------------
+    def detect(self, project_root: Path) -> bool:
+        if not self.detect_files:
+            return False
+        matched: list[Path] = []
+        for glob in self.detect_files:
+            matched.extend(project_root.glob(glob))
+        if not matched:
+            return False
+        if not self.detect_imports:
+            return True
+        for path in matched:
+            try:
+                text = path.read_text(encoding="utf-8", errors="ignore")
+            except OSError:
+                continue
+            if any(imp in text for imp in self.detect_imports):
+                return True
+        return False
+
+    # -- commands (override in subclasses) --------------------------------
+    def lint_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return []
+
+    def format_check_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return []
+
+    def typecheck_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return []
+
+    def test_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return []
+
+    def build_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return []
+
+    def dep_audit_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return []
+
+    def contract_generator(self, project_root: Path) -> CommandSpec | None:  # noqa: ARG002
+        return None
+
+    def invariant_enforcers(self, project_root: Path) -> list[InvariantEnforcer]:  # noqa: ARG002
+        return []
+
+
+__all__ = ["BaseAdapter"]

hexaswarm_core-0.1.1/hexa_swarm_core/adapters/generic_shell.py

@@ -0,0 +1,47 @@
+"""generic-shell adapter — fallback for `hexa adopt` on unknown stacks.
+
+Does not presume any linter/test runner. Reads `.hexa/profile.yaml` or a
+`Makefile` for user-provided commands. Safe to use anywhere — just a thin
+command registry that keeps the CLI interface uniform across stacks.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from hexa_swarm_core.adapters.base import BaseAdapter
+from hexa_swarm_core.adapters.protocol import CommandSpec
+
+
+class GenericShellAdapter(BaseAdapter):
+    name = "generic-shell"
+    language = "shell"
+    detect_files = ["Makefile", "justfile", "Taskfile.yml"]
+    priority = 5  # very low — only matches when nothing else does
+
+    def detect(self, project_root: Path) -> bool:
+        # Always available as an explicit fallback, but `detect()` only returns
+        # True when a Make-like runner exists. Registry still allows forcing
+        # this adapter via `--stack generic-shell`.
+        return any((project_root / f).exists() for f in self.detect_files)
+
+    def _make_cmd(self, target: str, description: str) -> list[CommandSpec]:
+        return [CommandSpec(["make", target], description=description)]
+
+    def lint_cmd(self, project_root: Path) -> list[CommandSpec]:
+        return self._make_cmd("lint", "make lint") if (project_root / "Makefile").exists() else []
+
+    def format_check_cmd(self, project_root: Path) -> list[CommandSpec]:
+        return self._make_cmd("fmt", "make fmt") if (project_root / "Makefile").exists() else []
+
+    def typecheck_cmd(self, project_root: Path) -> list[CommandSpec]:
+        return self._make_cmd("typecheck", "make typecheck") if (project_root / "Makefile").exists() else []
+
+    def test_cmd(self, project_root: Path) -> list[CommandSpec]:
+        return self._make_cmd("test", "make test") if (project_root / "Makefile").exists() else []
+
+    def build_cmd(self, project_root: Path) -> list[CommandSpec]:
+        return self._make_cmd("build", "make build") if (project_root / "Makefile").exists() else []
+
+
+__all__ = ["GenericShellAdapter"]

hexaswarm_core-0.1.1/hexa_swarm_core/adapters/go_chi.py

@@ -0,0 +1,47 @@
+"""go-chi StackAdapter - Go services using the chi router."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from hexa_swarm_core.adapters.base import BaseAdapter
+from hexa_swarm_core.adapters.protocol import CommandSpec, InvariantEnforcer
+
+
+class GoChiAdapter(BaseAdapter):
+    name = "go-chi"
+    language = "go"
+    detect_files = ["go.mod"]
+    detect_imports = ["github.com/go-chi/chi"]
+    priority = 65
+
+    def lint_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [CommandSpec(["golangci-lint", "run", "./..."], description="golangci-lint")]
+
+    def format_check_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [CommandSpec(["gofmt", "-l", "."], description="gofmt -l (nonempty = drift)")]
+
+    def typecheck_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [CommandSpec(["go", "build", "-o", os.devnull, "./..."], description="go build (typecheck)")]
+
+    def test_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [CommandSpec(["go", "test", "-race", "-count=1", "./..."], description="go test -race")]
+
+    def build_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [CommandSpec(["go", "build", "./..."], description="go build")]
+
+    def dep_audit_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [CommandSpec(["govulncheck", "./..."], description="govulncheck")]
+
+    def invariant_enforcers(self, project_root: Path) -> list[InvariantEnforcer]:  # noqa: ARG002
+        return [
+            InvariantEnforcer(
+                invariant="S5",
+                description="go vet must pass before merge",
+                cmd=["go", "vet", "./..."],
+            ),
+        ]
+
+
+__all__ = ["GoChiAdapter"]

hexaswarm_core-0.1.1/hexa_swarm_core/adapters/kotlin_ktor.py

@@ -0,0 +1,55 @@
+"""kotlin-ktor StackAdapter - Kotlin services using Ktor."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from hexa_swarm_core.adapters.base import BaseAdapter
+from hexa_swarm_core.adapters.protocol import CommandSpec, InvariantEnforcer
+
+
+class KotlinKtorAdapter(BaseAdapter):
+    name = "kotlin-ktor"
+    language = "kotlin"
+    detect_files = [
+        "build.gradle.kts",
+        "build.gradle",
+        "settings.gradle.kts",
+    ]
+    detect_imports = ["io.ktor"]
+    priority = 65
+
+    @staticmethod
+    def _gradle(project_root: Path) -> str:
+        return "./gradlew" if (project_root / "gradlew").exists() else "gradle"
+
+    def lint_cmd(self, project_root: Path) -> list[CommandSpec]:
+        g = self._gradle(project_root)
+        return [CommandSpec([g, "ktlintCheck"], description="ktlint")]
+
+    def format_check_cmd(self, project_root: Path) -> list[CommandSpec]:
+        g = self._gradle(project_root)
+        return [CommandSpec([g, "detekt"], description="detekt")]
+
+    def typecheck_cmd(self, project_root: Path) -> list[CommandSpec]:
+        g = self._gradle(project_root)
+        return [CommandSpec([g, "compileKotlin", "--no-daemon"], description="kotlin compile")]
+
+    def test_cmd(self, project_root: Path) -> list[CommandSpec]:
+        g = self._gradle(project_root)
+        return [CommandSpec([g, "test", "--no-daemon"], description="gradle test")]
+
+    def build_cmd(self, project_root: Path) -> list[CommandSpec]:
+        g = self._gradle(project_root)
+        return [CommandSpec([g, "build", "-x", "test", "--no-daemon"], description="gradle build")]
+
+    def dep_audit_cmd(self, project_root: Path) -> list[CommandSpec]:
+        g = self._gradle(project_root)
+        # Requires the OWASP dependency-check plugin; a no-op when absent.
+        return [CommandSpec([g, "dependencyCheckAnalyze", "--no-daemon"], description="owasp dep-check")]
+
+    def invariant_enforcers(self, project_root: Path) -> list[InvariantEnforcer]:  # noqa: ARG002
+        return []
+
+
+__all__ = ["KotlinKtorAdapter"]

hexaswarm_core-0.1.1/hexa_swarm_core/adapters/node_express.py

@@ -0,0 +1,38 @@
+"""node-express StackAdapter - Express / Fastify / Koa style Node services."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from hexa_swarm_core.adapters._node_base import NodeAdapterBase
+from hexa_swarm_core.adapters.protocol import InvariantEnforcer
+
+
+class NodeExpressAdapter(NodeAdapterBase):
+    name = "node-express"
+    detect_files = ["package.json"]
+    detect_imports = ["express", "fastify", "koa"]
+    priority = 58
+
+    def detect(self, project_root: Path) -> bool:
+        pkg = project_root / "package.json"
+        if not pkg.exists():
+            return False
+        try:
+            data = json.loads(pkg.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return False
+        deps = dict(data.get("dependencies") or {})
+        deps.update(data.get("devDependencies") or {})
+        # `next` and `@nestjs/*` are owned by dedicated adapters - opt out
+        # so polyglot repos don't get this adapter attached twice.
+        if "next" in deps or any(d.startswith("@nestjs/") for d in deps):
+            return False
+        return any(imp in deps for imp in self.detect_imports)
+
+    def invariant_enforcers(self, project_root: Path) -> list[InvariantEnforcer]:  # noqa: ARG002
+        return []
+
+
+__all__ = ["NodeExpressAdapter"]

hexaswarm_core-0.1.1/hexa_swarm_core/adapters/node_nest.py

@@ -0,0 +1,36 @@
+"""node-nest StackAdapter - NestJS backend services."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from hexa_swarm_core.adapters._node_base import NodeAdapterBase
+from hexa_swarm_core.adapters.protocol import InvariantEnforcer
+
+
+class NodeNestAdapter(NodeAdapterBase):
+    name = "node-nest"
+    detect_files = ["package.json", "nest-cli.json"]
+    detect_imports = ["@nestjs/core", "@nestjs/common"]
+    priority = 68
+
+    def detect(self, project_root: Path) -> bool:
+        if (project_root / "nest-cli.json").exists():
+            return True
+        pkg = project_root / "package.json"
+        if not pkg.exists():
+            return False
+        try:
+            data = json.loads(pkg.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return False
+        deps = dict(data.get("dependencies") or {})
+        deps.update(data.get("devDependencies") or {})
+        return any(d.startswith("@nestjs/") for d in deps)
+
+    def invariant_enforcers(self, project_root: Path) -> list[InvariantEnforcer]:  # noqa: ARG002
+        return []
+
+
+__all__ = ["NodeNestAdapter"]

hexaswarm_core-0.1.1/hexa_swarm_core/adapters/node_next.py

@@ -0,0 +1,41 @@
+"""node-next StackAdapter - Next.js App Router projects."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from hexa_swarm_core.adapters._node_base import NodeAdapterBase
+from hexa_swarm_core.adapters.protocol import InvariantEnforcer
+
+
+class NodeNextAdapter(NodeAdapterBase):
+    name = "node-next"
+    detect_files = [
+        "package.json",
+        "next.config.ts",
+        "next.config.js",
+        "next.config.mjs",
+    ]
+    detect_imports = ["next"]
+    priority = 70
+
+    def detect(self, project_root: Path) -> bool:
+        if any((project_root / p).exists() for p in ("next.config.ts", "next.config.js", "next.config.mjs")):
+            return True
+        pkg = project_root / "package.json"
+        if not pkg.exists():
+            return False
+        try:
+            data = json.loads(pkg.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return False
+        deps = dict(data.get("dependencies") or {})
+        deps.update(data.get("devDependencies") or {})
+        return "next" in deps
+
+    def invariant_enforcers(self, project_root: Path) -> list[InvariantEnforcer]:  # noqa: ARG002
+        return []
+
+
+__all__ = ["NodeNextAdapter"]

hexaswarm_core-0.1.1/hexa_swarm_core/adapters/protocol.py

@@ -0,0 +1,66 @@
+"""
+StackAdapter Protocol — the contract every language/framework adapter fulfils.
+
+A polymorphic `quality-gate` / `contract-sync` / `invariants-check` command works
+identically across Python, Node, Go, Rust, etc. — because it dispatches to the
+adapter that matches the current project.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+@dataclass(frozen=True)
+class CommandSpec:
+    """One shell invocation the adapter wants to run."""
+
+    cmd: list[str]
+    cwd: str | None = None  # relative to project root; None = project root
+    env: dict[str, str] | None = None
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class InvariantEnforcer:
+    """A check tied to a safety invariant (S1..S6) that an adapter wants to
+    enforce on this stack. Runs within the quality-gate or a dedicated
+    `invariants` job; failure is merge-blocking.
+    """
+
+    invariant: str  # e.g. "S1", "S3"
+    description: str
+    cmd: list[str]  # shell command; nonzero exit = violation
+
+
+@runtime_checkable
+class StackAdapter(Protocol):
+    """Every adapter implements this. See `BaseAdapter` for a default skeleton."""
+
+    name: str  # e.g. "py-fastapi", "node-next"
+    language: str  # "python", "typescript", "go", ...
+    detect_files: list[str]  # file globs whose presence indicates this stack
+    detect_imports: list[str]  # optional: substrings that must appear in a detect_file
+    priority: int  # higher wins when multiple adapters match
+
+    def detect(self, project_root: Path) -> bool:
+        """Return True if this adapter applies to the given project root."""
+        ...
+
+    def lint_cmd(self, project_root: Path) -> list[CommandSpec]: ...
+    def format_check_cmd(self, project_root: Path) -> list[CommandSpec]: ...
+    def typecheck_cmd(self, project_root: Path) -> list[CommandSpec]: ...
+    def test_cmd(self, project_root: Path) -> list[CommandSpec]: ...
+    def build_cmd(self, project_root: Path) -> list[CommandSpec]: ...
+    def dep_audit_cmd(self, project_root: Path) -> list[CommandSpec]: ...
+
+    def contract_generator(self, project_root: Path) -> CommandSpec | None:
+        """Command that regenerates `.ai-sync/contracts/openapi.yaml` (or None)."""
+        ...
+
+    def invariant_enforcers(self, project_root: Path) -> list[InvariantEnforcer]: ...
+
+
+__all__ = ["CommandSpec", "InvariantEnforcer", "StackAdapter"]