specsmith 0.2.1.dev41__tar.gz → 0.2.1.dev43__tar.gz

{specsmith-0.2.1.dev41/src/specsmith.egg-info → specsmith-0.2.1.dev43}/PKG-INFO

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

{specsmith-0.2.1.dev41 → specsmith-0.2.1.dev43}/pyproject.toml

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

{specsmith-0.2.1.dev41 → specsmith-0.2.1.dev43}/src/specsmith/cli.py

@@ -291,12 +291,23 @@ def compress(project_dir: str, threshold: int, keep_recent: int) -> None:
     default=".",
     help="Project root directory.",
 )
-def upgrade(spec_version: str | None, project_dir: str) -> None:
-    """Update governance files to match a newer spec version."""
+@click.option(
+    "--full",
+    is_flag=True,
+    default=False,
+    help="Full sync: also regenerate exec shims, CI, agent files, create missing community files.",
+)
+def upgrade(spec_version: str | None, project_dir: str, full: bool) -> None:
+    """Update governance files to match a newer spec version.
+
+    With --full: also regenerates exec shims (PID tracking), CI configs,
+    agent integrations, and creates missing community files. Safe: never
+    overwrites AGENTS.md, LEDGER.md, or user documentation.
+    """
     from specsmith.upgrader import run_upgrade
 
     root = Path(project_dir).resolve()
-    result = run_upgrade(root, target_version=spec_version)
+    result = run_upgrade(root, target_version=spec_version, full=full)
     console.print(result.message)
 
     if result.updated_files:
@@ -1544,5 +1555,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.dev43/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.dev41 → specsmith-0.2.1.dev43}/src/specsmith/scaffolder.py

@@ -137,19 +137,47 @@ 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,
         ProjectType.BACKEND_FRONTEND,
         ProjectType.BACKEND_FRONTEND_TRAY,
     ):
-        files.append(("pyproject.toml.j2", "pyproject.toml"))
+        files.append(("python/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
 
 

specsmith-0.2.1.dev43/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.dev43/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.dev43/src/specsmith/templates/go/go.mod.j2

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

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

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

specsmith-0.2.1.dev43/src/specsmith/templates/js/package.json.j2

@@ -0,0 +1,48 @@
+{
+  "name": "{{ package_name }}",
+  "version": "0.1.0",
+  "description": "{{ project.description or project.name }}",
+  "license": "{{ project.license }}",
+{% if project.type.value == 'web-frontend' %}
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "lint": "eslint src/",
+    "test": "vitest"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "vite": "^6.0.0",
+    "eslint": "^9.0.0",
+    "vitest": "^3.0.0"
+  }
+{% elif project.type.value == 'fullstack-js' %}
+  "scripts": {
+    "dev": "concurrently \"npm run dev:server\" \"npm run dev:client\"",
+    "dev:server": "node server/src/index.js",
+    "dev:client": "vite",
+    "build": "vite build",
+    "lint": "eslint .",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "express": "^5.0.0"
+  },
+  "devDependencies": {
+    "concurrently": "^9.0.0",
+    "eslint": "^9.0.0",
+    "vitest": "^3.0.0"
+  }
+{% else %}
+  "scripts": {
+    "start": "node src/index.js",
+    "lint": "eslint src/",
+    "test": "vitest"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "eslint": "^9.0.0",
+    "vitest": "^3.0.0"
+  }
+{% endif %}
+}

specsmith-0.2.1.dev43/src/specsmith/templates/rust/Cargo.toml.j2

@@ -0,0 +1,19 @@
+[package]
+name = "{{ package_name }}"
+version = "0.1.0"
+edition = "2021"
+description = "{{ project.description or project.name }}"
+license = "{{ project.license }}"
+
+[dependencies]
+{% if project.type.value == 'cli-rust' %}
+clap = { version = "4", features = ["derive"] }
+{% endif %}
+
+[dev-dependencies]
+
+{% if project.type.value == 'cli-rust' %}
+[[bin]]
+name = "{{ package_name }}"
+path = "src/main.rs"
+{% endif %}

specsmith-0.2.1.dev43/src/specsmith/templates/rust/main.rs.j2

@@ -0,0 +1,15 @@
+use clap::Parser;
+
+/// {{ project.description or project.name }}
+#[derive(Parser, Debug)]
+#[command(version, about)]
+struct Args {
+    /// Name to greet
+    #[arg(short, long, default_value = "world")]
+    name: String,
+}
+
+fn main() {
+    let args = Args::parse();
+    println!("Hello, {}!", args.name);
+}

specsmith-0.2.1.dev43/src/specsmith/templates/scripts/exec.cmd.j2

@@ -0,0 +1,63 @@
+@echo off
+REM {{ project.name }} — Command Execution Shim (Windows)
+REM Wraps external commands with PID tracking, timeout enforcement, and abort support.
+REM Usage: scripts\exec.cmd "<command>" [timeout_seconds]
+REM
+REM PID files: .specsmith\pids\<pid>.json (for specsmith ps / specsmith abort)
+REM Logs:      .specsmith\logs\exec_<timestamp>.stdout/.stderr
+REM Prefer:    specsmith exec "<command>" --timeout <N>  (Python-based, full tracking)
+
+setlocal enabledelayedexpansion
+
+set "COMMAND=%~1"
+set "TIMEOUT_SEC=%~2"
+if "%TIMEOUT_SEC%"=="" set "TIMEOUT_SEC=120"
+
+set "PROJECT_ROOT=%~dp0.."
+set "PID_DIR=%PROJECT_ROOT%\.specsmith\pids"
+set "LOG_DIR=%PROJECT_ROOT%\.specsmith\logs"
+if not exist "%PID_DIR%" mkdir "%PID_DIR%"
+if not exist "%LOG_DIR%" mkdir "%LOG_DIR%"
+
+for /f "tokens=2 delims==" %%I in ('wmic os get localdatetime /value') do set "DT=%%I"
+set "TIMESTAMP=%DT:~0,4%-%DT:~4,2%-%DT:~6,2%_%DT:~8,2%-%DT:~10,2%-%DT:~12,2%"
+set "STDOUT_LOG=%LOG_DIR%\exec_%TIMESTAMP%.stdout"
+set "STDERR_LOG=%LOG_DIR%\exec_%TIMESTAMP%.stderr"
+
+echo [exec] Command : %COMMAND%
+echo [exec] Timeout : %TIMEOUT_SEC%s
+
+REM Launch command and capture PID
+start /b cmd /c "%COMMAND%" > "%STDOUT_LOG%" 2> "%STDERR_LOG%"
+for /f "tokens=2" %%P in ('tasklist /fi "imagename eq cmd.exe" /nh ^| findstr /i "cmd"') do (
+    set "CMD_PID=%%P"
+)
+
+REM Write PID file for tracking
+echo {"pid": %CMD_PID%, "command": "%COMMAND%", "timeout": %TIMEOUT_SEC%} > "%PID_DIR%\%CMD_PID%.json"
+
+REM Wait with timeout
+set /a ELAPSED=0
+:wait_loop
+tasklist /fi "PID eq %CMD_PID%" /nh 2>nul | findstr /i "%CMD_PID%" >nul
+if errorlevel 1 goto :done
+if %ELAPSED% geq %TIMEOUT_SEC% goto :timeout
+timeout /t 1 /nobreak >nul
+set /a ELAPSED+=1
+goto :wait_loop
+
+:timeout
+echo [exec] TIMEOUT after %TIMEOUT_SEC%s — killing PID %CMD_PID%
+taskkill /F /PID %CMD_PID% /T >nul 2>&1
+del "%PID_DIR%\%CMD_PID%.json" >nul 2>&1
+exit /b 124
+
+:done
+del "%PID_DIR%\%CMD_PID%.json" >nul 2>&1
+set "EXIT_CODE=%ERRORLEVEL%"
+if %EXIT_CODE% equ 0 (
+    echo [exec] OK — exit code 0
+) else (
+    echo [exec] FAILED — exit code %EXIT_CODE%
+)
+exit /b %EXIT_CODE%