shappetrack 1.0.0__tar.gz

shappetrack-1.0.0/.dockerignore

@@ -0,0 +1,48 @@
+# Secrets — must NEVER be baked into the image (injected at runtime instead).
+# .env exists in the repo; config.py reads it if present.
+.env
+.env.*
+docs/engine-credentials.local.md
+
+# Runtime data / state — belongs on a volume, not in the image.
+# storage/git = bare repos (config.py), storage/blobs = release uploads (releases.py)
+storage/
+logs/
+*.db
+*.sqlite
+*.sqlite3
+*.log
+
+# Version control
+.git
+.gitignore
+
+# Python caches / virtualenvs (rebuilt/irrelevant in the image)
+venv/
+.venv/
+env/
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Local tooling / editor
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# Throwaway migration backup created during prod-readiness work
+_migration_backup/
+
+# Tests are not needed in the production image (pytest.ini, tests/)
+tests/
+pytest.ini
+
+# Docker build context self-reference (not needed inside the image)
+Dockerfile
+docker-compose.yml
+.dockerignore

shappetrack-1.0.0/.env.example

@@ -0,0 +1,107 @@
+# ============================================================
+# SECRETS — generate strong values before any non-dev use:
+#   python scripts/generate_secret.py
+# In production (ENVIRONMENT=production) the app REFUSES to start
+# if SECRET_KEY / ENCRYPTION_KEY are empty or left at dev defaults.
+# ============================================================
+
+# Server Configuration
+APP_NAME=ShapeTrack
+APP_VERSION=1.0.0
+ENVIRONMENT=development
+DEBUG=True
+HOST=0.0.0.0
+PORT=8000
+
+# Database Configuration
+DATABASE_URL=postgresql://shapetrack:shapetrack_password@localhost:5432/shapetrack
+# For development, you can use SQLite:
+# DATABASE_URL=sqlite:///./shapetrack.db
+
+# Security & Encryption
+SECRET_KEY=your-secret-key-here-change-in-production
+ENCRYPTION_KEY=your-encryption-key-here-change-in-production
+JWT_ALGORITHM=RS256
+JWT_EXPIRATION_MINUTES=1440
+
+# Storage Paths
+BLOB_STORAGE_PATH=./storage/blobs
+COMMIT_STORAGE_PATH=./storage/commits
+REPOSITORY_STORAGE_PATH=./storage/repositories
+
+# MissedTask Integration
+MISSEDTASK_API_URL=http://localhost:3000
+MISSEDTASK_API_KEY=your-missedtask-api-key
+
+# CORS (for web UI)
+ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173
+
+# Logging
+LOG_LEVEL=INFO
+LOG_FILE=./logs/shapetrack.log
+
+# Admin User (created on first run)
+# ADMIN_USERNAME is also the pinned "base admin": it is always kept as an admin on
+# login and can never be demoted or deactivated via the API (lockout protection).
+# In production this is set to "shappeadmin".
+ADMIN_USERNAME=admin
+ADMIN_EMAIL=admin@shappe.internal
+ADMIN_PASSWORD=change-me-on-first-login
+
+# ShappeTrack engine (Gitea) integration
+AUTH_BACKEND=engine
+GATEWAY_ENABLED=true
+ENGINE_BASE_URL=http://127.0.0.1:3000
+ENGINE_ADMIN_TOKEN=get-from-gitea-settings-applications
+SHAPPETRACK_RUNNER_TOKEN=get-from-gitea-runner-registration
+
+# ============================================================
+# Public git access — shown to users in the repo "Clone" box.
+# Dev defaults to localhost; in production set these to the real host.
+#   PUBLIC_GIT_HOST=track-api.shappe.ai
+#   PUBLIC_GIT_SCHEME=https
+#   SSH_HOST=track-api.shappe.ai
+#   SSH_PORT=22          # 22 if the NLB exposes 22 (clean shappetrack@host URLs)
+# SSH_USER is the branded login user shown in git@ URLs (keep "shappetrack").
+# ============================================================
+PUBLIC_GIT_HOST=localhost:8000
+PUBLIC_GIT_SCHEME=http
+SSH_USER=shappetrack
+SSH_HOST=localhost
+SSH_PORT=2222
+
+# Email / SMTP (password reset, notifications). Local dev leaves EMAIL_ENABLED=false
+# (email is simply skipped). Production sets these — SMTP creds come from SSM/Secrets.
+EMAIL_ENABLED=false
+SMTP_HOST=
+SMTP_PORT=587
+SMTP_USE_TLS=true
+FROM_EMAIL=track@shappemail.com
+# Used to build links in emails (e.g. password-reset). Prod: https://track.shappe.ai
+FRONTEND_BASE_URL=http://localhost:6173
+
+# Migrations: prod runs alembic separately, so the container sets RUN_MIGRATIONS=false.
+# Locally you can set true to auto-migrate on startup.
+RUN_MIGRATIONS=true
+
+# Git committer identity — the backend shells out to `git merge` (core/merge_service.py)
+# to merge pull requests. git refuses to create a commit without an identity
+# ("empty ident name"). These env vars are inherited by the git subprocess.
+GIT_AUTHOR_NAME=ShappeTrack
+GIT_AUTHOR_EMAIL=noreply@shappe.ai
+GIT_COMMITTER_NAME=ShappeTrack
+GIT_COMMITTER_EMAIL=noreply@shappe.ai
+
+# ============================================================
+# docker-compose infrastructure values (LOCAL DEV ONLY).
+# In production (ECS) these come from AWS Secrets Manager / SSM / task env,
+# NOT from this file. See docs/config-inventory.md.
+# ============================================================
+# Postgres (the postgres service + engine DB share these)
+POSTGRES_USER=shape
+POSTGRES_PASSWORD=Shappe@1234      # DEV ONLY — use a strong secret in prod
+POSTGRES_DB=shape-track
+# Gitea engine public host (compose). Prod: the engine's internal/public host.
+ENGINE_DOMAIN=localhost
+ENGINE_ROOT_URL=http://localhost:3000/
+ENGINE_SSH_DOMAIN=localhost        # host advertised in git@ SSH clone URLs

shappetrack-1.0.0/.github/workflows/deploy.yml

@@ -0,0 +1,312 @@
+name: CI/CD — Backend
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: backend-${{ github.ref }}
+  cancel-in-progress: false   # never cancel a deploy mid-flight
+
+env:
+  AWS_REGION: ap-south-1
+  AWS_ROLE_ARN: arn:aws:iam::626635399249:role/shappetrack-backend-gh-deploy
+  ECR_REPO: 626635399249.dkr.ecr.ap-south-1.amazonaws.com/shappetrack-backend
+  ECS_CLUSTER: shappetrack-cluster
+  ECS_SERVICE: shappetrack-backend
+  CONTAINER_NAME: backend
+  MIGRATE_CONTAINER: migrate
+  MIGRATE_TASKDEF: shappetrack-migrate
+  MIGRATE_LOG_GROUP: /ecs/shappetrack-backend
+  HEALTH_URL: https://track-api.shappe.ai/health
+  PRIVATE_SUBNETS: subnet-0e4b373e2d2be0f0c,subnet-0fd7355f30a5c4f21
+  BACKEND_SG: sg-04fd5f7806cdb3287
+
+jobs:
+  # ── JOB 1: security ────────────────────────────────────────────
+  security:
+    name: Secret Scan & SAST
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout (full history)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Secret scan (TruffleHog — verified only)
+        uses: trufflesecurity/trufflehog@main
+        with:
+          path: ./
+          base: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
+          head: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.event.after }}
+          extra_args: --only-verified
+
+      # Dependency vulnerability scanning is handled by pip-audit (JOB 2).
+      # The GitHub dependency-review-action requires GitHub Advanced Security
+      # on private repos, so it is intentionally not used here.
+
+      - name: Semgrep SAST (Python)
+        uses: semgrep/semgrep-action@v1
+        with:
+          config: >-
+            p/security-audit
+            p/owasp-top-ten
+            p/python
+
+  # ── JOB 2: CI — lint, CVE, tests, MIGRATION TEST, docker build ─
+  ci:
+    name: Lint · CVE · Test · Migrate · Build
+    runs-on: ubuntu-latest
+    needs: security
+    # Throwaway Postgres for the migration test — spun up by GitHub, dies with the job.
+    # No AWS, no cost. Lets us run `alembic upgrade head` against a REAL Postgres so
+    # migration conflicts (e.g. DuplicateColumn) fail CI instead of reaching production.
+    services:
+      postgres:
+        image: postgres:15
+        env:
+          POSTGRES_USER: citest
+          POSTGRES_PASSWORD: citest
+          POSTGRES_DB: citestdb
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install dev dependencies
+        run: pip install -r requirements-dev.txt
+
+      - name: Lint (ruff — non-blocking until debt cleared)
+        run: pip install ruff && ruff check . || true
+
+      - name: Dependency CVE scan (pip-audit — non-blocking)
+        run: pip install pip-audit && pip-audit -r requirements.txt || true
+
+      - name: Run tests (pytest — sqlite in-memory, blocking)
+        run: pytest -q
+
+      # ⭐ MIGRATION TEST — run the full alembic chain against a REAL Postgres.
+      # Catches DuplicateColumn / conflicting / non-idempotent migrations BEFORE
+      # they can reach production. upgrade head -> downgrade base -> upgrade head
+      # also proves migrations are reversible and idempotent. BLOCKING.
+      - name: Test migrations on real Postgres
+        env:
+          DATABASE_URL: postgresql://citest:citest@localhost:5432/citestdb
+          ENVIRONMENT: ci
+          SECRET_KEY: ci-dummy-secret-key-not-used-in-prod
+          ENCRYPTION_KEY: ci-dummy-encryption-key-not-used-in-prod
+          ADMIN_PASSWORD: ci-dummy-admin-pass
+          ALLOWED_ORIGINS: "*"
+        run: |
+          # Full round-trip on a clean Postgres (industry best practice):
+          #   upgrade head  -> catches conflicts / DuplicateColumn / missing-dep migrations
+          #   downgrade base-> verifies every migration is reversible (incl. ENUM cleanup)
+          #   upgrade head  -> verifies idempotency (re-upgrade after full downgrade works)
+          # Any broken/non-reversible migration fails CI here, before it can reach prod.
+          alembic upgrade head
+          alembic downgrade base
+          alembic upgrade head
+
+      - name: Docker build (verify image builds — blocking)
+        run: docker build -t shappetrack-backend:ci .
+
+  # ── JOB 3: deploy (auto on push to main) ──────────────────────
+  deploy:
+    name: Deploy to ECS
+    runs-on: ubuntu-latest
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout (full history — needed to diff the whole push range for migrations)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Configure AWS credentials (OIDC)
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ env.AWS_ROLE_ARN }}
+          aws-region: ${{ env.AWS_REGION }}
+
+      - name: Login to ECR
+        uses: aws-actions/amazon-ecr-login@v2
+
+      # Immutable tag: git SHA + run attempt (unique even on re-runs)
+      - name: Build & push image
+        id: build
+        run: |
+          TAG="${{ github.sha }}-${{ github.run_attempt }}"
+          IMAGE="$ECR_REPO:$TAG"
+          docker build -t "$IMAGE" .
+          docker push "$IMAGE"
+          echo "image=$IMAGE" >> "$GITHUB_OUTPUT"
+
+      # Record current task-def so we can roll back if the deploy goes bad
+      - name: Record rollback task-def
+        run: |
+          CUR=$(aws ecs describe-services --cluster "$ECS_CLUSTER" --services "$ECS_SERVICE" \
+            --query "services[0].taskDefinition" --output text)
+          echo "ROLLBACK_TASKDEF=$CUR" >> "$GITHUB_ENV"
+          echo "Rollback target: $CUR"
+
+      # ── Decide whether to run the migration release-phase task.
+      # LESSON (twice bitten): "HEAD~1..HEAD" only sees the LAST commit. When a
+      # push contains several commits and the migration is in an earlier one,
+      # that window misses it and the migration is silently skipped while the
+      # new app code already expects the new schema -> prod 500s.
+      # Fix: diff across the ENTIRE push range (github.event.before..sha). And if
+      # that range can't be computed for ANY reason, FAIL SAFE = run migrations.
+      # Running is safe even with no changes: `alembic upgrade head` is a no-op
+      # when the DB is already at head (verified from logs below). A needless
+      # ~20s migration task is far cheaper than a skipped-but-needed migration.
+      - name: Detect migration changes
+        id: migcheck
+        env:
+          BEFORE_SHA: ${{ github.event.before }}
+        run: |
+          RUN=false
+          # Zero SHA (first push to the branch) or unfetched base -> can't diff -> run.
+          if [ -z "$BEFORE_SHA" ] || [ "$BEFORE_SHA" = "0000000000000000000000000000000000000000" ]; then
+            echo "No usable before-SHA — running migrations to be safe."
+            RUN=true
+          elif ! git cat-file -e "$BEFORE_SHA^{commit}" 2>/dev/null; then
+            # base commit not in the shallow checkout — deepen, else fail safe
+            git fetch --depth=50 origin "$BEFORE_SHA" 2>/dev/null || true
+            if ! git cat-file -e "$BEFORE_SHA^{commit}" 2>/dev/null; then
+              echo "before-SHA $BEFORE_SHA not fetchable — running migrations to be safe."
+              RUN=true
+            fi
+          fi
+          if [ "$RUN" != "true" ]; then
+            CHANGED=$(git diff --name-only "$BEFORE_SHA" "${{ github.sha }}" -- alembic/versions/ || echo "DIFF_FAILED")
+            if [ "$CHANGED" = "DIFF_FAILED" ]; then
+              echo "git diff failed — running migrations to be safe."
+              RUN=true
+            elif [ -n "$CHANGED" ]; then
+              echo "Migration files changed across the push:"; echo "$CHANGED"
+              RUN=true
+            else
+              echo "No migration changes across ${BEFORE_SHA}..${{ github.sha }} — skipping migration step."
+            fi
+          fi
+          echo "changed=$RUN" >> "$GITHUB_OUTPUT"
+
+      # ── RELEASE PHASE: run migration task, verify from LOGS (not just exit 0)
+      - name: Render migrate task-def
+        if: steps.migcheck.outputs.changed == 'true'
+        id: rendermig
+        uses: aws-actions/amazon-ecs-render-task-definition@v1
+        with:
+          task-definition-family: ${{ env.MIGRATE_TASKDEF }}
+          container-name: ${{ env.MIGRATE_CONTAINER }}
+          image: ${{ steps.build.outputs.image }}
+
+      - name: Run & verify migration
+        if: steps.migcheck.outputs.changed == 'true'
+        run: |
+          # The render action can emit "tags": [] which register-task-definition rejects
+          # ("Tags can not be empty"). Strip an empty tags array before registering.
+          jq 'if .tags == [] then del(.tags) else . end' ${{ steps.rendermig.outputs.task-definition }} > /tmp/migrate-td.json
+          ARN=$(aws ecs register-task-definition \
+            --cli-input-json file:///tmp/migrate-td.json \
+            --query "taskDefinition.taskDefinitionArn" --output text)
+          echo "Running migration: $ARN"
+          TASK=$(aws ecs run-task --cluster "$ECS_CLUSTER" --task-definition "$ARN" --launch-type EC2 \
+            --network-configuration "awsvpcConfiguration={subnets=[${PRIVATE_SUBNETS}],securityGroups=[${BACKEND_SG}]}" \
+            --query "tasks[0].taskArn" --output text)
+          aws ecs wait tasks-stopped --cluster "$ECS_CLUSTER" --tasks "$TASK"
+          EXIT=$(aws ecs describe-tasks --cluster "$ECS_CLUSTER" --tasks "$TASK" \
+            --query "tasks[0].containers[0].exitCode" --output text)
+          echo "Migration exit code: $EXIT"
+          # The container exit code is the AUTHORITATIVE pass/fail. `alembic upgrade`
+          # exits non-zero on any Python/DDL error, and Postgres transactional DDL
+          # rolls the whole upgrade back on failure — so exit 0 means the migration
+          # applied (or was already at head). A non-numeric/empty EXIT (couldn't read
+          # it) is also a hard fail.
+          case "$EXIT" in
+            0) echo "Migration container exited 0 — success." ;;
+            *) echo "Migration FAILED (exit=$EXIT) — aborting"; exit 1 ;;
+          esac
+
+          # Fetch the logs for HUMAN VISIBILITY and a best-effort sanity check ONLY.
+          # A failure to READ the logs (IAM/timing) must NOT abort a migration that
+          # already exited 0 — that false-abort bit us once. We isolate the log text
+          # from any AWS-CLI error so the CLI's own "...Error..." can't be mistaken
+          # for a migration error.
+          TASK_ID=$(basename "$TASK")
+          sleep 5
+          if LOGS=$(aws logs get-log-events --log-group-name "$MIGRATE_LOG_GROUP" \
+                --log-stream-name "migrate/${MIGRATE_CONTAINER}/${TASK_ID}" \
+                --query "events[*].message" --output text 2>/dev/null); then
+            echo "Migration logs:"; echo "$LOGS"
+            # Only a genuine migration-side failure signature downgrades a 0-exit to
+            # a hard fail (belt-and-suspenders; should never fire when exit==0).
+            if echo "$LOGS" | grep -qiE "Traceback|SQLAlchemyError|psycopg|DuplicateColumn|UndefinedTable|relation .* does not exist|type .* already exists"; then
+              echo "Migration exited 0 but logs show a failure signature — aborting to be safe"; exit 1
+            fi
+            echo "Migration verified (exit 0 + logs clean)."
+          else
+            # Could not read logs — do NOT abort. Exit 0 already proved success.
+            echo "Note: could not read migration logs (permissions/timing); relying on exit code 0."
+          fi
+
+      # ── Deploy app: render committed task-def with new image, update service, wait stable
+      - name: Render backend task-def (committed file)
+        id: renderapp
+        uses: aws-actions/amazon-ecs-render-task-definition@v1
+        with:
+          task-definition: task-definition.json
+          container-name: ${{ env.CONTAINER_NAME }}
+          image: ${{ steps.build.outputs.image }}
+
+      - name: Deploy to ECS + wait stable
+        uses: aws-actions/amazon-ecs-deploy-task-definition@v2
+        with:
+          task-definition: ${{ steps.renderapp.outputs.task-definition }}
+          service: ${{ env.ECS_SERVICE }}
+          cluster: ${{ env.ECS_CLUSTER }}
+          wait-for-service-stability: true
+
+      # ── Smoke test the live API
+      - name: Smoke test /health
+        id: smoke
+        run: |
+          for i in 1 2 3 4 5 6; do
+            code=$(curl -s -o /tmp/h.json -w "%{http_code}" "$HEALTH_URL")
+            if [ "$code" = "200" ] && grep -q '"status"' /tmp/h.json; then
+              echo "Healthy (HTTP $code): $(cat /tmp/h.json)"; echo "ok=true" >> "$GITHUB_OUTPUT"; exit 0
+            fi
+            echo "Attempt $i: HTTP $code — retry 10s"; sleep 10
+          done
+          echo "ok=false" >> "$GITHUB_OUTPUT"
+
+      # ── Rollback to previous task-def on smoke failure
+      - name: Rollback on smoke failure
+        if: steps.smoke.outputs.ok == 'false'
+        run: |
+          echo "Smoke failed — rolling back to $ROLLBACK_TASKDEF"
+          aws ecs update-service --cluster "$ECS_CLUSTER" --service "$ECS_SERVICE" \
+            --task-definition "$ROLLBACK_TASKDEF" --force-new-deployment
+          aws ecs wait services-stable --cluster "$ECS_CLUSTER" --services "$ECS_SERVICE"
+          code=$(curl -s -o /dev/null -w "%{http_code}" "$HEALTH_URL")
+          echo "Post-rollback health: HTTP $code"
+          exit 1

shappetrack-1.0.0/.gitignore

@@ -0,0 +1,42 @@
+# ===== Secrets (NEVER commit) =====
+.env
+.env.local
+.env.*.local
+docs/engine-credentials.local.md
+
+# ===== Python =====
+venv/
+.venv/
+env/
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+# Python build artifacts (CLI packaging: wheels, sdists, PyInstaller output)
+dist/
+build/
+*.spec
+.ruff_cache/
+
+# ===== Database / runtime data =====
+*.db
+*.sqlite
+*.sqlite3
+storage/
+logs/
+*.log
+
+# ===== OS / editor =====
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/*
+!.vscode/extensions.json
+
+# ===== Backups / scratch =====
+*.backup
+*.bak
+*.orig
+*.tmp

shappetrack-1.0.0/.python-version

@@ -0,0 +1 @@
+3.11

shappetrack-1.0.0/Dockerfile

@@ -0,0 +1,84 @@
+# ShappeTrack Backend — production image
+# Stack proven from repo: Python 3.11 + FastAPI, run by gunicorn/uvicorn worker.
+# (requirements.txt, main.py, docker-entrypoint.sh)
+
+# ---------- Stage 1: build dependency wheels ----------
+# Same base as runtime so wheels are ABI-compatible.
+FROM python:3.11-slim AS builder
+
+WORKDIR /app
+
+# No compiler installed: every dependency in requirements.txt is pure-Python or
+# ships a manylinux wheel (psycopg2-BINARY, cryptography, bcrypt). Verified — no
+# source builds are required.
+COPY requirements.txt .
+
+# Build wheels for all pinned deps into /wheels for a clean copy into runtime.
+# requirements.txt is fully version-pinned (no lockfile in repo) -> reproducible.
+RUN pip wheel --no-cache-dir --wheel-dir /wheels -r requirements.txt
+
+
+# ---------- Stage 2: runtime ----------
+FROM python:3.11-slim AS runtime
+
+# PYTHONUNBUFFERED        — flush stdout/stderr immediately so logs reach
+#                           CloudWatch in real time and aren't lost on crash.
+# PYTHONDONTWRITEBYTECODE — no .pyc clutter in an immutable/ephemeral container.
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+# Runtime OS deps:
+#   git  — the app shells out to the git binary via subprocess
+#          (core/git_server.py: "git init --bare", "git log", "git for-each-ref";
+#           core/merge_service.py: "git rev-parse", "git merge-base").
+#   tini — PID 1 init that forwards signals (SIGTERM from ECS) and REAPS the
+#          orphaned git subprocesses the app spawns, preventing zombie buildup.
+# postgresql-client and gcc are intentionally NOT installed — nothing in the
+# repo invokes psql/pg_* and no dependency compiles from source.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends git tini \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install the prebuilt wheels, then drop them. --no-cache-dir keeps pip's cache
+# out of the final layer.
+COPY --from=builder /wheels /wheels
+COPY requirements.txt .
+RUN pip install --no-cache-dir --no-index --find-links=/wheels -r requirements.txt \
+    && rm -rf /wheels
+
+# Application source. .dockerignore excludes .env*, storage/, logs/, .git, caches
+# and tests/ so secrets and runtime state never enter the image.
+COPY . .
+
+# Entrypoint is a real tracked script (docker-entrypoint.sh): it runs
+# `alembic upgrade head` (gated by RUN_MIGRATIONS) then execs gunicorn.
+RUN chmod +x /app/docker-entrypoint.sh
+
+# Writable runtime directories, owned by the non-root user:
+#   storage/ — bare git repos (config.py GIT_STORAGE_PATH=./storage/git) and
+#              release uploads (api/v1/releases.py writes BLOB_STORAGE_PATH/releases/<id>)
+#   logs/    — config.py ensure_storage_paths() creates dirname(LOG_FILE)=./logs
+# (Application logs go to stdout, but the logs/ dir is still created on boot.)
+RUN useradd --create-home --uid 10001 appuser \
+    && mkdir -p /app/storage /app/logs \
+    && chown -R appuser:appuser /app/storage /app/logs
+
+USER appuser
+
+# Port 8000 is the only bound port (config.py HOST=0.0.0.0 PORT=8000; entrypoint
+# binds ${HOST}:${PORT}). No SSH listener exists in this process, so 2222 is NOT
+# exposed (SSH_PORT in config.py is advertised clone-URL metadata only).
+EXPOSE 8000
+
+# /health is a real unauthenticated endpoint (main.py @app.get("/health")).
+# Use the stdlib so the check needs no extra packages.
+HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
+    CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8000/health', timeout=5).status==200 else 1)" || exit 1
+
+# tini as PID 1 (exec form): forwards SIGTERM to the entrypoint and reaps the
+# orphaned git subprocesses the app spawns. The entrypoint then `exec`s gunicorn
+# so signals reach it directly.
+# Reads ENVIRONMENT / WEB_CONCURRENCY / GUNICORN_TIMEOUT / RUN_MIGRATIONS from env.
+ENTRYPOINT ["/usr/bin/tini", "--", "/app/docker-entrypoint.sh"]

shappetrack-1.0.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: shappetrack
+Version: 1.0.0
+Summary: ShappeTrack CLI — clone, commit, and push ShappeTrack repositories with one app token. The git engine stays invisible.
+Project-URL: Homepage, https://track.shappe.ai
+Author: ShappeTrack
+License: Proprietary
+Keywords: cli,git,shappetrack,vcs
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Requires-Dist: httpx==0.26.0
+Requires-Dist: typer<1.0,>=0.12
+Description-Content-Type: text/markdown
+
+# ShappeTrack CLI
+
+Clone, commit, and push ShappeTrack repositories with **one app token**. Real
+`git` runs under the hood; the git engine is never exposed.
+
+```
+shappetrack login --server https://track-api.shappe.ai/api/v1
+shappetrack clone my-repo
+```
+
+## Install
+
+The CLI is a small Python package (`shappetrack-cli`). The recommended way is
+[`pipx`](https://pipx.pypa.io/), which installs it in an isolated environment so
+it never clashes with your other Python tools.
+
+### For end users (once published to PyPI)
+
+```bash
+pipx install shappetrack
+```
+
+### From source (internal / development)
+
+From the directory containing `pyproject.toml`:
+
+```bash
+pipx install .          # isolated, recommended
+# or
+pip install .           # into the current environment
+```
+
+Requires **Python 3.9+** and **git** on your PATH (the CLI runs real git under the hood).
+
+## Usage
+
+1. Create an app token in the web app: **Settings → Access Tokens** (starts with `shp_`).
+2. Log in once — this configures git credentials automatically:
+
+   ```bash
+   shappetrack login --server https://track-api.shappe.ai/api/v1
+   ```
+
+3. Then use the familiar commands (they run standard git underneath):
+
+   ```bash
+   shappetrack clone my-repo
+   shappetrack status
+   shappetrack add .
+   shappetrack commit -m "message" --task MT-101
+   shappetrack push
+   shappetrack pull
+   shappetrack branch feature-x
+   ```
+
+## How it works
+
+`shappetrack clone my-repo` runs `git clone https://track-api.shappe.ai/repos/my-repo`
+using the app token you logged in with. The backend proxies git traffic to the
+internal engine — you never see or handle the engine, its host, or its token.
+
+You can also clone with plain git directly (no CLI needed):
+
+```bash
+git clone https://track-api.shappe.ai/repos/my-repo
+# username: your ShappeTrack username, password: your shp_ app token
+```