snapstack 1.0.0__tar.gz

snapstack-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Test
+        run: pytest --tb=short -q

snapstack-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,76 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install --upgrade pip build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/snapstack
+    permissions:
+      id-token: write # Trusted publishing (no API token needed)
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event.release.prerelease == true
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/snapstack
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

snapstack-1.0.0/.gitignore

@@ -0,0 +1,92 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.pyd
+*.pdb
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+.env/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.cache/
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Linting
+.ruff_cache/
+.mypy_cache/
+
+# pysnap cache
+.cache/pysnap/
+
+# Environment files
+.env
+.env.*
+!.env.example
+
+# IDE / Editor
+.vscode/
+.idea/
+*.sublime-project
+*.sublime-workspace
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Temporary files
+*.tmp
+*.bak
+tmp/
+
+# Smoke test output
+my-api/
+
+# Root-level Docker files (pysnap is a CLI tool, Docker templates are inside pysnap/templates/)
+/Dockerfile
+/docker-compose.yml
+/.dockerignore
+
+# Speckit agent internals
+.agent/
+
+# Lock files (pysnap is a library/CLI, consumers pin their own deps)
+uv.lock
+

snapstack-1.0.0/.specify/memory/constitution.md

@@ -0,0 +1,170 @@
+<!--
+Sync Impact Report
+===================
+- Version change: N/A (initial) -> 1.0.0
+- Modified principles: N/A (first constitution)
+- Added sections:
+  - Core Principles (6 principles: Developer Experience, Correctness,
+    Backward Compatibility, Extensibility, Minimal Magic,
+    Testing as a First-Class Citizen)
+  - Technical Constraints
+  - Development Workflow
+  - Governance
+- Removed sections: None
+- Templates requiring updates:
+  - .specify/templates/plan-template.md ✅ reviewed (Constitution Check
+    section aligns with new principles; no changes needed)
+  - .specify/templates/spec-template.md ✅ reviewed (scope/requirements
+    structure compatible; no changes needed)
+  - .specify/templates/tasks-template.md ✅ reviewed (task categorization
+    compatible; testing tasks align with Principle VI)
+- Follow-up TODOs: None
+-->
+
+# Pysnap Constitution
+
+## Core Principles
+
+### I. Developer Experience
+
+Every interaction with pysnap MUST feel polished, fast, and intuitive.
+This is the highest-priority principle; all other principles are
+subordinate when trade-offs arise.
+
+- CLI output MUST use clear formatting (colors, spinners, structured
+  messages via Rich) so the developer always knows what is happening.
+- Interactive prompts MUST have sensible defaults. A developer MUST be
+  able to scaffold a working project by pressing Enter through every
+  prompt.
+- Error messages MUST be actionable: state what went wrong, why, and
+  what the developer can do to fix it.
+- Project generation MUST complete in under 5 seconds on commodity
+  hardware.
+- The `--help` output for every command MUST be self-documenting and
+  sufficient to use the tool without reading external docs.
+
+### II. Correctness
+
+Generated project code MUST always be runnable on first try with zero
+manual edits.
+
+- Every generated project MUST pass `pip install -e .` (or the
+  equivalent for the chosen package manager) without errors.
+- Every generated project MUST start its development server
+  successfully on the first run.
+- Every generated project's test suite MUST pass on first run with
+  zero failures.
+- Template variables MUST never leak into generated output. All
+  placeholders MUST be resolved before files are written.
+- CI/CD workflows included in generated projects MUST be valid and
+  functional against their target platforms (GitHub Actions, etc.).
+
+### III. Backward Compatibility
+
+Existing pysnap commands MUST never break between versions.
+
+- Public CLI commands (e.g., `pysnap create`) MUST NOT change their
+  argument signatures or default behavior in minor or patch releases.
+- Removal or renaming of a command MUST only occur in a major version
+  bump and MUST be preceded by at least one release with a deprecation
+  warning.
+- Configuration file formats MUST remain backward-compatible within a
+  major version series.
+- The pysnap public Python API (if any) follows semantic versioning:
+  breaking changes require a major version bump.
+
+### IV. Extensibility
+
+Every feature MUST be designed so community contributors can add new
+framework templates without touching core logic.
+
+- Framework scaffolding MUST be implemented through a template registry
+  pattern. Adding a new framework (e.g., Litestar, Starlette) MUST NOT
+  require modifications to the CLI command layer or the generation
+  engine.
+- Templates MUST be self-contained directories that declare their own
+  metadata (name, description, prompts, default values) via a manifest
+  file.
+- A `pysnap use <template-url>` command MUST support community
+  templates hosted externally (Git repos, tarballs).
+- Hook points (pre-generation, post-generation) MUST be available for
+  templates to run custom setup logic.
+
+### V. Minimal Magic
+
+Generated projects MUST be readable and educational. Developers MUST
+learn from the output rather than being confused by it.
+
+- Generated code MUST NOT use metaprogramming, dynamic imports, or
+  code generation at runtime unless the target framework requires it.
+- Every generated file MUST contain a clear purpose visible from its
+  name and a brief docstring or header comment.
+- Directory structures MUST follow the conventions of the target
+  framework's official documentation.
+- Dependencies in generated `pyproject.toml` MUST be pinned to
+  compatible ranges (e.g., `>=X.Y,<X+1`) with no unnecessary
+  transitive dependencies.
+- Generated code SHOULD prefer explicit imports, explicit
+  configuration, and standard-library solutions over third-party
+  abstractions.
+
+### VI. Testing as a First-Class Citizen
+
+Every generated project includes a working test suite by default, and
+pysnap itself MUST have full test coverage.
+
+- Every generated project MUST include a `tests/` directory with at
+  least one passing test (e.g., a health-check endpoint test).
+- Generated test suites MUST include a `conftest.py` with reusable
+  fixtures (app client, database session, etc.) appropriate to the
+  chosen framework.
+- Pysnap's own codebase MUST maintain >= 90% line coverage as measured
+  by `pytest --cov`.
+- Every new pysnap feature MUST ship with unit tests covering its
+  happy path and at least one error/edge case.
+- Integration tests MUST verify that generated projects pass their own
+  test suites end-to-end (generate -> install -> test).
+
+## Technical Constraints
+
+- **Language/Version**: Python >= 3.9 (as declared in `pyproject.toml`).
+- **CLI Framework**: Typer (with Rich for output formatting).
+- **Templating Engine**: Jinja2 for all code generation.
+- **Interactive Prompts**: Questionary for user input during scaffolding.
+- **Build System**: Hatchling.
+- **Linting/Formatting**: Ruff.
+- **License**: MIT.
+- **Supported Frameworks**: FastAPI (stable), Django (planned),
+  Flask (planned), community templates via registry.
+
+## Development Workflow
+
+- All changes MUST pass `ruff check` and `ruff format --check` before
+  merge.
+- All changes MUST pass the full `pytest` suite.
+- New features MUST include tests that cover both pysnap internals and
+  the correctness of generated output.
+- Pull requests MUST reference the relevant principle(s) from this
+  constitution when introducing architectural decisions.
+- Deprecations MUST follow the process defined in Principle III:
+  deprecation warning in release N, removal no earlier than release
+  N+1 (major).
+
+## Governance
+
+- This constitution is the authoritative source of design and
+  development policy for pysnap. It supersedes informal conventions,
+  ad-hoc decisions, and any conflicting documentation.
+- Amendments to this constitution require:
+  1. A written proposal describing the change and its rationale.
+  2. Review and approval by at least one project maintainer.
+  3. A version bump to this document following semantic versioning
+     (MAJOR for principle removals/redefinitions, MINOR for new
+     principles or material expansions, PATCH for clarifications).
+  4. A migration plan if the amendment affects existing templates,
+     commands, or contributor workflows.
+- All pull requests and code reviews MUST verify compliance with the
+  principles defined above. Non-compliance MUST be justified in
+  writing with a reference to the specific trade-off.
+
+**Version**: 1.0.0 | **Ratified**: 2026-03-04 | **Last Amended**: 2026-03-04

snapstack-1.0.0/.specify/scripts/powershell/check-prerequisites.ps1

@@ -0,0 +1,148 @@
+#!/usr/bin/env pwsh
+
+# Consolidated prerequisite checking script (PowerShell)
+#
+# This script provides unified prerequisite checking for Spec-Driven Development workflow.
+# It replaces the functionality previously spread across multiple scripts.
+#
+# Usage: ./check-prerequisites.ps1 [OPTIONS]
+#
+# OPTIONS:
+#   -Json               Output in JSON format
+#   -RequireTasks       Require tasks.md to exist (for implementation phase)
+#   -IncludeTasks       Include tasks.md in AVAILABLE_DOCS list
+#   -PathsOnly          Only output path variables (no validation)
+#   -Help, -h           Show help message
+
+[CmdletBinding()]
+param(
+    [switch]$Json,
+    [switch]$RequireTasks,
+    [switch]$IncludeTasks,
+    [switch]$PathsOnly,
+    [switch]$Help
+)
+
+$ErrorActionPreference = 'Stop'
+
+# Show help if requested
+if ($Help) {
+    Write-Output @"
+Usage: check-prerequisites.ps1 [OPTIONS]
+
+Consolidated prerequisite checking for Spec-Driven Development workflow.
+
+OPTIONS:
+  -Json               Output in JSON format
+  -RequireTasks       Require tasks.md to exist (for implementation phase)
+  -IncludeTasks       Include tasks.md in AVAILABLE_DOCS list
+  -PathsOnly          Only output path variables (no prerequisite validation)
+  -Help, -h           Show this help message
+
+EXAMPLES:
+  # Check task prerequisites (plan.md required)
+  .\check-prerequisites.ps1 -Json
+  
+  # Check implementation prerequisites (plan.md + tasks.md required)
+  .\check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks
+  
+  # Get feature paths only (no validation)
+  .\check-prerequisites.ps1 -PathsOnly
+
+"@
+    exit 0
+}
+
+# Source common functions
+. "$PSScriptRoot/common.ps1"
+
+# Get feature paths and validate branch
+$paths = Get-FeaturePathsEnv
+
+if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit:$paths.HAS_GIT)) { 
+    exit 1 
+}
+
+# If paths-only mode, output paths and exit (support combined -Json -PathsOnly)
+if ($PathsOnly) {
+    if ($Json) {
+        [PSCustomObject]@{
+            REPO_ROOT    = $paths.REPO_ROOT
+            BRANCH       = $paths.CURRENT_BRANCH
+            FEATURE_DIR  = $paths.FEATURE_DIR
+            FEATURE_SPEC = $paths.FEATURE_SPEC
+            IMPL_PLAN    = $paths.IMPL_PLAN
+            TASKS        = $paths.TASKS
+        } | ConvertTo-Json -Compress
+    } else {
+        Write-Output "REPO_ROOT: $($paths.REPO_ROOT)"
+        Write-Output "BRANCH: $($paths.CURRENT_BRANCH)"
+        Write-Output "FEATURE_DIR: $($paths.FEATURE_DIR)"
+        Write-Output "FEATURE_SPEC: $($paths.FEATURE_SPEC)"
+        Write-Output "IMPL_PLAN: $($paths.IMPL_PLAN)"
+        Write-Output "TASKS: $($paths.TASKS)"
+    }
+    exit 0
+}
+
+# Validate required directories and files
+if (-not (Test-Path $paths.FEATURE_DIR -PathType Container)) {
+    Write-Output "ERROR: Feature directory not found: $($paths.FEATURE_DIR)"
+    Write-Output "Run /speckit.specify first to create the feature structure."
+    exit 1
+}
+
+if (-not (Test-Path $paths.IMPL_PLAN -PathType Leaf)) {
+    Write-Output "ERROR: plan.md not found in $($paths.FEATURE_DIR)"
+    Write-Output "Run /speckit.plan first to create the implementation plan."
+    exit 1
+}
+
+# Check for tasks.md if required
+if ($RequireTasks -and -not (Test-Path $paths.TASKS -PathType Leaf)) {
+    Write-Output "ERROR: tasks.md not found in $($paths.FEATURE_DIR)"
+    Write-Output "Run /speckit.tasks first to create the task list."
+    exit 1
+}
+
+# Build list of available documents
+$docs = @()
+
+# Always check these optional docs
+if (Test-Path $paths.RESEARCH) { $docs += 'research.md' }
+if (Test-Path $paths.DATA_MODEL) { $docs += 'data-model.md' }
+
+# Check contracts directory (only if it exists and has files)
+if ((Test-Path $paths.CONTRACTS_DIR) -and (Get-ChildItem -Path $paths.CONTRACTS_DIR -ErrorAction SilentlyContinue | Select-Object -First 1)) { 
+    $docs += 'contracts/' 
+}
+
+if (Test-Path $paths.QUICKSTART) { $docs += 'quickstart.md' }
+
+# Include tasks.md if requested and it exists
+if ($IncludeTasks -and (Test-Path $paths.TASKS)) { 
+    $docs += 'tasks.md' 
+}
+
+# Output results
+if ($Json) {
+    # JSON output
+    [PSCustomObject]@{ 
+        FEATURE_DIR = $paths.FEATURE_DIR
+        AVAILABLE_DOCS = $docs 
+    } | ConvertTo-Json -Compress
+} else {
+    # Text output
+    Write-Output "FEATURE_DIR:$($paths.FEATURE_DIR)"
+    Write-Output "AVAILABLE_DOCS:"
+    
+    # Show status of each potential document
+    Test-FileExists -Path $paths.RESEARCH -Description 'research.md' | Out-Null
+    Test-FileExists -Path $paths.DATA_MODEL -Description 'data-model.md' | Out-Null
+    Test-DirHasFiles -Path $paths.CONTRACTS_DIR -Description 'contracts/' | Out-Null
+    Test-FileExists -Path $paths.QUICKSTART -Description 'quickstart.md' | Out-Null
+    
+    if ($IncludeTasks) {
+        Test-FileExists -Path $paths.TASKS -Description 'tasks.md' | Out-Null
+    }
+}

snapstack-1.0.0/.specify/scripts/powershell/common.ps1

@@ -0,0 +1,137 @@
+#!/usr/bin/env pwsh
+# Common PowerShell functions analogous to common.sh
+
+function Get-RepoRoot {
+    try {
+        $result = git rev-parse --show-toplevel 2>$null
+        if ($LASTEXITCODE -eq 0) {
+            return $result
+        }
+    } catch {
+        # Git command failed
+    }
+    
+    # Fall back to script location for non-git repos
+    return (Resolve-Path (Join-Path $PSScriptRoot "../../..")).Path
+}
+
+function Get-CurrentBranch {
+    # First check if SPECIFY_FEATURE environment variable is set
+    if ($env:SPECIFY_FEATURE) {
+        return $env:SPECIFY_FEATURE
+    }
+    
+    # Then check git if available
+    try {
+        $result = git rev-parse --abbrev-ref HEAD 2>$null
+        if ($LASTEXITCODE -eq 0) {
+            return $result
+        }
+    } catch {
+        # Git command failed
+    }
+    
+    # For non-git repos, try to find the latest feature directory
+    $repoRoot = Get-RepoRoot
+    $specsDir = Join-Path $repoRoot "specs"
+    
+    if (Test-Path $specsDir) {
+        $latestFeature = ""
+        $highest = 0
+        
+        Get-ChildItem -Path $specsDir -Directory | ForEach-Object {
+            if ($_.Name -match '^(\d{3})-') {
+                $num = [int]$matches[1]
+                if ($num -gt $highest) {
+                    $highest = $num
+                    $latestFeature = $_.Name
+                }
+            }
+        }
+        
+        if ($latestFeature) {
+            return $latestFeature
+        }
+    }
+    
+    # Final fallback
+    return "main"
+}
+
+function Test-HasGit {
+    try {
+        git rev-parse --show-toplevel 2>$null | Out-Null
+        return ($LASTEXITCODE -eq 0)
+    } catch {
+        return $false
+    }
+}
+
+function Test-FeatureBranch {
+    param(
+        [string]$Branch,
+        [bool]$HasGit = $true
+    )
+    
+    # For non-git repos, we can't enforce branch naming but still provide output
+    if (-not $HasGit) {
+        Write-Warning "[specify] Warning: Git repository not detected; skipped branch validation"
+        return $true
+    }
+    
+    if ($Branch -notmatch '^[0-9]{3}-') {
+        Write-Output "ERROR: Not on a feature branch. Current branch: $Branch"
+        Write-Output "Feature branches should be named like: 001-feature-name"
+        return $false
+    }
+    return $true
+}
+
+function Get-FeatureDir {
+    param([string]$RepoRoot, [string]$Branch)
+    Join-Path $RepoRoot "specs/$Branch"
+}
+
+function Get-FeaturePathsEnv {
+    $repoRoot = Get-RepoRoot
+    $currentBranch = Get-CurrentBranch
+    $hasGit = Test-HasGit
+    $featureDir = Get-FeatureDir -RepoRoot $repoRoot -Branch $currentBranch
+    
+    [PSCustomObject]@{
+        REPO_ROOT     = $repoRoot
+        CURRENT_BRANCH = $currentBranch
+        HAS_GIT       = $hasGit
+        FEATURE_DIR   = $featureDir
+        FEATURE_SPEC  = Join-Path $featureDir 'spec.md'
+        IMPL_PLAN     = Join-Path $featureDir 'plan.md'
+        TASKS         = Join-Path $featureDir 'tasks.md'
+        RESEARCH      = Join-Path $featureDir 'research.md'
+        DATA_MODEL    = Join-Path $featureDir 'data-model.md'
+        QUICKSTART    = Join-Path $featureDir 'quickstart.md'
+        CONTRACTS_DIR = Join-Path $featureDir 'contracts'
+    }
+}
+
+function Test-FileExists {
+    param([string]$Path, [string]$Description)
+    if (Test-Path -Path $Path -PathType Leaf) {
+        Write-Output "  ✓ $Description"
+        return $true
+    } else {
+        Write-Output "  ✗ $Description"
+        return $false
+    }
+}
+
+function Test-DirHasFiles {
+    param([string]$Path, [string]$Description)
+    if ((Test-Path -Path $Path -PathType Container) -and (Get-ChildItem -Path $Path -ErrorAction SilentlyContinue | Where-Object { -not $_.PSIsContainer } | Select-Object -First 1)) {
+        Write-Output "  ✓ $Description"
+        return $true
+    } else {
+        Write-Output "  ✗ $Description"
+        return $false
+    }
+}
+