specsmith 0.2.1.dev40__tar.gz → 0.2.1.dev42__tar.gz

{specsmith-0.2.1.dev40/src/specsmith.egg-info → specsmith-0.2.1.dev42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.2.1.dev40
+Version: 0.2.1.dev42
 Summary: Forge governed project scaffolds from the Agentic AI Development Workflow Specification.
 Author: BitConcepts
 License: MIT

{specsmith-0.2.1.dev40 → specsmith-0.2.1.dev42}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.2.1.dev40"
+version = "0.2.1.dev42"
 description = "Forge governed project scaffolds from the Agentic AI Development Workflow Specification."
 readme = "README.md"
 license = {text = "MIT"}

{specsmith-0.2.1.dev40 → specsmith-0.2.1.dev42}/src/specsmith/auditor.py

@@ -125,10 +125,14 @@ def check_governance_files(root: Path) -> list[AuditResult]:
         found = path.exists()
         # For architecture.md, also search subdirectories (e.g. docs/architecture/*.md)
         if not found and "architecture" in f:
-            found = bool(
-                list((root / "docs").glob("**/architecture*"))
-                + list((root / "docs").glob("**/ARCHITECTURE*"))
-            ) if (root / "docs").is_dir() else False
+            found = (
+                bool(
+                    list((root / "docs").glob("**/architecture*"))
+                    + list((root / "docs").glob("**/ARCHITECTURE*"))
+                )
+                if (root / "docs").is_dir()
+                else False
+            )
         results.append(
             AuditResult(
                 name=f"recommended:{f}",
@@ -580,8 +584,7 @@ def run_auto_fix(root: Path, report: AuditReport) -> list[str]:
                 path = root / "docs" / "ARCHITECTURE.md"
                 path.parent.mkdir(parents=True, exist_ok=True)
                 path.write_text(
-                    f"# Architecture — {root.name}\n\n"
-                    "[Run `specsmith architect` to populate]\n",
+                    f"# Architecture — {root.name}\n\n[Run `specsmith architect` to populate]\n",
                     encoding="utf-8",
                 )
                 fixed.append("Created stub docs/ARCHITECTURE.md")

{specsmith-0.2.1.dev40 → specsmith-0.2.1.dev42}/src/specsmith/cli.py

@@ -703,9 +703,7 @@ def architect(project_dir: str, non_interactive: bool) -> None:
             f"  [yellow]Note:[/yellow] Existing docs at {', '.join(existing)} "
             "are referenced but not merged. Review manually."
         )
-    console.print(
-        "  [dim]Run \"specsmith audit --project-dir .\" to verify governance health.[/dim]"
-    )
+    console.print('  [dim]Run "specsmith audit --project-dir ." to verify governance health.[/dim]')
 
 
 # ---------------------------------------------------------------------------
@@ -1463,7 +1461,10 @@ def credits_analyze(project_dir: str) -> None:
     "--watermarks", default=None, help="Comma-separated USD watermark alerts (e.g. 5,10,25,50)."
 )
 def credits_budget(
-    project_dir: str, cap: float | None, alert_pct: int | None, watermarks: str | None,
+    project_dir: str,
+    cap: float | None,
+    alert_pct: int | None,
+    watermarks: str | None,
 ) -> None:
     """View or set credit budget and alert thresholds."""
     from specsmith.credits import load_budget, save_budget
@@ -1543,5 +1544,92 @@ def serve(port: int) -> None:
     )
 
 
+# ---------------------------------------------------------------------------
+# Process execution and abort
+# ---------------------------------------------------------------------------
+
+
+@main.command(name="exec")
+@click.argument("command")
+@click.option("--timeout", default=120, help="Timeout in seconds (default: 120).")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+def exec_cmd(command: str, timeout: int, project_dir: str) -> None:
+    """Execute a command with PID tracking and timeout enforcement.
+
+    Tracks the process in .specsmith/pids/ so it can be listed (specsmith ps)
+    or aborted (specsmith abort). Logs stdout/stderr to .specsmith/logs/.
+    Works cross-platform: Windows, Linux, macOS.
+    """
+    from specsmith.executor import run_tracked
+
+    root = Path(project_dir).resolve()
+    console.print(f"[bold]exec[/bold] {command} (timeout={timeout}s)")
+
+    result = run_tracked(root, command, timeout=timeout)
+
+    if result.timed_out:
+        console.print(f"[red]TIMEOUT[/red] after {timeout}s (PID {result.pid})")
+    elif result.exit_code == 0:
+        console.print(f"[green]OK[/green] ({result.duration:.1f}s) — exit code 0")
+    else:
+        console.print(f"[red]FAILED[/red] ({result.duration:.1f}s) — exit code {result.exit_code}")
+    if result.stdout_file:
+        console.print(f"  stdout: {result.stdout_file}")
+    if result.stderr_file:
+        console.print(f"  stderr: {result.stderr_file}")
+    raise SystemExit(result.exit_code)
+
+
+@main.command(name="ps")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+def ps_cmd(project_dir: str) -> None:
+    """List tracked running processes."""
+    from specsmith.executor import list_processes
+
+    root = Path(project_dir).resolve()
+    procs = list_processes(root)
+    if not procs:
+        console.print("No tracked processes running.")
+        return
+    for p in procs:
+        elapsed = p.elapsed
+        remaining = max(0, p.timeout - elapsed)
+        status = "[red]EXPIRED[/red]" if p.is_expired else f"{remaining:.0f}s left"
+        console.print(f"  PID {p.pid}  {status}  {p.command}")
+    console.print(f"\n  {len(procs)} process(es)")
+
+
+@main.command(name="abort")
+@click.option("--pid", type=int, default=None, help="Abort a specific PID.")
+@click.option("--all", "abort_all_flag", is_flag=True, default=False, help="Abort all tracked.")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+def abort_cmd(pid: int | None, abort_all_flag: bool, project_dir: str) -> None:
+    """Abort tracked process(es). Sends SIGTERM then SIGKILL (POSIX) or taskkill (Windows)."""
+    from specsmith.executor import abort_all, abort_process, list_processes
+
+    root = Path(project_dir).resolve()
+
+    if abort_all_flag:
+        killed = abort_all(root)
+        if killed:
+            console.print(f"[green]Aborted {len(killed)} process(es): {killed}[/green]")
+        else:
+            console.print("No tracked processes to abort.")
+    elif pid:
+        if abort_process(root, pid):
+            console.print(f"[green]Aborted PID {pid}[/green]")
+        else:
+            console.print(f"[red]Could not abort PID {pid}[/red]")
+    else:
+        procs = list_processes(root)
+        if not procs:
+            console.print("No tracked processes. Use --pid or --all.")
+            return
+        console.print("Tracked processes:")
+        for p in procs:
+            console.print(f"  PID {p.pid}  {p.command}")
+        console.print("\nUse --pid <N> or --all to abort.")
+
+
 if __name__ == "__main__":
     main()

{specsmith-0.2.1.dev40 → specsmith-0.2.1.dev42}/src/specsmith/credit_analyzer.py

@@ -43,8 +43,7 @@ def analyze_spend(root: Path) -> AnalysisReport:
                 severity="info",
                 message="No credit data yet.",
                 recommendation=(
-                    "Record usage with `specsmith credits record` "
-                    "or integrate with your AI agent."
+                    "Record usage with `specsmith credits record` or integrate with your AI agent."
                 ),
             )
         )
@@ -112,8 +111,7 @@ def analyze_spend(root: Path) -> AnalysisReport:
                 category="governance",
                 severity="info",
                 message=(
-                    f"Governance files total {total_gov_lines} lines "
-                    f"across {len(gov_files)} files."
+                    f"Governance files total {total_gov_lines} lines across {len(gov_files)} files."
                 ),
                 recommendation=(
                     "Ensure agents lazy-load governance files. Only rules.md + workflow.md "

{specsmith-0.2.1.dev40 → specsmith-0.2.1.dev42}/src/specsmith/credits.py

@@ -167,9 +167,9 @@ def record_usage(
         provider=provider,
         tokens_in=tokens_in,
         tokens_out=tokens_out,
-        estimated_cost_usd=cost_usd if cost_usd is not None else estimate_cost(
-            model, tokens_in, tokens_out
-        ),
+        estimated_cost_usd=cost_usd
+        if cost_usd is not None
+        else estimate_cost(model, tokens_in, tokens_out),
         task=task,
         duration_seconds=duration_seconds,
     )
@@ -180,7 +180,10 @@ def record_usage(
 
 
 def get_summary(
-    root: Path, *, since: str = "", month: str = "",
+    root: Path,
+    *,
+    since: str = "",
+    month: str = "",
 ) -> CreditSummary:
     """Get aggregate credit summary with budget alerts."""
     entries = _load_entries(root)
@@ -222,8 +225,7 @@ def get_summary(
         pct = (month_cost / budget.monthly_cap_usd) * 100 if budget.monthly_cap_usd else 0
         if pct >= 100:
             summary.alerts.append(
-                f"BUDGET EXCEEDED: ${month_cost:.2f} / ${budget.monthly_cap_usd:.2f} "
-                f"({pct:.0f}%)"
+                f"BUDGET EXCEEDED: ${month_cost:.2f} / ${budget.monthly_cap_usd:.2f} ({pct:.0f}%)"
             )
         elif pct >= budget.alert_threshold_pct:
             summary.alerts.append(

specsmith-0.2.1.dev42/src/specsmith/executor.py

@@ -0,0 +1,267 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Executor — cross-platform process execution with PID tracking and abort.
+
+Provides governed command execution with:
+- PID file tracking in .specsmith/pids/
+- Configurable timeout enforcement
+- Cross-platform abort (Windows taskkill / POSIX SIGTERM+SIGKILL)
+- Process listing for agent visibility
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import subprocess
+import sys
+import time
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+@dataclass
+class TrackedProcess:
+    """Metadata for a tracked process."""
+
+    pid: int
+    command: str
+    started: str  # ISO timestamp
+    timeout: int  # seconds
+    pid_file: str = ""
+
+    @property
+    def started_dt(self) -> datetime:
+        return datetime.fromisoformat(self.started)
+
+    @property
+    def elapsed(self) -> float:
+        return (datetime.now(tz=timezone.utc) - self.started_dt).total_seconds()
+
+    @property
+    def is_expired(self) -> bool:
+        return self.elapsed > self.timeout
+
+
+@dataclass
+class ExecResult:
+    """Result of a tracked execution."""
+
+    command: str
+    exit_code: int
+    pid: int
+    duration: float
+    timed_out: bool = False
+    aborted: bool = False
+    stdout_file: str = ""
+    stderr_file: str = ""
+
+
+def _pids_dir(root: Path) -> Path:
+    d = root / ".specsmith" / "pids"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _logs_dir(root: Path) -> Path:
+    d = root / ".specsmith" / "logs"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _write_pid_file(root: Path, proc: TrackedProcess) -> Path:
+    """Write PID tracking file. Returns path to PID file."""
+    pid_file = _pids_dir(root) / f"{proc.pid}.json"
+    proc.pid_file = str(pid_file)
+    pid_file.write_text(json.dumps(asdict(proc), indent=2), encoding="utf-8")
+    return pid_file
+
+
+def _remove_pid_file(root: Path, pid: int) -> None:
+    """Remove PID tracking file."""
+    pid_file = _pids_dir(root) / f"{pid}.json"
+    if pid_file.exists():
+        pid_file.unlink()
+
+
+def _is_process_alive(pid: int) -> bool:
+    """Check if a process is still running (cross-platform)."""
+    try:
+        if sys.platform == "win32":
+            # Windows: use tasklist to check
+            result = subprocess.run(
+                ["tasklist", "/FI", f"PID eq {pid}", "/NH"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            return str(pid) in result.stdout
+        else:
+            # POSIX: signal 0 checks existence without killing
+            os.kill(pid, 0)
+            return True
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+
+
+def _kill_process(pid: int, *, graceful_timeout: float = 5.0) -> bool:
+    """Kill a process cross-platform. Returns True if killed.
+
+    Strategy:
+    - POSIX: SIGTERM → wait → SIGKILL
+    - Windows: taskkill → taskkill /F
+    """
+    if not _is_process_alive(pid):
+        return True  # Already dead
+
+    try:
+        if sys.platform == "win32":
+            # Graceful first
+            subprocess.run(
+                ["taskkill", "/PID", str(pid)],
+                capture_output=True,
+                timeout=graceful_timeout,
+            )
+            time.sleep(min(graceful_timeout, 2.0))
+            if not _is_process_alive(pid):
+                return True
+            # Force kill
+            subprocess.run(
+                ["taskkill", "/F", "/PID", str(pid), "/T"],
+                capture_output=True,
+                timeout=5,
+            )
+        else:
+            # SIGTERM first
+            os.kill(pid, signal.SIGTERM)
+            deadline = time.monotonic() + graceful_timeout
+            while time.monotonic() < deadline:
+                if not _is_process_alive(pid):
+                    return True
+                time.sleep(0.2)
+            # SIGKILL
+            os.kill(pid, signal.SIGKILL)
+    except (OSError, subprocess.TimeoutExpired, subprocess.SubprocessError):
+        pass
+
+    time.sleep(0.5)
+    return not _is_process_alive(pid)
+
+
+def run_tracked(
+    root: Path,
+    command: str,
+    *,
+    timeout: int = 120,
+    capture: bool = True,
+) -> ExecResult:
+    """Execute a command with PID tracking and timeout enforcement.
+
+    - Writes PID file to .specsmith/pids/<pid>.json
+    - Enforces timeout via subprocess.Popen + polling
+    - Logs stdout/stderr to .specsmith/logs/
+    - Cleans up PID file on completion
+    - Cross-platform: works on Windows, Linux, macOS
+    """
+    started = datetime.now(tz=timezone.utc).isoformat()
+    ts = datetime.now(tz=timezone.utc).strftime("%Y%m%d_%H%M%S")
+
+    stdout_path = _logs_dir(root) / f"exec_{ts}.stdout"
+    stderr_path = _logs_dir(root) / f"exec_{ts}.stderr"
+
+    # Determine shell
+    if sys.platform == "win32":
+        shell_args: list[str] = ["cmd", "/c", command]
+    else:
+        shell_args = ["bash", "-c", command]
+
+    stdout_fh = open(stdout_path, "w", encoding="utf-8") if capture else None  # noqa: SIM115
+    stderr_fh = open(stderr_path, "w", encoding="utf-8") if capture else None  # noqa: SIM115
+
+    try:
+        proc = subprocess.Popen(  # noqa: S603
+            shell_args,
+            stdout=stdout_fh or subprocess.PIPE,
+            stderr=stderr_fh or subprocess.PIPE,
+            cwd=str(root),
+        )
+
+        tracked = TrackedProcess(
+            pid=proc.pid,
+            command=command,
+            started=started,
+            timeout=timeout,
+        )
+        pid_file = _write_pid_file(root, tracked)
+
+        start = time.monotonic()
+        timed_out = False
+
+        try:
+            proc.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            timed_out = True
+            _kill_process(proc.pid)
+            proc.wait(timeout=5)  # Reap zombie
+
+        duration = time.monotonic() - start
+        exit_code = proc.returncode if proc.returncode is not None else -1
+
+        # Clean up PID file
+        if pid_file.exists():
+            pid_file.unlink()
+
+        return ExecResult(
+            command=command,
+            exit_code=124 if timed_out else exit_code,
+            pid=proc.pid,
+            duration=duration,
+            timed_out=timed_out,
+            stdout_file=str(stdout_path) if capture else "",
+            stderr_file=str(stderr_path) if capture else "",
+        )
+
+    finally:
+        if stdout_fh:
+            stdout_fh.close()
+        if stderr_fh:
+            stderr_fh.close()
+
+
+def list_processes(root: Path) -> list[TrackedProcess]:
+    """List all tracked processes. Prunes stale PID files for dead processes."""
+    pids_dir = _pids_dir(root)
+    result: list[TrackedProcess] = []
+
+    for pid_file in pids_dir.glob("*.json"):
+        try:
+            data = json.loads(pid_file.read_text(encoding="utf-8"))
+            tp = TrackedProcess(**data)
+            if _is_process_alive(tp.pid):
+                result.append(tp)
+            else:
+                # Stale PID file — process already exited
+                pid_file.unlink()
+        except (json.JSONDecodeError, TypeError, OSError):
+            pid_file.unlink(missing_ok=True)
+
+    return result
+
+
+def abort_process(root: Path, pid: int) -> bool:
+    """Abort a specific tracked process by PID. Returns True if killed."""
+    killed = _kill_process(pid)
+    _remove_pid_file(root, pid)
+    return killed
+
+
+def abort_all(root: Path) -> list[int]:
+    """Abort all tracked processes. Returns list of killed PIDs."""
+    killed: list[int] = []
+    for tp in list_processes(root):
+        if _kill_process(tp.pid):
+            killed.append(tp.pid)
+        _remove_pid_file(root, tp.pid)
+    return killed

{specsmith-0.2.1.dev40 → specsmith-0.2.1.dev42}/src/specsmith/importer.py

@@ -790,15 +790,31 @@ def _extract_governance_sections(root: Path) -> dict[str, str]:
     # Body-level content keywords for secondary classification.
     # Used when heading doesn't match — scan body text for strong signals.
     _BODY_ARCHITECTURE_KW = [
-        "register map", "address offset", "0x0", "register name",
-        "block diagram", "data flow", "interface spec",
-        "directory layout", "src/", "repository structure",
-        "milestone", "roadmap", "completion", "phase 2 target",
+        "register map",
+        "address offset",
+        "0x0",
+        "register name",
+        "block diagram",
+        "data flow",
+        "interface spec",
+        "directory layout",
+        "src/",
+        "repository structure",
+        "milestone",
+        "roadmap",
+        "completion",
+        "phase 2 target",
     ]
     _BODY_DRIFT_KW = [
-        "subst v:", "path-length", "one-time setup", "per-machine",
-        "environment variable", "install once", "bootstrap",
-        "windows path", "ntfs",
+        "subst v:",
+        "path-length",
+        "one-time setup",
+        "per-machine",
+        "environment variable",
+        "install once",
+        "bootstrap",
+        "windows path",
+        "ntfs",
     ]
 
     for heading, body in sections.items():

{specsmith-0.2.1.dev40 → specsmith-0.2.1.dev42}/src/specsmith/scaffolder.py

@@ -137,7 +137,7 @@ def _build_file_map(config: ProjectConfig) -> list[tuple[str, str]]:
     # Community / compliance files
     files.extend(_build_community_files(config))
 
-    # Python project types get pyproject.toml and src layout
+    # Language-specific project files (#41)
     if config.type in (
         ProjectType.CLI_PYTHON,
         ProjectType.LIBRARY_PYTHON,
@@ -146,10 +146,38 @@ def _build_file_map(config: ProjectConfig) -> list[tuple[str, str]]:
     ):
         files.append(("pyproject.toml.j2", "pyproject.toml"))
         files.append(("python/init.py.j2", f"src/{config.package_name}/__init__.py"))
-
         if config.type == ProjectType.CLI_PYTHON:
             files.append(("python/cli.py.j2", f"src/{config.package_name}/cli.py"))
 
+    elif config.type in (ProjectType.CLI_RUST, ProjectType.LIBRARY_RUST):
+        files.append(("rust/Cargo.toml.j2", "Cargo.toml"))
+        if config.type == ProjectType.CLI_RUST:
+            files.append(("rust/main.rs.j2", "src/main.rs"))
+
+    elif config.type == ProjectType.CLI_GO:
+        files.append(("go/go.mod.j2", "go.mod"))
+        files.append(("go/main.go.j2", "cmd/main.go"))
+
+    elif config.type in (
+        ProjectType.WEB_FRONTEND,
+        ProjectType.FULLSTACK_JS,
+    ):
+        files.append(("js/package.json.j2", "package.json"))
+
+    # ReadTheDocs integration (#38) — Python and doc projects
+    if config.type in (
+        ProjectType.CLI_PYTHON,
+        ProjectType.LIBRARY_PYTHON,
+        ProjectType.SPEC_DOCUMENT,
+        ProjectType.USER_MANUAL,
+    ):
+        files.append(("docs/readthedocs.yaml.j2", ".readthedocs.yaml"))
+        files.append(("docs/mkdocs.yml.j2", "mkdocs.yml"))
+
+    # Release workflow template (#44) — gitflow + GitHub projects
+    if config.vcs_platform == "github" and config.branching_strategy == "gitflow":
+        files.append(("workflows/release.yml.j2", ".github/workflows/release.yml"))
+
     return files
 
 
@@ -406,9 +434,7 @@ def _build_community_files(config: ProjectConfig) -> list[tuple[str, str]]:
         files.append(("community/code_of_conduct.md.j2", "CODE_OF_CONDUCT.md"))
 
     if "pr-template" in cf and config.vcs_platform == "github":
-        files.append(
-            ("community/pull_request_template.md.j2", ".github/PULL_REQUEST_TEMPLATE.md")
-        )
+        files.append(("community/pull_request_template.md.j2", ".github/PULL_REQUEST_TEMPLATE.md"))
 
     if "issue-templates" in cf and config.vcs_platform == "github":
         files.extend(

{specsmith-0.2.1.dev40 → specsmith-0.2.1.dev42}/src/specsmith/session.py

@@ -138,8 +138,7 @@ def run_session_end(root: Path) -> SessionReport:
                     name="credits",
                     status="ok",
                     message=(
-                        f"Credits: ${cs.total_cost_usd:.4f} total, "
-                        f"{cs.session_count} session(s)"
+                        f"Credits: ${cs.total_cost_usd:.4f} total, {cs.session_count} session(s)"
                     ),
                 )
             )

specsmith-0.2.1.dev42/src/specsmith/templates/docs/mkdocs.yml.j2

@@ -0,0 +1,34 @@
+site_name: {{ project.name }}
+site_description: {{ project.description or project.name }}
+repo_url: https://github.com/{{ project.name }}
+edit_uri: edit/main/docs/
+
+docs_dir: docs/site
+
+theme:
+  name: material
+  palette:
+    - scheme: default
+      primary: deep purple
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: deep purple
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.sections
+    - content.code.copy
+
+nav:
+  - Home: index.md
+
+markdown_extensions:
+  - tables
+  - admonition
+  - pymdownx.highlight
+  - pymdownx.superfences
+  - toc:
+      permalink: true

specsmith-0.2.1.dev42/src/specsmith/templates/docs/readthedocs.yaml.j2

@@ -0,0 +1,22 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+{% if project.language == 'python' %}
+    python: "3.12"
+{% elif project.language in ('javascript', 'typescript') %}
+    nodejs: "20"
+{% endif %}
+
+mkdocs:
+  configuration: mkdocs.yml
+
+{% if project.language == 'python' %}
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+{% endif %}

specsmith-0.2.1.dev42/src/specsmith/templates/go/go.mod.j2

@@ -0,0 +1,3 @@
+module {{ package_name }}
+
+go 1.22

specsmith-0.2.1.dev42/src/specsmith/templates/go/main.go.j2

@@ -0,0 +1,7 @@
+package main
+
+import "fmt"
+
+func main() {
+	fmt.Println("{{ project.name }}")
+}