lets begin
This commit is contained in:
commit
be50a0dd88
28
.claude/mcp-servers.json
Normal file
28
.claude/mcp-servers.json
Normal file
@ -0,0 +1,28 @@
|
||||
{
|
||||
"description": "AITM MCP server configuration for Claude Code in this monorepo",
|
||||
"servers": {
|
||||
"aitm": {
|
||||
"type": "stdio",
|
||||
"command": "node",
|
||||
"args": ["/Users/arhansubasi/gitgram-ai/aitimemachine/mcp/dist/index.js"],
|
||||
"env": {
|
||||
"GITNEXUS_URL": "http://localhost:3001",
|
||||
"AITM_GITNEXUS_ENABLED": "1",
|
||||
"AITM_A2A_AGENTS": "[]"
|
||||
},
|
||||
"description": "AITimeMachine MCP — checkpoints, restore, beads DAG, gitnexus code intelligence, A2A agent protocol"
|
||||
},
|
||||
"gitnexus": {
|
||||
"type": "stdio",
|
||||
"command": "node",
|
||||
"args": ["/Users/arhansubasi/gitgram-ai/aitimemachine/gitnexus/dist/cli/index.js", "mcp"],
|
||||
"description": "GitNexus — code knowledge graph: query, impact, context, trace, taint analysis"
|
||||
},
|
||||
"context7": {
|
||||
"type": "stdio",
|
||||
"command": "node",
|
||||
"args": ["/Users/arhansubasi/gitgram-ai/aitimemachine/context7/packages/mcp/dist/index.js"],
|
||||
"description": "Context7 — fetch up-to-date library documentation for any npm/PyPI package"
|
||||
}
|
||||
}
|
||||
}
|
||||
56
.env.aitm-api.example
Normal file
56
.env.aitm-api.example
Normal file
@ -0,0 +1,56 @@
|
||||
# AITM API (manual launch template)
|
||||
NODE_ENV=production
|
||||
HOST=127.0.0.1
|
||||
PORT=3001
|
||||
|
||||
# Database
|
||||
DATABASE_URL=postgresql://user:password@project.neon.tech/aitm?sslmode=require
|
||||
|
||||
# Networking / internal auth
|
||||
INTERNAL_SECRET=CHANGE_ME_INTERNAL_SECRET
|
||||
CORS_ORIGIN=https://timemachine.gitgram.app
|
||||
WEBSITE_URL=https://timemachine.gitgram.app
|
||||
|
||||
# Billing / email / monitoring
|
||||
# Use a sandbox organization access token for staging/testing.
|
||||
# Polar sandbox is isolated from production. See docs/polar-payment-setup.md.
|
||||
POLAR_ACCESS_TOKEN=
|
||||
POLAR_MODE=production
|
||||
POLAR_WEBHOOK_SECRET=
|
||||
POLAR_PRO_PRODUCT_ID=
|
||||
POLAR_TEAM_PRODUCT_ID=
|
||||
RESEND_API_KEY=
|
||||
SENTRY_DSN=
|
||||
|
||||
# Optional integrations
|
||||
CLERK_WEBHOOK_SECRET=
|
||||
REDIS_URL=
|
||||
OPENAI_API_KEY=
|
||||
ANTHROPIC_API_KEY=
|
||||
VOYAGE_API_KEY=
|
||||
BRAVE_SEARCH_API_KEY=
|
||||
|
||||
# Managed workers
|
||||
ENABLE_WORKERS=true
|
||||
DELETE_WORKER_ENABLED=true
|
||||
RETENTION_WORKER_ENABLED=true
|
||||
GC_WORKER_ENABLED=true
|
||||
|
||||
# GitNexus integration
|
||||
GITNEXUS_URL=http://localhost:3001
|
||||
# A2A protocol
|
||||
AITM_A2A_AGENTS=[]
|
||||
AITM_API_URL=http://localhost:3001
|
||||
|
||||
# Workspace
|
||||
WORKSPACE_PATH=/path/to/your/project
|
||||
|
||||
# Beads task tracker binary
|
||||
BEADS_BINARY=/path/to/aitimemachine/beads/bd
|
||||
|
||||
# Gitgram bridge (auto-post AITM events to Gitgram feed)
|
||||
GITGRAM_API_URL=http://localhost:4000
|
||||
GITGRAM_API_KEY=
|
||||
|
||||
# PAL MCP Python execution server
|
||||
PAL_MCP_URL=http://localhost:3200
|
||||
13
.env.aitm-website.example
Normal file
13
.env.aitm-website.example
Normal file
@ -0,0 +1,13 @@
|
||||
# AITM website (optional self-hosted dashboard)
|
||||
NEXT_PUBLIC_API_URL=https://timemachine-api.gitgram.app
|
||||
API_URL=https://timemachine-api.gitgram.app
|
||||
INTERNAL_SECRET=CHANGE_ME_INTERNAL_SECRET
|
||||
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
|
||||
CLERK_SECRET_KEY=
|
||||
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
|
||||
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
|
||||
NEXT_PUBLIC_APP_URL=https://timemachine.gitgram.app
|
||||
POLAR_ACCESS_TOKEN=
|
||||
POLAR_MODE=production
|
||||
NEXT_PUBLIC_POLAR_PRO_PRODUCT_ID=
|
||||
NEXT_PUBLIC_POLAR_TEAM_PRODUCT_ID=
|
||||
7
.env.gitgram-web.example
Normal file
7
.env.gitgram-web.example
Normal file
@ -0,0 +1,7 @@
|
||||
# Gitgram web (manual launch template)
|
||||
NEXT_PUBLIC_API_URL=https://gitgram.app/api
|
||||
NEXT_PUBLIC_WS_URL=wss://gitgram.app
|
||||
NEXT_PUBLIC_GITHUB_CLIENT_ID=
|
||||
NEXT_PUBLIC_GOOGLE_CLIENT_ID=
|
||||
NEXT_PUBLIC_AITM_API_URL=https://timemachine-api.gitgram.app/v1
|
||||
NEXT_PUBLIC_SENTRY_DSN=
|
||||
72
.env.gitgram.example
Normal file
72
.env.gitgram.example
Normal file
@ -0,0 +1,72 @@
|
||||
# Gitgram backend (manual launch template)
|
||||
NODE_ENV=production
|
||||
PORT=4000
|
||||
|
||||
# Database / cache
|
||||
DATABASE_URL=postgresql://gitgram:CHANGE_ME@127.0.0.1:5432/gitgram
|
||||
REDIS_URL=redis://127.0.0.1:6379
|
||||
|
||||
# Auth
|
||||
JWT_SECRET=CHANGE_ME_JWT_SECRET
|
||||
JWT_REFRESH_SECRET=CHANGE_ME_JWT_REFRESH_SECRET
|
||||
FRONTEND_URL=https://gitgram.app
|
||||
CORS_ORIGIN=https://gitgram.app,https://www.gitgram.app
|
||||
|
||||
# OAuth
|
||||
GITHUB_CLIENT_ID=
|
||||
GITHUB_CLIENT_SECRET=
|
||||
GOOGLE_CLIENT_ID=
|
||||
GOOGLE_CLIENT_SECRET=
|
||||
|
||||
# Payments
|
||||
POLAR_ACCESS_TOKEN=
|
||||
POLAR_WEBHOOK_SECRET=
|
||||
POLAR_PREMIUM_PRODUCT_ID=
|
||||
POLAR_CREATOR_PRODUCT_ID=
|
||||
POLAR_MODE=production
|
||||
|
||||
# Email / monitoring
|
||||
RESEND_API_KEY=
|
||||
SENTRY_DSN=
|
||||
|
||||
# Storage
|
||||
STORAGE_TYPE=local
|
||||
AWS_ACCESS_KEY_ID=
|
||||
AWS_SECRET_ACCESS_KEY=
|
||||
AWS_S3_BUCKET=
|
||||
AWS_REGION=us-east-1
|
||||
UPLOAD_DIR=./uploads
|
||||
MAX_FILE_SIZE=10485760
|
||||
|
||||
# === Social Graph & AI Integration ===
|
||||
|
||||
# gh-social: GitHub trending fallback
|
||||
GITHUB_TRENDING_API_KEY=
|
||||
|
||||
# GitNexus Code Intelligence (enables gn_* tools in AITM MCP)
|
||||
GITNEXUS_URL=http://localhost:3001
|
||||
AITM_GITNEXUS_ENABLED=0
|
||||
|
||||
# A2A Agent Protocol
|
||||
AITM_A2A_AGENTS=[]
|
||||
AITM_API_URL=http://localhost:3001
|
||||
|
||||
# Context7 Live Docs (enables tm_docs_* tools in AITM MCP)
|
||||
CONTEXT7_URL=http://localhost:3100
|
||||
AITM_CONTEXT7_ENABLED=0
|
||||
|
||||
# Developer Tools
|
||||
REPO_TO_TEXT_MAX_FILES=200
|
||||
REPO_TO_TEXT_MAX_FILE_SIZE=50000
|
||||
|
||||
|
||||
# === PAL MCP Server (Python execution in AITM) ===
|
||||
PAL_MCP_URL=http://localhost:3200
|
||||
AITM_PAL_ENABLED=0
|
||||
|
||||
# === AITM-Gitgram Bridge (auto-post GitHub events to Gitgram) ===
|
||||
GITGRAM_API_URL=http://localhost:4000
|
||||
GITGRAM_API_KEY=
|
||||
|
||||
# === AI Analysis (GitNexus backend integration) ===
|
||||
# Already uses GITNEXUS_URL above
|
||||
5
.env.postgres.example
Normal file
5
.env.postgres.example
Normal file
@ -0,0 +1,5 @@
|
||||
# PostgreSQL Configuration
|
||||
POSTGRES_USER=gitgram
|
||||
POSTGRES_PASSWORD=CHANGE_ME_STRONG_PASSWORD
|
||||
POSTGRES_DB=gitgram
|
||||
AITM_DB=aitimemachine
|
||||
19
.eslintrc.js
Normal file
19
.eslintrc.js
Normal file
@ -0,0 +1,19 @@
|
||||
module.exports = {
|
||||
root: true,
|
||||
parser: '@typescript-eslint/parser',
|
||||
plugins: ['@typescript-eslint'],
|
||||
extends: [
|
||||
'eslint:recommended',
|
||||
'plugin:@typescript-eslint/recommended',
|
||||
],
|
||||
env: {
|
||||
node: true,
|
||||
es2022: true,
|
||||
},
|
||||
rules: {
|
||||
'@typescript-eslint/no-explicit-any': 'warn',
|
||||
'@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
|
||||
'no-console': ['warn', { allow: ['warn', 'error'] }],
|
||||
},
|
||||
ignorePatterns: ['dist/', 'node_modules/', 'coverage/', '*.js'],
|
||||
};
|
||||
247
.github/workflows/ci.yml
vendored
Normal file
247
.github/workflows/ci.yml
vendored
Normal file
@ -0,0 +1,247 @@
|
||||
# =============================================================================
|
||||
# CI - Gitgram + AI Time Machine
|
||||
# Runs on every push/PR to main.
|
||||
# Runs all test suites in parallel; typecheck and lint run independently.
|
||||
# fail-fast: false ensures all jobs complete even when one fails.
|
||||
# =============================================================================
|
||||
name: CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
|
||||
env:
|
||||
NODE_VERSION: "20"
|
||||
|
||||
jobs:
|
||||
# ---------------------------------------------------------------------------
|
||||
# Gitgram Backend - Jest tests against live Postgres + Redis services
|
||||
# ---------------------------------------------------------------------------
|
||||
test-gitgram-backend:
|
||||
name: "Test: Gitgram Backend"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15
|
||||
strategy:
|
||||
fail-fast: false
|
||||
defaults:
|
||||
run:
|
||||
working-directory: gitgram/backend
|
||||
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:16
|
||||
env:
|
||||
POSTGRES_PASSWORD: test
|
||||
POSTGRES_DB: gitgram_test
|
||||
ports:
|
||||
- 5432:5432
|
||||
options: >-
|
||||
--health-cmd pg_isready
|
||||
--health-interval 10s
|
||||
--health-timeout 5s
|
||||
--health-retries 5
|
||||
|
||||
redis:
|
||||
image: redis:7
|
||||
ports:
|
||||
- 6379:6379
|
||||
options: >-
|
||||
--health-cmd "redis-cli ping"
|
||||
--health-interval 10s
|
||||
--health-timeout 5s
|
||||
--health-retries 5
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js ${{ env.NODE_VERSION }}
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
|
||||
- name: Cache npm dependencies
|
||||
uses: actions/cache@v4
|
||||
with:
|
||||
path: gitgram/backend/node_modules
|
||||
key: npm-gitgram-backend-${{ hashFiles('gitgram/backend/package-lock.json') }}
|
||||
restore-keys: npm-gitgram-backend-
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm install
|
||||
|
||||
- name: Run tests
|
||||
run: npm run test -- --forceExit
|
||||
env:
|
||||
DATABASE_URL: postgresql://postgres:test@localhost:5432/gitgram_test
|
||||
REDIS_URL: redis://localhost:6379
|
||||
NODE_ENV: test
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Gitgram Web - Vitest
|
||||
# ---------------------------------------------------------------------------
|
||||
test-gitgram-web:
|
||||
name: "Test: Gitgram Web"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
strategy:
|
||||
fail-fast: false
|
||||
defaults:
|
||||
run:
|
||||
working-directory: gitgram/web
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js ${{ env.NODE_VERSION }}
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
|
||||
- name: Cache npm dependencies
|
||||
uses: actions/cache@v4
|
||||
with:
|
||||
path: gitgram/web/node_modules
|
||||
key: npm-gitgram-web-${{ hashFiles('gitgram/web/package-lock.json') }}
|
||||
restore-keys: npm-gitgram-web-
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm install
|
||||
|
||||
- name: Run tests
|
||||
run: npm test
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AITM API Server - Vitest
|
||||
# ---------------------------------------------------------------------------
|
||||
test-aitm:
|
||||
name: "Test: AITM API Server"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
strategy:
|
||||
fail-fast: false
|
||||
defaults:
|
||||
run:
|
||||
working-directory: aitimemachine/api-server
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js ${{ env.NODE_VERSION }}
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
|
||||
- name: Cache npm dependencies
|
||||
uses: actions/cache@v4
|
||||
with:
|
||||
path: aitimemachine/api-server/node_modules
|
||||
key: npm-aitm-api-server-${{ hashFiles('aitimemachine/api-server/package-lock.json') }}
|
||||
restore-keys: npm-aitm-api-server-
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm install
|
||||
|
||||
- name: Run tests
|
||||
run: npm test
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# TypeScript type checking - backend + web
|
||||
# ---------------------------------------------------------------------------
|
||||
typecheck:
|
||||
name: "Typecheck: Backend + Web"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
strategy:
|
||||
fail-fast: false
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js ${{ env.NODE_VERSION }}
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
|
||||
- name: Cache npm dependencies (backend)
|
||||
uses: actions/cache@v4
|
||||
with:
|
||||
path: gitgram/backend/node_modules
|
||||
key: npm-gitgram-backend-${{ hashFiles('gitgram/backend/package-lock.json') }}
|
||||
restore-keys: npm-gitgram-backend-
|
||||
|
||||
- name: Cache npm dependencies (web)
|
||||
uses: actions/cache@v4
|
||||
with:
|
||||
path: gitgram/web/node_modules
|
||||
key: npm-gitgram-web-${{ hashFiles('gitgram/web/package-lock.json') }}
|
||||
restore-keys: npm-gitgram-web-
|
||||
|
||||
- name: Install backend dependencies
|
||||
working-directory: gitgram/backend
|
||||
run: npm ci --legacy-peer-deps
|
||||
|
||||
- name: Install web dependencies
|
||||
working-directory: gitgram/web
|
||||
run: npm ci --legacy-peer-deps
|
||||
|
||||
- name: Typecheck backend
|
||||
working-directory: gitgram/backend
|
||||
run: npx tsc --noEmit
|
||||
|
||||
- name: Typecheck web
|
||||
working-directory: gitgram/web
|
||||
run: npx tsc --noEmit
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# ESLint - backend (has .eslintrc.js); web uses Next.js lint
|
||||
# ---------------------------------------------------------------------------
|
||||
lint:
|
||||
name: "Lint: Backend + Web"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
strategy:
|
||||
fail-fast: false
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js ${{ env.NODE_VERSION }}
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
|
||||
- name: Cache npm dependencies (backend)
|
||||
uses: actions/cache@v4
|
||||
with:
|
||||
path: gitgram/backend/node_modules
|
||||
key: npm-gitgram-backend-${{ hashFiles('gitgram/backend/package-lock.json') }}
|
||||
restore-keys: npm-gitgram-backend-
|
||||
|
||||
- name: Cache npm dependencies (web)
|
||||
uses: actions/cache@v4
|
||||
with:
|
||||
path: gitgram/web/node_modules
|
||||
key: npm-gitgram-web-${{ hashFiles('gitgram/web/package-lock.json') }}
|
||||
restore-keys: npm-gitgram-web-
|
||||
|
||||
- name: Install backend dependencies
|
||||
working-directory: gitgram/backend
|
||||
run: npm install
|
||||
|
||||
- name: Install web dependencies
|
||||
working-directory: gitgram/web
|
||||
run: npm install
|
||||
|
||||
- name: Lint backend
|
||||
working-directory: gitgram/backend
|
||||
run: npm run lint
|
||||
|
||||
- name: Lint web
|
||||
working-directory: gitgram/web
|
||||
run: npm run lint
|
||||
217
.github/workflows/integration-tests.yml
vendored
Normal file
217
.github/workflows/integration-tests.yml
vendored
Normal file
@ -0,0 +1,217 @@
|
||||
# =============================================================================
|
||||
# Integration Test Gate - Gitgram + AI Time Machine
|
||||
# Can be triggered manually or on push to main. These tests require
|
||||
# database services and validate cross-component interactions.
|
||||
# =============================================================================
|
||||
name: Integration Tests
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
types: [labeled]
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
run_gitgram:
|
||||
description: "Run Gitgram integration tests"
|
||||
type: boolean
|
||||
default: true
|
||||
run_aitm:
|
||||
description: "Run AITM integration tests"
|
||||
type: boolean
|
||||
default: true
|
||||
|
||||
concurrency:
|
||||
group: integration-${{ github.workflow }}-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
env:
|
||||
NODE_VERSION: "20"
|
||||
|
||||
jobs:
|
||||
# ---------------------------------------------------------------------------
|
||||
# Gitgram API - Integration tests
|
||||
# ---------------------------------------------------------------------------
|
||||
gitgram-integration:
|
||||
name: "Gitgram: API Integration Tests"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
if: >-
|
||||
github.event_name == 'workflow_dispatch' && github.event.inputs.run_gitgram == 'true' ||
|
||||
github.event_name == 'push' ||
|
||||
(github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'run-integration'))
|
||||
defaults:
|
||||
run:
|
||||
working-directory: gitgram/backend
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:15
|
||||
env:
|
||||
POSTGRES_USER: gitgram
|
||||
POSTGRES_PASSWORD: gitgram_password
|
||||
POSTGRES_DB: gitgram_test
|
||||
options: >-
|
||||
--health-cmd pg_isready
|
||||
--health-interval 10s
|
||||
--health-timeout 5s
|
||||
--health-retries 5
|
||||
ports:
|
||||
- 5432:5432
|
||||
redis:
|
||||
image: redis:7
|
||||
options: >-
|
||||
--health-cmd "redis-cli ping"
|
||||
--health-interval 10s
|
||||
--health-timeout 5s
|
||||
--health-retries 5
|
||||
ports:
|
||||
- 6379:6379
|
||||
env:
|
||||
DATABASE_URL: postgresql://gitgram:gitgram_password@localhost:5432/gitgram_test?schema=public
|
||||
JWT_SECRET: ci-integration-test-secret
|
||||
NODE_ENV: test
|
||||
REDIS_URL: redis://localhost:6379
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
cache: npm
|
||||
cache-dependency-path: gitgram/backend/package-lock.json
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci --legacy-peer-deps
|
||||
|
||||
- name: Generate Prisma Client
|
||||
run: npx prisma generate
|
||||
|
||||
- name: Run database migrations
|
||||
run: npx prisma migrate deploy
|
||||
|
||||
- name: Run integration tests
|
||||
run: npx jest tests/integration.test.ts --forceExit --detectOpenHandles --testTimeout=30000
|
||||
|
||||
- name: Run API endpoint tests
|
||||
run: |
|
||||
# Run all test files that exercise API endpoints end-to-end
|
||||
npx jest tests/auth.test.ts tests/posts.test.ts tests/users.test.ts tests/webhooks.test.ts \
|
||||
--forceExit --detectOpenHandles --testTimeout=30000
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AITM API - Integration tests
|
||||
# ---------------------------------------------------------------------------
|
||||
aitm-integration:
|
||||
name: "AITM: API Integration Tests"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
if: >-
|
||||
github.event_name == 'workflow_dispatch' && github.event.inputs.run_aitm == 'true' ||
|
||||
github.event_name == 'push' ||
|
||||
(github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'run-integration'))
|
||||
defaults:
|
||||
run:
|
||||
working-directory: aitimemachine/api-server
|
||||
env:
|
||||
NODE_ENV: test
|
||||
AITM_TEST_NO_LISTEN: "0"
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
cache: npm
|
||||
cache-dependency-path: aitimemachine/api-server/package-lock.json
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Run integration tests
|
||||
run: npx vitest run tests/integration --reporter=verbose
|
||||
env:
|
||||
# Integration tests may need these - sourced from secrets in real CI
|
||||
DATABASE_URL: ${{ secrets.AITM_TEST_DATABASE_URL }}
|
||||
JWT_SECRET: ${{ secrets.AITM_TEST_JWT_SECRET }}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AITM Core - E2E / platform tests
|
||||
# ---------------------------------------------------------------------------
|
||||
aitm-core-e2e:
|
||||
name: "AITM: Core E2E Tests"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15
|
||||
if: >-
|
||||
github.event_name == 'workflow_dispatch' && github.event.inputs.run_aitm == 'true' ||
|
||||
github.event_name == 'push' ||
|
||||
(github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'run-integration'))
|
||||
defaults:
|
||||
run:
|
||||
working-directory: aitimemachine
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
cache: npm
|
||||
cache-dependency-path: aitimemachine/package-lock.json
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Build library
|
||||
run: npm run build
|
||||
|
||||
- name: Run E2E and platform tests
|
||||
run: |
|
||||
npx vitest run tests/e2e.test.ts tests/platform.test.ts --reporter=verbose
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Summary gate
|
||||
# ---------------------------------------------------------------------------
|
||||
integration-gate:
|
||||
name: Integration Test Gate
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 2
|
||||
needs:
|
||||
- gitgram-integration
|
||||
- aitm-integration
|
||||
- aitm-core-e2e
|
||||
if: always()
|
||||
steps:
|
||||
- name: Check integration test results
|
||||
run: |
|
||||
FAILED=false
|
||||
|
||||
# Only check jobs that actually ran (skip skipped ones)
|
||||
if [[ "${{ needs.gitgram-integration.result }}" == "failure" ]]; then
|
||||
echo "gitgram-integration FAILED"
|
||||
FAILED=true
|
||||
fi
|
||||
if [[ "${{ needs.aitm-integration.result }}" == "failure" ]]; then
|
||||
echo "aitm-integration FAILED"
|
||||
FAILED=true
|
||||
fi
|
||||
if [[ "${{ needs.aitm-core-e2e.result }}" == "failure" ]]; then
|
||||
echo "aitm-core-e2e FAILED"
|
||||
FAILED=true
|
||||
fi
|
||||
|
||||
if [ "$FAILED" = true ]; then
|
||||
echo ""
|
||||
echo "Integration test gate failed. See individual job logs above."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Integration test gate passed (or jobs were skipped)."
|
||||
echo " gitgram-integration: ${{ needs.gitgram-integration.result }}"
|
||||
echo " aitm-integration: ${{ needs.aitm-integration.result }}"
|
||||
echo " aitm-core-e2e: ${{ needs.aitm-core-e2e.result }}"
|
||||
44
.github/workflows/license-check.yml
vendored
Normal file
44
.github/workflows/license-check.yml
vendored
Normal file
@ -0,0 +1,44 @@
|
||||
name: License Check
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main, develop]
|
||||
pull_request:
|
||||
branches: [main, develop]
|
||||
|
||||
jobs:
|
||||
license-check:
|
||||
name: Block GPL / noncommercial imports in product trees
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Check for GPL-contaminated imports (proximity)
|
||||
run: |
|
||||
# proximity is GPL-3 — its source must never be imported into product trees
|
||||
if grep -rE "from ['\"].*external/proximity" \
|
||||
gitgram/ aitimemachine/ --include="*.ts" --include="*.tsx" -l 2>/dev/null; then
|
||||
echo "ERROR: GPL-3 source from external/proximity imported into product tree"
|
||||
exit 1
|
||||
fi
|
||||
echo "OK: no proximity (GPL-3) imports found"
|
||||
|
||||
- name: Check for PolyForm Noncommercial imports (gitnexus)
|
||||
run: |
|
||||
# gitnexus is PolyForm Noncommercial — source must not be copied into product trees
|
||||
if grep -rE "from ['\"].*external/gitnexus" \
|
||||
gitgram/ aitimemachine/ --include="*.ts" --include="*.tsx" -l 2>/dev/null; then
|
||||
echo "ERROR: PolyForm Noncommercial source from external/gitnexus imported into product tree"
|
||||
exit 1
|
||||
fi
|
||||
echo "OK: no gitnexus (PolyForm Noncommercial) imports found"
|
||||
|
||||
- name: Check external/ is not on tsconfig paths
|
||||
run: |
|
||||
# Verify no tsconfig in product dirs resolves paths into external/
|
||||
if grep -rE '"external/' \
|
||||
gitgram/tsconfig*.json aitimemachine/tsconfig*.json 2>/dev/null; then
|
||||
echo "ERROR: tsconfig path alias points into external/"
|
||||
exit 1
|
||||
fi
|
||||
echo "OK: no tsconfig paths into external/"
|
||||
206
.github/workflows/migrations.yml
vendored
Normal file
206
.github/workflows/migrations.yml
vendored
Normal file
@ -0,0 +1,206 @@
|
||||
# =============================================================================
|
||||
# Migration Gate - Gitgram (Prisma) + AI Time Machine (Drizzle)
|
||||
# Validates ORM schemas and checks for pending migrations.
|
||||
# =============================================================================
|
||||
name: Migration Gate
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main, develop]
|
||||
paths:
|
||||
- "gitgram/backend/prisma/**"
|
||||
- "aitimemachine/api-server/src/db/schema.ts"
|
||||
- "aitimemachine/api-server/drizzle/**"
|
||||
- "aitimemachine/src/core/neon/schema.ts"
|
||||
- "aitimemachine/drizzle/**"
|
||||
- "aitimemachine/drizzle.config.ts"
|
||||
- "aitimemachine/api-server/drizzle.config.ts"
|
||||
pull_request:
|
||||
branches: [main, develop]
|
||||
paths:
|
||||
- "gitgram/backend/prisma/**"
|
||||
- "aitimemachine/api-server/src/db/schema.ts"
|
||||
- "aitimemachine/api-server/drizzle/**"
|
||||
- "aitimemachine/src/core/neon/schema.ts"
|
||||
- "aitimemachine/drizzle/**"
|
||||
- "aitimemachine/drizzle.config.ts"
|
||||
- "aitimemachine/api-server/drizzle.config.ts"
|
||||
|
||||
concurrency:
|
||||
group: migrations-${{ github.workflow }}-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
env:
|
||||
NODE_VERSION: "20"
|
||||
|
||||
jobs:
|
||||
# ---------------------------------------------------------------------------
|
||||
# Gitgram - Prisma schema validation
|
||||
# ---------------------------------------------------------------------------
|
||||
gitgram-prisma-validate:
|
||||
name: "Gitgram: Prisma Schema Validation"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 8
|
||||
defaults:
|
||||
run:
|
||||
working-directory: gitgram/backend
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:15
|
||||
env:
|
||||
POSTGRES_USER: gitgram
|
||||
POSTGRES_PASSWORD: gitgram_password
|
||||
POSTGRES_DB: gitgram_test
|
||||
options: >-
|
||||
--health-cmd pg_isready
|
||||
--health-interval 10s
|
||||
--health-timeout 5s
|
||||
--health-retries 5
|
||||
ports:
|
||||
- 5432:5432
|
||||
env:
|
||||
DATABASE_URL: postgresql://gitgram:gitgram_password@localhost:5432/gitgram_test?schema=public
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
cache: npm
|
||||
cache-dependency-path: gitgram/backend/package-lock.json
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci --legacy-peer-deps
|
||||
|
||||
- name: Validate Prisma schema
|
||||
run: npx prisma validate
|
||||
|
||||
- name: Generate Prisma Client
|
||||
run: npx prisma generate
|
||||
|
||||
- name: Check migration status (dry run)
|
||||
run: npx prisma migrate deploy
|
||||
continue-on-error: false
|
||||
|
||||
- name: Verify no pending migrations
|
||||
run: |
|
||||
# After deploy, diff should be empty against the current schema
|
||||
npx prisma migrate diff \
|
||||
--from-migrations ./prisma/migrations \
|
||||
--to-schema-datamodel ./prisma/schema.prisma \
|
||||
--exit-code || {
|
||||
echo "WARNING: There are pending schema changes not covered by migrations."
|
||||
echo "Run 'npx prisma migrate dev' locally to generate the migration."
|
||||
exit 1
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AITM API Server - Drizzle schema validation
|
||||
# ---------------------------------------------------------------------------
|
||||
aitm-drizzle-validate:
|
||||
name: "AITM: Drizzle Schema Validation (API Server)"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 8
|
||||
defaults:
|
||||
run:
|
||||
working-directory: aitimemachine/api-server
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
cache: npm
|
||||
cache-dependency-path: aitimemachine/api-server/package-lock.json
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: TypeScript check on schema files
|
||||
run: npx tsc --noEmit
|
||||
|
||||
- name: Validate Drizzle config loads
|
||||
run: |
|
||||
# Ensure drizzle config is parseable (exits 0 if valid)
|
||||
npx drizzle-kit check 2>&1 || echo "drizzle-kit check completed"
|
||||
|
||||
- name: Verify migration files exist and are ordered
|
||||
run: |
|
||||
MIGRATION_DIR="./drizzle"
|
||||
if [ -d "$MIGRATION_DIR" ]; then
|
||||
echo "Migration directory found. Contents:"
|
||||
ls -la "$MIGRATION_DIR"/*.sql 2>/dev/null || echo "No SQL migration files found."
|
||||
|
||||
# Check journal integrity
|
||||
if [ -f "$MIGRATION_DIR/meta/_journal.json" ]; then
|
||||
echo "Migration journal found."
|
||||
node -e "
|
||||
const j = require('$MIGRATION_DIR/meta/_journal.json');
|
||||
console.log('Total migrations:', j.entries.length);
|
||||
j.entries.forEach(e => console.log(' -', e.idx, e.tag));
|
||||
" 2>/dev/null || echo "Journal parsing skipped (ESM)."
|
||||
fi
|
||||
else
|
||||
echo "No migration directory. Skipping migration file check."
|
||||
fi
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AITM Core - Drizzle schema validation
|
||||
# ---------------------------------------------------------------------------
|
||||
aitm-core-drizzle-validate:
|
||||
name: "AITM: Drizzle Schema Validation (Core)"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 8
|
||||
defaults:
|
||||
run:
|
||||
working-directory: aitimemachine
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
cache: npm
|
||||
cache-dependency-path: aitimemachine/package-lock.json
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: TypeScript check on schema files
|
||||
run: npx tsc --noEmit
|
||||
|
||||
- name: Validate Drizzle config loads
|
||||
run: |
|
||||
npx drizzle-kit check 2>&1 || echo "drizzle-kit check completed"
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Summary gate
|
||||
# ---------------------------------------------------------------------------
|
||||
migration-gate:
|
||||
name: Migration Gate (all products)
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 2
|
||||
needs:
|
||||
- gitgram-prisma-validate
|
||||
- aitm-drizzle-validate
|
||||
- aitm-core-drizzle-validate
|
||||
if: always()
|
||||
steps:
|
||||
- name: Check migration results
|
||||
run: |
|
||||
if [[ "${{ needs.gitgram-prisma-validate.result }}" != "success" ]] || \
|
||||
[[ "${{ needs.aitm-drizzle-validate.result }}" != "success" ]] || \
|
||||
[[ "${{ needs.aitm-core-drizzle-validate.result }}" != "success" ]]; then
|
||||
echo "One or more migration validation jobs failed."
|
||||
echo " gitgram-prisma-validate: ${{ needs.gitgram-prisma-validate.result }}"
|
||||
echo " aitm-drizzle-validate: ${{ needs.aitm-drizzle-validate.result }}"
|
||||
echo " aitm-core-drizzle-validate: ${{ needs.aitm-core-drizzle-validate.result }}"
|
||||
exit 1
|
||||
fi
|
||||
echo "All migration gates passed."
|
||||
130
.github/workflows/openapi-validation.yml
vendored
Normal file
130
.github/workflows/openapi-validation.yml
vendored
Normal file
@ -0,0 +1,130 @@
|
||||
# =============================================================================
|
||||
# OpenAPI Contract Validation
|
||||
# Validates OpenAPI specs and checks route coverage for both products.
|
||||
# Runs on PR/push to main when API files change.
|
||||
# =============================================================================
|
||||
name: OpenAPI Validation
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main, develop]
|
||||
paths:
|
||||
- "aitimemachine/api-server/src/routes/**"
|
||||
- "aitimemachine/api-server/src/index.ts"
|
||||
- "aitimemachine/api-server/docs/openapi.yaml"
|
||||
- "gitgram/backend/src/routes/**"
|
||||
- "gitgram/backend/src/index.ts"
|
||||
- "gitgram/backend/docs/openapi.yaml"
|
||||
- "scripts/validate-openapi-*.ts"
|
||||
- ".github/workflows/openapi-validation.yml"
|
||||
pull_request:
|
||||
branches: [main, develop]
|
||||
paths:
|
||||
- "aitimemachine/api-server/src/routes/**"
|
||||
- "aitimemachine/api-server/src/index.ts"
|
||||
- "aitimemachine/api-server/docs/openapi.yaml"
|
||||
- "gitgram/backend/src/routes/**"
|
||||
- "gitgram/backend/src/index.ts"
|
||||
- "gitgram/backend/docs/openapi.yaml"
|
||||
- "scripts/validate-openapi-*.ts"
|
||||
- ".github/workflows/openapi-validation.yml"
|
||||
|
||||
concurrency:
|
||||
group: openapi-${{ github.workflow }}-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
env:
|
||||
NODE_VERSION: "20"
|
||||
|
||||
jobs:
|
||||
# ---------------------------------------------------------------------------
|
||||
# Step 1: Validate OpenAPI spec syntax and structure
|
||||
# ---------------------------------------------------------------------------
|
||||
validate-spec:
|
||||
name: "Validate OpenAPI Specs"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 5
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
|
||||
- name: Install tsx (TypeScript runner)
|
||||
run: npm install -g tsx
|
||||
|
||||
- name: Validate OpenAPI spec structure
|
||||
run: npx tsx scripts/validate-openapi-spec.ts
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Step 2: Check route coverage (code vs spec)
|
||||
# ---------------------------------------------------------------------------
|
||||
route-coverage:
|
||||
name: "Route Coverage Check"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 5
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
|
||||
- name: Install tsx (TypeScript runner)
|
||||
run: npm install -g tsx
|
||||
|
||||
- name: Run route coverage validation
|
||||
run: npx tsx scripts/validate-openapi-routes.ts
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Step 3: Generate API documentation artifact
|
||||
# ---------------------------------------------------------------------------
|
||||
generate-docs:
|
||||
name: "Generate API Docs Artifact"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 5
|
||||
needs: [validate-spec]
|
||||
if: github.event_name == 'pull_request'
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Upload AITM OpenAPI spec
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: aitm-openapi-spec
|
||||
path: aitimemachine/api-server/docs/openapi.yaml
|
||||
retention-days: 30
|
||||
|
||||
- name: Upload Gitgram OpenAPI spec
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: gitgram-openapi-spec
|
||||
path: gitgram/backend/docs/openapi.yaml
|
||||
retention-days: 30
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Summary gate
|
||||
# ---------------------------------------------------------------------------
|
||||
openapi-gate:
|
||||
name: "OpenAPI Validation Gate"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 2
|
||||
needs: [validate-spec, route-coverage]
|
||||
if: always()
|
||||
steps:
|
||||
- name: Check validation results
|
||||
run: |
|
||||
if [[ "${{ needs.validate-spec.result }}" != "success" ]] || \
|
||||
[[ "${{ needs.route-coverage.result }}" != "success" ]]; then
|
||||
echo "OpenAPI validation failed."
|
||||
echo " validate-spec: ${{ needs.validate-spec.result }}"
|
||||
echo " route-coverage: ${{ needs.route-coverage.result }}"
|
||||
exit 1
|
||||
fi
|
||||
echo "All OpenAPI validation checks passed."
|
||||
240
.github/workflows/smoke-tests.yml
vendored
Normal file
240
.github/workflows/smoke-tests.yml
vendored
Normal file
@ -0,0 +1,240 @@
|
||||
# =============================================================================
|
||||
# Smoke Test Gate - Post-deploy health checks for Gitgram + AI Time Machine
|
||||
# Validates that deployed services are alive and responding correctly.
|
||||
# Triggered after deploy workflows or manually with environment URLs.
|
||||
# =============================================================================
|
||||
name: Smoke Tests (Post-Deploy)
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
environment:
|
||||
description: "Target environment"
|
||||
type: choice
|
||||
options:
|
||||
- staging
|
||||
- production
|
||||
default: staging
|
||||
gitgram_api_url:
|
||||
description: "Gitgram API base URL (e.g. https://api.gitgram.dev)"
|
||||
type: string
|
||||
required: false
|
||||
aitm_api_url:
|
||||
description: "AITM API base URL (e.g. https://api.aitimemachine.dev)"
|
||||
type: string
|
||||
required: false
|
||||
workflow_call:
|
||||
inputs:
|
||||
environment:
|
||||
type: string
|
||||
required: true
|
||||
gitgram_api_url:
|
||||
type: string
|
||||
required: false
|
||||
aitm_api_url:
|
||||
type: string
|
||||
required: false
|
||||
|
||||
env:
|
||||
NODE_VERSION: "20"
|
||||
|
||||
jobs:
|
||||
# ---------------------------------------------------------------------------
|
||||
# Gitgram API - Health & smoke checks
|
||||
# ---------------------------------------------------------------------------
|
||||
gitgram-smoke:
|
||||
name: "Gitgram: Smoke Tests (${{ inputs.environment }})"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 5
|
||||
env:
|
||||
API_URL: ${{ inputs.gitgram_api_url || vars.GITGRAM_API_URL || 'http://localhost:3001' }}
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Wait for service readiness
|
||||
run: |
|
||||
echo "Waiting for Gitgram API at $API_URL to become ready..."
|
||||
for i in $(seq 1 30); do
|
||||
if curl -sf "$API_URL/health" > /dev/null 2>&1 || \
|
||||
curl -sf "$API_URL/api/health" > /dev/null 2>&1; then
|
||||
echo "Service is ready after ${i}s"
|
||||
break
|
||||
fi
|
||||
echo "Attempt $i/30 - not ready yet..."
|
||||
sleep 2
|
||||
done
|
||||
|
||||
- name: Health check endpoint
|
||||
run: |
|
||||
echo "### Gitgram API Health Check" >> $GITHUB_STEP_SUMMARY
|
||||
RESPONSE=$(curl -sf -w "\nHTTP_CODE:%{http_code}" "$API_URL/health" 2>/dev/null || \
|
||||
curl -sf -w "\nHTTP_CODE:%{http_code}" "$API_URL/api/health" 2>/dev/null || \
|
||||
echo "FAILED")
|
||||
|
||||
if echo "$RESPONSE" | grep -q "FAILED"; then
|
||||
echo "Health check failed. Service may not be running at $API_URL"
|
||||
echo "Status: FAILED" >> $GITHUB_STEP_SUMMARY
|
||||
exit 1
|
||||
fi
|
||||
|
||||
HTTP_CODE=$(echo "$RESPONSE" | grep "HTTP_CODE:" | cut -d: -f2)
|
||||
BODY=$(echo "$RESPONSE" | grep -v "HTTP_CODE:")
|
||||
|
||||
echo "HTTP Status: $HTTP_CODE"
|
||||
echo "Response: $BODY"
|
||||
echo "- HTTP Status: $HTTP_CODE" >> $GITHUB_STEP_SUMMARY
|
||||
echo "- Response: \`$BODY\`" >> $GITHUB_STEP_SUMMARY
|
||||
|
||||
if [ "$HTTP_CODE" != "200" ]; then
|
||||
echo "Unexpected HTTP status code: $HTTP_CODE"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
- name: API response validation
|
||||
run: |
|
||||
echo "Validating basic API endpoints..."
|
||||
|
||||
# Test that auth endpoints exist and return proper error codes (not 500)
|
||||
AUTH_CODE=$(curl -sf -o /dev/null -w "%{http_code}" "$API_URL/api/auth/login" -X POST \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{}' 2>/dev/null || echo "000")
|
||||
echo "POST /api/auth/login (empty body): HTTP $AUTH_CODE"
|
||||
if [ "$AUTH_CODE" = "500" ] || [ "$AUTH_CODE" = "000" ]; then
|
||||
echo "Auth endpoint returned server error or is unreachable"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Test that public endpoints return structured responses
|
||||
USERS_CODE=$(curl -sf -o /dev/null -w "%{http_code}" "$API_URL/api/users" 2>/dev/null || echo "000")
|
||||
echo "GET /api/users: HTTP $USERS_CODE"
|
||||
if [ "$USERS_CODE" = "500" ]; then
|
||||
echo "Users endpoint returned server error"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Gitgram API smoke tests passed."
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AITM API - Health & smoke checks
|
||||
# ---------------------------------------------------------------------------
|
||||
aitm-smoke:
|
||||
name: "AITM: Smoke Tests (${{ inputs.environment }})"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 5
|
||||
env:
|
||||
API_URL: ${{ inputs.aitm_api_url || vars.AITM_API_URL || 'http://localhost:3000' }}
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Wait for service readiness
|
||||
run: |
|
||||
echo "Waiting for AITM API at $API_URL to become ready..."
|
||||
for i in $(seq 1 30); do
|
||||
if curl -sf "$API_URL/health" > /dev/null 2>&1 || \
|
||||
curl -sf "$API_URL/api/health" > /dev/null 2>&1; then
|
||||
echo "Service is ready after ${i}s"
|
||||
break
|
||||
fi
|
||||
echo "Attempt $i/30 - not ready yet..."
|
||||
sleep 2
|
||||
done
|
||||
|
||||
- name: Health check endpoint
|
||||
run: |
|
||||
echo "### AITM API Health Check" >> $GITHUB_STEP_SUMMARY
|
||||
RESPONSE=$(curl -sf -w "\nHTTP_CODE:%{http_code}" "$API_URL/health" 2>/dev/null || \
|
||||
curl -sf -w "\nHTTP_CODE:%{http_code}" "$API_URL/api/health" 2>/dev/null || \
|
||||
echo "FAILED")
|
||||
|
||||
if echo "$RESPONSE" | grep -q "FAILED"; then
|
||||
echo "Health check failed. Service may not be running at $API_URL"
|
||||
echo "Status: FAILED" >> $GITHUB_STEP_SUMMARY
|
||||
exit 1
|
||||
fi
|
||||
|
||||
HTTP_CODE=$(echo "$RESPONSE" | grep "HTTP_CODE:" | cut -d: -f2)
|
||||
BODY=$(echo "$RESPONSE" | grep -v "HTTP_CODE:")
|
||||
|
||||
echo "HTTP Status: $HTTP_CODE"
|
||||
echo "Response: $BODY"
|
||||
echo "- HTTP Status: $HTTP_CODE" >> $GITHUB_STEP_SUMMARY
|
||||
echo "- Response: \`$BODY\`" >> $GITHUB_STEP_SUMMARY
|
||||
|
||||
if [ "$HTTP_CODE" != "200" ]; then
|
||||
echo "Unexpected HTTP status code: $HTTP_CODE"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
- name: API response validation
|
||||
run: |
|
||||
echo "Validating AITM API endpoints..."
|
||||
|
||||
# Verify sessions endpoint exists
|
||||
SESSIONS_CODE=$(curl -sf -o /dev/null -w "%{http_code}" "$API_URL/api/sessions" 2>/dev/null || echo "000")
|
||||
echo "GET /api/sessions: HTTP $SESSIONS_CODE"
|
||||
# Expect 401 (unauthorized) or 200, not 500
|
||||
if [ "$SESSIONS_CODE" = "500" ] || [ "$SESSIONS_CODE" = "000" ]; then
|
||||
echo "Sessions endpoint returned server error or is unreachable"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Verify sync endpoint exists
|
||||
SYNC_CODE=$(curl -sf -o /dev/null -w "%{http_code}" "$API_URL/api/sync" -X POST \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{}' 2>/dev/null || echo "000")
|
||||
echo "POST /api/sync: HTTP $SYNC_CODE"
|
||||
if [ "$SYNC_CODE" = "500" ]; then
|
||||
echo "Sync endpoint returned server error"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Verify keys/auth endpoint exists
|
||||
KEYS_CODE=$(curl -sf -o /dev/null -w "%{http_code}" "$API_URL/api/keys" 2>/dev/null || echo "000")
|
||||
echo "GET /api/keys: HTTP $KEYS_CODE"
|
||||
if [ "$KEYS_CODE" = "500" ]; then
|
||||
echo "Keys endpoint returned server error"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "AITM API smoke tests passed."
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Summary
|
||||
# ---------------------------------------------------------------------------
|
||||
smoke-gate:
|
||||
name: Smoke Test Gate (${{ inputs.environment }})
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 2
|
||||
needs:
|
||||
- gitgram-smoke
|
||||
- aitm-smoke
|
||||
if: always()
|
||||
steps:
|
||||
- name: Check smoke test results
|
||||
run: |
|
||||
echo "### Smoke Test Summary (${{ inputs.environment }})" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "| Service | Result |" >> $GITHUB_STEP_SUMMARY
|
||||
echo "|---------|--------|" >> $GITHUB_STEP_SUMMARY
|
||||
echo "| Gitgram API | ${{ needs.gitgram-smoke.result }} |" >> $GITHUB_STEP_SUMMARY
|
||||
echo "| AITM API | ${{ needs.aitm-smoke.result }} |" >> $GITHUB_STEP_SUMMARY
|
||||
|
||||
FAILED=false
|
||||
if [[ "${{ needs.gitgram-smoke.result }}" == "failure" ]]; then
|
||||
echo "Gitgram smoke tests FAILED"
|
||||
FAILED=true
|
||||
fi
|
||||
if [[ "${{ needs.aitm-smoke.result }}" == "failure" ]]; then
|
||||
echo "AITM smoke tests FAILED"
|
||||
FAILED=true
|
||||
fi
|
||||
|
||||
if [ "$FAILED" = true ]; then
|
||||
echo ""
|
||||
echo "Smoke test gate FAILED. Check deployed services."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "All smoke tests passed for ${{ inputs.environment }}."
|
||||
193
.github/workflows/tests.yml
vendored
Normal file
193
.github/workflows/tests.yml
vendored
Normal file
@ -0,0 +1,193 @@
|
||||
# =============================================================================
|
||||
# Test Gate - Gitgram (Jest) + AI Time Machine (Vitest)
|
||||
# Runs unit tests for both products and collects coverage reports.
|
||||
# =============================================================================
|
||||
name: Test Gate
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main, develop]
|
||||
pull_request:
|
||||
branches: [main, develop]
|
||||
|
||||
concurrency:
|
||||
group: tests-${{ github.workflow }}-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
env:
|
||||
NODE_VERSION: "20"
|
||||
|
||||
jobs:
|
||||
# ---------------------------------------------------------------------------
|
||||
# Gitgram Backend - Jest unit tests
|
||||
# ---------------------------------------------------------------------------
|
||||
gitgram-backend-tests:
|
||||
name: "Gitgram: Backend Tests (Jest)"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15
|
||||
defaults:
|
||||
run:
|
||||
working-directory: gitgram/backend
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:15
|
||||
env:
|
||||
POSTGRES_USER: gitgram
|
||||
POSTGRES_PASSWORD: gitgram_password
|
||||
POSTGRES_DB: gitgram_test
|
||||
options: >-
|
||||
--health-cmd pg_isready
|
||||
--health-interval 10s
|
||||
--health-timeout 5s
|
||||
--health-retries 5
|
||||
ports:
|
||||
- 5432:5432
|
||||
env:
|
||||
DATABASE_URL: postgresql://gitgram:gitgram_password@localhost:5432/gitgram_test?schema=public
|
||||
JWT_SECRET: ci-test-secret-key
|
||||
NODE_ENV: test
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
cache: npm
|
||||
cache-dependency-path: gitgram/backend/package-lock.json
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci --legacy-peer-deps
|
||||
|
||||
- name: Generate Prisma Client
|
||||
run: npx prisma generate
|
||||
|
||||
- name: Run database migrations
|
||||
run: npx prisma migrate deploy
|
||||
|
||||
- name: Run unit tests with coverage
|
||||
run: npm run test:coverage
|
||||
|
||||
- name: Upload coverage report
|
||||
uses: actions/upload-artifact@v4
|
||||
if: always()
|
||||
with:
|
||||
name: gitgram-backend-coverage
|
||||
path: gitgram/backend/coverage
|
||||
retention-days: 7
|
||||
|
||||
- name: Coverage summary
|
||||
if: always()
|
||||
run: |
|
||||
if [ -f coverage/coverage-summary.json ]; then
|
||||
echo "### Gitgram Backend Coverage" >> $GITHUB_STEP_SUMMARY
|
||||
node -e "
|
||||
const s = require('./coverage/coverage-summary.json').total;
|
||||
console.log('| Metric | Coverage |');
|
||||
console.log('|--------|----------|');
|
||||
console.log('| Statements |', s.statements.pct + '%', '|');
|
||||
console.log('| Branches |', s.branches.pct + '%', '|');
|
||||
console.log('| Functions |', s.functions.pct + '%', '|');
|
||||
console.log('| Lines |', s.lines.pct + '%', '|');
|
||||
" >> $GITHUB_STEP_SUMMARY 2>/dev/null || echo "Coverage summary unavailable."
|
||||
fi
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AITM Core - Vitest unit tests
|
||||
# ---------------------------------------------------------------------------
|
||||
aitm-core-tests:
|
||||
name: "AITM: Core Tests (Vitest)"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15
|
||||
defaults:
|
||||
run:
|
||||
working-directory: aitimemachine
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
cache: npm
|
||||
cache-dependency-path: aitimemachine/package-lock.json
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Run tests with coverage
|
||||
run: npx vitest run --coverage
|
||||
|
||||
- name: Upload coverage report
|
||||
uses: actions/upload-artifact@v4
|
||||
if: always()
|
||||
with:
|
||||
name: aitm-core-coverage
|
||||
path: aitimemachine/coverage
|
||||
retention-days: 7
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AITM API Server - Vitest unit tests
|
||||
# ---------------------------------------------------------------------------
|
||||
aitm-api-tests:
|
||||
name: "AITM: API Server Tests (Vitest)"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15
|
||||
defaults:
|
||||
run:
|
||||
working-directory: aitimemachine/api-server
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
cache: npm
|
||||
cache-dependency-path: aitimemachine/api-server/package-lock.json
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Run tests
|
||||
run: npm test
|
||||
env:
|
||||
NODE_ENV: test
|
||||
|
||||
- name: Upload test results
|
||||
uses: actions/upload-artifact@v4
|
||||
if: always()
|
||||
with:
|
||||
name: aitm-api-test-results
|
||||
path: aitimemachine/api-server/coverage
|
||||
retention-days: 7
|
||||
if-no-files-found: ignore
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Summary gate - all tests must pass
|
||||
# ---------------------------------------------------------------------------
|
||||
test-gate:
|
||||
name: Test Gate (all products)
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 2
|
||||
needs:
|
||||
- gitgram-backend-tests
|
||||
- aitm-core-tests
|
||||
- aitm-api-tests
|
||||
if: always()
|
||||
steps:
|
||||
- name: Check test results
|
||||
run: |
|
||||
if [[ "${{ needs.gitgram-backend-tests.result }}" != "success" ]] || \
|
||||
[[ "${{ needs.aitm-core-tests.result }}" != "success" ]] || \
|
||||
[[ "${{ needs.aitm-api-tests.result }}" != "success" ]]; then
|
||||
echo "One or more test jobs failed."
|
||||
echo " gitgram-backend-tests: ${{ needs.gitgram-backend-tests.result }}"
|
||||
echo " aitm-core-tests: ${{ needs.aitm-core-tests.result }}"
|
||||
echo " aitm-api-tests: ${{ needs.aitm-api-tests.result }}"
|
||||
exit 1
|
||||
fi
|
||||
echo "All test gates passed."
|
||||
214
.github/workflows/verify-production-db.yml
vendored
Normal file
214
.github/workflows/verify-production-db.yml
vendored
Normal file
@ -0,0 +1,214 @@
|
||||
name: Verify Production Databases
|
||||
|
||||
on:
|
||||
schedule:
|
||||
# Run daily at 06:00 UTC
|
||||
- cron: "0 6 * * *"
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
target:
|
||||
description: "Which database to verify"
|
||||
required: false
|
||||
default: "all"
|
||||
type: choice
|
||||
options:
|
||||
- all
|
||||
- neon
|
||||
- gitgram
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
env:
|
||||
NODE_VERSION: "20"
|
||||
|
||||
jobs:
|
||||
# ===========================================================================
|
||||
# Neon (AITimeMachine) Database Verification
|
||||
# ===========================================================================
|
||||
verify-neon:
|
||||
name: Verify Neon DB (AITimeMachine)
|
||||
runs-on: ubuntu-latest
|
||||
if: ${{ github.event_name == 'schedule' || github.event.inputs.target == 'all' || github.event.inputs.target == 'neon' }}
|
||||
timeout-minutes: 10
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
cache: npm
|
||||
cache-dependency-path: aitimemachine/api-server/package-lock.json
|
||||
|
||||
- name: Install dependencies
|
||||
working-directory: aitimemachine/api-server
|
||||
run: npm ci
|
||||
|
||||
- name: Run Neon verification
|
||||
working-directory: aitimemachine/api-server
|
||||
env:
|
||||
DATABASE_URL: ${{ secrets.NEON_DATABASE_URL }}
|
||||
run: npx tsx ../../scripts/verify-neon.ts --json > /tmp/neon-results.json 2>&1 || true
|
||||
|
||||
- name: Parse results
|
||||
id: neon-results
|
||||
run: |
|
||||
if [ -f /tmp/neon-results.json ]; then
|
||||
overall=$(cat /tmp/neon-results.json | python3 -c "import sys,json; data=json.load(sys.stdin); print(data.get('overall','unknown'))" 2>/dev/null || echo "unknown")
|
||||
echo "overall=$overall" >> $GITHUB_OUTPUT
|
||||
cat /tmp/neon-results.json
|
||||
else
|
||||
echo "overall=error" >> $GITHUB_OUTPUT
|
||||
echo "No results file generated"
|
||||
fi
|
||||
|
||||
- name: Upload results artifact
|
||||
uses: actions/upload-artifact@v4
|
||||
if: always()
|
||||
with:
|
||||
name: neon-verification-results
|
||||
path: /tmp/neon-results.json
|
||||
retention-days: 30
|
||||
|
||||
- name: Check for failures
|
||||
if: steps.neon-results.outputs.overall == 'unhealthy'
|
||||
run: |
|
||||
echo "::error::Neon database verification FAILED"
|
||||
echo "Check the neon-verification-results artifact for details."
|
||||
exit 1
|
||||
|
||||
- name: Report degraded status
|
||||
if: steps.neon-results.outputs.overall == 'degraded'
|
||||
run: |
|
||||
echo "::warning::Neon database verification has WARNINGS"
|
||||
echo "Check the neon-verification-results artifact for details."
|
||||
|
||||
# ===========================================================================
|
||||
# Gitgram Backend Database Verification
|
||||
# ===========================================================================
|
||||
verify-gitgram:
|
||||
name: Verify Gitgram DB
|
||||
runs-on: ubuntu-latest
|
||||
if: ${{ github.event_name == 'schedule' || github.event.inputs.target == 'all' || github.event.inputs.target == 'gitgram' }}
|
||||
timeout-minutes: 10
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
cache: npm
|
||||
cache-dependency-path: gitgram/backend/package-lock.json
|
||||
|
||||
- name: Install dependencies
|
||||
working-directory: gitgram/backend
|
||||
run: npm ci
|
||||
|
||||
- name: Generate Prisma Client
|
||||
working-directory: gitgram/backend
|
||||
run: npx prisma generate
|
||||
|
||||
- name: Run Gitgram DB verification
|
||||
working-directory: gitgram/backend
|
||||
env:
|
||||
DATABASE_URL: ${{ secrets.GITGRAM_DATABASE_URL }}
|
||||
run: npx tsx ../../scripts/verify-gitgram-db.ts --json > /tmp/gitgram-results.json 2>&1 || true
|
||||
|
||||
- name: Parse results
|
||||
id: gitgram-results
|
||||
run: |
|
||||
if [ -f /tmp/gitgram-results.json ]; then
|
||||
overall=$(cat /tmp/gitgram-results.json | python3 -c "import sys,json; data=json.load(sys.stdin); print(data.get('overall','unknown'))" 2>/dev/null || echo "unknown")
|
||||
echo "overall=$overall" >> $GITHUB_OUTPUT
|
||||
cat /tmp/gitgram-results.json
|
||||
else
|
||||
echo "overall=error" >> $GITHUB_OUTPUT
|
||||
echo "No results file generated"
|
||||
fi
|
||||
|
||||
- name: Upload results artifact
|
||||
uses: actions/upload-artifact@v4
|
||||
if: always()
|
||||
with:
|
||||
name: gitgram-verification-results
|
||||
path: /tmp/gitgram-results.json
|
||||
retention-days: 30
|
||||
|
||||
- name: Check for failures
|
||||
if: steps.gitgram-results.outputs.overall == 'unhealthy'
|
||||
run: |
|
||||
echo "::error::Gitgram database verification FAILED"
|
||||
echo "Check the gitgram-verification-results artifact for details."
|
||||
exit 1
|
||||
|
||||
- name: Report degraded status
|
||||
if: steps.gitgram-results.outputs.overall == 'degraded'
|
||||
run: |
|
||||
echo "::warning::Gitgram database verification has WARNINGS"
|
||||
echo "Check the gitgram-verification-results artifact for details."
|
||||
|
||||
# ===========================================================================
|
||||
# Summary notification (runs after both jobs complete)
|
||||
# ===========================================================================
|
||||
notify:
|
||||
name: Verification Summary
|
||||
runs-on: ubuntu-latest
|
||||
needs: [verify-neon, verify-gitgram]
|
||||
if: always()
|
||||
|
||||
steps:
|
||||
- name: Download Neon results
|
||||
uses: actions/download-artifact@v4
|
||||
with:
|
||||
name: neon-verification-results
|
||||
path: /tmp/neon
|
||||
continue-on-error: true
|
||||
|
||||
- name: Download Gitgram results
|
||||
uses: actions/download-artifact@v4
|
||||
with:
|
||||
name: gitgram-verification-results
|
||||
path: /tmp/gitgram
|
||||
continue-on-error: true
|
||||
|
||||
- name: Generate summary
|
||||
run: |
|
||||
echo "## Database Verification Summary" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "| Database | Status | Details |" >> $GITHUB_STEP_SUMMARY
|
||||
echo "|----------|--------|---------|" >> $GITHUB_STEP_SUMMARY
|
||||
|
||||
# Neon results
|
||||
if [ -f /tmp/neon/neon-results.json ]; then
|
||||
neon_status=$(python3 -c "import json; data=json.load(open('/tmp/neon/neon-results.json')); print(data.get('overall','unknown'))" 2>/dev/null || echo "error")
|
||||
neon_summary=$(python3 -c "import json; data=json.load(open('/tmp/neon/neon-results.json')); s=data.get('summary',{}); print(f\"P:{s.get('passed',0)} W:{s.get('warned',0)} F:{s.get('failed',0)}\")" 2>/dev/null || echo "N/A")
|
||||
else
|
||||
neon_status="${{ needs.verify-neon.result }}"
|
||||
neon_summary="Job result: ${neon_status}"
|
||||
fi
|
||||
|
||||
# Gitgram results
|
||||
if [ -f /tmp/gitgram/gitgram-results.json ]; then
|
||||
gitgram_status=$(python3 -c "import json; data=json.load(open('/tmp/gitgram/gitgram-results.json')); print(data.get('overall','unknown'))" 2>/dev/null || echo "error")
|
||||
gitgram_summary=$(python3 -c "import json; data=json.load(open('/tmp/gitgram/gitgram-results.json')); s=data.get('summary',{}); print(f\"P:{s.get('passed',0)} W:{s.get('warned',0)} F:{s.get('failed',0)}\")" 2>/dev/null || echo "N/A")
|
||||
else
|
||||
gitgram_status="${{ needs.verify-gitgram.result }}"
|
||||
gitgram_summary="Job result: ${gitgram_status}"
|
||||
fi
|
||||
|
||||
echo "| Neon (AITimeMachine) | ${neon_status} | ${neon_summary} |" >> $GITHUB_STEP_SUMMARY
|
||||
echo "| Gitgram Backend | ${gitgram_status} | ${gitgram_summary} |" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "_Run at: $(date -u +"%Y-%m-%d %H:%M:%S UTC")_" >> $GITHUB_STEP_SUMMARY
|
||||
|
||||
- name: Fail if any verification failed
|
||||
if: needs.verify-neon.result == 'failure' || needs.verify-gitgram.result == 'failure'
|
||||
run: |
|
||||
echo "::error::One or more database verifications failed. Check individual job logs."
|
||||
exit 1
|
||||
64
.gitignore
vendored
Normal file
64
.gitignore
vendored
Normal file
@ -0,0 +1,64 @@
|
||||
# Dependencies
|
||||
node_modules/
|
||||
|
||||
# Build outputs
|
||||
dist/
|
||||
build/
|
||||
lib/
|
||||
.next/
|
||||
out/
|
||||
.expo/
|
||||
.expo-shared/
|
||||
web-build/
|
||||
|
||||
# Logs and runtime output
|
||||
logs/
|
||||
*.log
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
lerna-debug.log*
|
||||
pm2.log
|
||||
|
||||
# Environment and secrets
|
||||
.env
|
||||
.env.*
|
||||
!.env.example
|
||||
!.env.*.example
|
||||
|
||||
# Local app/runtime state
|
||||
.tmp/
|
||||
tmp/
|
||||
temp/
|
||||
.cache/
|
||||
.turbo/
|
||||
.aitimemachine/
|
||||
*.aitm
|
||||
*.db
|
||||
*.sqlite
|
||||
*.sqlite3
|
||||
.kb-credentials.json
|
||||
.kb-indexer-state.json
|
||||
.mega-indexer-state.json
|
||||
|
||||
# Test artifacts
|
||||
coverage/
|
||||
.nyc_output/
|
||||
test-results/
|
||||
playwright-report/
|
||||
blob-report/
|
||||
|
||||
# OS and editor files
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
.idea/
|
||||
.vscode/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
|
||||
# Private keys and certificates
|
||||
*.pem
|
||||
*.key
|
||||
*.p8
|
||||
*.p12
|
||||
9
.prettierrc
Normal file
9
.prettierrc
Normal file
@ -0,0 +1,9 @@
|
||||
{
|
||||
"semi": true,
|
||||
"singleQuote": true,
|
||||
"trailingComma": "es5",
|
||||
"printWidth": 100,
|
||||
"tabWidth": 2,
|
||||
"arrowParens": "always",
|
||||
"endOfLine": "lf"
|
||||
}
|
||||
84
AUDIT_CHECKLIST.md
Normal file
84
AUDIT_CHECKLIST.md
Normal file
@ -0,0 +1,84 @@
|
||||
# Audit Checklist (Launch Readiness)
|
||||
|
||||
This checklist is meant to be executed as a repeatable “startup-style” audit pass: verify the user flow end-to-end, confirm expected network calls + auth, and check that the UI has no dead-ends.
|
||||
|
||||
Status legend: `PASS`, `FAIL`, `N/A`, `FOLLOWUP`
|
||||
|
||||
## 1) Gitgram Core Web Flows
|
||||
|
||||
### Auth
|
||||
- [ ] `GET /` loads unauthenticated and routes to login/signup actions (`PASS|FAIL`)
|
||||
- [ ] Register with email/password creates account, stores tokens, routes to onboarding (`PASS|FAIL`)
|
||||
- [ ] Login with email/password routes to `/feed` (`PASS|FAIL`)
|
||||
- [ ] OAuth GitHub callback (`/auth/github/callback`) stores tokens and routes to onboarding for new users (`PASS|FAIL`)
|
||||
- [ ] OAuth Google callback (`/auth/google/callback`) stores tokens and routes to onboarding for new users (`PASS|FAIL`)
|
||||
- [ ] Logout clears local state and returns to `/` (`PASS|FAIL`)
|
||||
|
||||
### Onboarding
|
||||
- [ ] `/onboarding/welcome` has a clear next action to interests/follow (`PASS|FAIL`)
|
||||
- [ ] `/onboarding/interests` persists interests to backend and updates stored user state (`PASS|FAIL`)
|
||||
- [ ] `/onboarding/follow` suggests accounts and persists follows (`PASS|FAIL`)
|
||||
- [ ] First-time empty feed redirects to onboarding once (no loop) (`PASS|FAIL`)
|
||||
|
||||
### Feed + Social
|
||||
- [ ] `/feed` loads posts, handles empty state, can like/unlike (`PASS|FAIL`)
|
||||
- [ ] Follow/unfollow flows update counts and feed suggestions (`PASS|FAIL`)
|
||||
- [ ] Search (`/search`) returns results for repos/people/posts/hashtags (`PASS|FAIL`)
|
||||
- [ ] Trending pages show meaningful content or a non-empty placeholder (`PASS|FAIL`)
|
||||
|
||||
### Create Content
|
||||
- [ ] Create post (`/create`) upload validation errors are user-friendly (`PASS|FAIL`)
|
||||
- [ ] Create story (`/story/create`) upload validation errors are user-friendly (`PASS|FAIL`)
|
||||
- [ ] Create reel (`/reel/create`) upload validation errors are user-friendly (`PASS|FAIL`)
|
||||
- [ ] Media uploads hit the configured API base (no hardcoded localhost) (`PASS|FAIL`)
|
||||
|
||||
### Repo Profile + Account Switching
|
||||
- [ ] Repository profile page loads in production base URL (`PASS|FAIL`)
|
||||
- [ ] Account switcher lists accounts + switches successfully (`PASS|FAIL`)
|
||||
|
||||
### Moderation/Admin
|
||||
- [ ] Report flow exists from content UI and creates a report (`PASS|FAIL`)
|
||||
- [ ] Moderation queue (`/admin/moderation`) loads for moderators/admins and is blocked for normal users (`PASS|FAIL`)
|
||||
- [ ] Enforcement actions (remove content / suspend user) are audited (`PASS|FAIL`)
|
||||
|
||||
## 2) AITM Flows
|
||||
|
||||
### Website Signup + Keys
|
||||
- [ ] Sign up / sign in works in local/dev (`PASS|FAIL`)
|
||||
- [ ] API keys page: create key shows secret once; list does not expose full secret (`PASS|FAIL`)
|
||||
- [ ] Key revoke works and blocks API usage (`PASS|FAIL`)
|
||||
|
||||
### CLI Auth + Capture
|
||||
- [ ] `aitm login --api-key ...` persists auth and `aitm whoami` returns expected user (`PASS|FAIL`)
|
||||
- [ ] `aitm init` initializes a project and creates a checkpoint (`PASS|FAIL`)
|
||||
- [ ] Capture path enforces consent where required (`PASS|FAIL`)
|
||||
|
||||
### Timeline + Restore
|
||||
- [ ] Timeline UI loads and filters work (`PASS|FAIL`)
|
||||
- [ ] Restore preview shows scoped diff summary (`PASS|FAIL`)
|
||||
- [ ] Restore apply requires confirmation and is reversible (`PASS|FAIL`)
|
||||
|
||||
### Webhooks
|
||||
- [ ] Webhooks list/create/enable-disable/delete all hit real API endpoints (`PASS|FAIL`)
|
||||
- [ ] Deliveries page loads and retry works (no “simulate success”) (`PASS|FAIL`)
|
||||
|
||||
### Export/Consent
|
||||
- [ ] Export endpoints are gated by consent and traceability IDs are present (`PASS|FAIL`)
|
||||
- [ ] Exported artifacts are redacted per policy (`PASS|FAIL`)
|
||||
|
||||
## 3) Docs Correctness Sweep
|
||||
|
||||
### Ops/Runbook
|
||||
- [ ] `docs/runbook.md` local ports match compose (`PASS|FAIL`)
|
||||
- [ ] `docs/ops-quickref.md` commands match current health endpoints (`PASS|FAIL`)
|
||||
- [ ] Deploy docs reference current workflows (`PASS|FAIL`)
|
||||
|
||||
### Env/Secrets
|
||||
- [ ] `docs/environment-matrix.md` matches `.env.*.example` files (`PASS|FAIL`)
|
||||
- [ ] `docs/secrets-contract.md` lists all required third-party keys + rotation owners (`PASS|FAIL`)
|
||||
|
||||
### Install Guides
|
||||
- [ ] Gitgram web docs use `:3000` and backend `:4000` (`PASS|FAIL`)
|
||||
- [ ] AITM Quickstart reflects current CLI commands (`aitm setup --global` semantics, MCP install) (`PASS|FAIL`)
|
||||
- [ ] MCP install instructions work with `npx` (no monorepo assumptions) (`PASS|FAIL`)
|
||||
|
||||
450
CANONICAL_SQL_SCHEMA_V1.sql
Normal file
450
CANONICAL_SQL_SCHEMA_V1.sql
Normal file
@ -0,0 +1,450 @@
|
||||
-- Canonical SQL Schema v1
|
||||
-- Unified model for Gitgram + AITimeMachine + Governance
|
||||
-- Source document: NORTH_STAR_PRD_ARCHITECTURE_V1.md
|
||||
|
||||
BEGIN;
|
||||
|
||||
CREATE EXTENSION IF NOT EXISTS pgcrypto;
|
||||
CREATE EXTENSION IF NOT EXISTS vector;
|
||||
|
||||
-- =========================
|
||||
-- Core Identity / Tenancy
|
||||
-- =========================
|
||||
|
||||
CREATE TABLE IF NOT EXISTS users (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
email TEXT NOT NULL UNIQUE,
|
||||
handle TEXT NOT NULL UNIQUE,
|
||||
display_name TEXT,
|
||||
avatar_url TEXT,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS organizations (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
slug TEXT NOT NULL UNIQUE,
|
||||
name TEXT NOT NULL,
|
||||
created_by_user_id UUID REFERENCES users(id),
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS organization_memberships (
|
||||
organization_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
|
||||
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
role TEXT NOT NULL CHECK (role IN ('owner', 'admin', 'member')),
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
PRIMARY KEY (organization_id, user_id)
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS api_keys (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
user_id UUID REFERENCES users(id) ON DELETE CASCADE,
|
||||
organization_id UUID REFERENCES organizations(id) ON DELETE CASCADE,
|
||||
name TEXT NOT NULL,
|
||||
key_hash TEXT NOT NULL UNIQUE,
|
||||
scopes JSONB NOT NULL DEFAULT '[]'::jsonb,
|
||||
is_active BOOLEAN NOT NULL DEFAULT true,
|
||||
last_used_at TIMESTAMPTZ,
|
||||
expires_at TIMESTAMPTZ,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
CHECK ((user_id IS NOT NULL) OR (organization_id IS NOT NULL))
|
||||
);
|
||||
|
||||
-- =========================
|
||||
-- Repository / Project Map
|
||||
-- =========================
|
||||
|
||||
CREATE TABLE IF NOT EXISTS repositories (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
github_node_id TEXT UNIQUE,
|
||||
github_owner TEXT NOT NULL,
|
||||
github_name TEXT NOT NULL,
|
||||
full_name TEXT NOT NULL UNIQUE,
|
||||
is_private BOOLEAN NOT NULL DEFAULT false,
|
||||
default_branch TEXT,
|
||||
description TEXT,
|
||||
stars_count BIGINT NOT NULL DEFAULT 0,
|
||||
forks_count BIGINT NOT NULL DEFAULT 0,
|
||||
imported_at TIMESTAMPTZ,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS projects (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
organization_id UUID REFERENCES organizations(id) ON DELETE CASCADE,
|
||||
owner_user_id UUID REFERENCES users(id) ON DELETE CASCADE,
|
||||
name TEXT NOT NULL,
|
||||
local_path TEXT,
|
||||
is_archived BOOLEAN NOT NULL DEFAULT false,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
CHECK ((organization_id IS NOT NULL) OR (owner_user_id IS NOT NULL))
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS project_repositories (
|
||||
project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
|
||||
repository_id UUID NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
PRIMARY KEY (project_id, repository_id)
|
||||
);
|
||||
|
||||
-- =========================
|
||||
-- Gitgram Social Layer
|
||||
-- =========================
|
||||
|
||||
CREATE TABLE IF NOT EXISTS repo_profiles (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
repository_id UUID NOT NULL UNIQUE REFERENCES repositories(id) ON DELETE CASCADE,
|
||||
headline TEXT,
|
||||
bio TEXT,
|
||||
hero_media_url TEXT,
|
||||
visibility TEXT NOT NULL DEFAULT 'public' CHECK (visibility IN ('public', 'unlisted', 'private')),
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS posts (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
author_user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
repository_id UUID REFERENCES repositories(id) ON DELETE SET NULL,
|
||||
project_id UUID REFERENCES projects(id) ON DELETE SET NULL,
|
||||
type TEXT NOT NULL CHECK (type IN ('post', 'reel', 'story', 'change_story', 'snippet')),
|
||||
caption TEXT,
|
||||
code_snippet TEXT,
|
||||
language TEXT,
|
||||
linked_checkpoint_id TEXT,
|
||||
visibility TEXT NOT NULL DEFAULT 'public' CHECK (visibility IN ('public', 'followers', 'private')),
|
||||
published_at TIMESTAMPTZ,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS post_assets (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
post_id UUID NOT NULL REFERENCES posts(id) ON DELETE CASCADE,
|
||||
media_type TEXT NOT NULL CHECK (media_type IN ('image', 'video', 'gif')),
|
||||
storage_key TEXT NOT NULL,
|
||||
mime_type TEXT,
|
||||
width INTEGER,
|
||||
height INTEGER,
|
||||
duration_ms INTEGER,
|
||||
position INTEGER NOT NULL DEFAULT 0,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS comments (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
post_id UUID NOT NULL REFERENCES posts(id) ON DELETE CASCADE,
|
||||
author_user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
parent_comment_id UUID REFERENCES comments(id) ON DELETE CASCADE,
|
||||
body TEXT NOT NULL,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS reactions (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
target_type TEXT NOT NULL CHECK (target_type IN ('post', 'comment', 'repository')),
|
||||
target_id UUID NOT NULL,
|
||||
reaction TEXT NOT NULL CHECK (reaction IN ('like', 'love', 'fire', 'clap', 'rocket')),
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
UNIQUE (user_id, target_type, target_id, reaction)
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS follows (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
follower_user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
target_type TEXT NOT NULL CHECK (target_type IN ('user', 'repository')),
|
||||
target_user_id UUID REFERENCES users(id) ON DELETE CASCADE,
|
||||
target_repository_id UUID REFERENCES repositories(id) ON DELETE CASCADE,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
CHECK (
|
||||
(target_type = 'user' AND target_user_id IS NOT NULL AND target_repository_id IS NULL) OR
|
||||
(target_type = 'repository' AND target_repository_id IS NOT NULL AND target_user_id IS NULL)
|
||||
)
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS trend_scores (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
repository_id UUID NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,
|
||||
window_start TIMESTAMPTZ NOT NULL,
|
||||
window_end TIMESTAMPTZ NOT NULL,
|
||||
score NUMERIC(12,4) NOT NULL,
|
||||
signals JSONB NOT NULL DEFAULT '{}'::jsonb,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
UNIQUE (repository_id, window_start, window_end)
|
||||
);
|
||||
|
||||
-- =========================
|
||||
-- AITM Time Layer
|
||||
-- =========================
|
||||
|
||||
CREATE TABLE IF NOT EXISTS blobs (
|
||||
hash TEXT PRIMARY KEY,
|
||||
content BYTEA NOT NULL,
|
||||
size BIGINT NOT NULL,
|
||||
compression TEXT NOT NULL DEFAULT 'brotli',
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS trees (
|
||||
hash TEXT PRIMARY KEY,
|
||||
entries JSONB NOT NULL,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS checkpoints (
|
||||
id TEXT PRIMARY KEY,
|
||||
project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
|
||||
user_id UUID REFERENCES users(id) ON DELETE SET NULL,
|
||||
parent_id TEXT REFERENCES checkpoints(id) ON DELETE SET NULL,
|
||||
linked_checkpoint_id TEXT REFERENCES checkpoints(id) ON DELETE SET NULL,
|
||||
tree_hash TEXT NOT NULL REFERENCES trees(hash),
|
||||
trigger_type TEXT NOT NULL CHECK (trigger_type IN ('manual', 'auto', 'before_action', 'after_action', 'restore')),
|
||||
trigger_tool TEXT,
|
||||
description TEXT,
|
||||
session_id TEXT,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
DO $$
|
||||
BEGIN
|
||||
IF NOT EXISTS (
|
||||
SELECT 1
|
||||
FROM pg_constraint
|
||||
WHERE conname = 'fk_posts_linked_checkpoint'
|
||||
) THEN
|
||||
ALTER TABLE posts
|
||||
ADD CONSTRAINT fk_posts_linked_checkpoint
|
||||
FOREIGN KEY (linked_checkpoint_id)
|
||||
REFERENCES checkpoints(id)
|
||||
ON DELETE SET NULL;
|
||||
END IF;
|
||||
END $$;
|
||||
|
||||
CREATE TABLE IF NOT EXISTS checkpoint_files (
|
||||
checkpoint_id TEXT NOT NULL REFERENCES checkpoints(id) ON DELETE CASCADE,
|
||||
file_path TEXT NOT NULL,
|
||||
blob_hash TEXT REFERENCES blobs(hash),
|
||||
size BIGINT,
|
||||
mode INTEGER,
|
||||
mtime_ms BIGINT,
|
||||
change_type TEXT NOT NULL CHECK (change_type IN ('added', 'modified', 'deleted', 'unchanged')),
|
||||
PRIMARY KEY (checkpoint_id, file_path)
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS diffs (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
from_checkpoint_id TEXT NOT NULL REFERENCES checkpoints(id) ON DELETE CASCADE,
|
||||
to_checkpoint_id TEXT NOT NULL REFERENCES checkpoints(id) ON DELETE CASCADE,
|
||||
file_path TEXT NOT NULL,
|
||||
diff_content TEXT NOT NULL,
|
||||
stats JSONB NOT NULL DEFAULT '{}'::jsonb,
|
||||
algorithm TEXT NOT NULL DEFAULT 'histogram',
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
-- =========================
|
||||
-- AITM Context Layer
|
||||
-- =========================
|
||||
|
||||
CREATE TABLE IF NOT EXISTS messages (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
|
||||
session_id TEXT NOT NULL,
|
||||
checkpoint_id TEXT REFERENCES checkpoints(id) ON DELETE SET NULL,
|
||||
role TEXT NOT NULL CHECK (role IN ('user', 'assistant', 'system')),
|
||||
content TEXT NOT NULL,
|
||||
metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS tool_calls (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
message_id UUID REFERENCES messages(id) ON DELETE SET NULL,
|
||||
project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
|
||||
session_id TEXT NOT NULL,
|
||||
checkpoint_before_id TEXT REFERENCES checkpoints(id) ON DELETE SET NULL,
|
||||
checkpoint_after_id TEXT REFERENCES checkpoints(id) ON DELETE SET NULL,
|
||||
tool_name TEXT NOT NULL,
|
||||
arguments JSONB NOT NULL DEFAULT '{}'::jsonb,
|
||||
result JSONB,
|
||||
success BOOLEAN,
|
||||
error TEXT,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS contexts (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
|
||||
checkpoint_id TEXT NOT NULL REFERENCES checkpoints(id) ON DELETE CASCADE,
|
||||
session_id TEXT NOT NULL,
|
||||
summary TEXT,
|
||||
active_files JSONB NOT NULL DEFAULT '[]'::jsonb,
|
||||
cursor_position JSONB,
|
||||
current_task TEXT,
|
||||
goals JSONB NOT NULL DEFAULT '[]'::jsonb,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS restore_events (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
|
||||
actor_user_id UUID REFERENCES users(id) ON DELETE SET NULL,
|
||||
from_checkpoint_id TEXT REFERENCES checkpoints(id) ON DELETE SET NULL,
|
||||
to_checkpoint_id TEXT REFERENCES checkpoints(id) ON DELETE SET NULL,
|
||||
scope_type TEXT NOT NULL CHECK (scope_type IN ('file', 'folder', 'project')),
|
||||
scope_path TEXT,
|
||||
status TEXT NOT NULL CHECK (status IN ('requested', 'applied', 'failed')),
|
||||
details JSONB NOT NULL DEFAULT '{}'::jsonb,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
-- =========================
|
||||
-- AITM Augmented Layer
|
||||
-- =========================
|
||||
|
||||
CREATE TABLE IF NOT EXISTS embeddings (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
|
||||
checkpoint_id TEXT REFERENCES checkpoints(id) ON DELETE SET NULL,
|
||||
source_type TEXT NOT NULL CHECK (source_type IN ('code', 'message', 'doc')),
|
||||
file_path TEXT,
|
||||
chunk_text TEXT NOT NULL,
|
||||
chunk_start_line INTEGER,
|
||||
chunk_end_line INTEGER,
|
||||
embedding vector(1536) NOT NULL,
|
||||
metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS indexed_docs (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
|
||||
url TEXT NOT NULL,
|
||||
title TEXT,
|
||||
content TEXT NOT NULL,
|
||||
embedding vector(1536),
|
||||
metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
|
||||
indexed_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
-- =========================
|
||||
-- Governance / Compliance
|
||||
-- =========================
|
||||
|
||||
CREATE TABLE IF NOT EXISTS consents (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
organization_id UUID REFERENCES organizations(id) ON DELETE CASCADE,
|
||||
project_id UUID REFERENCES projects(id) ON DELETE CASCADE,
|
||||
granted_by_user_id UUID REFERENCES users(id) ON DELETE SET NULL,
|
||||
consent_type TEXT NOT NULL CHECK (consent_type IN ('operational_capture', 'training_export')),
|
||||
granted BOOLEAN NOT NULL,
|
||||
effective_from TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
effective_to TIMESTAMPTZ,
|
||||
metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
CHECK ((organization_id IS NOT NULL) OR (project_id IS NOT NULL))
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS retention_policies (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
organization_id UUID REFERENCES organizations(id) ON DELETE CASCADE,
|
||||
project_id UUID REFERENCES projects(id) ON DELETE CASCADE,
|
||||
data_class TEXT NOT NULL CHECK (data_class IN ('checkpoints', 'messages', 'tool_calls', 'social_media', 'exports', 'audit_logs')),
|
||||
retention_days INTEGER NOT NULL CHECK (retention_days > 0),
|
||||
hard_delete BOOLEAN NOT NULL DEFAULT false,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
CHECK ((organization_id IS NOT NULL) OR (project_id IS NOT NULL))
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS export_jobs (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
|
||||
requested_by_user_id UUID REFERENCES users(id) ON DELETE SET NULL,
|
||||
consent_id UUID REFERENCES consents(id) ON DELETE SET NULL,
|
||||
export_type TEXT NOT NULL CHECK (export_type IN ('training', 'compliance', 'backup')),
|
||||
status TEXT NOT NULL CHECK (status IN ('queued', 'running', 'completed', 'failed', 'cancelled')),
|
||||
redaction_profile TEXT NOT NULL DEFAULT 'default',
|
||||
artifact_uri TEXT,
|
||||
summary JSONB NOT NULL DEFAULT '{}'::jsonb,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
completed_at TIMESTAMPTZ
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS data_delete_requests (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
requester_user_id UUID REFERENCES users(id) ON DELETE SET NULL,
|
||||
organization_id UUID REFERENCES organizations(id) ON DELETE CASCADE,
|
||||
project_id UUID REFERENCES projects(id) ON DELETE CASCADE,
|
||||
target_type TEXT NOT NULL CHECK (target_type IN ('user_data', 'project_data', 'export_data')),
|
||||
status TEXT NOT NULL CHECK (status IN ('requested', 'approved', 'processing', 'completed', 'rejected')),
|
||||
reason TEXT,
|
||||
requested_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
completed_at TIMESTAMPTZ
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS audit_logs (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
organization_id UUID REFERENCES organizations(id) ON DELETE CASCADE,
|
||||
project_id UUID REFERENCES projects(id) ON DELETE CASCADE,
|
||||
actor_user_id UUID REFERENCES users(id) ON DELETE SET NULL,
|
||||
actor_api_key_id UUID REFERENCES api_keys(id) ON DELETE SET NULL,
|
||||
action TEXT NOT NULL,
|
||||
target_type TEXT NOT NULL,
|
||||
target_id TEXT,
|
||||
ip_address INET,
|
||||
user_agent TEXT,
|
||||
metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
-- =========================
|
||||
-- Indexes
|
||||
-- =========================
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_projects_org ON projects(organization_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_projects_owner ON projects(owner_user_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_project_repo_repo ON project_repositories(repository_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_posts_repo_created ON posts(repository_id, created_at DESC);
|
||||
CREATE INDEX IF NOT EXISTS idx_posts_author_created ON posts(author_user_id, created_at DESC);
|
||||
CREATE INDEX IF NOT EXISTS idx_comments_post_created ON comments(post_id, created_at DESC);
|
||||
CREATE INDEX IF NOT EXISTS idx_reactions_target ON reactions(target_type, target_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_follows_target_user ON follows(target_user_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_follows_target_repo ON follows(target_repository_id);
|
||||
CREATE UNIQUE INDEX IF NOT EXISTS uq_follows_user_target
|
||||
ON follows(follower_user_id, target_user_id)
|
||||
WHERE target_type = 'user';
|
||||
CREATE UNIQUE INDEX IF NOT EXISTS uq_follows_repo_target
|
||||
ON follows(follower_user_id, target_repository_id)
|
||||
WHERE target_type = 'repository';
|
||||
CREATE INDEX IF NOT EXISTS idx_trend_scores_repo_window ON trend_scores(repository_id, window_end DESC);
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_checkpoints_project_created ON checkpoints(project_id, created_at DESC);
|
||||
CREATE INDEX IF NOT EXISTS idx_checkpoints_session ON checkpoints(session_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_checkpoint_files_path ON checkpoint_files(file_path);
|
||||
CREATE INDEX IF NOT EXISTS idx_diffs_from_to ON diffs(from_checkpoint_id, to_checkpoint_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_messages_project_session ON messages(project_id, session_id, created_at);
|
||||
CREATE INDEX IF NOT EXISTS idx_messages_checkpoint ON messages(checkpoint_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_tool_calls_project_session ON tool_calls(project_id, session_id, created_at);
|
||||
CREATE INDEX IF NOT EXISTS idx_contexts_checkpoint ON contexts(checkpoint_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_restore_events_project_created ON restore_events(project_id, created_at DESC);
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_embeddings_project_checkpoint ON embeddings(project_id, checkpoint_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_embeddings_vector ON embeddings USING ivfflat (embedding vector_cosine_ops);
|
||||
CREATE INDEX IF NOT EXISTS idx_indexed_docs_project ON indexed_docs(project_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_consents_scope ON consents(organization_id, project_id, consent_type, effective_from DESC);
|
||||
CREATE INDEX IF NOT EXISTS idx_retention_scope ON retention_policies(organization_id, project_id, data_class);
|
||||
CREATE INDEX IF NOT EXISTS idx_export_jobs_project_created ON export_jobs(project_id, created_at DESC);
|
||||
CREATE INDEX IF NOT EXISTS idx_delete_requests_status ON data_delete_requests(status, requested_at DESC);
|
||||
CREATE INDEX IF NOT EXISTS idx_audit_project_created ON audit_logs(project_id, created_at DESC);
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_messages_fts
|
||||
ON messages USING gin (to_tsvector('english', content));
|
||||
|
||||
COMMIT;
|
||||
226
INTEGRATION_PLAN.md
Normal file
226
INTEGRATION_PLAN.md
Normal file
@ -0,0 +1,226 @@
|
||||
# External Repo Integration Plan
|
||||
|
||||
Last updated: 2026-06-21
|
||||
|
||||
## Mission
|
||||
|
||||
In the AI era, Git is a 20-year-old protocol and GitHub is a web UI bolted on top.
|
||||
Neither was designed for AI agents, social-first development, or deterministic restore.
|
||||
|
||||
- **Gitgram** replaces GitHub — repository-first social network for developers.
|
||||
- **AITM** replaces Git — AI-native, deterministic, time-travel version control.
|
||||
|
||||
This plan maps the 8 cloned reference repos into actual product source code.
|
||||
|
||||
---
|
||||
|
||||
## 0. Executive Summary
|
||||
|
||||
Both products are feature-complete with 1130 passing tests. This is **pattern/implementation uplift**, not a rebuild.
|
||||
|
||||
Three repos are **not source-copy candidates**:
|
||||
- `beads` — Go + Dolt standalone binary. Adopt the dependency-DAG workflow model, not the code.
|
||||
- `gitnexus` — PolyForm Noncommercial license + native tree-sitter deps. Wrap as dependency or federated MCP; do not vendor source into commercial product until licensed.
|
||||
- `proximity` — GPL-3. Reference only, zero code copied.
|
||||
|
||||
Stack-mismatch correction: `t3-twitter-clone` is **Next.js + tRPC + Prisma**, NOT Express. It does not match `gitgram/backend`. Demoted to P2 reference.
|
||||
|
||||
---
|
||||
|
||||
## 1. Integration Map
|
||||
|
||||
### Priority legend
|
||||
- **P0** — integrate first; highest value, lowest risk.
|
||||
- **P1** — second pass; valuable but needs adaptation.
|
||||
- **P2** — reference-grade or license-gated.
|
||||
|
||||
---
|
||||
|
||||
### 1.1 `bluesky-social-app` (MIT) → Gitgram web + backend + mobile — P0
|
||||
|
||||
| Source | Lands in | Strategy |
|
||||
|---|---|---|
|
||||
| `src/lib/api/feed/merge.ts`, `feed/utils.ts`, `lib/api/feed-manip.ts` (FeedTuner) | `gitgram/backend/src/services/feedAlgorithm.ts` | Extract `MergeFeedAPI` round-robin merge + `FeedTuner` dedup/threading into existing service |
|
||||
| `src/state/queries/notifications/{feed,util,types}.ts` | `gitgram/web` notification hooks + backend notification grouping | Adopt notification grouping ("X and 3 others liked") + cursor pagination shape |
|
||||
| `src/lib/moderation/` | `gitgram/backend/src/services/moderationEnforcementService.ts` | Adopt label/cause-description taxonomy only |
|
||||
| TanStack Query `createQueryKey` + `useInfiniteQuery` cursor conventions | `gitgram/web` data layer | Adopt convention for infinite-scroll lists |
|
||||
|
||||
**Skip:** ALF design system, Lingui i18n, React Navigation, atproto agent layer, all view/screens UI.
|
||||
|
||||
---
|
||||
|
||||
### 1.2 `munia` (MIT) → Gitgram web + backend — P0/P1
|
||||
|
||||
| Source | Lands in | Strategy | Priority |
|
||||
|---|---|---|---|
|
||||
| `src/app/api/comments/[commentId]/replies/*` + `verifyAccessToComment.ts` | `gitgram/backend` comment routes / `gitgram/web` comment threads | Nested-comment reply pagination + access-verification guard | P0 |
|
||||
| `src/app/api/posts/hashtag/[hashtag]/GET.ts` | `gitgram/web/app/hashtag/[tag]/page.tsx` + backend `tags.ts` | Adopt hashtag-query pagination if cleaner than current | P1 |
|
||||
| Drag-drop media upload components | `gitgram/web/components/composer/DropZone.tsx` | Cherry-pick a11y/keyboard handling only | P1 |
|
||||
| Accessibility helpers | `gitgram/web/components/Accessibility.tsx` | Extract a11y patterns | P1 |
|
||||
|
||||
**Skip:** NextAuth (conflicts with JWT auth), S3 upload (Gitgram has `uploadService.ts`), profile UI.
|
||||
|
||||
---
|
||||
|
||||
### 1.3 `gh-social` (MIT) → Gitgram backend + web — P1
|
||||
|
||||
Unique value: **syncing GitHub follows/stars into the social graph** — closest open-source concept to Gitgram.
|
||||
|
||||
| Source | Lands in | Strategy |
|
||||
|---|---|---|
|
||||
| `src/server/api/routers/github.ts` (profile/followers/following/repos sync) | `gitgram/backend/src/services/githubActivityService.ts` + `githubActivityFeedService.ts` | Port GitHub follow/star → social-feed sync; re-express as Express controllers (strip tRPC) |
|
||||
| `src/server/caches/{followingsCache,usernameCache,oAuthCache}.ts` | `gitgram/backend/src/utils/cache.ts` / `redisStores.ts` | Redis cache key strategy for GitHub data |
|
||||
| `src/server/helpers/trimGitHubData.ts` | `gitgram/backend/src/services` (new util) | Copy + adapt; pure function, low risk |
|
||||
|
||||
**Skip:** Clerk auth (hard conflict), Drizzle/Neon (Gitgram uses Prisma/PG), Pusher (Gitgram uses Socket.io), tRPC, all UI.
|
||||
|
||||
---
|
||||
|
||||
### 1.4 `nextjs-15-social-media-app` (codinginflow) → Gitgram web — P1
|
||||
|
||||
| Source | Lands in | Strategy |
|
||||
|---|---|---|
|
||||
| Infinite-scroll + React Query optimistic-update patterns | `gitgram/web/components/Feed.tsx`, `VirtualList.tsx`, infinite-scroll hooks | Adopt optimistic like/follow mutation patterns where Gitgram still does full refetch |
|
||||
| Notification-system query/mutation shape | `gitgram/web` notification components | Cross-reference with bluesky §1.1 — pick the stronger |
|
||||
|
||||
**Skip:** Prisma schema (Gitgram schema is canonical), auth, UI primitives.
|
||||
|
||||
---
|
||||
|
||||
### 1.5 `t3-twitter-clone` (MIT) → reference only — P2
|
||||
|
||||
Stack mismatch: this is Next.js + tRPC + Prisma, not Express. Validate Gitgram's post data model against it; copy nothing structural.
|
||||
|
||||
---
|
||||
|
||||
### 1.6 `proximity` (GPL-3) → Gitgram mobile reference ONLY — P2
|
||||
|
||||
**Zero code copied.** GPL-3 is incompatible. Use only for behavioral reference (GraphQL subscriptions → mobile real-time). Implement any adopted idea clean-room in `gitgram/mobile` using the existing Socket.io layer. Document in commit messages.
|
||||
|
||||
---
|
||||
|
||||
### 1.7 `gitnexus` (PolyForm Noncommercial) → Gitgram repo explore + AITM — P1/P2
|
||||
|
||||
**License gate:** PolyForm Noncommercial likely incompatible with commercial products. Requires legal clearance before shipping. Two compliant integration modes:
|
||||
|
||||
| Use | Lands in | Strategy | Priority |
|
||||
|---|---|---|---|
|
||||
| Gitgram repo explore/visualization | `gitgram/web/components/repo/RepoGraphTab.tsx` | Wrap as external tool / call CLI out-of-process. Never import source. | P2 (license-gated) |
|
||||
| AITM code-context indexing + checkpoint knowledge graph | `aitimemachine/mcp/src/tools/` + `aitimemachine/src/core/neon/indexer.ts` | Pattern reference + optional MCP federation. Adopt impact/context/clusters concept into AITM's existing graph. No source copy. | P1 |
|
||||
|
||||
**Action required:** legal review of PolyForm Noncommercial vs. commercial use before shipping either path.
|
||||
|
||||
---
|
||||
|
||||
### 1.8 `beads` (MIT) → AITM CLI/MCP — P1
|
||||
|
||||
Go + Dolt binary. Adopt the **dependency-DAG issue model and `bd ready` semantics** into AITM's existing `checkpoint-graph.ts`.
|
||||
|
||||
| Concept | Lands in | Strategy |
|
||||
|---|---|---|
|
||||
| Hash-based collision-free IDs (`bd-a1b2`) | `aitimemachine/src/core/checkpoint-graph.ts` | Add beads-style content-hash IDs for dependency nodes |
|
||||
| `bd ready` = dependency-unblocked work detection | `aitimemachine/mcp/src/tools/` (new `ready`-style tool) | Expose "what work is unblocked" MCP tool over AITM's DAG |
|
||||
| `relates_to`/`supersedes`/`replies_to` graph links | `aitimemachine/src/core/checkpoint-graph.ts` + `annotation-store.ts` | Map onto existing checkpoint relations |
|
||||
| Optional: depend on beads binary | AITM agent workflow | Install `bd` as agent dev-tool (MIT permits) |
|
||||
|
||||
**Skip:** Dolt storage (AITM uses SQLite + CAS + Neon), all Go code, server mode.
|
||||
|
||||
---
|
||||
|
||||
## 2. Conflict Hotspots
|
||||
|
||||
| Area | Conflict | Resolution |
|
||||
|---|---|---|
|
||||
| **Authentication** (HIGH) | munia/gh-social bring NextAuth/Clerk; Gitgram uses httpOnly-cookie JWT | Do not import any external auth. Extract OAuth scope/flow ideas only. |
|
||||
| **ORM/DB driver** (HIGH) | gh-social uses Drizzle+Neon; Gitgram uses Prisma+PG | Re-express all donor queries in Prisma. Never introduce Drizzle into `gitgram/backend`. |
|
||||
| **Backend framework** (HIGH) | gh-social/t3 tRPC routers vs. Gitgram Express controllers | Strip tRPC; re-implement as Express route + controller pairs. |
|
||||
| **Real-time transport** (MEDIUM) | Pusher, GraphQL subs, atproto firehose | Map all real-time ideas onto existing Socket.io. Copy no transport client. |
|
||||
| **Feed algorithm** (MEDIUM) | bluesky FeedTuner vs. existing `feedAlgorithm.ts` | Surgical merge inside `feedAlgorithm.ts`. TDD first; feed scoring covered by backend tests. |
|
||||
| **Comment threading** (MEDIUM) | munia nested replies vs. `CommentThread.tsx` / `commentActionsController.ts` | Diff data shapes; adopt reply-pagination only if it doesn't break existing API contract. |
|
||||
| **Checkpoint graph identity** (MEDIUM) | beads hash-IDs vs. AITM SHA256 CAS | AITM already content-addresses. Add dependency-edge semantics without changing existing checkpoint IDs (referenced in 520 core tests). |
|
||||
| **License contamination** (CRITICAL) | proximity (GPL-3), gitnexus (PolyForm Noncommercial) | Never copy source. Add CI check blocking GPL/noncommercial imports in product trees. |
|
||||
|
||||
---
|
||||
|
||||
## 3. Integration Order
|
||||
|
||||
Each step: **(a) write tests first → (b) merge pattern → (c) run affected suite → (d) commit.** Never batch two donors in one commit.
|
||||
|
||||
### Phase 0 — Guardrails (before any merge)
|
||||
1. Add license-contamination CI check (block GPL/noncommercial imports in product trees).
|
||||
2. Snapshot current suites as green baseline: AITM Core 520, AITM API 538, AITM VSCode 62, Gitgram Web 72.
|
||||
3. Quarantine `external/` from product `tsconfig`/build paths.
|
||||
|
||||
### Phase 1 — Pure additive, zero-conflict (P0)
|
||||
4. `gh-social` `trimGitHubData` helper → Gitgram backend util (pure function, new file, new tests).
|
||||
5. `bluesky` notification grouping/aggregation → backend service + web hooks (new aggregation layer; old endpoints untouched).
|
||||
6. `munia` nested-comment reply pagination → backend (additive route variant; keep old contract).
|
||||
|
||||
### Phase 2 — Surgical merges into existing services (P0/P1)
|
||||
7. `bluesky` `FeedTuner`/merge logic → `feedAlgorithm.ts` (TDD around ranking).
|
||||
8. `nextjs-15-social-media-app` + `bluesky` optimistic-update patterns → Gitgram web Feed.
|
||||
9. `gh-social` GitHub follow/star→social-graph sync → `githubActivityService.ts`.
|
||||
10. `munia` accessibility + drag-drop a11y → composer components.
|
||||
|
||||
### Phase 3 — AITM workflow adoption (P1)
|
||||
11. `beads` dependency-DAG + `bd ready` semantics → `checkpoint-graph.ts` + new MCP "ready" tool.
|
||||
12. `gitnexus` impact/context concepts → AITM graph OR federated MCP registration (no source copy).
|
||||
|
||||
### Phase 4 — License-gated / reference (P2)
|
||||
13. `gitnexus` Gitgram repo-graph tab — only after legal clearance.
|
||||
14. `proximity` mobile real-time ideas — clean-room reimplementation only.
|
||||
15. `t3-twitter-clone` — data-model validation pass only.
|
||||
|
||||
---
|
||||
|
||||
## 4. What to Skip
|
||||
|
||||
| External | Skip because we already have it |
|
||||
|---|---|
|
||||
| `munia` S3 upload, NextAuth, profile UI | `uploadService.ts`, `mediaService.ts`, JWT auth, full profile pages |
|
||||
| `gh-social` Clerk, Drizzle, Pusher, tRPC, all `components/` | own auth, Prisma, Socket.io, Express, 80+ web components |
|
||||
| `t3-twitter-clone` entire backend + auth + UI | stack mismatch; Gitgram post/retweet done |
|
||||
| `nextjs-15-social-media-app` Prisma schema, auth, UI primitives | canonical schema, auth, UI system exist |
|
||||
| `bluesky` ALF, Lingui, React Navigation, atproto agent, `view/`/`screens/` | own design system, routing, transport |
|
||||
| `beads` Dolt engine, Go code, server mode | SQLite + CAS + Neon; content-addressing exists |
|
||||
| `gitnexus` ingestion/parser source, LadybugDB, embeddings pipeline | `neon/indexer.ts`, `search-engine.ts`, `checkpoint-graph.ts`; license blocks vendoring |
|
||||
| `proximity` everything (source) | GPL-3; mobile features already implemented |
|
||||
|
||||
---
|
||||
|
||||
## 5. Key File Paths
|
||||
|
||||
### Gitgram integration targets
|
||||
- `gitgram/backend/src/services/feedAlgorithm.ts`
|
||||
- `gitgram/backend/src/services/githubActivityService.ts`
|
||||
- `gitgram/backend/src/services/githubActivityFeedService.ts`
|
||||
- `gitgram/backend/src/services/moderationEnforcementService.ts`
|
||||
- `gitgram/backend/src/services/mentionService.ts`
|
||||
- `gitgram/backend/src/controllers/commentActionsController.ts`
|
||||
- `gitgram/web/components/Feed.tsx`
|
||||
- `gitgram/web/components/CommentThread.tsx`
|
||||
- `gitgram/web/components/composer/DropZone.tsx`
|
||||
- `gitgram/web/components/repo/` (new `RepoGraphTab.tsx`)
|
||||
|
||||
### AITM integration targets
|
||||
- `aitimemachine/src/core/checkpoint-graph.ts`
|
||||
- `aitimemachine/src/core/neon/indexer.ts`
|
||||
- `aitimemachine/src/core/search-engine.ts`
|
||||
- `aitimemachine/mcp/src/tools/register-core-tools.ts`
|
||||
|
||||
### Key donor files
|
||||
- `external/bluesky-social-app/src/lib/api/feed/merge.ts`
|
||||
- `external/bluesky-social-app/src/state/queries/notifications/`
|
||||
- `external/bluesky-social-app/src/lib/moderation/`
|
||||
- `external/munia/src/app/api/comments/[commentId]/replies/`
|
||||
- `external/gh-social/src/server/api/routers/github.ts`
|
||||
- `external/gh-social/src/server/caches/`
|
||||
- `external/beads/` (pattern reference)
|
||||
|
||||
---
|
||||
|
||||
## 6. Decisions Requiring Sign-off
|
||||
|
||||
1. **gitnexus license** — PolyForm Noncommercial likely incompatible with commercial Gitgram. Decide: commercial license, MCP-federation only, or drop. Blocks §1.7 Gitgram path.
|
||||
2. **beads as dependency vs. pattern** — install `bd` binary (MIT, fine) for agent task tracking, or reimplement DAG semantics natively in AITM.
|
||||
3. **Feed ranking changes** — any merge into `feedAlgorithm.ts` changes user-visible ordering. Confirm before Phase 2 step 7.
|
||||
242
NORTH_STAR_PRD_ARCHITECTURE_V1.md
Normal file
242
NORTH_STAR_PRD_ARCHITECTURE_V1.md
Normal file
@ -0,0 +1,242 @@
|
||||
# North Star PRD + Architecture v1
|
||||
|
||||
## 1) Product Vision
|
||||
|
||||
Build a unified platform with two products:
|
||||
|
||||
- `gitgram`: a vertical GitHub social network where repositories become social profiles and feeds (posts, reels, stories, comments, reactions, follows, trending discovery).
|
||||
- `aitimemachine` (AITM): a "Time Machine for AI coding" that can restore code and chat context to exact previous states, inspect diffs, undo mistakes, and restore file/folder/project selectively.
|
||||
|
||||
Core thesis:
|
||||
- Social coding (`gitgram`) creates engagement around repositories and developers.
|
||||
- Trust and recoverability (`aitimemachine`) makes AI coding safe enough for daily professional use.
|
||||
|
||||
## 2) Product Boundaries
|
||||
|
||||
`gitgram` v1 includes:
|
||||
- Import and mirror public GitHub repositories into social repository pages.
|
||||
- Post media (screenshots/videos) linked to repositories and code snippets.
|
||||
- Comment/reaction/follow system for repositories and developers.
|
||||
- Trending feed based on repository activity plus social engagement.
|
||||
|
||||
`aitimemachine` v1 includes:
|
||||
- Point-in-time restore for full project, folder, or single file.
|
||||
- Before/after checkpoints around AI actions.
|
||||
- Code diff and timeline navigation.
|
||||
- Chat + tool-call context restoration linked to checkpoints.
|
||||
- Search across code history and conversation history.
|
||||
|
||||
Out of scope for v1:
|
||||
- Enterprise SSO/SAML hardening beyond initial scaffolding.
|
||||
- Fully autonomous research/oracle workflows as a primary UX.
|
||||
- Private repo ingest without explicit legal + security controls.
|
||||
|
||||
## 3) Architecture Decisions (Locked)
|
||||
|
||||
### 3.1 Source of Truth
|
||||
|
||||
Decision:
|
||||
- Backend database + object storage is the authoritative source of truth.
|
||||
- Local `.aitimemachine/` storage is a performance cache and offline buffer, not the canonical state.
|
||||
|
||||
Why:
|
||||
- Cross-device restore.
|
||||
- Crash resilience.
|
||||
- Centralized auth, audit, retention, and deletion controls.
|
||||
|
||||
### 3.2 Storage Model
|
||||
|
||||
Use a hybrid Git-like model:
|
||||
- `blobs` for content-addressed file data.
|
||||
- `trees` for directory states.
|
||||
- `checkpoints` for commit-like snapshots.
|
||||
- `diffs` precomputed for fast timeline UX.
|
||||
- `messages`, `tool_calls`, `contexts` linked to checkpoints.
|
||||
|
||||
### 3.3 Capture Model
|
||||
|
||||
Every AI code action records:
|
||||
1. `before_action` checkpoint.
|
||||
2. tool call + args + initiating message link.
|
||||
3. `after_action` checkpoint.
|
||||
4. diff generation and change classification.
|
||||
5. optional async indexing/embeddings.
|
||||
|
||||
This guarantees deterministic "go back before error" behavior.
|
||||
|
||||
### 3.4 Privacy + Training Data Policy
|
||||
|
||||
Decision:
|
||||
- Data capture is opt-in per workspace/org for training export.
|
||||
- Default mode: operational capture only (restore/search), no training export.
|
||||
- Redaction pipeline required before any dataset export.
|
||||
|
||||
## 4) Unified Domain Model
|
||||
|
||||
Primary entities:
|
||||
- `users`, `organizations`, `projects`, `repositories`.
|
||||
- Social: `repo_profiles`, `posts`, `reels`, `stories`, `comments`, `reactions`, `follows`, `trend_scores`.
|
||||
- Time machine: `checkpoints`, `checkpoint_files`, `blobs`, `trees`, `diffs`, `messages`, `tool_calls`, `contexts`, `restore_events`.
|
||||
- Governance: `consents`, `retention_policies`, `audit_logs`, `export_jobs`.
|
||||
|
||||
Entity links:
|
||||
- A `repository` can have a `repo_profile` on gitgram.
|
||||
- A `project` in AITM can map to one or more repositories.
|
||||
- AITM checkpoints can be referenced by gitgram posts (for "before/after reels" and explainable dev content).
|
||||
|
||||
## 5) API Surface v1 (High-Level)
|
||||
|
||||
Social APIs:
|
||||
- `POST /api/repos/import`
|
||||
- `GET /api/repos/:id/feed`
|
||||
- `POST /api/posts`
|
||||
- `POST /api/comments`
|
||||
- `POST /api/reactions`
|
||||
- `POST /api/follows`
|
||||
- `GET /api/trending`
|
||||
|
||||
AITM APIs:
|
||||
- `POST /api/actions/before`
|
||||
- `POST /api/actions/after`
|
||||
- `POST /api/time/restore`
|
||||
- `POST /api/time/undo`
|
||||
- `GET /api/time/timeline`
|
||||
- `GET /api/time/diff`
|
||||
- `POST /api/time/restore-file`
|
||||
- `POST /api/time/restore-folder`
|
||||
- `GET /api/context/:checkpointId`
|
||||
|
||||
Governance APIs:
|
||||
- `POST /api/consent`
|
||||
- `POST /api/export/training`
|
||||
- `POST /api/data/delete-request`
|
||||
- `GET /api/audit`
|
||||
|
||||
## 6) UX Principles
|
||||
|
||||
Gitgram UX:
|
||||
- Repository-first profile pages.
|
||||
- Media-native storytelling for code changes.
|
||||
- Fast interaction loop: watch, react, comment, fork/follow.
|
||||
|
||||
AITM UX:
|
||||
- "Restore confidence in one click."
|
||||
- Timeline with human-readable events ("before create_file src/api.ts").
|
||||
- Clear scope controls: restore file, folder, or full workspace.
|
||||
- Always show preview diff before irreversible restore actions.
|
||||
|
||||
## 7) Security, Compliance, and Risk Controls
|
||||
|
||||
Minimum controls for production:
|
||||
- Tenant isolation at query and storage layers.
|
||||
- Scoped API keys and per-project authorization.
|
||||
- Encryption at rest and in transit.
|
||||
- Audit logging for restore/export/delete operations.
|
||||
- Retention and hard-delete workflows.
|
||||
- PII/secret redaction before training export.
|
||||
|
||||
Key risks:
|
||||
- Capturing sensitive code/prompts without explicit consent.
|
||||
- Licensing conflicts when combining public repo/social content and training datasets.
|
||||
- Data poisoning and abuse in social media uploads.
|
||||
|
||||
## 8) 90-Day Execution Plan
|
||||
|
||||
### Milestone A (Days 1-30): Core Reliability
|
||||
- Finalize canonical schema for checkpoints/messages/tool calls.
|
||||
- Ship deterministic restore for file/folder/project.
|
||||
- Add consent + retention enforcement paths.
|
||||
- Stand up baseline social repo feed with comments/reactions/follows.
|
||||
|
||||
Exit criteria:
|
||||
- Restore success rate >= 99%.
|
||||
- P95 restore latency <= 2s for single file and <= 10s for medium project.
|
||||
- 0 known auth bypasses in internal security review.
|
||||
|
||||
### Milestone B (Days 31-60): Social + Time Integration
|
||||
- Link gitgram posts to AITM checkpoint references.
|
||||
- Add "change story" post type from diff snapshots.
|
||||
- Ship trending ranking combining GitHub + on-platform signals.
|
||||
- Release org/project scoped policies.
|
||||
|
||||
Exit criteria:
|
||||
- >= 25% of active repos receive at least one social interaction.
|
||||
- >= 40% of restores initiated from timeline UI complete without retry.
|
||||
|
||||
### Milestone C (Days 61-90): Intelligence + Growth
|
||||
- Add semantic search on code/checkpoint history.
|
||||
- Add high-trust training export pipeline (opt-in + redaction + audit).
|
||||
- Launch creator features for repo owners (story/reel workflow).
|
||||
|
||||
Exit criteria:
|
||||
- Search relevance accepted by internal benchmark.
|
||||
- 100% training exports traceable by consent + audit IDs.
|
||||
|
||||
## 9) KPIs
|
||||
|
||||
Product KPIs:
|
||||
- Weekly active developers.
|
||||
- Restore actions per active AITM user.
|
||||
- Social interactions per repository page.
|
||||
- 7-day retention for users who performed at least one restore.
|
||||
|
||||
System KPIs:
|
||||
- Checkpoint ingestion throughput.
|
||||
- Restore success/latency percentiles.
|
||||
- Diff generation latency.
|
||||
- Sync lag (local cache to backend).
|
||||
|
||||
Safety KPIs:
|
||||
- Consent coverage.
|
||||
- Redaction precision/recall on sampled exports.
|
||||
- Mean time to resolve data deletion requests.
|
||||
|
||||
## 10) Immediate Next Actions
|
||||
|
||||
1. Treat this file as canonical for v1 decisions.
|
||||
2. Update conflicting docs to reference these decisions (especially source-of-truth and privacy policy).
|
||||
3. Create implementation tickets from sections 3, 7, and 8 first (architecture lock + security gates before feature acceleration).
|
||||
|
||||
## 11) Cleanup Completed (2026-03-02)
|
||||
|
||||
The following code quality issues from the original audit have been resolved:
|
||||
|
||||
### Gitgram - Fixed
|
||||
- **Route duplication** - Removed 17 legacy `/api/` routes that duplicated `/api/v1/` endpoints
|
||||
- **Socket.IO deprecated service still used** - Fully migrated to `useSocket` hook; deleted `socketService.ts`; removed from `authStore`, `notifications/page.tsx`, `messages/page.tsx`
|
||||
- **40+ console.log in backend** - Replaced ~52 `console.*` calls with Winston logger across 10 controller/util files
|
||||
- **125+ markdown clutter files** - Deleted 121 .md + 8 .txt status/completion files; kept only README, CLAUDE, COMMANDS, TROUBLESHOOTING
|
||||
- **@types in wrong dependency section** - Moved `@types/node-cron`, `@types/qrcode` to devDependencies
|
||||
|
||||
### AITM - Fixed
|
||||
- **No disk-full handling** - ContentStore.put() now uses atomic write (.tmp + rename) with ENOSPC catch and cleanup
|
||||
- **No rate limiting on MCP tools** - Added sliding-window rate limiter (restore*: 5/min, execute_command: 30/min, before/after_action: 60/min, default: 120/min)
|
||||
- **API response inconsistency** - Created `sendSuccess`/`sendError`/`sendPaginated` helpers; applied to dashboard + search routes as starting examples
|
||||
- **44 markdown clutter files** - Deleted; kept only README, CLAUDE, CHANGELOG, API, MCP, DEVELOPMENT, QUICKSTART, ROADMAP
|
||||
- **@types in wrong dependency section** - Moved `@types/chokidar`, `@types/jsonwebtoken`, `@types/pg` to devDependencies
|
||||
|
||||
### Fixed (Phases 7-10, 2026-03-02)
|
||||
- **Centralized error handling** — ApiError class + Errors factory applied to all 50 controllers via asyncHandler
|
||||
- **Route consolidation** — Merged authNew→auth, deleted dead postsNew/postsController/postControllerUpdate
|
||||
- **Swagger/OpenAPI** — 6 new schemas, annotations on 5 route files
|
||||
- **Backend test infrastructure** — Mocked Prisma/Redis/auth/external services; 6 new test files (205+ tests)
|
||||
- **N+1 query fix** — analyticsController uses aggregate/count instead of findMany+JS reduce
|
||||
- **Redis cache** — Unified cacheMiddleware (Redis primary + in-memory fallback, X-Cache headers)
|
||||
- **WebSocket hardening** — Rate limiting, input validation, heartbeat config, map cleanup
|
||||
- **Health endpoints** — Extracted to /health, /health/ready, /health/db
|
||||
- **AITM CI** — Added api-server-tests job
|
||||
- **Structured logging** — console.log→logger in env-contract/index, request correlation IDs
|
||||
- **Monorepo tooling** — Root package.json (test:all, lint:all, build:all), shared ESLint/Prettier
|
||||
- **AITM Sentry** — @sentry/node integrated in api-server
|
||||
- **cli-v2.ts refactored** — Modularized from 4,381 LOC to 91 LOC (done in Phase 6)
|
||||
- **httpOnly cookies** — Already implemented; frontend uses withCredentials:true, localStorage only caches user metadata
|
||||
|
||||
### Fixed (Tasks 9-11, 2026-03-02)
|
||||
- **AITM API URL alignment** — corrected mismatched AITM routes in integration service (`/restore/projects`, `/time/diff`, `/context/:id`)
|
||||
- **Abuse detection on Redis** — all three abuse layers now use Redis-backed stores with in-memory fallback (`RedisSlidingWindow` + `RedisHashStore`)
|
||||
- **TypeScript strict mode** — Gitgram backend already runs with `strict: true` and compiles clean
|
||||
|
||||
### Remaining Issues (Not Yet Fixed)
|
||||
- Zero web/mobile tests
|
||||
- 839 uses of `any` in AITM
|
||||
- ~~Cross-product linking (posts <-> checkpoints)~~ — ✅ ALREADY BUILT: 7-step wizard (create-change-story), AitmChangeStoryCard renderer, aitmService API client, RepoAitmSettings, RepoCheckpointSection, CHANGE_STORY post type, checkpointRef field, webhook auto-generation
|
||||
163
PLAN.md
Normal file
163
PLAN.md
Normal file
@ -0,0 +1,163 @@
|
||||
# gitgram-ai Development Plan
|
||||
|
||||
Last updated: 2026-03-02
|
||||
|
||||
## Current State
|
||||
|
||||
Both products are feature-complete for v1 and compile/build clean. A monorepo cleanup session on 2026-03-02 resolved significant code hygiene debt. Neither product is publicly usable yet due to operational blockers.
|
||||
|
||||
### What Was Fixed (2026-03-02 Cleanup)
|
||||
|
||||
| Area | Change | Impact |
|
||||
|------|--------|--------|
|
||||
| Gitgram markdown clutter | Deleted 121 .md + 8 .txt status files | Repo is navigable |
|
||||
| AITM markdown clutter | Deleted 46 status .md files | Repo is navigable |
|
||||
| Legacy route duplication | Removed 17 `/api/` routes duplicating `/api/v1/` | Halved attack surface |
|
||||
| console.* sprawl | Replaced ~52 calls with Winston logger (10 files) | Structured logging |
|
||||
| socketService deprecation | Full migration to useSocket hook; service deleted | Clean React patterns |
|
||||
| @types misconfig | Moved 5 @types packages to devDependencies | Correct dependency graph |
|
||||
| AITM disk-full handling | Atomic write + ENOSPC catch in ContentStore.put() | Data safety |
|
||||
| MCP rate limiting | Sliding-window limiter (5-120/min per tool) | Abuse prevention |
|
||||
| API response helpers | sendSuccess/sendError/sendPaginated created | Consistency foundation |
|
||||
|
||||
### What Was Fixed (2026-03-02 Follow-up: Tasks #9-#11)
|
||||
|
||||
| Area | Change | Impact |
|
||||
|------|--------|--------|
|
||||
| AITM API URL alignment | Fixed mismatched endpoints in backend AITM service (`/restore/projects`, `/time/diff`, `/context/:id`) | Prevents integration 404s |
|
||||
| Abuse detection state | Migrated spam guard stores to `RedisHashStore` with in-memory fallback | Multi-instance readiness with dev safety fallback |
|
||||
| TypeScript strict mode | Confirmed `strict: true` in backend `tsconfig.json` and clean compile | Type-safety enforcement active |
|
||||
|
||||
### What's Still Broken
|
||||
|
||||
| Issue | Product | Severity | Est. Effort |
|
||||
|-------|---------|----------|-------------|
|
||||
| CLI/MCP not on npm | AITM | **Blocker** | 1-2 hours |
|
||||
| No production secrets configured | Both | **Blocker** | 2-4 hours |
|
||||
| localStorage for JWT tokens | Gitgram | High | 4-6 hours |
|
||||
| cli-v2.ts mega-file (4,381 LOC) | AITM | High | 4-6 hours |
|
||||
| Zero web/mobile tests | Gitgram | High | Multi-day |
|
||||
| 839 uses of `any` | AITM | High | 8-12 hours |
|
||||
| Cross-product linking | Both | Medium | Multi-week |
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Launch Unblockers (Next Session)
|
||||
|
||||
Goal: Make both products usable by real humans.
|
||||
|
||||
### 3.1 Publish AITM to npm (Blocker #1)
|
||||
- Verify `package.json` metadata (name, version, bin, files, repository)
|
||||
- Run `npm pack` and inspect tarball contents
|
||||
- Publish `aitimemachine` CLI to npm
|
||||
- Publish MCP server package to npm
|
||||
- Verify `npm install -g aitimemachine && aitm --version` works
|
||||
- Update website install instructions if needed
|
||||
|
||||
### 3.2 Configure production secrets (Blocker #2)
|
||||
- Create GitHub OAuth App (Client ID + Secret)
|
||||
- Create Google OAuth credentials
|
||||
- Set up Polar.sh keys (access token + webhook secret + product IDs)
|
||||
- Verify Resend email service (domain + API key)
|
||||
- Set up Clerk production instance for AITM
|
||||
- Set up Polar.sh billing keys for AITM
|
||||
- Configure Sentry DSNs for error tracking (both products)
|
||||
- Document all keys in `.env.example` files
|
||||
|
||||
### 3.3 Deploy infrastructure
|
||||
- Provision Hetzner VPS (run `deploy/setup-hetzner.sh`)
|
||||
- Configure Cloudflare DNS (gitgram.app, timemachine.gitgram.app, timemachine-api.gitgram.app)
|
||||
- Fill production `.env` files from templates
|
||||
- Run `docker compose -f docker-compose.prod.yml up -d`
|
||||
- Verify health endpoints respond
|
||||
- Set up UptimeRobot monitoring
|
||||
|
||||
### 3.4 End-to-end smoke test
|
||||
- AITM: `npm install -g` -> `aitm init` -> `aitm checkpoint` -> dashboard shows real data
|
||||
- Gitgram: signup -> GitHub OAuth -> create post -> comment -> notification
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Security Hardening (~1 week)
|
||||
|
||||
### 4.1 Migrate JWT storage to httpOnly cookies
|
||||
- Backend: Set tokens via `Set-Cookie` with `httpOnly`, `secure`, `sameSite=strict`
|
||||
- Frontend: Remove `localStorage.getItem('token')` pattern
|
||||
- Update API client to stop sending `Authorization` header (cookies auto-sent)
|
||||
- Update CORS config for credential passing
|
||||
- Test: full auth flow, refresh token rotation, logout
|
||||
|
||||
### 4.2 Move abuse detection to Redis (Completed 2026-03-02)
|
||||
- Replace in-memory Maps with Redis sorted sets
|
||||
- Key pattern: `abuse:{userId}:{action}` with TTL-based expiry
|
||||
- Works across multiple backend instances
|
||||
- Preserve existing threshold configs
|
||||
|
||||
### 4.3 Validate AITM callback URLs
|
||||
- Whitelist allowed OAuth redirect URIs
|
||||
- Reject open redirect attempts
|
||||
- Add state parameter CSRF validation to browser login flow
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Code Quality (~2 weeks)
|
||||
|
||||
### 5.1 Enable TypeScript strict mode in Gitgram backend (Completed 2026-03-02)
|
||||
- Set `strict: true` in `tsconfig.json`
|
||||
- Fix errors file-by-file (prioritize controllers > services > utils)
|
||||
- Target: eliminate 1,070 uses of `any`
|
||||
|
||||
### 5.2 Break up AITM cli-v2.ts
|
||||
- Create `src/commands/` directory
|
||||
- Extract each command group into its own module (checkpoint.ts, restore.ts, search.ts, etc.)
|
||||
- cli-v2.ts becomes a thin shell that registers commands
|
||||
- Target: no file > 300 LOC
|
||||
|
||||
### 5.3 Add frontend test coverage
|
||||
- Set up Vitest + Testing Library for Gitgram web
|
||||
- Write tests for auth flows, post creation, notification rendering
|
||||
- Set up Playwright for critical path E2E tests
|
||||
- CI: run tests on PR
|
||||
|
||||
### 5.4 Finish API response helper migration (AITM)
|
||||
- Apply `sendSuccess`/`sendError`/`sendPaginated` to all remaining routes
|
||||
- Remove ad-hoc response shapes
|
||||
- Update API docs/Swagger
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Cross-Product Integration (~3 weeks)
|
||||
|
||||
### 6.1 Link gitgram posts to AITM checkpoints
|
||||
- Add `checkpointRef` field to Gitgram Post model
|
||||
- Create "Change Story" post type (auto-generated from AITM diffs)
|
||||
- API: `POST /api/v1/posts` accepts optional `aitm_checkpoint_id`
|
||||
- UI: "Share as post" button in AITM timeline
|
||||
|
||||
### 6.2 Semantic search for AITM
|
||||
- Add embedding generation on checkpoint creation (OpenAI or local model)
|
||||
- Store embeddings in pgvector column
|
||||
- API: `POST /api/search/semantic` with cosine similarity ranking
|
||||
- CLI: `aitm search --semantic "when did I add auth?"`
|
||||
|
||||
### 6.3 AITM automatic GC
|
||||
- Schedule GC worker (daily cron)
|
||||
- Configurable retention: keep last N checkpoints, or last N days
|
||||
- Clean orphaned blobs after checkpoint deletion
|
||||
- User-facing storage usage dashboard
|
||||
|
||||
---
|
||||
|
||||
## Operational Checklist (Pre-Launch)
|
||||
|
||||
- [ ] npm packages published (aitimemachine, MCP server)
|
||||
- [ ] Production VPS provisioned and Docker running
|
||||
- [ ] DNS configured (both domains)
|
||||
- [ ] All production secrets in `.env`
|
||||
- [ ] Health endpoints verified (`/health` returns 200)
|
||||
- [ ] Error tracking live (Sentry)
|
||||
- [ ] Analytics live (PostHog or Plausible)
|
||||
- [ ] Uptime monitoring configured
|
||||
- [ ] SSL certificates active (Cloudflare)
|
||||
- [ ] Backup strategy for Postgres (Neon auto-backup or pg_dump cron)
|
||||
- [ ] End-to-end smoke test passes for both products
|
||||
307
PRIORITIZED_TICKETS_V1.md
Normal file
307
PRIORITIZED_TICKETS_V1.md
Normal file
@ -0,0 +1,307 @@
|
||||
# gitgram-ai Prioritized Engineering Tickets (v1)
|
||||
|
||||
Last updated: 2026-03-02
|
||||
Source: `SINGLE_SOURCE_PLAN.md`
|
||||
|
||||
## Conventions
|
||||
|
||||
- Priority: `P0` blocker, `P1` high, `P2` medium, `P3` growth
|
||||
- Estimate scale: `S` (0.5-1 day), `M` (1-3 days), `L` (3-5 days), `XL` (5+ days)
|
||||
- Owner is a role placeholder for assignment
|
||||
|
||||
## P0 - Launch Blockers
|
||||
|
||||
### GGAI-001 - Publish AITM CLI to npm
|
||||
- Priority: P0
|
||||
- Owner: AITM Backend Engineer
|
||||
- Estimate: M
|
||||
- Dependencies: None
|
||||
- Scope:
|
||||
- Verify CLI package metadata (`name`, `version`, `bin`, `files`, `repository`)
|
||||
- Run `npm pack` and inspect tarball
|
||||
- Publish package
|
||||
- Validate global install and command boot
|
||||
- Acceptance criteria:
|
||||
- `npm install -g <aitm-cli-package>` succeeds on clean environment
|
||||
- `aitm --version` returns published version
|
||||
- Package includes required runtime files and excludes local-only artifacts
|
||||
|
||||
### GGAI-002 - Publish AITM MCP server package to npm
|
||||
- Priority: P0
|
||||
- Owner: AITM Backend Engineer
|
||||
- Estimate: M
|
||||
- Dependencies: GGAI-001
|
||||
- Scope:
|
||||
- Verify package metadata and export entrypoints
|
||||
- Publish MCP server package
|
||||
- Validate install and startup command
|
||||
- Acceptance criteria:
|
||||
- MCP package installs from npm without local path assumptions
|
||||
- Server starts and responds to a health/ping call
|
||||
- Package README install instructions are accurate
|
||||
|
||||
### GGAI-003 - Configure production secrets for both products
|
||||
- Priority: P0
|
||||
- Owner: DevOps Engineer
|
||||
- Estimate: L
|
||||
- Dependencies: None
|
||||
- Scope:
|
||||
- Provision and store OAuth, billing, email, and error-tracking keys
|
||||
- Set secure values for Gitgram and AITM production environments
|
||||
- Align `.env.example` keys with actual runtime requirements
|
||||
- Acceptance criteria:
|
||||
- All required env vars exist in production secret store
|
||||
- Services boot without missing-env startup errors
|
||||
- `.env.example` files are complete and current
|
||||
|
||||
### GGAI-004 - Deploy production baseline infrastructure
|
||||
- Priority: P0
|
||||
- Owner: DevOps Engineer
|
||||
- Estimate: L
|
||||
- Dependencies: GGAI-003
|
||||
- Scope:
|
||||
- Provision VPS and system prerequisites
|
||||
- Configure DNS, TLS, and production compose stack
|
||||
- Configure uptime monitoring and baseline alerts
|
||||
- Acceptance criteria:
|
||||
- Public domains resolve correctly
|
||||
- SSL/TLS active for all public endpoints
|
||||
- `docker compose -f docker-compose.prod.yml up -d` stable with healthy services
|
||||
- Monitoring shows green status for required endpoints
|
||||
|
||||
### GGAI-005 - Execute end-to-end smoke verification
|
||||
- Priority: P0
|
||||
- Owner: QA Engineer
|
||||
- Estimate: M
|
||||
- Dependencies: GGAI-001, GGAI-002, GGAI-004
|
||||
- Scope:
|
||||
- Validate AITM install/init/checkpoint/timeline flow
|
||||
- Validate Gitgram signup/oauth/post/comment/notification flow
|
||||
- Record failures with logs and repro steps
|
||||
- Acceptance criteria:
|
||||
- Both critical user journeys pass end-to-end in production-like environment
|
||||
- No blocker-severity defects remain open
|
||||
- Smoke test checklist is documented and repeatable
|
||||
|
||||
## P1 - Security Closure
|
||||
|
||||
### GGAI-006 - Migrate Gitgram JWT handling to httpOnly cookies
|
||||
- Priority: P1
|
||||
- Owner: Gitgram Full-Stack Engineer
|
||||
- Estimate: L
|
||||
- Dependencies: GGAI-005
|
||||
- Scope:
|
||||
- Replace `localStorage` token flow with secure cookie flow
|
||||
- Update backend auth cookie issuance and frontend API client behavior
|
||||
- Update CORS and CSRF assumptions as needed
|
||||
- Acceptance criteria:
|
||||
- No auth token persistence in `localStorage`
|
||||
- Login, refresh, and logout flows pass in browser validation
|
||||
- Cookies set with `httpOnly`, `secure`, and `sameSite` policy
|
||||
|
||||
### GGAI-007 - Harden AITM OAuth callback and redirect validation
|
||||
- Priority: P1
|
||||
- Owner: AITM Backend Engineer
|
||||
- Estimate: M
|
||||
- Dependencies: GGAI-005
|
||||
- Scope:
|
||||
- Enforce allowlist for redirect URIs
|
||||
- Reject open redirects
|
||||
- Validate CSRF state parameter on OAuth callback path
|
||||
- Acceptance criteria:
|
||||
- Open redirect attempts are rejected
|
||||
- Missing/invalid state values fail safely
|
||||
- Valid OAuth flows remain functional across supported providers
|
||||
|
||||
### GGAI-008 - Complete AITM API response helper migration
|
||||
- Priority: P1
|
||||
- Owner: AITM Backend Engineer
|
||||
- Estimate: M
|
||||
- Dependencies: GGAI-005
|
||||
- Scope:
|
||||
- Apply `sendSuccess`, `sendError`, `sendPaginated` to remaining routes
|
||||
- Remove inconsistent ad-hoc response shapes
|
||||
- Update API docs/examples
|
||||
- Acceptance criteria:
|
||||
- All AITM API routes use standardized response helpers
|
||||
- Error/status structure is consistent across endpoints
|
||||
- API docs reflect final response contracts
|
||||
|
||||
### GGAI-009 - Validate retention/delete/export audit workflows
|
||||
- Priority: P1
|
||||
- Owner: Security Engineer
|
||||
- Estimate: M
|
||||
- Dependencies: GGAI-003, GGAI-008
|
||||
- Scope:
|
||||
- Execute staging tests for consent, retention policy, delete request, and export auditability
|
||||
- Confirm audit log completeness for restore/export/delete operations
|
||||
- Acceptance criteria:
|
||||
- Each data governance path has a passing test record
|
||||
- Audit logs contain actor, action, timestamp, and trace identifiers
|
||||
- No critical compliance gaps remain in staging checklist
|
||||
|
||||
## P2 - Reliability and Code Quality
|
||||
|
||||
### GGAI-010 - Refactor AITM cli-v2.ts into modular command architecture
|
||||
- Priority: P2
|
||||
- Owner: AITM Backend Engineer
|
||||
- Estimate: L
|
||||
- Dependencies: GGAI-005
|
||||
- Scope:
|
||||
- Extract command groups into `src/commands/*`
|
||||
- Keep root CLI file as registration/bootstrap shell
|
||||
- Preserve existing command UX and flags
|
||||
- Acceptance criteria:
|
||||
- No single CLI file exceeds 300 LOC target
|
||||
- CLI behavior remains backward compatible for existing commands
|
||||
- Build and command smoke tests pass
|
||||
|
||||
### GGAI-011 - Reduce unsafe `any` usage on AITM critical paths
|
||||
- Priority: P2
|
||||
- Owner: AITM Backend Engineer
|
||||
- Estimate: XL
|
||||
- Dependencies: GGAI-010
|
||||
- Scope:
|
||||
- Prioritize controllers and services for strict typing improvements
|
||||
- Introduce reusable DTO/types where repeated shapes exist
|
||||
- Avoid broad `as unknown as` type escapes
|
||||
- Acceptance criteria:
|
||||
- Significant reduction of `any` usage in controller/service directories
|
||||
- TypeScript strict build remains clean
|
||||
- No runtime regressions in checkpoint/restore/search flows
|
||||
|
||||
### GGAI-012 - Add Gitgram frontend unit/integration test stack
|
||||
- Priority: P2
|
||||
- Owner: Frontend Engineer
|
||||
- Estimate: L
|
||||
- Dependencies: GGAI-006
|
||||
- Scope:
|
||||
- Configure Vitest + Testing Library
|
||||
- Add tests for auth flows, post creation, notification rendering
|
||||
- Integrate into project scripts
|
||||
- Acceptance criteria:
|
||||
- Tests run in CI and local environments
|
||||
- Core flows have deterministic passing tests
|
||||
- Failures produce actionable output
|
||||
|
||||
### GGAI-013 - Add Playwright critical-path E2E and CI gate
|
||||
- Priority: P2
|
||||
- Owner: QA Engineer
|
||||
- Estimate: L
|
||||
- Dependencies: GGAI-012
|
||||
- Scope:
|
||||
- Implement E2E coverage for highest-risk user journeys
|
||||
- Add CI workflow gate for pull requests
|
||||
- Add retry/flakiness guardrails
|
||||
- Acceptance criteria:
|
||||
- PR CI blocks on E2E failure for protected branches
|
||||
- E2E suite covers login, posting, and timeline-critical flows
|
||||
- Flakiness is below agreed threshold
|
||||
|
||||
## P3 - Cross-Product Integration and Growth
|
||||
|
||||
### GGAI-014 - Add checkpoint reference field to Gitgram posts
|
||||
- Priority: P3
|
||||
- Owner: Gitgram Backend Engineer
|
||||
- Estimate: M
|
||||
- Dependencies: GGAI-005
|
||||
- Scope:
|
||||
- Add model/schema field for AITM checkpoint linkage
|
||||
- Extend create post API with optional checkpoint reference
|
||||
- Validate ownership and access permissions
|
||||
- Acceptance criteria:
|
||||
- Post creation accepts and stores valid checkpoint reference
|
||||
- Unauthorized checkpoint linkage attempts are rejected
|
||||
- API docs include new field contract
|
||||
|
||||
### GGAI-015 - Ship AITM "Share as Post" flow
|
||||
- Priority: P3
|
||||
- Owner: Full-Stack Engineer
|
||||
- Estimate: L
|
||||
- Dependencies: GGAI-014
|
||||
- Scope:
|
||||
- Add action in AITM timeline to publish linked content to Gitgram
|
||||
- Include metadata payload for checkpoint context and diff summary
|
||||
- Handle auth/session boundary between products
|
||||
- Acceptance criteria:
|
||||
- User can publish from AITM timeline to Gitgram in one flow
|
||||
- Published post contains valid checkpoint linkage and preview content
|
||||
- Error handling covers auth failure and unavailable target service
|
||||
|
||||
### GGAI-016 - Implement "Change Story" post type from AITM diffs
|
||||
- Priority: P3
|
||||
- Owner: Full-Stack Engineer
|
||||
- Estimate: L
|
||||
- Dependencies: GGAI-015
|
||||
- Scope:
|
||||
- Define post subtype and rendering format for before/after diff narratives
|
||||
- Generate summary payload from checkpoint diffs
|
||||
- Add UI treatment in feed and repository profile views
|
||||
- Acceptance criteria:
|
||||
- Change Story posts render with consistent schema and UI
|
||||
- Diff-backed story content links to source checkpoint data
|
||||
- Feed interactions (comment/react/share) work unchanged
|
||||
|
||||
### GGAI-017 - Launch unified trend ranking (GitHub + platform signals)
|
||||
- Priority: P3
|
||||
- Owner: Data Engineer
|
||||
- Estimate: L
|
||||
- Dependencies: GGAI-016
|
||||
- Scope:
|
||||
- Build ranking formula combining repository activity and social engagement
|
||||
- Add score computation job and API exposure
|
||||
- Add basic anti-gaming controls
|
||||
- Acceptance criteria:
|
||||
- Trending endpoint returns deterministic ranked results
|
||||
- Ranking inputs are documented and observable
|
||||
- No critical abuse vector in initial review
|
||||
|
||||
### GGAI-018 - Add AITM semantic search over code/checkpoint history
|
||||
- Priority: P3
|
||||
- Owner: AITM Backend Engineer
|
||||
- Estimate: XL
|
||||
- Dependencies: GGAI-011
|
||||
- Scope:
|
||||
- Generate embeddings at checkpoint creation
|
||||
- Store vectors and serve semantic retrieval API
|
||||
- Expose CLI/query interface for semantic search
|
||||
- Acceptance criteria:
|
||||
- Semantic query returns ranked relevant checkpoint results
|
||||
- Performance meets agreed p95 threshold for target corpus size
|
||||
- Relevance passes internal benchmark gate
|
||||
|
||||
### GGAI-019 - Implement training export pipeline with consent, redaction, audit
|
||||
- Priority: P3
|
||||
- Owner: Security Engineer
|
||||
- Estimate: XL
|
||||
- Dependencies: GGAI-009
|
||||
- Scope:
|
||||
- Enforce opt-in consent checks prior to export jobs
|
||||
- Run redaction pipeline before data leaves operational storage
|
||||
- Persist full export lineage and audit metadata
|
||||
- Acceptance criteria:
|
||||
- Exports fail closed without valid consent
|
||||
- Redaction pipeline executes and produces measurable precision/recall report
|
||||
- Every export has traceable consent ID and audit record
|
||||
|
||||
### GGAI-020 - Creator workflow tools for repository owners
|
||||
- Priority: P3
|
||||
- Owner: Product Engineer
|
||||
- Estimate: L
|
||||
- Dependencies: GGAI-016
|
||||
- Scope:
|
||||
- Add story/reel workflow tooling around code change events
|
||||
- Provide templates for explainable dev content
|
||||
- Instrument adoption analytics
|
||||
- Acceptance criteria:
|
||||
- Repo owners can create and publish creator-format content from product UI
|
||||
- Workflow usage metrics are captured and queryable
|
||||
- No regression in existing post creation flows
|
||||
|
||||
## Suggested Sprint Packaging
|
||||
|
||||
- Sprint 1: GGAI-001 to GGAI-005
|
||||
- Sprint 2: GGAI-006 to GGAI-009
|
||||
- Sprint 3: GGAI-010 to GGAI-013
|
||||
- Sprint 4+: GGAI-014 onward by product strategy and capacity
|
||||
|
||||
82
README.md
Normal file
82
README.md
Normal file
@ -0,0 +1,82 @@
|
||||
# gitgram-ai (Monorepo)
|
||||
|
||||
Two products:
|
||||
|
||||
1. `gitgram` (GitHub social network)
|
||||
2. `aitimemachine` (AITM, "Time Machine for AI coding")
|
||||
|
||||
This repo is organized as a monorepo for local development and ops docs. Each product has its own `README.md`, and the repo still contains historical automation artifacts that are not the launch source of truth.
|
||||
|
||||
## Quick Start (Local, Full Stack)
|
||||
|
||||
Runs Postgres + Redis + Gitgram backend + Gitgram web + AITM API via Docker Compose.
|
||||
|
||||
```bash
|
||||
docker compose up
|
||||
```
|
||||
|
||||
Service URLs (when running the full stack together):
|
||||
- Gitgram web: `http://localhost:3000`
|
||||
- Gitgram backend: `http://localhost:4000` (`GET /health`)
|
||||
- AITM API: `http://localhost:3001` (`GET /health`)
|
||||
|
||||
Notes:
|
||||
- AITM website is not started by the root `docker-compose.yml` (to avoid port conflicts with Gitgram web). Run it separately if needed.
|
||||
- AITM database defaults to whatever `aitimemachine/api-server/.env` provides (`DATABASE_URL`). In production, use Neon; locally you can use a local Postgres if you want.
|
||||
|
||||
## Start AITM Website Locally
|
||||
|
||||
When Gitgram web is already on `:3000`, run AITM website on `:3002`:
|
||||
|
||||
```bash
|
||||
cd aitimemachine/website
|
||||
cp .env.example .env.local
|
||||
PORT=3002 npm run dev
|
||||
```
|
||||
|
||||
Open `http://localhost:3002`.
|
||||
|
||||
## Production Compose (Single VPS)
|
||||
|
||||
Use `docs/runbook.md` as the canonical manual launch contract.
|
||||
|
||||
`docker-compose.prod.yml` is retained as a non-canonical full-docker reference, not the launch source of truth.
|
||||
|
||||
## Release Gates
|
||||
|
||||
Run these before staging/production deploys:
|
||||
|
||||
```bash
|
||||
npm run verify:aitm-packages
|
||||
npm run verify:aitm-local
|
||||
npm run verify:secrets:staging
|
||||
npm run verify:secrets:production
|
||||
```
|
||||
|
||||
AITM API local startup without external secret keys:
|
||||
|
||||
```bash
|
||||
npm run verify:aitm-local
|
||||
npm run dev:aitm-api:clean
|
||||
```
|
||||
|
||||
Stage A local smoke gate:
|
||||
|
||||
```bash
|
||||
npm run smoke:local-launch
|
||||
```
|
||||
|
||||
Optional flags:
|
||||
- `SKIP_HTTP=1 npm run smoke:local-launch`
|
||||
- `AUTO_START=1 npm run smoke:local-launch`
|
||||
- `RUN_AITM_CLI_SMOKE=1 npm run smoke:local-launch`
|
||||
- `RUN_AITM_MCP_SMOKE=1 npm run smoke:local-launch`
|
||||
|
||||
## Docs Index
|
||||
|
||||
- Strict execution queue: `REMAINING.md`
|
||||
- North star PRD/architecture: `NORTH_STAR_PRD_ARCHITECTURE_V1.md`
|
||||
- Manual launch runbook: `docs/runbook.md`
|
||||
- Deploy pipeline contract: `docs/deploy-pipeline.md`
|
||||
- Env var matrix: `docs/environment-matrix.md`
|
||||
- Secrets contract: `docs/secrets-contract.md`
|
||||
146
REMAINING.md
Normal file
146
REMAINING.md
Normal file
@ -0,0 +1,146 @@
|
||||
# V1 Strict Execution Queue
|
||||
|
||||
Status legend: `DONE`, `IN_PROGRESS`, `TODO`, `BLOCKED`
|
||||
Ordering rule: highest dependency + launch risk first, then product acceleration.
|
||||
|
||||
## Queue (Strict Order)
|
||||
|
||||
1. `DONE` **[#20] Tenant isolation enforcement + tests across all data access paths**
|
||||
- Depends on: none
|
||||
- Why first: hard security gate for all products.
|
||||
- Progress: scoped reads/writes/events/stats and tree-storage isolation in sqlite_repo.ts. Finalized with 41 new tests in `tenant-isolation.test.ts` covering cloud sync paths (9), export paths (9), local API server routes (6), 15+ additional route file auth verification (14), and complete route coverage matrix (3).
|
||||
|
||||
2. `DONE` **[#21] Enforce org/project consent policies on every capture/export path**
|
||||
- Depends on: #20
|
||||
- Progress: consent enforcement on all capture/export paths with `assertConsent` + `handleApiError`. Cloud route stack enforces consent on writes and reads. Tests: `tests/consent-policy.test.ts`, `tests/consent-export-gates.test.ts`, `tests/api-server-authz.test.ts`, plus e2e pipeline test `tests/consent-pipeline-e2e.test.ts` (7 tests covering full denial, mid-pipeline revocation, selective consent, CloudSync blocking).
|
||||
|
||||
3. `DONE` **[#25] Formal authz/security review and close bypass findings**
|
||||
- Depends on: #20, #21
|
||||
- Progress: closed all high-risk API authz bypasses. Finalized with 10 new test cases in `api-server-authz.test.ts` covering cloud mutation (7 POST), cloud read (7 GET), sync/neon (5 POST), search sub-routes, timeline sub-routes, diff routes, internal API secret enforcement, public route accessibility, and consent route auth requirements.
|
||||
|
||||
4. `DONE` **[#24] Deletion/retention SLA metrics + alerting**
|
||||
- Depends on: #21
|
||||
- Progress: retention SLA evaluator with JSONL persistence, API endpoints (`/api/retention/sla`, `/api/retention/alerts`), CLI surface. 30 tests in `aitimemachine/tests/retention-sla-complete.test.ts` covering all 4 threshold types, multi-violation, env config, persistence, API response shape, checks structure.
|
||||
|
||||
5. `DONE` **[#23] Export traceability guarantees (consent ID + audit ID linkage 100%)**
|
||||
- Depends on: #21
|
||||
- Progress: strict export trace linkage (`exportId`, `consentSnapshotId`, `auditId`) integrated into all export entrypoints. 12 tests in `aitimemachine/tests/export-traceability-complete.test.ts` covering non-null fields, per-exporter trace validation, audit entries, deterministic consent snapshots.
|
||||
|
||||
6. `DONE` **[#22] Training export pipeline + redaction precision/recall measurement**
|
||||
- Depends on: #21, #23
|
||||
- Progress: redaction benchmark harness, privacy-redactor with P/R/F1 metrics, CI gate. 26 tests in `aitimemachine/tests/training-export-e2e.test.ts` covering e2e export+redaction, 18 PrivacyRedactor edge cases (API keys, emails, IPs, credit cards, JWTs, SSH keys), 5 benchmark custom sample tests.
|
||||
|
||||
7. `DONE` **[#26] Licensing/compliance guardrails for repo ingest + dataset export**
|
||||
- Depends on: #21, #22
|
||||
- Progress: SPDX license policy engine with dual-license OR/AND semantics, integrated into all export+ingest paths, compliance API endpoint. Enhanced `license-policy.ts` with `dualLicenseClasses` support. 60+ tests in `aitimemachine/tests/license-compliance-e2e.test.ts` covering unknown licenses, dual-license SPDX expressions, license changes, LICENSE file detection, restrictive blocking, all SPDX classifications, endpoint structure, legacy npm formats.
|
||||
|
||||
8. `DONE` **[#3] Implement canonical checkpoint tree storage (trees, not only blobs/checkpoints/diffs)**
|
||||
- Depends on: none
|
||||
- Progress: canonical tree persistence, wired into CLI/MCP. 7 tests including traversal, hash integrity, round-trip, deduplication.
|
||||
|
||||
9. `DONE` **[#4] Deterministic restore correctness tests for large/edge project states**
|
||||
- Depends on: #3
|
||||
- Progress: 51 tests across 3 files: `restore-correctness.test.ts` (16 tests - 150+ files, binary, symlinks, idempotency, deep nesting), `restore-edge-cases.test.ts` (18 tests - concurrent mods, CAS failures, round-trips, empty manifests), `restore-integrity.test.ts` (17 tests - hash verification, permissions, timestamps, audit trails, stress integrity).
|
||||
|
||||
10. `DONE` **[#9] End-to-end verification for before/after action chain integrity**
|
||||
- Depends on: #3, #4
|
||||
- Progress: added action-chain verifier (`aitimemachine/src/tools/action-chain-integrity.ts`) with checks for missing links, self-links, prefix mismatches, temporal ordering, event-link mismatches, and chain cycles. Added CLI surface `aitm verify-action-chains` in `aitimemachine/src/cli.ts` (supports `--project`, `--limit`, `--json`, exits non-zero on integrity failures). 12 tests in `aitimemachine/tests/action-chain-integrity.test.ts` covering broken chains, CLI exit codes.
|
||||
|
||||
11. `DONE` **[#7] Restore performance tuning to hit latency SLOs**
|
||||
- Depends on: #4
|
||||
- Progress: optimized restore validation hot path in `aitimemachine/src/core/restore.ts` to use CAS existence checks (`cas.has`) instead of fully loading each blob. 6 tests with SLO benchmarks (P95<=2s/10s) in `aitimemachine/tests/restore-validation-performance.test.ts`.
|
||||
|
||||
12. `DONE` **[#8] Retry/resume flow for failed restores with user diagnostics**
|
||||
- Depends on: #4, #11
|
||||
- Progress: `restoreWorkspaceWithRetry` with exponential backoff, diagnostics JSON, `resumeRestoreFromLatestTmp` with validation, `listRestoreDiagnostics` + `getRestoreDiagnosticsSummary`, CLI `aitm restore-diagnostics`. 22 tests covering resume, backoff, diagnostics schema, edge cases.
|
||||
|
||||
13. `DONE` **[#10] Benchmark dashboards (restore success, latency p95/p99, diff latency)**
|
||||
- Depends on: #4, #11
|
||||
- Progress: benchmark metrics pipeline (`aitimemachine/src/core/benchmark-metrics.ts`) with JSONL events, percentile calculations, dashboard aggregation. CLI `aitm benchmark-dashboard` command. 14 tests covering percentile accuracy and aggregation in `aitimemachine/tests/benchmark-metrics.test.ts`.
|
||||
|
||||
14. `DONE` **[#5] Semantic search relevance benchmark harness + acceptance thresholds**
|
||||
- Depends on: baseline search implementation
|
||||
- Progress: benchmark harness (`aitimemachine/src/core/search-relevance-benchmark.ts`) with top1/MRR/recall@3 metrics, env thresholds, CLI command `aitm search-relevance-benchmark`. 11 tests in `aitimemachine/tests/search-relevance-benchmark.test.ts` + CI gate in `aitimemachine/tests/search-relevance-gate.test.ts`.
|
||||
|
||||
15. `DONE` **[#1] Timeline UI with human-readable events + scoped filters**
|
||||
- Depends on: timeline API/filter readiness
|
||||
- Progress: timeline dashboard with humanized events, scoped filters, server-side propagation. Finalized with 40+ new action gerunds in utils.ts, enhanced trigger type labels (before/after AI, deploy, ci, webhook), keyboard shortcuts (1-5 filters, L linked, F expand, / search, R refresh, Esc close, ? help), FilteredEmptyState with contextual messages, polished TimelineSkeleton matching actual layout.
|
||||
|
||||
16. `DONE` **[#2] Restore preview UX + explicit confirm-before-apply flow**
|
||||
- Depends on: restore preview API reliability
|
||||
- Progress: finalized 3-step restore flow: Step 1 (preview with file stats + type icons), Step 2 (expandable per-file diff viewer + restore reason), Step 3 (warning panel + confirmation checkbox + typed RESTORE token), plus success animation screen. Visual step indicator, back/cancel navigation, enhanced loading/error states.
|
||||
|
||||
17. `DONE` **[#6] Checkpoint-linked context replay UX (messages + tool calls)**
|
||||
- Depends on: context retrieval API completeness
|
||||
- Progress: finalized with message threading (groupIntoThreads, ThreadedConversationView, MessageThread, ToolCallSequence, CheckpointMarkerInline), threaded/panel view toggle, ContextStatsBar (6 metrics), enhanced ToolCallViewer (duration display, args summary, 3-state status, file type icons, read file support), richer mock data (5 messages, 7 tool calls), share toast, polished loading/error/empty states.
|
||||
|
||||
18. `DONE` **[#13] Media pipeline hardening (validation, transcoding, abuse controls, lifecycle)**
|
||||
- Depends on: base composer APIs
|
||||
- Progress: hardened upload routes with media validation + rate limiting. Finalized with 51 tests in `mediaPipelineHardening.test.ts` (802 lines) covering media lifecycle management (15), transcoding config validation (5), abuse content size/MIME limits (7), magic byte + content validation (14), scheduler integration (4), and upload route hardening static analysis (6).
|
||||
|
||||
19. `DONE` **[#14] Moderation workflow (report, review queue, enforcement actions)**
|
||||
- Depends on: #13
|
||||
- Progress: full moderation system with enforcement service (warn/remove/suspend/ban + appeal reversal), auto-moderation pipeline (hate speech, spam, NSFW detection with dual thresholds), `ModerationAppeal` Prisma model, user suspension fields, priority/escalation on reports, 11 API endpoints, admin dashboard with review queue/stats/activity tabs, wired into post/comment/reel creation. Frontend moderation dashboard at `web/app/admin/moderation/page.tsx`.
|
||||
|
||||
20. `DONE` **[#19] Anti-spam/rate-limit policy + abuse detection gates**
|
||||
- Depends on: #13, #14
|
||||
- Progress: implemented first enforcement slice in Gitgram moderation/report flows by adding dedicated per-user rate-limit tiers (`REPORTS`, `APPEALS`, `MODERATION_ACTIONS`) in `backend/src/config/rateLimitConfig.ts`, exporting new tiered middleware gates in `backend/src/middleware/tieredRateLimiter.ts`, and wiring them into report/appeal/moderation action routes (`backend/src/routes/reports.ts`, `backend/src/routes/admin.ts`). Extended abuse/rate-limit gates to additional report ingress routes (`backend/src/routes/posts.ts`, `backend/src/routes/reels.ts`, `backend/src/routes/messages.ts`, `backend/src/routes/privacy.ts`) and added spam checks for report/appeal text payloads in `backend/src/middleware/antiSpamMiddleware.ts` (including body-param target ID support). Fixed IPv6-safe rate-limit keying in `backend/src/middleware/rateLimiter.ts` to close express-rate-limit bypass warnings. Added persistent abuse telemetry (`backend/src/services/abuseTelemetryService.ts`) and wired violation/restriction/rate-limit/spam events into abuse middleware/services; exposed admin abuse counters via `GET /api/v1/admin/abuse/stats` and incidents feed `GET /api/v1/admin/abuse/incidents` in `backend/src/routes/admin.ts`. Added runtime-tunable abuse policy controls in `backend/src/services/abuseDetectionService.ts` and admin config endpoints (`GET/PUT /api/v1/admin/abuse/config`, `POST /api/v1/admin/abuse/config/reset`) with validation in `backend/src/validators/adminValidator.ts`. Added focused route-contract coverage for abuse admin paths in `backend/tests/adminAbuseRoutesAuthzValidation.test.ts` (`401/403/400/200` across config, reset, status, override endpoints).
|
||||
|
||||
21. `DONE` **[#15] Trending ranking quality tuning (signal weighting + anti-gaming)**
|
||||
- Depends on: baseline trending signals
|
||||
- Progress: hardened ranking governance and anti-gaming correctness in Gitgram backend by enforcing admin-only access on trending signal config endpoints (`GET/PUT /api/v1/trending/config*`) via role checks in `backend/src/routes/trending.ts`, and fixed anti-gaming penalty mapping so `burst_comments` uses `postComments` penalty weight (instead of likes weight) in `backend/src/services/trendingScoring.ts`. Added focused coverage in `backend/tests/trendingConfigRouteAuthz.test.ts` (`401/403/200` authz assertions) and `backend/tests/trendingScoring.test.ts` (penalty-weight correctness and cap behavior).
|
||||
|
||||
22. `DONE` **[#18] Search/discovery UX for trending repositories and creators**
|
||||
- Depends on: #21
|
||||
- Progress: 3 pages fully rewritten - `trending/page.tsx` (924 lines: Hot Now/Today/Week/Rising tabs, language+topic filters, repo/creator/post grids, infinite scroll), `search/page.tsx` (917 lines: auto-suggestions, trending searches, recent history, parallel multi-type search, filter chips), `explore/page.tsx` (590 lines: featured repos, personalized recommendations, category browsing, language filters). Plus scoped discovery at `explore/repos/page.tsx`.
|
||||
|
||||
23. `DONE` **[#17] Follow/follower and engagement analytics surfaces**
|
||||
- Depends on: baseline follow/interaction events
|
||||
- Progress: completed end-to-end analytics surface reliability by fixing API client pathing in `gitgram/web/services/analyticsService.ts` (migrated broken `/api/v1/*` calls to `/v1/*` against shared API base), so follower/engagement/content dashboards resolve correctly. Added route-level authz/validation hardening for user-specific analytics in `gitgram/backend/src/routes/userAnalytics.ts` with new validators in `gitgram/backend/src/validators/userAnalyticsValidator.ts` (`days`/`limit` bounds + `userId` checks) and focused route contract tests in `gitgram/backend/tests/userAnalyticsRoutesAuthzValidation.test.ts` (`401/400/200` assertions).
|
||||
|
||||
24. `DONE` **[#11] Repository profile UX (feed, media, interactions, checkpoint-linked posts)**
|
||||
- Depends on: none
|
||||
- Progress: backend pagination + snippets/media endpoints + tests. Frontend: RepoHero (topics, watchers), 6-tab nav (Feed/Media/Snippets/Activity/About/Settings), RepoSnippetsTab (language badges, code preview, infinite scroll), RepoActivityTab (GitHub timeline, AITM stories, filters), RepoCheckpointSection (diff stats, connector lines), Star+Share buttons.
|
||||
|
||||
25. `DONE` **[#12] Post/reel/story creation UX (screenshots/video/code snippets)**
|
||||
- Depends on: none
|
||||
- Progress: unified ContentComposer with POST/REEL/STORY tabs, MediaUploader (drag-and-drop), MediaPreview (multi-image carousel, video), CodeSnippetEditor (24 languages), RepoLinker (search + URL paste), SchedulePicker, DraftManager (auto-save + resume), DropZone. Updated create/story/post pages.
|
||||
|
||||
26. `DONE` **[#16] Repo-owner change-story workflow from AITM diffs**
|
||||
- Depends on: #11, #12
|
||||
- Progress: 7-step wizard at `web/app/create-change-story/page.tsx`, AITM API client (`web/services/aitmService.ts`), backend change story service with AES-256 key encryption + webhook auto-generation, `RepositoryAitmSettings` Prisma model, `Post.status` field (DRAFT/PUBLISHED), enhanced `AitmChangeStoryCard` component, repo settings UI for AITM integration, 3 AITM settings CRUD routes, change-stories webhook + publish routes.
|
||||
|
||||
27. `DONE` **[#27] Finalize production CI gates (build, migrations, service tests, integration-safe tests, smoke tests)**
|
||||
- Depends on: none
|
||||
- Progress: 4 workflow files across both products. Gitgram: ci.yml (9 jobs + gate), pr-check.yml (4 jobs). AITM: ci.yml (14 jobs + gate + release), pr-check.yml (6 jobs). Covers lint, tsc, build, Prisma/Drizzle migration validation, unit/integration tests, OpenAPI validation, redaction/search gates, smoke tests, Node 18/20 matrix.
|
||||
|
||||
28. `DONE` **[#28] Environment matrix + secrets contract for both products**
|
||||
- Depends on: #27
|
||||
- Progress: completed cross-product environment/secrets contract documentation with unified index `docs/environment-matrix.md`, product matrices in `gitgram/backend/ENV_MATRIX.md` + `aitimemachine/ENV_MATRIX.md`, and shared secret ownership/rotation contract in `docs/secrets-contract.md`.
|
||||
|
||||
29. `DONE` **[#29] Deploy pipeline for API + workers with rollback policy**
|
||||
- Depends on: #27, #28
|
||||
- Progress: completed deploy/rollback contract with product pipelines in `gitgram/.github/workflows/deploy.yml` and `aitimemachine/.github/workflows/deploy.yml` (pre-deploy gates, health checks, automatic rollback on failed gates, API+worker coverage), and added unified policy/runbook in `docs/deploy-pipeline.md`.
|
||||
|
||||
30. `DONE` **[#30] Managed scheduling wiring for retention/delete workers in production infra**
|
||||
- Depends on: #29
|
||||
- Progress: zero-dep cron scheduler with distributed locks, GC worker (stale checkpoint files + orphaned blobs), retention/delete/gc workers registered with configurable cron schedules, worker status API endpoints, opt-in via ENABLE_WORKERS=true, comprehensive tests. Production deploy wiring now enforces scheduler env propagation and worker health gates in `aitimemachine/.github/workflows/deploy.yml` (checks `GET /v1/workers/status` and rolls back on worker health failure), with contract updates in `aitimemachine/.env.example`, `aitimemachine/ENV_MATRIX.md`, and `docs/deploy-pipeline.md`.
|
||||
|
||||
31. `DONE` **[#31] Full OpenAPI contract validation in CI against implemented routes**
|
||||
- Depends on: #27
|
||||
- Progress: OpenAPI specs for both products (`aitimemachine/api-server/docs/openapi.yaml`, `gitgram/backend/docs/openapi.yaml`), route coverage validator (`scripts/validate-openapi-routes.ts`), spec structure validator (`scripts/validate-openapi-spec.ts`), CI integration.
|
||||
|
||||
32. `DONE` **[#32] Neon production verification job (schema probes + health probes + migration drift checks)**
|
||||
- Depends on: #27, #28
|
||||
- Progress: db-health.ts (connection, latency, replication, schema probes for 38 tables, migration drift), verify-neon.ts + verify-gitgram-db.ts standalone scripts, daily GitHub Actions workflow, GET /health/db + /health/schema endpoints, tests.
|
||||
|
||||
33. `DONE` **[#33] Unified cross-product runbook (Gitgram + AITM ops/incident/launch checklist)**
|
||||
- Depends on: #27, #29, #30, #31, #32
|
||||
- Progress: `docs/runbook.md` (1345 lines) covering service inventory, ops procedures, DB migration, backup/restore, health checks, worker management, P0-P3 incident response, launch checklist, maintenance. Plus `docs/ops-quickref.md` (247 lines) quick-reference card.
|
||||
|
||||
## Current Totals
|
||||
|
||||
- `IN_PROGRESS`: 0
|
||||
- `TODO`: 0
|
||||
- `DONE`: 33
|
||||
- `BLOCKED`: 0
|
||||
953
SINGLE_SOURCE_PLAN.md
Normal file
953
SINGLE_SOURCE_PLAN.md
Normal file
@ -0,0 +1,953 @@
|
||||
# gitgram-ai Single Source Plan (v1)
|
||||
|
||||
Last updated: 2026-06-21
|
||||
|
||||
## The Mission
|
||||
|
||||
Git is 20 years old. GitHub is a web UI bolted on top.
|
||||
Neither was built for AI agents generating 35 PRs a day,
|
||||
social-first development, or deterministic workflow restore.
|
||||
|
||||
**Gitgram = new GitHub.** Every repository is a social profile:
|
||||
posts, reels, stories, team photos, product videos, screenshots —
|
||||
code and community in one place, like Instagram/TikTok for devs.
|
||||
|
||||
**AITM = new Git.** AI-native, time-travel version control
|
||||
that handles agents at scale and makes open source great again.
|
||||
|
||||
See `INTEGRATION_PLAN.md` for how the 8 cloned external repos
|
||||
get merged into the actual product source trees.
|
||||
|
||||
Launch operations note (2026-05-09):
|
||||
- The canonical launch contract is now the manual single-host runbook in `docs/runbook.md`.
|
||||
- Historical references in this file to Vercel, Railway, or unfinished GitHub deploy workflows should be treated as planning notes, not launch instructions.
|
||||
|
||||
Reference intake note (2026-05-12):
|
||||
- `docs/can be fork.md` is the maintained reference-clone inventory for external upstream repos under `external/`.
|
||||
- Launch-critical external reference adoption is complete; this file remains the canonical execution plan.
|
||||
|
||||
## 1) Purpose
|
||||
|
||||
This document is the canonical execution plan for v1. It merges:
|
||||
- Product/architecture decisions from `NORTH_STAR_PRD_ARCHITECTURE_V1.md`
|
||||
- Delivery sequencing from `PLAN.md`
|
||||
|
||||
If any document conflicts with this one, this plan wins for implementation order.
|
||||
|
||||
## 2) Product Scope (Locked)
|
||||
|
||||
Products:
|
||||
- `gitgram`: repository-first social network for developers (posts, reels, stories, comments, reactions, follows, trending).
|
||||
- `aitimemachine` (AITM): deterministic restore and timeline system for AI coding workflows.
|
||||
|
||||
Out of scope for v1:
|
||||
- Enterprise SSO/SAML hardening beyond scaffolding.
|
||||
- Autonomous research/oracle workflows as primary UX.
|
||||
- Private repo ingest without explicit legal and security controls.
|
||||
|
||||
## 3) Architecture and Policy Decisions (Locked)
|
||||
|
||||
1. Source of truth:
|
||||
- Backend DB + object storage are authoritative.
|
||||
- Local `.aitimemachine/` is cache/offline buffer only.
|
||||
|
||||
2. Storage model:
|
||||
- `blobs`, `trees`, `checkpoints`, precomputed `diffs`, plus linked `messages`, `tool_calls`, `contexts`.
|
||||
|
||||
3. Capture model per AI action:
|
||||
- `before_action` checkpoint.
|
||||
- tool call metadata + initiating message link.
|
||||
- `after_action` checkpoint.
|
||||
- diff generation/classification.
|
||||
- optional async indexing/embeddings.
|
||||
|
||||
4. Privacy and training:
|
||||
- Training export is opt-in per workspace/org.
|
||||
- Default is operational capture only.
|
||||
- Redaction required before export.
|
||||
|
||||
5. Security minimums:
|
||||
- Tenant isolation.
|
||||
- Scoped auth and per-project authorization.
|
||||
- Encryption at rest/in transit.
|
||||
- Audit logs for restore/export/delete.
|
||||
- Retention + hard-delete workflows.
|
||||
- PII/secret redaction before training export.
|
||||
|
||||
## 4) Current State (As of 2026-03-17)
|
||||
|
||||
- Both products are **fully implemented, compiled, tested, and production-ready** at the code level.
|
||||
- All core features verified end-to-end (see Section 4a and 4b below).
|
||||
- Payment provider migrated from Stripe to Polar.sh (Stripe unavailable in Turkey).
|
||||
- Only deployment/infrastructure work remains for launch.
|
||||
|
||||
### Completed (prior to 2026-03-02):
|
||||
- Route duplication removed in Gitgram.
|
||||
- Socket service migration completed.
|
||||
- Logging standardized with Winston.
|
||||
- API response helper foundation added in AITM.
|
||||
- Disk-full handling added in AITM ContentStore writes.
|
||||
- MCP rate limiting added.
|
||||
- Abuse detection moved to Redis-backed store (with fallback).
|
||||
- AITM backend URL alignment fixes completed.
|
||||
- TypeScript strict mode confirmed in both backends.
|
||||
|
||||
### Completed (2026-03-02 to 2026-03-09):
|
||||
|
||||
**Rebranding & Core Fixes:**
|
||||
- AITM rebranded from legacy "gitmind" references across CLI, API server, extensions.
|
||||
- CLI modularized from monolithic `cli-v2.ts` into per-command files under `src/cli/`.
|
||||
- MCP server consolidated from 3 separate packages into single unified package.
|
||||
- AITM API server error responses standardized via `wrapErrorMessage()` middleware.
|
||||
|
||||
**Test Coverage (1130+ tests, all passing):**
|
||||
- AITM Core: 520/520 (35 suites) — CLI commands, smart-restore, core engine.
|
||||
- AITM API Server: 538/538 + 19 skip (45 suites) — all integration/service tests.
|
||||
- AITM VS Code Extension: 62/62.
|
||||
- Gitgram Web: 72/72 (7 suites) — auth, post, user, component tests.
|
||||
- Test infrastructure: fixed supertest/listen mock conflict, fixed error format across 18 test files.
|
||||
|
||||
**Security Hardening:**
|
||||
- Advertisement endpoints: added rate limiting, UUID validation, ad-exists check before tracking.
|
||||
- Advertisement creation: added input validation (URL, budget, type, dates, content length).
|
||||
- Repository claim: added GitHub ownership verification via Octokit permissions check.
|
||||
- Webhook signature: fixed timing-unsafe comparison to use `crypto.timingSafeEqual`.
|
||||
- Gitgram auth already uses httpOnly cookies (JWT primary method).
|
||||
- AITM OAuth: CSRF state tokens verified in SSO tests.
|
||||
|
||||
**Type Safety:**
|
||||
- AITM API server `db` export: fixed root cause `any` → `NeonHttpDatabase<typeof schema>` (eliminated ~30 implicit any errors).
|
||||
- Fixed 21 explicit `any` types in AITM services (retention, webhookDelivery, sessionManager, data-pipeline).
|
||||
- Fixed `any` types in Gitgram paymentService, aitmService, mobile storeService, messages, notifications.
|
||||
- All type checks pass with zero errors across all products.
|
||||
|
||||
**Bug Fixes:**
|
||||
- Mobile store: fixed call to non-existent `getProducts()` → `getItems()`.
|
||||
- Mobile create post: replaced stubbed console.log handler with real `postService.createPost`.
|
||||
- Docker: fixed postgres version, port mappings, added missing env vars to AITM Dockerfile.
|
||||
- Removed dead code (unused `mock.ts` service file).
|
||||
|
||||
**CI/CD (already in place):**
|
||||
- 7 GitHub Actions workflows: ci.yml, tests.yml, integration-tests.yml, smoke-tests.yml, migrations.yml, verify-production-db.yml, openapi-validation.yml.
|
||||
- `.env.example` files for all products (root + per-package).
|
||||
|
||||
### Completed (2026-03-17):
|
||||
|
||||
**Payment Migration:**
|
||||
- Stripe → Polar.sh across entire codebase (backend, frontend, mobile, docs).
|
||||
- `@polar-sh/sdk@0.46.4` replaces `stripe` package.
|
||||
- Webhook verification uses `validateEvent` from `@polar-sh/sdk/webhooks` (Standard Webhooks spec).
|
||||
- Prisma schema: `stripeCustomerId`/`stripeSubscriptionId` → `polarCustomerId`/`polarSubscriptionId`.
|
||||
- Env vars: `POLAR_ACCESS_TOKEN`, `POLAR_WEBHOOK_SECRET`, `POLAR_PREMIUM_PRODUCT_ID`, `POLAR_CREATOR_PRODUCT_ID`, `POLAR_MODE`.
|
||||
|
||||
### Completed (2026-05-12):
|
||||
|
||||
**Payment Launch Alignment From Local Polar Source:**
|
||||
- Added `docs/polar-payment-setup.md` using the cloned `external/polar` docs/source as the billing reference.
|
||||
- Confirmed service integrations should use Polar Organization Access Tokens, not OAuth/OpenID Connect.
|
||||
- Confirmed sandbox and production are isolated, and both Gitgram and AITM now honor `POLAR_MODE`.
|
||||
- AITM website billing routes now share a `POLAR_MODE`-aware Polar client instead of assuming one environment.
|
||||
- AITM API webhook verification now uses the SDK validator path and accepts both camelCase and snake_case event fields.
|
||||
- Gitgram backend webhook handling now uses the SDK validator flow through a CommonJS-compatible wrapper instead of ad hoc event-field assumptions.
|
||||
- AITM API env validation now includes `POLAR_MODE`, and remaining env examples were updated to document it.
|
||||
- `npm run verify:launch` is back to failing only on real missing secrets / placeholder values, not on Polar contract mismatches.
|
||||
- Launch tooling now supports env-specific operator files such as `.env.gitgram.staging` and `.env.aitm-api.staging`, so staging can use Polar sandbox values without conflicting with production `POLAR_MODE=production`.
|
||||
- Dedicated Neon databases now exist for Gitgram and AITM staging/production, and the root env files now contain real DB URLs plus generated app-owned secrets instead of placeholders.
|
||||
- Launch readiness is now split into `core` versus `full` integration gates, so deployability is no longer blocked on GitHub OAuth, Polar, Resend, or Sentry being configured on day zero.
|
||||
|
||||
### Completed (2026-05-13):
|
||||
|
||||
**Reference Clone Adoption Into Product Code:**
|
||||
- Gitgram adopted `external/repo2txt` / `external/repo-to-text` into a shipped repo-to-text surface: backend export endpoint, short-path text page, raw text route, queryable export sizing, and discovery-surface `Text` / `Raw` links.
|
||||
- Gitgram web now has real Playwright coverage for the public repo-routing and repo-to-text surface: short-path `/:owner/:repo`, legacy `github/.../text` canonicalization, queryable export sizing, and repo-page → text-view navigation.
|
||||
- AITM MCP adopted `external/a2a-js` into a real A2A contract layer: canonical `message/send` handling with legacy `tasks/send` compatibility, protocol-versioned agent cards, spec-shaped task responses, and a repeatable `scripts/a2a-smoke-test.sh` verification path.
|
||||
- AITM MCP adopted the core `external/pal-mcp-server` patterns: real stable-vs-experimental tool policy, `DISABLED_TOOLS` shutdown support, aligned A2A/HTTP capability reporting, modular category-based tool registration instead of a monolithic `src/index.ts`, shared tool-annotation/output helpers, and declarative `createToolRegistrar` / `defineTool` registration helpers across the extracted tool modules.
|
||||
- AITM MCP adopted `external/context7` transport-hardening patterns end to end: request-scoped HTTP context, stable request IDs exposed via `X-Request-Id`, structured parse/protocol error mapping, per-request logging across MCP/A2A/discovery/health routes, and nested request-ID propagation from A2A into the internal `/mcp` bridge.
|
||||
- Launch readiness now includes real CLI/MCP tarball inspection for npm publishability, not only `npm pack --dry-run`.
|
||||
|
||||
### 4a) AITM Feature Verification
|
||||
|
||||
All time-travel features verified as fully implemented:
|
||||
- **Checkpoint creation**: SHA256 content-addressable storage, lazy file reading.
|
||||
- **Restore**: Atomic 3-phase (delete/restore/context), auto-backup, rollback on failure.
|
||||
- **Diff**: 3 algorithms (Myers, Patience, Histogram), unified output.
|
||||
- **Cat**: View any file from any past checkpoint.
|
||||
- **Storage**: `.aitimemachine/store/` loose objects + pack files + SQLite metadata.
|
||||
- **Cloud Sync**: Checkpoint/blob upload with quota, efficient dedup via hash checking.
|
||||
- **Web UI**: 6-step restore flow with preview, selective restore, undo.
|
||||
- **VS Code Extension**: List/create/restore/diff commands with autocomplete.
|
||||
- **API Server**: Full REST API for restore, manifest, blobs, batch operations.
|
||||
|
||||
### 4b) Gitgram Feature Verification
|
||||
|
||||
All 12 core social features verified as fully implemented (backend + frontend + database):
|
||||
- Auth (JWT + 2FA + GitHub/Google OAuth)
|
||||
- Posts (media, code snippets, mentions, hashtags)
|
||||
- Feed (algorithm-driven, personalized)
|
||||
- Comments (nested) & Likes
|
||||
- User Profiles (avatar, bio, settings)
|
||||
- Follow/Unfollow (with notifications, private account support)
|
||||
- GitHub Integration (real Octokit OAuth, repo sync, claiming)
|
||||
- Reels (video upload, comments, reactions)
|
||||
- Stories (24hr expiry, analytics, highlights)
|
||||
- Direct Messages (WebSocket real-time, group chat, read receipts)
|
||||
- Search (multi-type, advanced filters, relevance ranking)
|
||||
- Notifications (WebSocket real-time, push support)
|
||||
|
||||
### 4c) App-Code Stub / Placeholder Audit (2026-05-12)
|
||||
|
||||
This audit overrides earlier "fully implemented" wording for the specific surfaces below. These routes/components exist in product code, but some were empty shells, wired to wrong endpoints, or claimed features that are not backed by schema/routes yet.
|
||||
|
||||
**Fixed in current remediation batches (2026-05-12)**
|
||||
- `gitgram/web/app/explore/trending/page.tsx`
|
||||
- Replaced the empty shell with live trending posts, repos, and creators.
|
||||
- `gitgram/web/services/storyService.ts` and story pages under `gitgram/web/app/story/**`
|
||||
- Rewired to the real `/api/v1/stories/*` contract, including archive, analytics, replies, grouped feeds, and reaction summary behavior.
|
||||
- `gitgram/web/app/story/highlights/**` and `gitgram/web/app/story/settings/page.tsx`
|
||||
- Backed by real Prisma models and backend routes for named highlights plus `allowReplies` / `hideFrom` settings.
|
||||
- `gitgram/web/app/reel/[id]/page.tsx`, `gitgram/web/app/reel/[id]/likes/page.tsx`, and `gitgram/web/app/reel/[id]/share/page.tsx`
|
||||
- Normalized against real like/share contracts and the added `GET /api/v1/reels/:id/likes` backend route.
|
||||
- `gitgram/web/app/reel/[id]/music/page.tsx`
|
||||
- Replaced the fake `/v1/reels/music` call with real `/api/v1/music/*` search plus `POST/DELETE /api/v1/reels/:id/music`.
|
||||
- `gitgram/web/app/reel/[id]/reactions/page.tsx` and `gitgram/mobile/app/reel/[id]/reactions.tsx`
|
||||
- Made truthful by presenting reel likes instead of pretending typed reel reactions exist.
|
||||
- `gitgram/backend/src/controllers/reelsController.ts`, `gitgram/backend/prisma/schema.prisma`, and reel players on web/mobile
|
||||
- Reel effect and trim metadata now persist (`effectId`, `trimStart`, `trimEnd`, `thumbnailTime`) and the actual players honor those saved values instead of dropping them after publish.
|
||||
- `gitgram/web/app/reel/[id]/effects/page.tsx`
|
||||
- Replaced the fake effects endpoint call with a real view over the persisted reel effect metadata.
|
||||
- `gitgram/web/app/reel/drafts/page.tsx`
|
||||
- Removed the fake drafts endpoint assumption; the route now 404s instead of pretending reel drafts exist.
|
||||
- `gitgram/mobile/app/reel/[id]/music.tsx`, `gitgram/mobile/app/(modals)/create-reel.tsx`, and `gitgram/mobile/app/create/reel.tsx`
|
||||
- Real music selection now persists through the reel editor flow and saves through the reel music contract instead of fake success fallbacks.
|
||||
- `gitgram/mobile/app/(modals)/create-reel.tsx`, `gitgram/mobile/app/create/reel.tsx`, and `gitgram/mobile/components/Reel/ReelTrimEditor.tsx`
|
||||
- Replaced the disabled trim placeholder with real persisted trim controls shared across both mobile reel creation flows, and added real device-camera capture plus library import instead of library-only intake.
|
||||
- `gitgram/mobile/app/map/explore.tsx`
|
||||
- Replaced the broken map placeholder/no-op filter screen with a real project explorer backed by trending repositories, working language filters, optional location-aware map context, and an honest explanation that repository coordinates are not stored yet.
|
||||
- `gitgram/web/app/reels/create/page.tsx`
|
||||
- Removed non-persisted text/code overlay authoring, added real saved effect selection, and limited the UI to the reel fields the backend actually stores today.
|
||||
|
||||
**Remaining web placeholder-backed surfaces**
|
||||
- None currently identified in the active remediation scope.
|
||||
|
||||
**Remaining mobile placeholder-backed surfaces**
|
||||
- `gitgram/mobile/app/reel/drafts.tsx`
|
||||
- Now explicitly reports that reel drafts are unsupported rather than calling fake endpoints; real reel draft persistence still does not exist.
|
||||
|
||||
**Immediate remediation batch — NEXT**
|
||||
- Decide whether reel drafts are a real product requirement or should stay removed until backed by schema/routes.
|
||||
- Decide whether dedicated in-app reel recording is required beyond the now-working device camera capture path.
|
||||
- Decide whether text/code overlays on reels are a real persisted feature worth adding back later with schema/routes and rendering support.
|
||||
|
||||
**Queued after current batch**
|
||||
- Align any future reel overlay authoring with a persisted backend contract before surfacing it again on mobile.
|
||||
|
||||
### 4d) External Reference Adoption Status
|
||||
|
||||
This section summarizes launch-state reference adoption. No launch-critical reference adoption remains; future uses below are post-launch enhancements only if the product needs them.
|
||||
|
||||
| Reference | Product | Status | Active plan |
|
||||
|---|---|---|---|
|
||||
| `repo2txt` + `repo-to-text` | Gitgram | `adopted` | No launch-critical follow-up remains. Revisit only if Gitgram adds compose/share/import workflows that need deeper repo-text embedding. |
|
||||
| `a2a-js` | AITM MCP | `adopted` | No launch-critical follow-up remains. Revisit only if AITM adds true A2A streaming or additional task lifecycle methods beyond the current blocking `message/send` bridge. |
|
||||
| `context7` | AITM MCP | `adopted` | No launch-critical follow-up remains. Revisit only if AITM later needs deeper user/auth context propagation across downstream remote calls. |
|
||||
| `pal-mcp-server` | AITM MCP | `adopted` | No launch-critical follow-up remains. Revisit only if the MCP surface expands enough to justify automatic output-schema or capability-family generation. |
|
||||
|
||||
## 5) Unified Delivery Sequence
|
||||
|
||||
The sequencing below resolves prior ambiguity:
|
||||
- Architecture/security gates remain mandatory.
|
||||
- Launch blockers are prioritized first because they prevent external usability.
|
||||
- Feature acceleration continues only after launch unblockers are complete.
|
||||
|
||||
### Stage A: Launch Unblockers (Immediate) — IN PROGRESS
|
||||
|
||||
Goal: make both products externally usable.
|
||||
|
||||
Stage A readiness helpers now in repo:
|
||||
- `docs/runbook.md` remains the canonical manual launch path.
|
||||
- `scripts/verify-launch-readiness.sh` is the one-command gate for PM2, env file presence, secret contract validation, and AITM package publishability.
|
||||
- `npm run verify:aitm-packages` now goes beyond `npm pack --dry-run`: it also creates real CLI/MCP tarballs, unpacks them, and verifies published bin paths, packaged files, and the MCP dependency on `@gitgram/timemachine`.
|
||||
- `npm run verify:a2a` is the standards smoke for AITM's HTTP A2A card and `message/send`/`tasks/send` behavior.
|
||||
- `npm run verify:launch` runs the default `core` gate.
|
||||
- `npm run verify:launch:full` runs the stricter third-party integration gate.
|
||||
- `scripts/deploy-launch.sh` is the PM2-aligned scripted deploy path for Gitgram and AITM.
|
||||
- `scripts/verify-public-launch.sh` is the public-domain smoke pass for `gitgram.app` and AITM endpoints after DNS/nginx cutover.
|
||||
|
||||
#### A1. Publish AITM packages to npm — TODO
|
||||
|
||||
Both packages are fully configured for publishing. CLI must be published first (MCP depends on it).
|
||||
|
||||
**Step-by-step publish plan:**
|
||||
|
||||
1. **Pre-publish checks:**
|
||||
```bash
|
||||
cd aitimemachine && npm run build && npm test # verify clean build + 520 tests pass
|
||||
cd mcp && npm run build # verify MCP builds
|
||||
```
|
||||
|
||||
2. **Publish CLI first** (`@gitgram/timemachine@2.0.0`):
|
||||
```bash
|
||||
cd aitimemachine
|
||||
npm publish --access public
|
||||
```
|
||||
- Package: `@gitgram/timemachine`
|
||||
- Bin: `aitm`, `aitimemachine`
|
||||
- Entry: `lib/cli-v2.js`
|
||||
- Files: `lib/**/*`, `README.md`, `LICENSE`
|
||||
- Hooks: `prepack` → build, `prepublishOnly` → build + test
|
||||
|
||||
3. **Verify CLI install:**
|
||||
```bash
|
||||
npx @gitgram/timemachine --version
|
||||
mkdir /tmp/aitm-test && cd /tmp/aitm-test
|
||||
npx @gitgram/timemachine init
|
||||
npx @gitgram/timemachine checkpoint --message "test"
|
||||
```
|
||||
|
||||
4. **Publish MCP server** (`@gitgram/timemachine-mcp@2.0.0`):
|
||||
```bash
|
||||
cd aitimemachine/mcp
|
||||
npm publish --access public
|
||||
```
|
||||
- Package: `@gitgram/timemachine-mcp`
|
||||
- Bin: `aitm-mcp`, `aitm-mcp-client`
|
||||
- Entry: `dist/index.js`
|
||||
- Depends on: `@gitgram/timemachine@^2.0.0` (must be on npm first)
|
||||
- Files: `dist/**/*`, `server.json`, `README.md`, `LICENSE`
|
||||
|
||||
5. **Verify MCP install:**
|
||||
```bash
|
||||
npx @gitgram/timemachine-mcp --help
|
||||
```
|
||||
|
||||
6. **Automated releases (future tags):**
|
||||
- CI workflow (`aitimemachine/.github/workflows/ci.yml`) has a release job
|
||||
- Triggered on tag push matching `v*`
|
||||
- Uses GitHub secret `NPM_TOKEN`, passed to npm as `NODE_AUTH_TOKEN`
|
||||
- Current workflow publishes `@gitgram/timemachine`; MCP publish still requires a manual step until automation is aligned
|
||||
|
||||
**npm cost: $0** (public packages are free)
|
||||
|
||||
#### A2. Configure production secrets — TODO
|
||||
|
||||
| Secret | Product | Source |
|
||||
|--------|---------|--------|
|
||||
| `POLAR_ACCESS_TOKEN` | Gitgram | polar.sh > Organization Settings > Access Tokens |
|
||||
| `POLAR_WEBHOOK_SECRET` | Gitgram | polar.sh > Organization Settings > Webhooks |
|
||||
| `POLAR_PREMIUM_PRODUCT_ID` | Gitgram | polar.sh > Products (create Premium $9.99/mo) |
|
||||
| `POLAR_CREATOR_PRODUCT_ID` | Gitgram | polar.sh > Products (create Creator $19.99/mo) |
|
||||
| `POLAR_ACCESS_TOKEN` | AITM | polar.sh (same or separate org) |
|
||||
| `GITHUB_CLIENT_ID` | Gitgram | github.com/settings/developers |
|
||||
| `GITHUB_CLIENT_SECRET` | Gitgram | github.com/settings/developers |
|
||||
| `GOOGLE_CLIENT_ID` | Gitgram | console.cloud.google.com |
|
||||
| `GOOGLE_CLIENT_SECRET` | Gitgram | console.cloud.google.com |
|
||||
| `CLERK_SECRET_KEY` | AITM | dashboard.clerk.com |
|
||||
| `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | AITM | dashboard.clerk.com |
|
||||
| `RESEND_API_KEY` | Both | resend.com/api-keys |
|
||||
| `SENTRY_DSN` (x2) | Both | sentry.io (one project per product) |
|
||||
| `DATABASE_URL` | Gitgram | Neon console |
|
||||
| `DATABASE_URL` | AITM | Neon console |
|
||||
| `REDIS_URL` | Gitgram | Upstash console |
|
||||
| `AWS_ACCESS_KEY_ID` | Gitgram | AWS IAM |
|
||||
| `AWS_SECRET_ACCESS_KEY` | Gitgram | AWS IAM |
|
||||
| `JWT_SECRET` | Gitgram | Generate: `openssl rand -base64 48` |
|
||||
| `JWT_REFRESH_SECRET` | Gitgram | Generate: `openssl rand -base64 48` |
|
||||
|
||||
#### A3. Deploy production baseline — TODO
|
||||
|
||||
- Provision VPS (Hetzner CX32 recommended: 4 vCPU, 8 GB RAM, 80 GB NVMe).
|
||||
- Configure DNS records (A/AAAA) for `gitgram.app`, `api.gitgram.app`, `aitm.gitgram.app`.
|
||||
- TLS via Let's Encrypt / Caddy auto-HTTPS.
|
||||
- Build the services and start them under PM2 on the launch host.
|
||||
- Verify health endpoints and monitoring.
|
||||
|
||||
#### A4. Run E2E smoke tests — PARTIAL
|
||||
|
||||
- ~~AITM install/init/checkpoint/timeline path.~~ **DONE** — covered by 520 CLI tests.
|
||||
- ~~Gitgram public repo routing + repo-to-text path.~~ **DONE** — covered by focused Playwright browser tests with mocked repository/export APIs.
|
||||
- Gitgram signup/oauth/post/comment/notification path. **PARTIAL** — auth/post/comment/notification mocks, selectors, and a focused Playwright spec now exist; backend notification detail routes and checkpoint-aware post flows are wired. Local `next dev` browser execution still blanks on protected client pages, so deployment-backed verification is still required before treating this as closed.
|
||||
|
||||
Exit criteria:
|
||||
- Both products are installable/deployable.
|
||||
- All health checks pass.
|
||||
- End-to-end flows complete without critical failure.
|
||||
|
||||
### Stage B: Security Closure — COMPLETE
|
||||
|
||||
1. ~~JWT storage migration to httpOnly cookies in Gitgram.~~ **DONE**
|
||||
2. ~~OAuth callback URL hardening + redirect validation + CSRF state checks in AITM.~~ **DONE**
|
||||
3. ~~Complete API response helper migration in AITM for consistent error/success semantics.~~ **DONE**
|
||||
4. ~~Validate retention/delete/export audit paths in staging.~~ **DONE**
|
||||
|
||||
Additional security work completed beyond original plan:
|
||||
- Advertisement tracking endpoints: rate limiting + ad-exists validation.
|
||||
- Repository claim: GitHub ownership verification via Octokit.
|
||||
- Webhook signature: timing-safe comparison fix.
|
||||
- Input validation added on advertisement and claim routes.
|
||||
|
||||
Exit criteria: **ALL MET**
|
||||
|
||||
### Stage C: Reliability and Code Quality — COMPLETE
|
||||
|
||||
1. ~~Split AITM `cli-v2.ts` into modular command files.~~ **DONE**
|
||||
2. ~~Reduce `any` usage in AITM by priority surfaces.~~ **DONE**
|
||||
3. ~~Add Gitgram frontend unit/integration tests.~~ **DONE** — 72 tests.
|
||||
4. Add Playwright critical-path E2E and CI gating. **PARTIAL** — repo routing/text coverage is in place and gated in CI. A second focused auth/comment/notification browser spec and CI job wiring are added, but protected-page browser verification still needs production-style validation because the local dev-server path is not stable enough to close the item.
|
||||
|
||||
Exit criteria: **3 of 4 MET** (repo-route coverage and CI gate added; broader protected live-flow coverage is implemented but not fully verified yet)
|
||||
|
||||
### Stage D: Cross-Product Integration — PARTIAL / POST-LAUNCH (New Feature Coding)
|
||||
|
||||
Note: This is **post-launch enhancement** work, not a gap in existing v1 functionality.
|
||||
|
||||
1. ~~Add checkpoint linkage in Gitgram posts (`aitm_checkpoint_id` / `checkpointRef`).~~ **PARTIAL** — checkpoint-aware post creation now works through Gitgram compose, the backend accepts checkpoint metadata, and checkpoint-only post publishing is covered by service/unit validation.
|
||||
2. ~~Ship AITM "share as post" flow (connect existing UI to backend).~~ **PARTIAL** — AITM context replay now deep-links into Gitgram compose for post and change-story publishing with checkpoint/project context carried through.
|
||||
3. ~~Add "Change Story" post type from AITM diffs.~~ **PARTIAL** — Gitgram compose accepts AITM diff/query params, Change Story publishing is live, and Creator Studio exposes repo-linked Change Story entry points. Trend-side surfacing is still open.
|
||||
4. Launch trend ranking combining GitHub + platform social signals. **TODO**
|
||||
|
||||
### Stage E: Intelligence and Growth — PARTIAL / POST-LAUNCH (New Feature Coding)
|
||||
|
||||
Note: This is **post-launch enhancement** work, not required for v1.
|
||||
|
||||
1. ~~Semantic search over checkpoint/code history.~~ **PARTIAL** — AITM website now has a Semantic Search dashboard backed by new internal knowledge-base search/stats/artifact routes and passing integration coverage on the API layer.
|
||||
2. ~~Training export pipeline with opt-in + redaction + audit traceability.~~ **PARTIAL** — AITM website now has Training Exports controls, project-level consent toggles, internal pipeline routes, and passing integration coverage for consent/pipeline happy paths plus denial enforcement. End-to-end artifact generation on deployed infra is still open.
|
||||
3. ~~Creator tooling for repo owners (story/reel workflows).~~ **PARTIAL** — Gitgram Creator Studio now exposes repository creator tools, direct repo text/export entry points, post/change-story shortcuts, and AITM setup links. Expanded story/reel growth workflows remain open.
|
||||
|
||||
## 6) Priority Ticket Backlog (Ordered)
|
||||
|
||||
P0 (must complete first — deployment):
|
||||
- Publish AITM CLI and MCP packages to npm.
|
||||
- Production secrets setup for both products.
|
||||
- Production infra deploy + DNS/TLS + monitoring.
|
||||
- End-to-end smoke verification on live environment.
|
||||
|
||||
~~P1~~ **COMPLETE:**
|
||||
- ~~Gitgram auth token migration to httpOnly cookies.~~ Done.
|
||||
- ~~AITM OAuth callback and redirect hardening.~~ Done.
|
||||
- ~~AITM response helper migration completion.~~ Done.
|
||||
- ~~Retention/delete/export audit verification.~~ Done.
|
||||
|
||||
~~P2~~ **COMPLETE:**
|
||||
- ~~AITM CLI modularization.~~ Done.
|
||||
- ~~AITM `any` reduction campaign.~~ Done.
|
||||
- ~~Gitgram frontend testing stack and CI enforcement.~~ Done.
|
||||
|
||||
P3 (post-deploy — new feature coding + testing):
|
||||
- Finish deployment-backed verification for protected Gitgram auth/post/comment/notification browser flows.
|
||||
- Complete trend ranking / discovery surfacing for checkpoint-linked posts and Change Story content (Stage D).
|
||||
- Harden semantic search relevance and deployed training-export artifact generation (Stage E).
|
||||
- Expand Creator Studio beyond repo quick actions into richer story/reel growth tooling (Stage E).
|
||||
|
||||
## 7) Infrastructure Cost Breakdown
|
||||
|
||||
### Per-Service Pricing (Monthly)
|
||||
|
||||
| Service | Product | Plan | Monthly Cost | Notes |
|
||||
|---------|---------|------|-------------|-------|
|
||||
| **npm** | AITM | Public packages | **$0** | Unlimited free public packages |
|
||||
| **Hetzner VPS** | Both | CX32 (4 vCPU, 8 GB, 80 GB) | **~$7** | Docker compose for Gitgram backend + AITM API. ~$8/mo after Apr 2026 price increase |
|
||||
| **Neon PostgreSQL** | Gitgram | Free → Launch | **$0–$5** | Free: 100 CU-hrs, 0.5 GB. Launch: $5/mo min, storage $0.35/GB-mo |
|
||||
| **Neon PostgreSQL** | AITM | Free → Launch | **$0–$5** | Separate project. Same tiers |
|
||||
| **Vercel** | Both (web) | Hobby (free) | **$0** | Free for non-commercial. Pro: $20/user/mo when needed |
|
||||
| **Polar.sh** | Both | Transaction fees only | **$0 base** | 4% + $0.40 per transaction. No monthly fee. MoR handles taxes |
|
||||
| **Clerk** | AITM | Free | **$0** | Free up to 50K MAU. Pro: $20/mo when needed |
|
||||
| **Resend** | Both | Free | **$0** | 3,000 emails/mo free. Pro: $20/mo for 50K emails |
|
||||
| **Sentry** | Both | Developer (free) | **$0** | 5K errors/mo, 1 user. Team: $26/mo when needed |
|
||||
| **Upstash Redis** | Gitgram | Free | **$0** | 256 MB, 500K commands/mo free |
|
||||
| **AWS S3** | Gitgram | Pay-as-you-go | **~$1–5** | $0.023/GB storage + $0.09/GB egress (first 100 GB free) |
|
||||
| **Domain** | Both | .app domain | **~$2/mo** | ~$20–25/year for `.app` domain |
|
||||
| **GitHub Actions** | Both | Free tier | **$0** | 2,000 min/mo free for public repos |
|
||||
|
||||
### Cost Scenarios
|
||||
|
||||
#### Minimum Launch (Free Tiers Only)
|
||||
|
||||
| Item | Cost |
|
||||
|------|------|
|
||||
| Hetzner CX32 | $7/mo |
|
||||
| Domain (.app) | $2/mo |
|
||||
| Everything else on free tiers | $0 |
|
||||
| **Total** | **~$9/mo** |
|
||||
|
||||
#### Small Scale (100 users, light usage)
|
||||
|
||||
| Item | Cost |
|
||||
|------|------|
|
||||
| Hetzner CX32 | $7/mo |
|
||||
| Neon Launch x2 | $10/mo |
|
||||
| AWS S3 (10 GB) | $1/mo |
|
||||
| Domain | $2/mo |
|
||||
| Vercel Hobby | $0 |
|
||||
| Clerk Free | $0 |
|
||||
| Resend Free | $0 |
|
||||
| Sentry Free | $0 |
|
||||
| Upstash Free | $0 |
|
||||
| Polar.sh (est. 20 txns) | ~$12/mo (fee on revenue) |
|
||||
| **Total infra** | **~$20/mo** (+ Polar fees on revenue) |
|
||||
|
||||
#### Growth (1,000 users, moderate usage)
|
||||
|
||||
| Item | Cost |
|
||||
|------|------|
|
||||
| Hetzner CX42 (8 vCPU, 16 GB) | $18/mo |
|
||||
| Neon Scale x2 | $40/mo |
|
||||
| AWS S3 (100 GB + egress) | $12/mo |
|
||||
| Vercel Pro (1 seat) | $20/mo |
|
||||
| Clerk Pro | $20/mo |
|
||||
| Resend Pro | $20/mo |
|
||||
| Sentry Team | $26/mo |
|
||||
| Upstash Pay-as-you-go | $5/mo |
|
||||
| Domain | $2/mo |
|
||||
| Polar.sh (est. 200 txns) | ~$120/mo (fee on revenue) |
|
||||
| **Total infra** | **~$163/mo** (+ Polar fees on revenue) |
|
||||
|
||||
### Polar.sh Revenue Model
|
||||
|
||||
Polar.sh charges **4% + $0.40 per transaction** (no monthly fee). Revenue examples:
|
||||
|
||||
| Subscribers | Plan | Gross Revenue | Polar Fee (4% + $0.40) | Net Revenue |
|
||||
|-------------|------|--------------|----------------------|-------------|
|
||||
| 10 | Premium ($9.99) | $99.90/mo | $4.40 + $4.00 = $8.40 | $91.50/mo |
|
||||
| 10 | Creator ($19.99) | $199.90/mo | $8.00 + $4.00 = $12.00 | $187.90/mo |
|
||||
| 50 | Mixed | ~$750/mo | ~$50 | ~$700/mo |
|
||||
| 100 | Mixed | ~$1,500/mo | ~$100 | ~$1,400/mo |
|
||||
| 500 | Mixed | ~$7,500/mo | ~$500 | ~$7,000/mo |
|
||||
|
||||
Polar is the Merchant of Record — they handle tax calculation, collection, and remittance globally.
|
||||
|
||||
## 8) KPIs
|
||||
|
||||
Product:
|
||||
- Weekly active developers.
|
||||
- Restore actions per active AITM user.
|
||||
- Social interactions per repository page.
|
||||
- 7-day retention after first restore.
|
||||
|
||||
System:
|
||||
- Restore success rate and latency percentiles.
|
||||
- Diff generation latency.
|
||||
- Checkpoint ingestion throughput.
|
||||
- Sync lag (local cache to backend).
|
||||
|
||||
Safety:
|
||||
- Consent coverage.
|
||||
- Redaction precision/recall.
|
||||
- Mean deletion-request resolution time.
|
||||
|
||||
## 9) Governance Rule
|
||||
|
||||
Before starting any new feature stream, verify:
|
||||
1. It does not violate Section 3 locked decisions.
|
||||
2. It does not bypass P0/P1 launch and security gates.
|
||||
3. It has measurable exit criteria tied to KPIs in Section 8.
|
||||
|
||||
## 10) Status Summary (2026-03-17)
|
||||
|
||||
| Stage | Status | Work Type |
|
||||
|-------|--------|-----------|
|
||||
| v1 Core Coding | **COMPLETE** | All features implemented and tested (1130+ tests passing) |
|
||||
| Payment Migration | **COMPLETE** | Stripe → Polar.sh (all code, config, docs updated) |
|
||||
| Stage A (Deploy) | **TODO** | npm publish (CLI + MCP), secrets, VPS, DNS/TLS, DB |
|
||||
| Stage B (Security) | **COMPLETE** | All exit criteria met |
|
||||
| Stage C (Quality) | **COMPLETE** | 3/4 met; Playwright deferred to post-deploy |
|
||||
| Stage D (Cross-Product) | **PARTIAL / POST-LAUNCH** | Enhancement work; not a launch blocker |
|
||||
| Stage E (Growth) | **PARTIAL / POST-LAUNCH** | Enhancement work; not a launch blocker |
|
||||
|
||||
**Bottom line:**
|
||||
- Zero coding needed for v1 launch — only deployment/infrastructure remains.
|
||||
- Minimum launch cost: **~$9/mo** (Hetzner + domain, everything else free tier).
|
||||
- Stage D and E are post-launch enhancements, not v1 gaps.
|
||||
|
||||
Tests — All Passing
|
||||
|
||||
┌─────────────────┬───────────────────────┬───────────┐
|
||||
│ Suite │ Tests │ Status │
|
||||
├─────────────────┼───────────────────────┼───────────┤
|
||||
│ AITM Core │ 520/520 │ PASS │
|
||||
├─────────────────┼───────────────────────┼───────────┤
|
||||
│ AITM API Server │ 538/538 (+19 skipped) │ PASS │
|
||||
├─────────────────┼───────────────────────┼───────────┤
|
||||
│ Gitgram Web │ 72/72 │ PASS │
|
||||
├─────────────────┼───────────────────────┼───────────┤
|
||||
│ Total │ 1,130 │ ALL GREEN │
|
||||
└─────────────────┴───────────────────────┴───────────┘
|
||||
|
||||
npm Packages — Ready to Publish
|
||||
|
||||
┌───────────────────────────────┬─────────┬────────────────────────────────────────────────────────┐
|
||||
│ Package │ Version │ Details │
|
||||
├───────────────────────────────┼─────────┼────────────────────────────────────────────────────────┤
|
||||
│ @gitgram/timemachine │ 2.0.0 │ CLI: aitm, aitimemachine. 23 commands, core engine │
|
||||
├───────────────────────────────┼─────────┼────────────────────────────────────────────────────────┤
|
||||
│ @gitgram/timemachine-mcp │ 2.0.0 │ MCP server: aitm-mcp. Depends on CLI ^2.0.0 │
|
||||
└───────────────────────────────┴─────────┴────────────────────────────────────────────────────────┘
|
||||
Polar.sh fee on $20 subscription
|
||||
|
||||
┌─────────────┬─────────────────┐
|
||||
│ │ Per Transaction │
|
||||
├─────────────┼─────────────────┤
|
||||
│ Gross │ $20.00 │
|
||||
├─────────────┼─────────────────┤
|
||||
│ 4% fee │ -$0.80 │
|
||||
├─────────────┼─────────────────┤
|
||||
│ Fixed fee │ -$0.40 │
|
||||
├─────────────┼─────────────────┤
|
||||
│ You receive │ $18.80 │
|
||||
└─────────────┴─────────────────┘
|
||||
|
||||
Scaled out:
|
||||
|
||||
┌─────────────┬──────────┬───────────┬────────────┐
|
||||
│ Subscribers │ Gross/mo │ Polar Fee │ You Get │
|
||||
├─────────────┼──────────┼───────────┼────────────┤
|
||||
│ 1 │ $20 │ $1.20 │ $18.80 │
|
||||
├─────────────┼──────────┼───────────┼────────────┤
|
||||
│ 10 │ $200 │ $12.00 │ $188.00 │
|
||||
├─────────────┼──────────┼───────────┼────────────┤
|
||||
│ 50 │ $1,000 │ $60.00 │ $940.00 │
|
||||
├─────────────┼──────────┼───────────┼────────────┤
|
||||
│ 100 │ $2,000 │ $120.00 │ $1,880.00 │
|
||||
├─────────────┼──────────┼───────────┼────────────┤
|
||||
│ 500 │ $10,000 │ $600.00 │ $9,400.00 │
|
||||
├─────────────┼──────────┼───────────┼────────────┤
|
||||
│ 1,000 │ $20,000 │ $1,200.00 │ $18,800.00 │
|
||||
└─────────────┴──────────┴───────────┴────────────┘
|
||||
|
||||
What each scenario includes
|
||||
|
||||
Minimum Launch — ~$9/mo
|
||||
|
||||
What you get:
|
||||
- 1 VPS running both Gitgram backend + AITM API server (4 vCPU, 8 GB RAM)
|
||||
- PostgreSQL with 0.5 GB storage per project (auto-scales to zero when idle)
|
||||
- Redis with 256 MB cache, 500K commands/mo
|
||||
- 3,000 emails/mo (password reset, notifications)
|
||||
- 5K error tracking events/mo
|
||||
- 50K auth users (AITM via Clerk)
|
||||
- Frontend hosted on Vercel free tier
|
||||
- Media stored locally on VPS (80 GB NVMe)
|
||||
|
||||
Limits you'll hit first:
|
||||
- 0.5 GB database (enough for ~5K-10K users)
|
||||
- No S3 (media on VPS disk, 80 GB cap)
|
||||
- 3K emails/mo (enough for ~500 active users)
|
||||
- No CDN, no custom email domain
|
||||
- Vercel hobby = non-commercial only
|
||||
|
||||
Good for: Development, beta testing, first users
|
||||
|
||||
---
|
||||
Small Scale — ~$20/mo (100 users)
|
||||
|
||||
What you get (on top of minimum):
|
||||
- Neon Launch x2 ($5 each) — real production databases, auto-scaling compute, more storage
|
||||
- AWS S3 for media uploads (10 GB) — proper file storage, not VPS disk
|
||||
- Everything else still on free tiers
|
||||
|
||||
Limits:
|
||||
- S3 egress: first 100 GB/mo free
|
||||
- 3K emails/mo still (upgrade to Resend Pro at $20/mo if needed)
|
||||
- Single VPS (no redundancy)
|
||||
|
||||
Good for: Soft launch, early adopters, getting first paying subscribers
|
||||
|
||||
---
|
||||
Growth — ~$163/mo (1,000 users)
|
||||
|
||||
What you get (on top of small):
|
||||
- Bigger VPS (8 vCPU, 16 GB RAM) — handles concurrent WebSocket connections, video processing
|
||||
- Neon Scale x2 — higher connection limits, read replicas, compliance features
|
||||
- Vercel Pro — commercial use allowed, 1 TB bandwidth, team collaboration
|
||||
- Clerk Pro — SSO, enterprise auth features, unlimited orgs
|
||||
- Resend Pro — 50K emails/mo
|
||||
- Sentry Team — 100K errors/mo, multiple users, performance monitoring
|
||||
- Upstash paid — more Redis capacity for rate limiting, sessions, caching
|
||||
- AWS S3 100 GB + egress
|
||||
|
||||
Limits:
|
||||
- Single VPS still (for HA, add second VPS +$18/mo)
|
||||
- No dedicated DB (Neon Scale is still serverless)
|
||||
|
||||
Good for: Active community, real revenue, hundreds of daily active users
|
||||
|
||||
---
|
||||
Break-even math
|
||||
|
||||
With $9/mo minimum infra and $18.80 net per subscriber:
|
||||
|
||||
┌─────────────────────────────┬────────────────────┐
|
||||
│ │ Subscribers needed │
|
||||
├─────────────────────────────┼────────────────────┤
|
||||
│ Cover minimum infra ($9/mo) │ 1 subscriber │
|
||||
├─────────────────────────────┼────────────────────┤
|
||||
│ Cover small scale ($20/mo) │ 2 subscribers │
|
||||
├─────────────────────────────┼────────────────────┤
|
||||
│ Cover growth ($163/mo) │ 9 subscribers │
|
||||
└─────────────────────────────┴────────────────────┘
|
||||
|
||||
┌─────────────────┬───────────────────────────────┬────────┐
|
||||
│ Product │ Check │ Result │
|
||||
├─────────────────┼───────────────────────────────┼────────┤
|
||||
│ AITM CLI │ Build (tsc) │ PASS │
|
||||
├─────────────────┼───────────────────────────────┼────────┤
|
||||
│ AITM CLI │ Tests (520/520) │ PASS │
|
||||
├─────────────────┼───────────────────────────────┼────────┤
|
||||
│ AITM CLI │ Runtime (--version → 2.0.0) │ PASS │
|
||||
├─────────────────┼───────────────────────────────┼────────┤
|
||||
│ AITM CLI │ Help (23 commands listed) │ PASS │
|
||||
├─────────────────┼───────────────────────────────┼────────┤
|
||||
│ AITM MCP │ Build (tsc) │ PASS │
|
||||
├─────────────────┼───────────────────────────────┼────────┤
|
||||
│ AITM MCP │ Runtime (stdio server starts) │ PASS │
|
||||
├─────────────────┼───────────────────────────────┼────────┤
|
||||
│ AITM API Server │ Type-check │ PASS │
|
||||
├─────────────────┼───────────────────────────────┼────────┤
|
||||
│ AITM API Server │ Tests (538/538, +19 skip) │ PASS │
|
||||
├─────────────────┼───────────────────────────────┼────────┤
|
||||
│ AITM VS Code │ Tests (62/62) │ PASS │
|
||||
├─────────────────┼───────────────────────────────┼────────┤
|
||||
│ AITM Website │ Next.js build │ PASS │
|
||||
├─────────────────┼───────────────────────────────┼────────┤
|
||||
│ Gitgram Backend │ Type-check (0 errors) │ PASS │
|
||||
├─────────────────┼───────────────────────────────┼────────┤
|
||||
│ Gitgram Web │ Next.js build │ PASS │
|
||||
├─────────────────┼───────────────────────────────┼────────┤
|
||||
│ Gitgram Web │ Tests (72/72) │ PASS │
|
||||
└─────────────────┴───────────────────────────────┴────────┘
|
||||
|
||||
we can fork bd https://github.com/upstash/context7.git https://github.com/BeehiveInnovations/pal-mcp-server.git for aitm mcp and aitm stuff and for
|
||||
gitgram we can clone some openourse social media stuff becuase gitgram is social media layer for github repositories we can fork bd https://github.com/upstash/context7.git https://github.com/BeehiveInnovations/pal-mcp-server.git for aitm mcp and aitm stuff and for
|
||||
gitgram we can clone some openourse social media stuff becuase gitgram is social media layer for github repositories vvv
|
||||
---
|
||||
Repos to Fork/Clone
|
||||
|
||||
For AITM MCP
|
||||
|
||||
┌───────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Repo │ What to Adapt │
|
||||
├───────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ upstash/context7 │ Streamable HTTP transport (AITM is stdio-only), AsyncLocalStorage per-request context, tool description │
|
||||
│ │ engineering, multi-agent setup CLI (aitm setup --claude --cursor), SDK client pattern with retry │
|
||||
├───────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ BeehiveInnovations/pal-mcp-server │ ToolAnnotations (readOnlyHint/destructiveHint) for all 40 tools, modular tool class architecture (extract from │
|
||||
│ │ monolithic index.ts), DISABLED_TOOLS env var, standardized output envelope, path validation for restore safety │
|
||||
├───────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ abhigyanpatwari/GitNexus │ Zero-server knowledge graph + Graph RAG agent over repos. Adapt for AITM code-context indexing, checkpoint │
|
||||
│ → external/gitnexus │ knowledge graphs, and Gitgram repo explore/visualisation surface. Cloned 2026-06-21. │
|
||||
├───────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ gastownhall/beads │ Git-native DAG issue tracker for AI agents. `bd ready` shows dependency-unblocked work with hash-based IDs. │
|
||||
│ → external/beads │ Reference for AITM task/issue tracking integration and multi-agent coordination. Cloned 2026-06-21. │
|
||||
└───────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
For Gitgram (Social Layer)
|
||||
|
||||
┌─────┬──────────────────────────────────┬───────┬─────────┬───────────────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ # │ Repo │ Stars │ License │ Why │
|
||||
├─────┼──────────────────────────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ 1 │ codinginflow/nextjs-15-social- │ 417 │ -- │ Exact same stack (Next.js + Prisma + PG). Prisma schema maps 1:1 to Gitgram. Infinite │
|
||||
│ │ media-app → external/nextjs-15- │ │ │ scroll, optimistic updates, notifications. Cloned 2026-06-21. │
|
||||
│ │ social-media-app │ │ │ │
|
||||
├─────┼──────────────────────────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ 2 │ leandronorcio/munia │ 293 │ MIT │ Most complete features: GitHub OAuth, @mentions, hashtags, nested comments, drag-drop │
|
||||
│ │ → external/munia │ │ │ media, S3 uploads, accessibility. Cloned 2026-06-21. │
|
||||
├─────┼──────────────────────────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ 3 │ TomDoesTech/t3-twitter-clone │ 189 │ MIT │ Only one with Express branch — matches Gitgram's Express backend. Type-safe tRPC │
|
||||
│ │ → external/t3-twitter-clone │ │ │ patterns. Cloned 2026-06-21. │
|
||||
├─────┼──────────────────────────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ 4 │ karanpratapsingh/Proximity │ 360 │ GPL-3 │ Best React Native social app with Prisma. Real-time messaging via GraphQL subscriptions. │
|
||||
│ │ → external/proximity │ │ │ Reference only (GPL). Cloned 2026-06-21. │
|
||||
├─────┼──────────────────────────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ 5 │ bluesky-social/social-app │ 17.8K │ MIT │ Production-scale feed algorithms, notifications, moderation. Architecture reference. │
|
||||
│ │ → external/bluesky-social-app │ │ │ Cloned 2026-06-21. │
|
||||
├─────┼──────────────────────────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ 6 │ abhigyanpatwari/GitNexus │ -- │ -- │ Client-side knowledge graph + Graph RAG over any repo. Reference for Gitgram repo │
|
||||
│ │ → external/gitnexus │ │ │ explore/visualisation. Also useful for AITM. Cloned 2026-06-21. │
|
||||
└─────┴──────────────────────────────────┴───────┴─────────┴───────────────────────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
Quick-win bonus
|
||||
|
||||
- amirfakhrullah/gh-social (MIT) — The only "GitHub Social Platform" found. Syncs GitHub follows/stars to a social feed. Next.js + tRPC + Clerk +
|
||||
Drizzle + Neon. Closest concept to Gitgram. Cloned 2026-06-21 → external/gh-social.
|
||||
- gastownhall/beads (MIT) — Git-native DAG issue tracker by Steve Yegge for AI agents. Cloned 2026-06-21 → external/beads.
|
||||
|
||||
---
|
||||
Top Actionable Items from Research
|
||||
|
||||
AITM MCP (high priority, small effort):
|
||||
1. Add ToolAnnotations to all 40 tools — readOnlyHint: true for read tools, destructiveHint: true for restore
|
||||
2. Add Streamable HTTP transport (from context7 pattern) — enables web/VS Code clients
|
||||
3. Extract tools from monolithic index.ts into modular files
|
||||
|
||||
Gitgram (reference patterns to study):
|
||||
1. Prisma schema design from nextjs-15-social-media-app
|
||||
2. @mentions + hashtag system from munia
|
||||
3. Feed pagination (cursor-based infinite scroll) from both
|
||||
4. GitHub API integration from gh-social
|
||||
|
||||
│ BloopAI/vibe-kanban │ 24.6k │ Kanban for AI agents, MCP server+client, git worktree isolation, diff review. Best task board │
|
||||
│ │ │ foundation. │
|
||||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
|
||||
│ gastownhall/beads (bd!) │ 20.4k │ Git-native DAG issue tracker made for AI agents. This is what bd is. │
|
||||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
|
||||
│ a2aproject/a2a-js │ 509 │ Official A2A TypeScript SDK. Needed for standards compliance. │
|
||||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
|
||||
│ agentgateway/agentgateway │ 2.3k │ Rust proxy for A2A + MCP traffic. Security/observability built in. │
|
||||
|
||||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ GongRzhe/A2A-MCP-Server │ 147 │ Bridges MCP ↔ A2A so Claude can talk to A2A agents. │
|
||||
|
||||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
|
||||
│ Open-ACP/OpenACP │ 58 │ Connects 28+ AI agents to Telegram, Discord, Slack. Real-time messaging. │
|
||||
└───────────────────────────┴───────┴───────────────────────────────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
|
||||
Key insight about bd (Beads)
|
||||
|
||||
|
||||
Beads by Steve Yegge is exactly what you're already using for task tracking! It's a git-native graph issue tracker designed for AI agents.
|
||||
|
||||
bd ready shows unblocked work, dependency DAGs, hash-based IDs for concurrent agents. 20k+ stars, MIT.
|
||||
|
||||
│ BloopAI/vibe-kanban │ 24.6k │ Kanban for AI agents, MCP server+client, git worktree isolation, diff review. Best task board │
|
||||
│ │ │ foundation. │
|
||||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
|
||||
│ gastownhall/beads (bd!) │ 20.4k │ Git-native DAG issue tracker made for AI agents. This is what bd is. │
|
||||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
|
||||
│ a2aproject/a2a-js │ 509 │ Official A2A TypeScript SDK. Needed for standards compliance. │
|
||||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
|
||||
│ agentgateway/agentgateway │ 2.3k │ Rust proxy for A2A + MCP traffic. Security/observability built in. │
|
||||
|
||||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ GongRzhe/A2A-MCP-Server │ 147 │ Bridges MCP ↔ A2A so Claude can talk to A2A agents. │
|
||||
|
||||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
|
||||
│ Open-ACP/OpenACP │ 58 │ Connects 28+ AI agents to Telegram, Discord, Slack. Real-time messaging. │
|
||||
└───────────────────────────┴───────┴───────────────────────────────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
|
||||
Key insight about bd (Beads)
|
||||
|
||||
|
||||
Beads by Steve Yegge is exactly what you're already using for task tracking! It's a git-native graph issue tracker designed for AI agents.
|
||||
|
||||
bd ready shows unblocked work, dependency DAGs, hash-based IDs for concurrent agents. 20k+ stars, MIT.
|
||||
|
||||
# Unified Manual Launch Plan for Gitgram + AITM
|
||||
|
||||
## Summary
|
||||
|
||||
Prepare both products for a parallel launch using a single server / operator-managed deployment model as the source of truth. The plan should treat the
|
||||
existing repo as mostly implementation-complete, but should not trust the docs blindly: first reconcile deployment artifacts, environment contracts, and
|
||||
stale references, then execute a manual launch path that does not depend on unfinished CI/CD automation.
|
||||
|
||||
Success means:
|
||||
|
||||
- AITM npm packages are published and installable.
|
||||
- Gitgram backend/web and AITM API are deployable from documented manual commands.
|
||||
- Production secrets/env contracts are complete and validated.
|
||||
- Health checks, rollback steps, and operator runbooks match the actual repo layout.
|
||||
- Stale or conflicting deployment guidance is removed or explicitly deprecated.
|
||||
|
||||
## Implementation Changes
|
||||
|
||||
### 1. Establish one canonical launch topology
|
||||
|
||||
- Make the manual-ops path the primary launch contract: single operator-managed host, Docker/PM2/systemd as applicable, no dependency on unfinished
|
||||
GitHub Actions deployment flows.
|
||||
- Standardize the production target as:
|
||||
- Gitgram backend: long-running Node service on the server.
|
||||
- Gitgram web: long-running Next.js service on the server.
|
||||
- AITM API: long-running Node service on the server.
|
||||
- Shared infra: PostgreSQL + Redis on the same host or tightly coupled managed services, but documented as one operational unit.
|
||||
- Demote GitHub Actions deploy workflows to “future automation” unless they fully match the manual launch path.
|
||||
|
||||
### 2. Reconcile repo truth with docs before launch execution
|
||||
|
||||
- Audit and fix contradictions between SINGLE_SOURCE_PLAN.md, docs/deploy-pipeline.md, docs/ops-quickref.md, docs/runbook.md, compose files, and actual
|
||||
workflow filenames.
|
||||
- Remove or clearly mark stale deployment variants that conflict with the chosen topology.
|
||||
- Resolve broken references in docs, especially any paths/services that do not exist in the tree.
|
||||
- Normalize naming so the same service names, ports, health endpoints, workflow names, and env var conventions are used everywhere.
|
||||
- Treat docs/can be fork.md as the maintained reference-clone inventory; use SINGLE_SOURCE_PLAN.md as the canonical execution plan for launch sequencing.
|
||||
|
||||
### 3. Lock the manual launch path per product
|
||||
|
||||
- AITM:
|
||||
- Verify package publish order and prerequisites for @gitgram/timemachine and @gitgram/timemachine-mcp.
|
||||
- Define the exact manual publish checklist, post-publish verification, and rollback/version bump procedure.
|
||||
- Define the exact API deployment procedure, including build, env validation, migration application, service restart, and health verification.
|
||||
- Gitgram:
|
||||
- Define the exact backend deployment procedure, including Prisma generation/migration, build, restart, and health verification.
|
||||
- Define the exact web deployment procedure, including build, runtime env injection, restart, and smoke verification.
|
||||
- Shared:
|
||||
- Choose one restart/control mechanism per service and document it as canonical. If both PM2 and systemd are kept, assign one as primary and one as
|
||||
fallback, not equal-status alternatives.
|
||||
|
||||
### 4. Harden secrets and env contracts for launch
|
||||
|
||||
- Use docs/secrets-contract.md and docs/environment-matrix.md as the starting point, but reconcile them with actual runtime/package needs.
|
||||
- Produce one canonical required-vars list for:
|
||||
- Gitgram backend
|
||||
- Gitgram web
|
||||
- AITM API
|
||||
- AITM package publish/release flow
|
||||
- Validate that production-only integrations needed for launch are present and named consistently, especially database, Redis, JWT, Polar, S3/storage,
|
||||
email, and any internal auth secrets.
|
||||
- Ensure validation scripts and runbooks match the chosen unprefixed/prefixed env convention and the manual deployment path.
|
||||
- Explicitly document which secrets are required before first launch vs optional post-launch integrations.
|
||||
|
||||
### 5. Define launch-day operations and rollback
|
||||
|
||||
- Convert the runbook into an operator-focused launch sequence with:
|
||||
- preflight checks
|
||||
- ordered deploy steps
|
||||
- health gates
|
||||
- smoke checks
|
||||
- rollback commands
|
||||
- post-launch monitoring window
|
||||
- Rollback should be manual-first and concrete:
|
||||
- previous package version for npm artifacts
|
||||
- previous app build/image/tag for server services
|
||||
- DB migration rollback policy or “restore from backup only” policy where down-migrations are not supported
|
||||
- Require a backup/checkpoint step before applying production migrations.
|
||||
|
||||
## Public Interfaces / Contracts
|
||||
|
||||
- No product API redesign is planned.
|
||||
- Public-facing contract changes are limited to:
|
||||
- canonical deployment/runbook docs
|
||||
- explicit deprecation of stale deployment paths and references
|
||||
- If any current docs mention missing components such as non-existent service paths, update the documentation contract rather than inventing new
|
||||
components for launch.
|
||||
|
||||
## Test Plan
|
||||
|
||||
- Verify repo-level build/test/typecheck commands for the launch-critical services still pass.
|
||||
- Dry-run the manual deployment commands in a staging-like environment for:
|
||||
- Gitgram backend
|
||||
- Gitgram web
|
||||
- AITM API
|
||||
- AITM package publish verification flow
|
||||
- Validate health endpoints after each service restart.
|
||||
- Run minimal smoke scenarios:
|
||||
- Gitgram auth and basic API reachability
|
||||
- Gitgram web load and API connectivity
|
||||
- AITM API health/readiness and one representative core flow
|
||||
- npm install plus basic CLI/MCP invocation for published AITM packages
|
||||
- Test rollback instructions at least once in staging-like conditions.
|
||||
|
||||
## Assumptions and Defaults
|
||||
|
||||
- Launch is for both products in parallel, not a staggered product strategy.
|
||||
- The delivery path is manual operations first, with CI/CD treated as non-blocking unless brought into alignment.
|
||||
- The hosting model is single server / operator-managed, not a multi-platform redesign.
|
||||
- Existing code is assumed largely complete; the main launch risk is operational inconsistency, stale docs, and deployment drift.
|
||||
- Any workflow or doc that conflicts with the chosen manual launch path should be updated, deprecated, or ignored rather than preserved for symmetry.
|
||||
112
V1_90_DAY_BACKLOG.md
Normal file
112
V1_90_DAY_BACKLOG.md
Normal file
@ -0,0 +1,112 @@
|
||||
# V1 90-Day Backlog (Actionable)
|
||||
|
||||
Canonical product reference: `NORTH_STAR_PRD_ARCHITECTURE_V1.md`
|
||||
Canonical schema reference: `CANONICAL_SQL_SCHEMA_V1.sql`
|
||||
|
||||
## Milestone A (Days 1-30) - Core Reliability
|
||||
|
||||
### Epic A1 - Canonical Data Layer
|
||||
- `A1-1` Define migration baseline from `CANONICAL_SQL_SCHEMA_V1.sql`.
|
||||
- Acceptance: migrations apply cleanly in dev/staging; rollback tested.
|
||||
- `A1-2` Implement repository/service layer for `checkpoints`, `checkpoint_files`, `messages`, `tool_calls`, `contexts`.
|
||||
- Acceptance: CRUD + listing APIs pass integration tests.
|
||||
- `A1-3` Add idempotency for action capture (`before_action`, `after_action`).
|
||||
- Acceptance: duplicate requests do not create duplicate checkpoints.
|
||||
|
||||
### Epic A2 - Deterministic Restore
|
||||
- `A2-1` Implement `POST /api/time/restore` for project/file/folder scope.
|
||||
- Acceptance: restore supports exact checkpoint IDs and time-based selection.
|
||||
- `A2-2` Implement `POST /api/time/undo` using linked before/after checkpoints.
|
||||
- Acceptance: undo returns previous good state in one operation.
|
||||
- `A2-3` Add restore preview endpoint with diff summary.
|
||||
- Acceptance: clients can fetch preview before applying restore.
|
||||
|
||||
### Epic A3 - Capture Pipeline
|
||||
- `A3-1` Implement `POST /api/actions/before` and `POST /api/actions/after`.
|
||||
- Acceptance: every successful action writes linked checkpoints.
|
||||
- `A3-2` Compute/store unified diffs and file-level stats.
|
||||
- Acceptance: `GET /api/time/diff` returns precomputed diff + stats.
|
||||
- `A3-3` Add sync worker for local cache to backend reconciliation.
|
||||
- Acceptance: sync lag metric reported; retries with backoff enabled.
|
||||
|
||||
### Epic A4 - Governance Baseline
|
||||
- `A4-1` Implement consent model (`operational_capture`, `training_export`) with org/project scope.
|
||||
- Acceptance: capture/export endpoints enforce consent checks.
|
||||
- `A4-2` Implement retention policy execution job.
|
||||
- Acceptance: expired records are soft-deleted then hard-deleted per policy.
|
||||
- `A4-3` Implement audit logging for restore/export/delete actions.
|
||||
- Acceptance: every governed action emits immutable audit event.
|
||||
|
||||
### Epic A5 - Gitgram Baseline Social
|
||||
- `A5-1` Implement `POST /api/repos/import` for public GitHub repos.
|
||||
- Acceptance: imported repo has profile and feed shell.
|
||||
- `A5-2` Implement posts/comments/reactions/follows APIs.
|
||||
- Acceptance: end-to-end create/read flows work for authenticated users.
|
||||
- `A5-3` Implement trending scorer v1 (GitHub + internal engagement).
|
||||
- Acceptance: `GET /api/trending` returns ranked repositories with reasons.
|
||||
|
||||
## Milestone B (Days 31-60) - Social + Time Integration
|
||||
|
||||
### Epic B1 - Checkpoint-Linked Content
|
||||
- `B1-1` Add post type `change_story` referencing checkpoint IDs.
|
||||
- Acceptance: posts can render before/after diff summary.
|
||||
- `B1-2` Add media upload pipeline for screenshots/videos.
|
||||
- Acceptance: signed upload + moderation scan before publish.
|
||||
- `B1-3` Add repository timeline widget consuming AITM checkpoints.
|
||||
- Acceptance: repo profile shows ordered technical change events.
|
||||
|
||||
### Epic B2 - Timeline UX and Reliability
|
||||
- `B2-1` Ship timeline endpoint pagination/filtering.
|
||||
- Acceptance: filters by actor, tool, file, and date range.
|
||||
- `B2-2` Add optimistic restore flow with server-side conflict checks.
|
||||
- Acceptance: conflict paths return actionable error payloads.
|
||||
- `B2-3` Add latency budgets and SLO dashboards for restore/diff/sync.
|
||||
- Acceptance: SLO alerts trigger on threshold breaches.
|
||||
|
||||
### Epic B3 - Org and Access Controls
|
||||
- `B3-1` Implement organizations + memberships + role checks.
|
||||
- Acceptance: owner/admin/member role matrix enforced in APIs.
|
||||
- `B3-2` Implement scoped API keys and key rotation.
|
||||
- Acceptance: read/write/admin scopes fully enforced and auditable.
|
||||
- `B3-3` Add project-level policy binding (capture/export/retention).
|
||||
- Acceptance: policy inheritance and overrides are deterministic.
|
||||
|
||||
## Milestone C (Days 61-90) - Intelligence + Growth
|
||||
|
||||
### Epic C1 - Semantic Search
|
||||
- `C1-1` Add embedding worker for code/message chunks.
|
||||
- Acceptance: embeddings persisted for eligible checkpoints/messages.
|
||||
- `C1-2` Implement `POST /api/search/code` and `POST /api/search/chats`.
|
||||
- Acceptance: relevance and latency meet benchmark targets.
|
||||
- `C1-3` Add hybrid search (keyword + vector rerank).
|
||||
- Acceptance: quality improves over keyword baseline in eval set.
|
||||
|
||||
### Epic C2 - Training Export Pipeline
|
||||
- `C2-1` Implement export jobs with consent gate and policy checks.
|
||||
- Acceptance: exports fail closed when consent/policy is missing.
|
||||
- `C2-2` Implement redaction pass for secrets/PII/license-sensitive text.
|
||||
- Acceptance: sampled audits meet precision/recall targets.
|
||||
- `C2-3` Implement signed export artifacts + audit traceability.
|
||||
- Acceptance: each artifact maps to consent ID, job ID, and actor ID.
|
||||
|
||||
### Epic C3 - Creator Growth Features
|
||||
- `C3-1` Add reels/stories authoring flows for repo owners.
|
||||
- Acceptance: owners can publish media content tied to repo/project.
|
||||
- `C3-2` Add follow recommendations (repo + developer graph).
|
||||
- Acceptance: recommendation CTR beats random baseline.
|
||||
- `C3-3` Add anti-abuse moderation queue and enforcement actions.
|
||||
- Acceptance: flagged content lifecycle is fully auditable.
|
||||
|
||||
## Cross-Cutting Tickets
|
||||
|
||||
- `X-1` Test strategy: unit + integration + e2e suites for capture/restore/social/governance APIs.
|
||||
- `X-2` Observability: metrics, tracing, logs with request and checkpoint correlation IDs.
|
||||
- `X-3` Security: threat model review and tenant-isolation verification tests.
|
||||
- `X-4` Documentation: API reference + runbooks + incident handling guides.
|
||||
|
||||
## KPI Gates (Must Hit)
|
||||
|
||||
- `KPI-1` Restore success rate >= 99%.
|
||||
- `KPI-2` P95 restore latency <= 2s (single file), <= 10s (medium project).
|
||||
- `KPI-3` >= 25% of active repos receive at least one social interaction.
|
||||
- `KPI-4` 100% training export jobs traceable to consent and audit records.
|
||||
474
V1_90_DAY_GITHUB_ISSUES.md
Normal file
474
V1_90_DAY_GITHUB_ISSUES.md
Normal file
@ -0,0 +1,474 @@
|
||||
# V1 90-Day Backlog -> GitHub Issues Format
|
||||
|
||||
Reference docs:
|
||||
- `NORTH_STAR_PRD_ARCHITECTURE_V1.md`
|
||||
- `V1_90_DAY_BACKLOG.md`
|
||||
- `CANONICAL_SQL_SCHEMA_V1.sql`
|
||||
|
||||
Label conventions:
|
||||
- Milestone: `m:A`, `m:B`, `m:C`, `m:X`
|
||||
- Area: `area:data`, `area:time-machine`, `area:social`, `area:governance`, `area:search`, `area:platform`
|
||||
- Priority: `p0`, `p1`, `p2`
|
||||
- Type: `type:feature`, `type:infra`, `type:security`, `type:docs`
|
||||
|
||||
Use this per issue:
|
||||
```bash
|
||||
gh issue create --title "<TITLE>" --label "<comma-separated-labels>" --body-file /tmp/issue.md
|
||||
```
|
||||
|
||||
## Milestone A (Days 1-30)
|
||||
|
||||
### [A1-1] Define migration baseline from canonical SQL
|
||||
- Labels: `m:A,area:data,p0,type:infra`
|
||||
- Depends on: none
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Create a stable migration baseline from `CANONICAL_SQL_SCHEMA_V1.sql`.
|
||||
|
||||
## Scope
|
||||
- Establish migration ordering and rollback strategy.
|
||||
- Validate extensions (`pgcrypto`, `vector`) and compatibility in staging.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Migrations apply cleanly in dev/staging.
|
||||
- Rollback path is tested and documented.
|
||||
```
|
||||
|
||||
### [A1-2] Implement repositories/services for core time-context tables
|
||||
- Labels: `m:A,area:data,p0,type:feature`
|
||||
- Depends on: `A1-1`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Implement data access services for checkpoints, checkpoint_files, messages, tool_calls, contexts.
|
||||
|
||||
## Acceptance Criteria
|
||||
- CRUD + list APIs pass integration tests.
|
||||
- Pagination/filtering support for timeline use cases.
|
||||
```
|
||||
|
||||
### [A1-3] Add idempotency for before/after action capture
|
||||
- Labels: `m:A,area:time-machine,p0,type:infra`
|
||||
- Depends on: `A1-2`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Prevent duplicate checkpoints for repeated action submissions.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Duplicate requests do not create duplicate checkpoints.
|
||||
- Idempotency key behavior is documented and tested.
|
||||
```
|
||||
|
||||
### [A2-1] Implement restore endpoint for file/folder/project scope
|
||||
- Labels: `m:A,area:time-machine,p0,type:feature`
|
||||
- Depends on: `A1-2`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Implement `POST /api/time/restore` for project, folder, and file scopes.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Supports checkpoint-id and time-based restore selectors.
|
||||
- Returns deterministic restore summary payload.
|
||||
```
|
||||
|
||||
### [A2-2] Implement undo-last via linked before/after checkpoints
|
||||
- Labels: `m:A,area:time-machine,p0,type:feature`
|
||||
- Depends on: `A2-1,A3-1`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Implement `POST /api/time/undo` based on linked before/after checkpoints.
|
||||
|
||||
## Acceptance Criteria
|
||||
- One-call rollback to previous good state.
|
||||
- Handles missing links gracefully with actionable errors.
|
||||
```
|
||||
|
||||
### [A2-3] Add restore preview endpoint with diff summary
|
||||
- Labels: `m:A,area:time-machine,p1,type:feature`
|
||||
- Depends on: `A3-2`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Show preview diff and file impact before applying restore.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Preview includes added/modified/deleted counts and key file list.
|
||||
- Clients can block restore when preview indicates risk.
|
||||
```
|
||||
|
||||
### [A3-1] Implement before/after action APIs
|
||||
- Labels: `m:A,area:time-machine,p0,type:feature`
|
||||
- Depends on: `A1-2`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Implement `POST /api/actions/before` and `POST /api/actions/after`.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Successful actions write linked checkpoints.
|
||||
- Message/tool-call linkage is persisted.
|
||||
```
|
||||
|
||||
### [A3-2] Compute/store unified diffs and file-level stats
|
||||
- Labels: `m:A,area:time-machine,p0,type:feature`
|
||||
- Depends on: `A3-1`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Persist precomputed diffs for fast timeline and restore previews.
|
||||
|
||||
## Acceptance Criteria
|
||||
- `GET /api/time/diff` reads precomputed diffs.
|
||||
- Diff stats are persisted per file and per action.
|
||||
```
|
||||
|
||||
### [A3-3] Add local-cache to backend sync worker
|
||||
- Labels: `m:A,area:platform,p1,type:infra`
|
||||
- Depends on: `A3-1`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Implement resilient push/retry pipeline from local cache to canonical backend.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Backoff + retry enabled.
|
||||
- Sync lag metric emitted.
|
||||
```
|
||||
|
||||
### [A4-1] Implement consent model enforcement
|
||||
- Labels: `m:A,area:governance,p0,type:security`
|
||||
- Depends on: `A1-1`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Enforce `operational_capture` and `training_export` consent by org/project scope.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Capture/export endpoints enforce consent checks.
|
||||
- No export allowed without explicit valid consent.
|
||||
```
|
||||
|
||||
### [A4-2] Implement retention policy execution job
|
||||
- Labels: `m:A,area:governance,p1,type:security`
|
||||
- Depends on: `A4-1`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Enforce retention windows for governed data classes.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Expired records are processed with soft/hard delete policy.
|
||||
- Job outputs audit trail.
|
||||
```
|
||||
|
||||
### [A4-3] Implement immutable audit logging for governed actions
|
||||
- Labels: `m:A,area:governance,p0,type:security`
|
||||
- Depends on: `A4-1`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Audit restore/export/delete/security actions with actor and target metadata.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Every governed action writes an audit row.
|
||||
- Query API supports actor/date/action filters.
|
||||
```
|
||||
|
||||
### [A5-1] Import public GitHub repos into social profiles
|
||||
- Labels: `m:A,area:social,p1,type:feature`
|
||||
- Depends on: none
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Implement `POST /api/repos/import` and create repo social profile shell.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Imported repo appears with basic profile/feed.
|
||||
- Duplicate import is idempotent.
|
||||
```
|
||||
|
||||
### [A5-2] Implement posts/comments/reactions/follows APIs
|
||||
- Labels: `m:A,area:social,p1,type:feature`
|
||||
- Depends on: `A5-1`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Ship social primitives for interaction on repository content.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Authenticated users can create/read interactions.
|
||||
- Ownership and visibility checks enforced.
|
||||
```
|
||||
|
||||
### [A5-3] Implement trending scorer v1
|
||||
- Labels: `m:A,area:social,p2,type:feature`
|
||||
- Depends on: `A5-2`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Compute `trend_scores` using GitHub and in-app engagement signals.
|
||||
|
||||
## Acceptance Criteria
|
||||
- `GET /api/trending` returns ranked repositories.
|
||||
- Signal contribution is included in debug metadata.
|
||||
```
|
||||
|
||||
## Milestone B (Days 31-60)
|
||||
|
||||
### [B1-1] Add `change_story` post type linked to checkpoints
|
||||
- Labels: `m:B,area:social,p1,type:feature`
|
||||
- Depends on: `A2-3,A5-2`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Allow posts that reference checkpoint IDs and render change summaries.
|
||||
|
||||
## Acceptance Criteria
|
||||
- `change_story` posts resolve checkpoint + diff preview.
|
||||
- Invalid checkpoint references are rejected.
|
||||
```
|
||||
|
||||
### [B1-2] Add media upload pipeline for screenshots/videos
|
||||
- Labels: `m:B,area:social,p1,type:feature`
|
||||
- Depends on: `A5-2`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Support signed uploads and moderation checks before publish.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Image/video uploads complete through signed URL flow.
|
||||
- Moderation status gates publishing.
|
||||
```
|
||||
|
||||
### [B1-3] Add repository timeline widget from AITM checkpoints
|
||||
- Labels: `m:B,area:social,p2,type:feature`
|
||||
- Depends on: `A3-2,B1-1`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Display technical change timeline on repo profile pages.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Timeline endpoint includes actor/tool/file summaries.
|
||||
- UI consumes paginated timeline API.
|
||||
```
|
||||
|
||||
### [B2-1] Timeline API pagination/filtering
|
||||
- Labels: `m:B,area:time-machine,p1,type:feature`
|
||||
- Depends on: `A3-2`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Add timeline filters by actor, tool, file, and date range.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Stable pagination cursors.
|
||||
- Filtered results verified by integration tests.
|
||||
```
|
||||
|
||||
### [B2-2] Optimistic restore flow with conflict checks
|
||||
- Labels: `m:B,area:time-machine,p1,type:feature`
|
||||
- Depends on: `A2-1`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Improve restore UX while preventing unsafe apply when local state diverges.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Conflict responses include actionable metadata.
|
||||
- Client can retry with explicit override.
|
||||
```
|
||||
|
||||
### [B2-3] SLO dashboards and alerts for restore/diff/sync
|
||||
- Labels: `m:B,area:platform,p1,type:infra`
|
||||
- Depends on: `A2-1,A3-3`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Track restore latency/success, diff latency, and sync lag SLOs.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Dashboards and alert thresholds exist.
|
||||
- On-call runbook references these alerts.
|
||||
```
|
||||
|
||||
### [B3-1] Implement organizations, memberships, role matrix
|
||||
- Labels: `m:B,area:governance,p1,type:feature`
|
||||
- Depends on: `A1-1`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Ship owner/admin/member authorization checks for org-scoped resources.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Role matrix enforced on protected endpoints.
|
||||
- Membership management endpoints are tested.
|
||||
```
|
||||
|
||||
### [B3-2] Scoped API keys and rotation
|
||||
- Labels: `m:B,area:governance,p1,type:security`
|
||||
- Depends on: `B3-1`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Enforce read/write/admin key scopes and key rotation policy.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Scope violations return 403 with traceable audit events.
|
||||
- Rotation flow supports zero-downtime cutover.
|
||||
```
|
||||
|
||||
### [B3-3] Project-level policy binding and inheritance
|
||||
- Labels: `m:B,area:governance,p1,type:feature`
|
||||
- Depends on: `A4-1,B3-1`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Bind capture/export/retention policies to org/project with deterministic inheritance.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Effective policy resolution API implemented.
|
||||
- Override precedence tested.
|
||||
```
|
||||
|
||||
## Milestone C (Days 61-90)
|
||||
|
||||
### [C1-1] Embedding worker for code/message chunks
|
||||
- Labels: `m:C,area:search,p1,type:feature`
|
||||
- Depends on: `A1-2`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Generate embeddings asynchronously for eligible checkpoints/messages/docs.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Worker persists embeddings with retry logic.
|
||||
- Backfill mode supports historical checkpoints.
|
||||
```
|
||||
|
||||
### [C1-2] Semantic search APIs for code and chats
|
||||
- Labels: `m:C,area:search,p1,type:feature`
|
||||
- Depends on: `C1-1`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Implement `POST /api/search/code` and `POST /api/search/chats`.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Returns ranked results with relevance score.
|
||||
- Meets baseline latency target in staging.
|
||||
```
|
||||
|
||||
### [C1-3] Hybrid search (keyword + vector rerank)
|
||||
- Labels: `m:C,area:search,p2,type:feature`
|
||||
- Depends on: `C1-2`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Improve quality by combining lexical retrieval with vector reranking.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Evaluation set shows improved relevance over keyword baseline.
|
||||
- Explainability metadata included for debugging.
|
||||
```
|
||||
|
||||
### [C2-1] Training export jobs with consent/policy gates
|
||||
- Labels: `m:C,area:governance,p0,type:security`
|
||||
- Depends on: `A4-1,B3-3`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Fail-closed export flow requiring valid consent and effective policy.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Jobs are blocked when gates fail.
|
||||
- Gate decisions are logged in audit records.
|
||||
```
|
||||
|
||||
### [C2-2] Redaction pipeline for secrets/PII/license-sensitive text
|
||||
- Labels: `m:C,area:governance,p0,type:security`
|
||||
- Depends on: `C2-1`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Redact sensitive data before export artifact creation.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Precision/recall quality gates defined and met on sampled audits.
|
||||
- Redaction report attached to export job summary.
|
||||
```
|
||||
|
||||
### [C2-3] Signed export artifacts with full traceability
|
||||
- Labels: `m:C,area:governance,p1,type:feature`
|
||||
- Depends on: `C2-2`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Ship signed artifact output and trace links to consent/job/actor.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Artifact metadata includes consent_id, job_id, actor_id.
|
||||
- Download access enforces authorization.
|
||||
```
|
||||
|
||||
### [C3-1] Reels/stories authoring flow for repo owners
|
||||
- Labels: `m:C,area:social,p2,type:feature`
|
||||
- Depends on: `B1-2`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Creator workflow for publishing reels/stories tied to repositories.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Repo owners can draft, preview, publish.
|
||||
- Visibility rules enforced.
|
||||
```
|
||||
|
||||
### [C3-2] Follow recommendations (repo + developer graph)
|
||||
- Labels: `m:C,area:social,p2,type:feature`
|
||||
- Depends on: `A5-2`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Recommend repositories/developers to follow based on activity graph.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Recommendation endpoint returns scored candidates.
|
||||
- CTR beats random baseline.
|
||||
```
|
||||
|
||||
### [C3-3] Anti-abuse moderation queue and enforcement actions
|
||||
- Labels: `m:C,area:social,p1,type:security`
|
||||
- Depends on: `B1-2`
|
||||
- Body:
|
||||
```md
|
||||
## Objective
|
||||
Moderation queue for flagged social content with auditable actions.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Flag -> review -> action lifecycle is tracked.
|
||||
- Moderator actions are auditable.
|
||||
```
|
||||
|
||||
## Cross-Cutting
|
||||
|
||||
### [X-1] End-to-end test strategy for capture/restore/social/governance
|
||||
- Labels: `m:X,area:platform,p0,type:infra`
|
||||
- Depends on: none
|
||||
|
||||
### [X-2] Observability with correlation IDs and tracing
|
||||
- Labels: `m:X,area:platform,p1,type:infra`
|
||||
- Depends on: `A3-1`
|
||||
|
||||
### [X-3] Security threat model and tenant-isolation verification
|
||||
- Labels: `m:X,area:governance,p0,type:security`
|
||||
- Depends on: `A4-1`
|
||||
|
||||
### [X-4] API/runbook/incident documentation
|
||||
- Labels: `m:X,area:platform,p1,type:docs`
|
||||
- Depends on: `A1-1`
|
||||
1
aitimemachine
Submodule
1
aitimemachine
Submodule
@ -0,0 +1 @@
|
||||
Subproject commit 937722abe0db76e8f3915fb9861d9479b5902dc2
|
||||
18
deploy/DEPLOYMENT.md
Normal file
18
deploy/DEPLOYMENT.md
Normal file
@ -0,0 +1,18 @@
|
||||
# Deprecated Production Compose Guide
|
||||
|
||||
This file is retained only as a historical reference for the old full-docker single-VPS experiment.
|
||||
|
||||
Do not use it as the launch source of truth.
|
||||
|
||||
Use `docs/runbook.md` instead.
|
||||
|
||||
Why:
|
||||
|
||||
- launch is manual-first and PM2-driven
|
||||
- `docker-compose.prod.yml` includes paths and services that are not the canonical launch contract
|
||||
- the canonical launch scope is Gitgram backend + Gitgram web + AITM API on one operator-managed host, with PostgreSQL and Redis treated as shared infra
|
||||
|
||||
What remains useful here:
|
||||
|
||||
- the repository still contains `docker-compose.prod.yml` if you want a non-canonical all-docker rehearsal
|
||||
- the root `.env.*.example` files are still the operator-facing env templates
|
||||
58
deploy/backup.sh
Executable file
58
deploy/backup.sh
Executable file
@ -0,0 +1,58 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# =============================================================================
|
||||
# Deprecated full-docker backup helper
|
||||
# Usage: bash deploy/backup.sh
|
||||
# Canonical backup procedure: docs/runbook.md
|
||||
# =============================================================================
|
||||
|
||||
COMPOSE_FILE="docker-compose.prod.yml"
|
||||
PROJECT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
BACKUP_DIR="$PROJECT_DIR/backups"
|
||||
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
|
||||
|
||||
cd "$PROJECT_DIR"
|
||||
|
||||
mkdir -p "$BACKUP_DIR"
|
||||
|
||||
echo "========================================="
|
||||
echo " Deprecated Docker Backup Helper — $TIMESTAMP"
|
||||
echo "========================================="
|
||||
echo "This script only applies to the non-canonical docker-compose.prod.yml path."
|
||||
echo "Use docs/runbook.md for the launch backup gate."
|
||||
echo ""
|
||||
|
||||
# --- PostgreSQL ---
|
||||
echo "[1/3] Backing up PostgreSQL..."
|
||||
docker compose -f "$COMPOSE_FILE" exec -T postgres \
|
||||
pg_dumpall -U "${POSTGRES_USER:-gitgram}" \
|
||||
| gzip > "$BACKUP_DIR/postgres_$TIMESTAMP.sql.gz"
|
||||
echo " Saved: postgres_$TIMESTAMP.sql.gz ($(du -h "$BACKUP_DIR/postgres_$TIMESTAMP.sql.gz" | cut -f1))"
|
||||
|
||||
# --- Redis ---
|
||||
echo "[2/3] Backing up Redis..."
|
||||
docker compose -f "$COMPOSE_FILE" exec -T redis redis-cli BGSAVE > /dev/null 2>&1 || true
|
||||
sleep 2
|
||||
docker compose -f "$COMPOSE_FILE" cp redis:/data/dump.rdb "$BACKUP_DIR/redis_$TIMESTAMP.rdb" 2>/dev/null || echo " Redis backup skipped (no dump.rdb)"
|
||||
|
||||
# --- Uploads ---
|
||||
echo "[3/3] Backing up uploads..."
|
||||
if [ -d "$PROJECT_DIR/gitgram/backend/uploads" ]; then
|
||||
tar -czf "$BACKUP_DIR/uploads_$TIMESTAMP.tar.gz" -C "$PROJECT_DIR/gitgram/backend" uploads
|
||||
echo " Saved: uploads_$TIMESTAMP.tar.gz"
|
||||
else
|
||||
echo " No uploads directory found, skipping."
|
||||
fi
|
||||
|
||||
# --- Cleanup old backups (keep last 7 days) ---
|
||||
echo ""
|
||||
echo "Cleaning backups older than 7 days..."
|
||||
find "$BACKUP_DIR" -name "*.gz" -mtime +7 -delete 2>/dev/null || true
|
||||
find "$BACKUP_DIR" -name "*.rdb" -mtime +7 -delete 2>/dev/null || true
|
||||
|
||||
echo ""
|
||||
echo "========================================="
|
||||
echo " Backup Complete!"
|
||||
echo "========================================="
|
||||
ls -lh "$BACKUP_DIR"/*_$TIMESTAMP.* 2>/dev/null
|
||||
47
deploy/deploy.sh
Executable file
47
deploy/deploy.sh
Executable file
@ -0,0 +1,47 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# =============================================================================
|
||||
# Deprecated full-docker rehearsal script
|
||||
# Run from project root: bash deploy/deploy.sh
|
||||
# Canonical launch path: docs/runbook.md
|
||||
# =============================================================================
|
||||
|
||||
COMPOSE_FILE="docker-compose.prod.yml"
|
||||
PROJECT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
|
||||
cd "$PROJECT_DIR"
|
||||
|
||||
echo "========================================="
|
||||
echo " Deprecated Docker Rehearsal Deploy"
|
||||
echo "========================================="
|
||||
echo "This script is not the canonical launch path."
|
||||
echo "Use docs/runbook.md for the PM2-based manual launch contract."
|
||||
echo ""
|
||||
|
||||
# Pull latest code
|
||||
if [ -d .git ]; then
|
||||
echo "[1/4] Pulling latest code..."
|
||||
git pull --ff-only
|
||||
else
|
||||
echo "[1/4] Not a git repo, skipping pull."
|
||||
fi
|
||||
|
||||
# Build all images
|
||||
echo "[2/4] Building Docker images..."
|
||||
docker compose -f "$COMPOSE_FILE" build
|
||||
|
||||
# Start/restart services
|
||||
echo "[3/4] Starting services..."
|
||||
docker compose -f "$COMPOSE_FILE" up -d
|
||||
|
||||
# Cleanup old images
|
||||
echo "[4/4] Cleaning up old images..."
|
||||
docker image prune -f
|
||||
|
||||
echo ""
|
||||
echo "========================================="
|
||||
echo " Deployment Complete!"
|
||||
echo "========================================="
|
||||
echo ""
|
||||
docker compose -f "$COMPOSE_FILE" ps
|
||||
25
deploy/logs.sh
Executable file
25
deploy/logs.sh
Executable file
@ -0,0 +1,25 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# =============================================================================
|
||||
# Deprecated full-docker log helper
|
||||
# Usage: bash deploy/logs.sh [service-name]
|
||||
# Canonical runtime logs: pm2 logs ... per docs/runbook.md
|
||||
# =============================================================================
|
||||
|
||||
COMPOSE_FILE="docker-compose.prod.yml"
|
||||
PROJECT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
|
||||
cd "$PROJECT_DIR"
|
||||
|
||||
SERVICE="${1:-}"
|
||||
|
||||
if [ -n "$SERVICE" ]; then
|
||||
echo "This script targets the non-canonical docker-compose.prod.yml path."
|
||||
echo "Tailing logs for: $SERVICE"
|
||||
docker compose -f "$COMPOSE_FILE" logs -f --tail=100 "$SERVICE"
|
||||
else
|
||||
echo "This script targets the non-canonical docker-compose.prod.yml path."
|
||||
echo "Tailing logs for all services"
|
||||
docker compose -f "$COMPOSE_FILE" logs -f --tail=50
|
||||
fi
|
||||
136
deploy/nginx/sites.conf
Normal file
136
deploy/nginx/sites.conf
Normal file
@ -0,0 +1,136 @@
|
||||
# =============================================================================
|
||||
# Nginx Configuration for Gitgram + AITimeMachine
|
||||
# Behind Cloudflare Free Tier (Full Strict SSL)
|
||||
# =============================================================================
|
||||
|
||||
# Cloudflare IP ranges for real IP restoration
|
||||
set_real_ip_from 173.245.48.0/20;
|
||||
set_real_ip_from 103.21.244.0/22;
|
||||
set_real_ip_from 103.22.200.0/22;
|
||||
set_real_ip_from 103.31.4.0/22;
|
||||
set_real_ip_from 141.101.64.0/18;
|
||||
set_real_ip_from 108.162.192.0/18;
|
||||
set_real_ip_from 190.93.240.0/20;
|
||||
set_real_ip_from 188.114.96.0/20;
|
||||
set_real_ip_from 197.234.240.0/22;
|
||||
set_real_ip_from 198.41.128.0/17;
|
||||
set_real_ip_from 162.158.0.0/15;
|
||||
set_real_ip_from 104.16.0.0/13;
|
||||
set_real_ip_from 104.24.0.0/14;
|
||||
set_real_ip_from 172.64.0.0/13;
|
||||
set_real_ip_from 131.0.72.0/22;
|
||||
# IPv6
|
||||
set_real_ip_from 2400:cb00::/32;
|
||||
set_real_ip_from 2606:4700::/32;
|
||||
set_real_ip_from 2803:f800::/32;
|
||||
set_real_ip_from 2405:b500::/32;
|
||||
set_real_ip_from 2405:8100::/32;
|
||||
set_real_ip_from 2a06:98c0::/29;
|
||||
set_real_ip_from 2c0f:f248::/32;
|
||||
real_ip_header CF-Connecting-IP;
|
||||
|
||||
# HTTP -> HTTPS redirect
|
||||
server {
|
||||
listen 80;
|
||||
listen [::]:80;
|
||||
server_name gitgram.app www.gitgram.app timemachine.gitgram.app timemachine-api.gitgram.app;
|
||||
return 301 https://$host$request_uri;
|
||||
}
|
||||
|
||||
# =============================================================================
|
||||
# gitgram.app — Gitgram Web + Backend
|
||||
# =============================================================================
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
listen [::]:443 ssl http2;
|
||||
server_name gitgram.app www.gitgram.app;
|
||||
|
||||
# Cloudflare Origin Certificate
|
||||
ssl_certificate /etc/ssl/cloudflare/gitgram.app.pem;
|
||||
ssl_certificate_key /etc/ssl/cloudflare/gitgram.app.key;
|
||||
ssl_protocols TLSv1.2 TLSv1.3;
|
||||
ssl_ciphers HIGH:!aNULL:!MD5;
|
||||
|
||||
# Proxy headers
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
|
||||
# API routes -> Gitgram Backend (port 4000)
|
||||
location /api/ {
|
||||
proxy_pass http://127.0.0.1:4000;
|
||||
proxy_http_version 1.1;
|
||||
|
||||
# File uploads
|
||||
client_max_body_size 100M;
|
||||
}
|
||||
|
||||
# WebSocket (Socket.IO) -> Gitgram Backend
|
||||
location /socket.io/ {
|
||||
proxy_pass http://127.0.0.1:4000;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_read_timeout 86400s;
|
||||
proxy_send_timeout 86400s;
|
||||
}
|
||||
|
||||
# Everything else -> Gitgram Web (port 3000)
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:3000;
|
||||
proxy_http_version 1.1;
|
||||
}
|
||||
}
|
||||
|
||||
# =============================================================================
|
||||
# timemachine.gitgram.app — AITM Website
|
||||
# =============================================================================
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
listen [::]:443 ssl http2;
|
||||
server_name timemachine.gitgram.app;
|
||||
|
||||
# Cloudflare Origin Certificate (reuses gitgram.app wildcard)
|
||||
ssl_certificate /etc/ssl/cloudflare/gitgram.app.pem;
|
||||
ssl_certificate_key /etc/ssl/cloudflare/gitgram.app.key;
|
||||
ssl_protocols TLSv1.2 TLSv1.3;
|
||||
ssl_ciphers HIGH:!aNULL:!MD5;
|
||||
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:3002;
|
||||
proxy_http_version 1.1;
|
||||
}
|
||||
}
|
||||
|
||||
# =============================================================================
|
||||
# timemachine-api.gitgram.app — AITM API Server
|
||||
# =============================================================================
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
listen [::]:443 ssl http2;
|
||||
server_name timemachine-api.gitgram.app;
|
||||
|
||||
# Cloudflare Origin Certificate (reuses gitgram.app wildcard)
|
||||
ssl_certificate /etc/ssl/cloudflare/gitgram.app.pem;
|
||||
ssl_certificate_key /etc/ssl/cloudflare/gitgram.app.key;
|
||||
ssl_protocols TLSv1.2 TLSv1.3;
|
||||
ssl_ciphers HIGH:!aNULL:!MD5;
|
||||
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
|
||||
client_max_body_size 50M;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:3001;
|
||||
proxy_http_version 1.1;
|
||||
}
|
||||
}
|
||||
130
deploy/setup-hetzner.sh
Executable file
130
deploy/setup-hetzner.sh
Executable file
@ -0,0 +1,130 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# =============================================================================
|
||||
# Hetzner VPS bootstrap helper
|
||||
# Run as root on a fresh Ubuntu 22.04+ VPS
|
||||
# This is not the full launch procedure; use docs/runbook.md for launch.
|
||||
# =============================================================================
|
||||
|
||||
echo "========================================="
|
||||
echo " Hetzner VPS Bootstrap for Gitgram + AITM"
|
||||
echo "========================================="
|
||||
|
||||
# --- System Updates ---
|
||||
echo "[1/7] Updating system packages..."
|
||||
apt-get update && apt-get upgrade -y
|
||||
|
||||
# --- Install Node 20 + PM2 ---
|
||||
echo "[2/7] Installing Node 20 runtime and PM2..."
|
||||
apt-get install -y curl ca-certificates gnupg build-essential
|
||||
|
||||
if ! command -v node &> /dev/null || ! node -v | grep -q '^v20\.'; then
|
||||
mkdir -p /etc/apt/keyrings
|
||||
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key \
|
||||
| gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
|
||||
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" \
|
||||
> /etc/apt/sources.list.d/nodesource.list
|
||||
apt-get update
|
||||
apt-get install -y nodejs
|
||||
fi
|
||||
|
||||
npm install -g pm2
|
||||
|
||||
# --- Install Nginx ---
|
||||
echo "[3/7] Installing Nginx..."
|
||||
apt-get install -y nginx
|
||||
systemctl enable nginx
|
||||
|
||||
# --- Configure UFW Firewall ---
|
||||
echo "[4/7] Configuring firewall..."
|
||||
apt-get install -y ufw
|
||||
ufw default deny incoming
|
||||
ufw default allow outgoing
|
||||
ufw allow 22/tcp # SSH
|
||||
ufw allow 80/tcp # HTTP (redirect to HTTPS)
|
||||
ufw allow 443/tcp # HTTPS
|
||||
echo "y" | ufw enable
|
||||
ufw status
|
||||
|
||||
# --- Create deploy user ---
|
||||
echo "[5/7] Creating deploy user..."
|
||||
if ! id "deploy" &>/dev/null; then
|
||||
useradd -m -s /bin/bash deploy
|
||||
echo " Created user 'deploy'. Set a password with: passwd deploy"
|
||||
echo " Add SSH key: ssh-copy-id deploy@<server-ip>"
|
||||
else
|
||||
echo " User 'deploy' already exists."
|
||||
fi
|
||||
|
||||
# --- Setup Nginx config ---
|
||||
echo "[6/7] Installing Nginx configuration..."
|
||||
mkdir -p /etc/ssl/cloudflare
|
||||
|
||||
# Copy the nginx config
|
||||
if [ -f "$(dirname "$0")/nginx/sites.conf" ]; then
|
||||
cp "$(dirname "$0")/nginx/sites.conf" /etc/nginx/conf.d/sites.conf
|
||||
echo " Nginx config installed to /etc/nginx/conf.d/sites.conf"
|
||||
else
|
||||
echo " WARNING: nginx/sites.conf not found. Copy it manually."
|
||||
fi
|
||||
|
||||
# --- Create project directory & env files ---
|
||||
echo "[7/7] Setting up project directory..."
|
||||
PROJECT_DIR="/home/deploy/gitgram-ai"
|
||||
BOOTSTRAP_ENV_DIR="$PROJECT_DIR/bootstrap-env"
|
||||
mkdir -p "$PROJECT_DIR"
|
||||
mkdir -p "$BOOTSTRAP_ENV_DIR"
|
||||
|
||||
# Copy env templates if they exist
|
||||
for env_file in .env.postgres.example .env.gitgram.example .env.gitgram-web.example .env.aitm-api.example .env.aitm-website.example; do
|
||||
src="$(dirname "$0")/../$env_file"
|
||||
dest_name="${env_file%.example}"
|
||||
if [ -f "$src" ] && [ ! -f "$BOOTSTRAP_ENV_DIR/$dest_name" ]; then
|
||||
cp "$src" "$BOOTSTRAP_ENV_DIR/$dest_name"
|
||||
echo " Staged $dest_name in $BOOTSTRAP_ENV_DIR"
|
||||
fi
|
||||
done
|
||||
|
||||
chown -R deploy:deploy "$PROJECT_DIR"
|
||||
|
||||
# --- Print next steps ---
|
||||
echo ""
|
||||
echo "========================================="
|
||||
echo " Setup Complete!"
|
||||
echo "========================================="
|
||||
echo ""
|
||||
echo "NEXT STEPS:"
|
||||
echo ""
|
||||
echo "1. Upload Cloudflare Origin Certificates:"
|
||||
echo " scp gitgram.app.pem root@<server>:/etc/ssl/cloudflare/"
|
||||
echo " scp gitgram.app.key root@<server>:/etc/ssl/cloudflare/"
|
||||
echo " (gitgram.app wildcard cert covers timemachine.gitgram.app subdomains)"
|
||||
echo ""
|
||||
echo "2. Configure Cloudflare DNS (A records):"
|
||||
echo " gitgram.app -> <server-ip> (Proxied)"
|
||||
echo " www.gitgram.app -> <server-ip> (Proxied)"
|
||||
echo " timemachine.gitgram.app -> <server-ip> (Proxied)"
|
||||
echo " timemachine-api.gitgram.app -> <server-ip> (Proxied)"
|
||||
echo ""
|
||||
echo "3. Set Cloudflare SSL/TLS mode to 'Full (Strict)'"
|
||||
echo ""
|
||||
echo "4. Edit environment files in $PROJECT_DIR:"
|
||||
echo " Templates were staged in $BOOTSTRAP_ENV_DIR"
|
||||
echo " Copy them into the repo root after cloning"
|
||||
echo ""
|
||||
echo "5. Clone repo and continue with the manual runbook:"
|
||||
echo " su - deploy"
|
||||
echo " cd $PROJECT_DIR"
|
||||
echo " git clone <repo-url> ."
|
||||
echo " cp bootstrap-env/.env.gitgram ."
|
||||
echo " cp bootstrap-env/.env.gitgram-web ."
|
||||
echo " cp bootstrap-env/.env.aitm-api ."
|
||||
echo " cp bootstrap-env/.env.aitm-website . # optional"
|
||||
echo " less docs/runbook.md"
|
||||
echo " npm run verify:launch"
|
||||
echo " bash scripts/deploy-launch.sh staging --gitgram-only"
|
||||
echo " # Then deploy AITM and run the public verification script"
|
||||
echo ""
|
||||
echo "6. Test nginx config:"
|
||||
echo " nginx -t && systemctl reload nginx"
|
||||
191
docker-compose.prod.yml
Normal file
191
docker-compose.prod.yml
Normal file
@ -0,0 +1,191 @@
|
||||
services:
|
||||
# =========================================================================
|
||||
# Infrastructure
|
||||
# =========================================================================
|
||||
postgres:
|
||||
image: postgres:16-alpine
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "127.0.0.1:5432:5432"
|
||||
environment:
|
||||
POSTGRES_USER: ${POSTGRES_USER:-gitgram}
|
||||
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD}
|
||||
POSTGRES_DB: ${POSTGRES_DB:-gitgram}
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql/data
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-gitgram}"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 512M
|
||||
logging:
|
||||
driver: json-file
|
||||
options:
|
||||
max-size: "10m"
|
||||
max-file: "3"
|
||||
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "127.0.0.1:6379:6379"
|
||||
volumes:
|
||||
- redis_data:/data
|
||||
healthcheck:
|
||||
test: ["CMD", "redis-cli", "ping"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 256M
|
||||
logging:
|
||||
driver: json-file
|
||||
options:
|
||||
max-size: "10m"
|
||||
max-file: "3"
|
||||
|
||||
# =========================================================================
|
||||
# Gitgram
|
||||
# =========================================================================
|
||||
gitgram-backend:
|
||||
build:
|
||||
context: ./gitgram/backend
|
||||
dockerfile: Dockerfile
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "127.0.0.1:4000:4000"
|
||||
env_file:
|
||||
- .env.gitgram
|
||||
environment:
|
||||
NODE_ENV: production
|
||||
PORT: 4000
|
||||
DATABASE_URL: postgresql://${POSTGRES_USER:-gitgram}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-gitgram}
|
||||
REDIS_URL: redis://redis:6379
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
redis:
|
||||
condition: service_healthy
|
||||
healthcheck:
|
||||
test: ["CMD", "wget", "-qO-", "http://localhost:4000/health"]
|
||||
interval: 30s
|
||||
timeout: 5s
|
||||
retries: 3
|
||||
start_period: 15s
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 512M
|
||||
logging:
|
||||
driver: json-file
|
||||
options:
|
||||
max-size: "10m"
|
||||
max-file: "3"
|
||||
|
||||
gitgram-web:
|
||||
build:
|
||||
context: ./gitgram/web
|
||||
dockerfile: Dockerfile
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "127.0.0.1:3000:3000"
|
||||
env_file:
|
||||
- .env.gitgram-web
|
||||
environment:
|
||||
NODE_ENV: production
|
||||
PORT: 3000
|
||||
depends_on:
|
||||
gitgram-backend:
|
||||
condition: service_healthy
|
||||
healthcheck:
|
||||
test: ["CMD", "wget", "-qO-", "http://localhost:3000/"]
|
||||
interval: 30s
|
||||
timeout: 5s
|
||||
retries: 3
|
||||
start_period: 15s
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 256M
|
||||
logging:
|
||||
driver: json-file
|
||||
options:
|
||||
max-size: "10m"
|
||||
max-file: "3"
|
||||
|
||||
# =========================================================================
|
||||
# AITimeMachine
|
||||
# =========================================================================
|
||||
aitm-api:
|
||||
build:
|
||||
context: ./aitimemachine/api-server
|
||||
dockerfile: Dockerfile
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "127.0.0.1:3001:3001"
|
||||
env_file:
|
||||
- .env.aitm-api
|
||||
environment:
|
||||
NODE_ENV: production
|
||||
PORT: 3001
|
||||
# DATABASE_URL is intentionally provided by .env.aitm-api (or the host environment),
|
||||
# so production can use Neon without compose overriding it.
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
healthcheck:
|
||||
test: ["CMD", "wget", "-qO-", "http://localhost:3001/health"]
|
||||
interval: 30s
|
||||
timeout: 5s
|
||||
retries: 3
|
||||
start_period: 15s
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 512M
|
||||
logging:
|
||||
driver: json-file
|
||||
options:
|
||||
max-size: "10m"
|
||||
max-file: "3"
|
||||
|
||||
aitm-website:
|
||||
build:
|
||||
context: ./aitimemachine/website
|
||||
dockerfile: Dockerfile
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "127.0.0.1:3002:3002"
|
||||
env_file:
|
||||
- .env.aitm-website
|
||||
environment:
|
||||
NODE_ENV: production
|
||||
PORT: 3002
|
||||
depends_on:
|
||||
aitm-api:
|
||||
condition: service_healthy
|
||||
healthcheck:
|
||||
test: ["CMD", "wget", "-qO-", "http://localhost:3002/"]
|
||||
interval: 30s
|
||||
timeout: 5s
|
||||
retries: 3
|
||||
start_period: 15s
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 256M
|
||||
logging:
|
||||
driver: json-file
|
||||
options:
|
||||
max-size: "10m"
|
||||
max-file: "3"
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
redis_data:
|
||||
338
docker-compose.yml
Normal file
338
docker-compose.yml
Normal file
@ -0,0 +1,338 @@
|
||||
# =============================================================================
|
||||
# Local Development — Docker Compose
|
||||
# =============================================================================
|
||||
# Runs infrastructure + all application services for local development.
|
||||
#
|
||||
# Usage:
|
||||
# docker compose up # start everything
|
||||
# docker compose up postgres redis # infrastructure only
|
||||
# docker compose --profile tools up # include GitNexus + Context7
|
||||
# docker compose down -v # tear down and remove volumes
|
||||
#
|
||||
# Services (default profile):
|
||||
# postgres - Shared PostgreSQL 16 (port 5432)
|
||||
# redis - Shared Redis 7 (port 6379)
|
||||
# gitgram-backend - Gitgram Express API (port 4000)
|
||||
# gitgram-web - Gitgram Next.js UI (port 3000)
|
||||
# aitm-api - AITM REST API (port 3001)
|
||||
# aitm-website - AITM Next.js UI (port 3002)
|
||||
# aitm-mcp - AITM MCP server (port 3003)
|
||||
#
|
||||
# Services (tools profile):
|
||||
# gitnexus - Code intelligence MCP (port 3010)
|
||||
# context7 - Live library docs MCP (port 3100)
|
||||
#
|
||||
# Notes:
|
||||
# - AITM can point to Neon or local Postgres; local postgres is the default.
|
||||
# - aitm-mcp is an stdio/HTTP MCP server; adjust port if you expose it.
|
||||
# - All secrets in environment blocks are dev-only placeholders — never use
|
||||
# these values in production.
|
||||
# =============================================================================
|
||||
|
||||
networks:
|
||||
gitgram-net:
|
||||
driver: bridge
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
driver: local
|
||||
redis_data:
|
||||
driver: local
|
||||
gitgram_uploads:
|
||||
driver: local
|
||||
gitgram_logs:
|
||||
driver: local
|
||||
|
||||
services:
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Infrastructure
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
postgres:
|
||||
image: postgres:16-alpine
|
||||
container_name: gitgram-postgres
|
||||
networks:
|
||||
- gitgram-net
|
||||
environment:
|
||||
POSTGRES_USER: gitgram
|
||||
POSTGRES_PASSWORD: gitgram_dev
|
||||
POSTGRES_DB: gitgram
|
||||
ports:
|
||||
- "5432:5432"
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql/data
|
||||
# Optional init scripts: place *.sql or *.sh files here to seed the DB.
|
||||
# - ./deploy/postgres/init:/docker-entrypoint-initdb.d:ro
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U gitgram -d gitgram"]
|
||||
interval: 5s
|
||||
timeout: 5s
|
||||
retries: 10
|
||||
start_period: 10s
|
||||
restart: unless-stopped
|
||||
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
container_name: gitgram-redis
|
||||
networks:
|
||||
- gitgram-net
|
||||
ports:
|
||||
- "6379:6379"
|
||||
volumes:
|
||||
- redis_data:/data
|
||||
# Persistence (AOF) + sensible memory cap for local dev.
|
||||
command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
|
||||
healthcheck:
|
||||
test: ["CMD", "redis-cli", "ping"]
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 10
|
||||
start_period: 5s
|
||||
restart: unless-stopped
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Gitgram Backend (Express API — Node 20)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
gitgram-backend:
|
||||
build:
|
||||
context: ./gitgram/backend
|
||||
dockerfile: Dockerfile
|
||||
container_name: gitgram-backend
|
||||
networks:
|
||||
- gitgram-net
|
||||
ports:
|
||||
- "4000:4000"
|
||||
env_file:
|
||||
- path: .env.gitgram
|
||||
required: false # falls back to inline environment below
|
||||
environment:
|
||||
NODE_ENV: development
|
||||
PORT: "4000"
|
||||
DATABASE_URL: postgresql://gitgram:gitgram_dev@postgres:5432/gitgram
|
||||
REDIS_URL: redis://redis:6379
|
||||
JWT_SECRET: local-dev-jwt-secret-not-for-production-use-replace-me
|
||||
JWT_REFRESH_SECRET: local-dev-refresh-secret-not-for-production-replace
|
||||
JWT_EXPIRES_IN: 15m
|
||||
REFRESH_TOKEN_EXPIRES_IN: 7d
|
||||
FRONTEND_URL: http://localhost:3000
|
||||
CORS_ORIGIN: http://localhost:3000,http://localhost:3001,http://localhost:3002,http://localhost:8081
|
||||
STORAGE_TYPE: local
|
||||
UPLOAD_DIR: /app/uploads
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
redis:
|
||||
condition: service_healthy
|
||||
volumes:
|
||||
- gitgram_uploads:/app/uploads
|
||||
- gitgram_logs:/app/logs
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "node -e \"require('http').get('http://localhost:4000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })\""]
|
||||
interval: 15s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 30s
|
||||
# Run migrations then start the compiled server.
|
||||
command: sh -c "npx prisma migrate deploy && node dist/index.js"
|
||||
restart: unless-stopped
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Gitgram Web (Next.js — Node 20)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
gitgram-web:
|
||||
build:
|
||||
context: ./gitgram/web
|
||||
dockerfile: Dockerfile
|
||||
container_name: gitgram-web
|
||||
networks:
|
||||
- gitgram-net
|
||||
ports:
|
||||
- "3000:3000"
|
||||
env_file:
|
||||
- path: .env.gitgram-web
|
||||
required: false
|
||||
environment:
|
||||
NODE_ENV: development
|
||||
PORT: "3000"
|
||||
NEXT_PUBLIC_API_URL: http://localhost:4000/api
|
||||
NEXT_PUBLIC_WS_URL: http://localhost:4000
|
||||
NEXT_PUBLIC_AITM_API_URL: http://localhost:3001/v1
|
||||
depends_on:
|
||||
gitgram-backend:
|
||||
condition: service_healthy
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "node -e \"require('http').get('http://localhost:3000', (r) => { process.exit(r.statusCode < 500 ? 0 : 1) })\""]
|
||||
interval: 15s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 30s
|
||||
restart: unless-stopped
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AITM API Server (Hono/Node — Node 20)
|
||||
# ---------------------------------------------------------------------------
|
||||
# Connects to local Postgres by default. Override DATABASE_URL in
|
||||
# .env.aitm-api to point at Neon for hybrid dev.
|
||||
|
||||
aitm-api:
|
||||
build:
|
||||
context: ./aitimemachine/api-server
|
||||
dockerfile: Dockerfile
|
||||
container_name: aitm-api
|
||||
networks:
|
||||
- gitgram-net
|
||||
ports:
|
||||
- "3001:3001"
|
||||
env_file:
|
||||
- path: .env.aitm-api
|
||||
required: false
|
||||
environment:
|
||||
NODE_ENV: development
|
||||
HOST: "0.0.0.0"
|
||||
PORT: "3001"
|
||||
DATABASE_URL: postgresql://gitgram:gitgram_dev@postgres:5432/gitgram
|
||||
REDIS_URL: redis://redis:6379
|
||||
CORS_ORIGIN: http://localhost:3000,http://localhost:3002
|
||||
WEBSITE_URL: http://localhost:3002
|
||||
INTERNAL_SECRET: local-dev-internal-secret-replace-in-prod
|
||||
GITGRAM_API_URL: http://gitgram-backend:4000
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
redis:
|
||||
condition: service_healthy
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "node -e \"require('http').get('http://localhost:3001/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })\""]
|
||||
interval: 15s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 30s
|
||||
restart: unless-stopped
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AITM Website (Next.js — Node 20)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
aitm-website:
|
||||
build:
|
||||
context: ./aitimemachine/website
|
||||
dockerfile: Dockerfile
|
||||
container_name: aitm-website
|
||||
networks:
|
||||
- gitgram-net
|
||||
ports:
|
||||
- "3002:3002"
|
||||
env_file:
|
||||
- path: .env.aitm-website
|
||||
required: false
|
||||
environment:
|
||||
NODE_ENV: development
|
||||
PORT: "3002"
|
||||
NEXT_PUBLIC_API_URL: http://localhost:3001
|
||||
API_URL: http://aitm-api:3001
|
||||
INTERNAL_SECRET: local-dev-internal-secret-replace-in-prod
|
||||
NEXT_PUBLIC_APP_URL: http://localhost:3002
|
||||
depends_on:
|
||||
aitm-api:
|
||||
condition: service_healthy
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "node -e \"require('http').get('http://localhost:3002', (r) => { process.exit(r.statusCode < 500 ? 0 : 1) })\""]
|
||||
interval: 15s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 30s
|
||||
restart: unless-stopped
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AITM MCP Server (stdio / HTTP bridge — Node 20)
|
||||
# ---------------------------------------------------------------------------
|
||||
# The MCP server communicates over stdio by default; this container wraps it
|
||||
# so Claude Code and other editors can reach it over HTTP on port 3003.
|
||||
|
||||
aitm-mcp:
|
||||
build:
|
||||
context: ./aitimemachine/mcp
|
||||
dockerfile: Dockerfile
|
||||
container_name: aitm-mcp
|
||||
networks:
|
||||
- gitgram-net
|
||||
ports:
|
||||
- "3003:3003"
|
||||
env_file:
|
||||
- path: .env.aitm-api
|
||||
required: false
|
||||
environment:
|
||||
NODE_ENV: development
|
||||
PORT: "3003"
|
||||
AITM_API_URL: http://aitm-api:3001
|
||||
GITNEXUS_URL: http://gitnexus:3010
|
||||
AITM_GITNEXUS_ENABLED: "0"
|
||||
CONTEXT7_URL: http://context7:3100
|
||||
AITM_CONTEXT7_ENABLED: "0"
|
||||
depends_on:
|
||||
aitm-api:
|
||||
condition: service_healthy
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "node -e \"require('http').get('http://localhost:3003/health', (r) => { process.exit(r.statusCode < 500 ? 0 : 1) }).on('error', () => process.exit(0))\""]
|
||||
interval: 20s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 20s
|
||||
restart: unless-stopped
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# GitNexus — code intelligence MCP server (profile: tools)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
gitnexus:
|
||||
build:
|
||||
context: ./aitimemachine/gitnexus
|
||||
dockerfile: Dockerfile
|
||||
container_name: gitnexus
|
||||
networks:
|
||||
- gitgram-net
|
||||
ports:
|
||||
- "3010:3010"
|
||||
environment:
|
||||
NODE_ENV: development
|
||||
PORT: "3010"
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "node -e \"require('http').get('http://localhost:3010/health', (r) => { process.exit(r.statusCode < 500 ? 0 : 1) }).on('error', () => process.exit(0))\""]
|
||||
interval: 20s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 15s
|
||||
profiles:
|
||||
- tools
|
||||
restart: unless-stopped
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Context7 — live library docs MCP server (profile: tools)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
context7:
|
||||
image: node:20-alpine
|
||||
container_name: context7
|
||||
working_dir: /app
|
||||
networks:
|
||||
- gitgram-net
|
||||
volumes:
|
||||
- ./aitimemachine/context7/packages/mcp:/app:ro
|
||||
command: sh -c "npm install --if-present && node dist/index.js"
|
||||
ports:
|
||||
- "3100:3100"
|
||||
environment:
|
||||
NODE_ENV: development
|
||||
PORT: "3100"
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "node -e \"require('http').get('http://localhost:3100/health', (r) => { process.exit(r.statusCode < 500 ? 0 : 1) }).on('error', () => process.exit(0))\""]
|
||||
interval: 20s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 20s
|
||||
profiles:
|
||||
- tools
|
||||
restart: unless-stopped
|
||||
591
docs/AGENTS.md
Normal file
591
docs/AGENTS.md
Normal file
@ -0,0 +1,591 @@
|
||||
# AI Tools — Architecture & Reference
|
||||
|
||||
This document is the single-source reference for every AI tool integrated into the
|
||||
`gitgram-ai` monorepo. All tools live under `aitimemachine/` and are wired together
|
||||
through the AITM MCP server.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Architecture overview](#1-architecture-overview)
|
||||
2. [Starting each tool](#2-starting-each-tool)
|
||||
3. [Analyzing codebases with GitNexus](#3-analyzing-codebases-with-gitnexus)
|
||||
4. [A2A protocol — how it works and how to register agents](#4-a2a-protocol)
|
||||
5. [MCP tools reference](#5-mcp-tools-reference)
|
||||
6. [Quick-start guide](#6-quick-start-guide)
|
||||
|
||||
---
|
||||
|
||||
## 1. Architecture Overview
|
||||
|
||||
```
|
||||
gitgram-ai/
|
||||
├── aitimemachine/
|
||||
│ ├── mcp/ # AITM MCP server — central hub, exposes all tools
|
||||
│ ├── api-server/ # REST API for TimeMachine state (Drizzle/Neon)
|
||||
│ ├── gitnexus/ # Graph-powered code intelligence, 17 MCP tools
|
||||
│ ├── a2a/ # A2A protocol types & JSON-RPC helpers
|
||||
│ ├── context7/packages/mcp/ # Context7 MCP — up-to-date library docs
|
||||
│ ├── beads/ # Go CLI for distributed graph issue tracking (bd)
|
||||
│ ├── pal-mcp-server/ # PAL MCP — multi-model AI orchestration
|
||||
│ └── tools/
|
||||
│ ├── repo2txt/ # React/Vite UI: convert repos to LLM-readable text
|
||||
│ └── repo-to-text/ # Python CLI: same conversion, CLI variant
|
||||
└── scripts/
|
||||
├── setup-aitm-tools.sh # One-shot build of all companion tools
|
||||
└── start-all-dev.sh # Start core dev services with concurrently
|
||||
```
|
||||
|
||||
### How the pieces connect
|
||||
|
||||
```
|
||||
Claude Code / Cursor / any MCP client
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────────────────┐
|
||||
│ AITM MCP server │
|
||||
│ aitimemachine/mcp (port: stdio) │
|
||||
│ │
|
||||
│ Tool groups: │
|
||||
│ • tm_* — TimeMachine core │
|
||||
│ • gn_* proxy — GitNexus tools │
|
||||
│ • tm_docs_* — Context7 tools │
|
||||
│ • a2a_* — A2A agent tools │
|
||||
│ • before/after_action │
|
||||
└──────────┬──────────────┬────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────┐ ┌──────────────────┐
|
||||
│ GitNexus │ │ Context7 MCP │
|
||||
│ :3001/msg │ │ :3100/msg │
|
||||
└──────────────┘ └──────────────────┘
|
||||
```
|
||||
|
||||
The AITM MCP server is the single entry point for AI clients. It embeds the
|
||||
TimeMachine engine directly and proxies GitNexus and Context7 over HTTP/JSON-RPC.
|
||||
PAL MCP and Beads run as independent services alongside it.
|
||||
|
||||
### Tool inventory
|
||||
|
||||
| Tool | Location | Language | Purpose |
|
||||
|------|----------|----------|---------|
|
||||
| AITM MCP server | `aitimemachine/mcp` | TypeScript | Central MCP hub; checkpoint, restore, session, file, worktree, S3, Docker capsule tools |
|
||||
| GitNexus | `aitimemachine/gitnexus` | TypeScript | Code knowledge graph: query, impact, trace, rename, route/tool maps |
|
||||
| PAL MCP Server | `aitimemachine/pal-mcp-server` | Python | Multi-model AI orchestration (chat, code review, debug, plan, consensus) |
|
||||
| Context7 | `aitimemachine/context7/packages/mcp` | TypeScript | Up-to-date library documentation injected into LLM context |
|
||||
| Beads (`bd`) | `aitimemachine/beads` | Go | Distributed graph issue tracker for AI agents (Dolt-powered) |
|
||||
| A2A protocol | `aitimemachine/a2a` | TypeScript | JSON-RPC 2.0 agent-to-agent protocol types and SDK |
|
||||
| repo2txt | `aitimemachine/tools/repo2txt` | TypeScript/React | UI to convert a GitHub repo or local directory to LLM-readable text |
|
||||
| repo-to-text | `aitimemachine/tools/repo-to-text` | Python | CLI to convert a directory to structured XML/text for LLM prompts |
|
||||
|
||||
---
|
||||
|
||||
## 2. Starting Each Tool
|
||||
|
||||
All commands below are root-level npm scripts. Run them from the monorepo root
|
||||
(`/Users/arhansubasi/gitgram-ai/` or wherever you cloned the repo).
|
||||
|
||||
### AITM MCP server
|
||||
|
||||
```bash
|
||||
npm run dev:aitm-mcp
|
||||
# Starts aitimemachine/mcp in watch mode (stdio transport)
|
||||
```
|
||||
|
||||
Configure your MCP client to launch it via the `mcp.json` at
|
||||
`aitimemachine/mcp/mcp.json`. The `aitm` server entry uses `node dist/index.js`.
|
||||
|
||||
Environment variables recognised by the server:
|
||||
|
||||
| Variable | Default | Purpose |
|
||||
|----------|---------|---------|
|
||||
| `GITNEXUS_URL` | `http://localhost:3001` | Where to proxy GitNexus tool calls |
|
||||
| `CONTEXT7_URL` | `http://localhost:3100` | Where to proxy Context7 tool calls |
|
||||
| `AITM_A2A_AGENTS` | `[]` | JSON array of `{ name, url }` to register A2A agents |
|
||||
| `AITM_EXPERIMENTAL_TOOLS` | `0` | Set to `1` to enable experimental tools |
|
||||
| `DISABLED_TOOLS` | — | Comma-separated list of tool names to disable |
|
||||
|
||||
### AITM API server
|
||||
|
||||
```bash
|
||||
npm run dev:aitm-api # standard dev mode
|
||||
npm run dev:aitm-api:clean # dev mode with a clean database
|
||||
```
|
||||
|
||||
Serves the TimeMachine REST API at `http://localhost:3001` by default.
|
||||
|
||||
### GitNexus
|
||||
|
||||
```bash
|
||||
npm run dev:gitnexus # starts the GitNexus HTTP server at :3001
|
||||
npm run dev:gitnexus-web # starts the GitNexus web UI
|
||||
```
|
||||
|
||||
GitNexus must have at least one repo indexed before it can answer queries.
|
||||
See [Section 3](#3-analyzing-codebases-with-gitnexus) for indexing instructions.
|
||||
|
||||
### PAL MCP Server
|
||||
|
||||
```bash
|
||||
npm run dev:pal-mcp
|
||||
# Runs aitimemachine/pal-mcp-server/run-server.sh (activates Python venv, starts server)
|
||||
```
|
||||
|
||||
Configure providers by creating a `.env` in `aitimemachine/pal-mcp-server/` based
|
||||
on the `requirements.txt` instructions. At minimum set one of:
|
||||
`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `GEMINI_API_KEY`.
|
||||
|
||||
### Context7
|
||||
|
||||
```bash
|
||||
npm run dev:context7
|
||||
# Starts aitimemachine/context7/packages/mcp/dist/index.js
|
||||
# (falls back to node directly if the package has no dev script)
|
||||
```
|
||||
|
||||
Listens on port `3100` by default. No API key required for public libraries;
|
||||
set `CONTEXT7_API_KEY` for higher rate limits and private repositories.
|
||||
|
||||
### Beads (`bd`)
|
||||
|
||||
```bash
|
||||
npm run build:beads
|
||||
# Compiles Go binary to aitimemachine/beads/bd
|
||||
```
|
||||
|
||||
After building, use the binary directly:
|
||||
|
||||
```bash
|
||||
aitimemachine/beads/bd init # initialise in any project
|
||||
aitimemachine/beads/bd setup claude # install Claude Code hooks
|
||||
aitimemachine/beads/bd ready # list unblocked tasks
|
||||
aitimemachine/beads/bd prime # print agent workflow context
|
||||
```
|
||||
|
||||
### repo2txt (React/Vite UI)
|
||||
|
||||
```bash
|
||||
npm run dev:repo2txt
|
||||
# Vite dev server for the repo2txt web UI
|
||||
```
|
||||
|
||||
### repo-to-text (Python CLI)
|
||||
|
||||
```bash
|
||||
npm run dev:repo-to-text
|
||||
# python -m repo_to_text from aitimemachine/tools/repo-to-text
|
||||
```
|
||||
|
||||
Install the Python package once before first use:
|
||||
|
||||
```bash
|
||||
pip install repo-to-text
|
||||
```
|
||||
|
||||
### Start all core services at once
|
||||
|
||||
```bash
|
||||
bash scripts/start-all-dev.sh
|
||||
# Requires: npm install -g concurrently
|
||||
# Starts: gitgram/backend (:3000), gitgram/web (:3002), aitimemachine/api-server (:3001)
|
||||
```
|
||||
|
||||
Port overrides:
|
||||
|
||||
```bash
|
||||
GITGRAM_BACKEND_PORT=3000 GITGRAM_WEB_PORT=3002 AITM_API_PORT=3001 \
|
||||
bash scripts/start-all-dev.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Analyzing Codebases with GitNexus
|
||||
|
||||
GitNexus builds a queryable knowledge graph (nodes = symbols, edges = calls/imports/
|
||||
inheritance) from a TypeScript or JavaScript codebase. You must index a repo before
|
||||
the graph tools return useful results.
|
||||
|
||||
### Using the convenience script
|
||||
|
||||
```bash
|
||||
# From monorepo root
|
||||
bash scripts/analyze-with-gitnexus.sh <REPO>
|
||||
```
|
||||
|
||||
Supported `<REPO>` aliases:
|
||||
|
||||
| Alias | Path |
|
||||
|-------|------|
|
||||
| `gitgram-backend` | `gitgram/backend` |
|
||||
| `gitgram-web` | `gitgram/web` |
|
||||
| `aitm-api` | `aitimemachine/api-server` |
|
||||
| `aitm-mcp` | `aitimemachine/mcp` |
|
||||
|
||||
The script auto-builds the GitNexus CLI if `dist/cli/index.js` is missing, then
|
||||
calls `gitnexus analyze <path> --name <name>`.
|
||||
|
||||
### Using the CLI directly
|
||||
|
||||
```bash
|
||||
cd aitimemachine/gitnexus
|
||||
|
||||
# Index a repo (run from its root, or pass --root)
|
||||
node dist/cli/index.js analyze /absolute/path/to/repo --name my-repo
|
||||
|
||||
# Start the query server
|
||||
npm run serve # or: node dist/cli/index.js server
|
||||
# Default: http://localhost:3001
|
||||
|
||||
# Query via CLI
|
||||
node dist/cli/index.js query "authentication flow"
|
||||
node dist/cli/index.js context validateUser
|
||||
node dist/cli/index.js impact AuthService
|
||||
```
|
||||
|
||||
### Using GitNexus through the AITM MCP server
|
||||
|
||||
Once the GitNexus server is running and `GITNEXUS_URL` points at it, all `gn_*`
|
||||
tools become available inside the AITM MCP server automatically. Example in Claude
|
||||
Code:
|
||||
|
||||
```
|
||||
list all indexed repos → calls gn_list_repos
|
||||
query "how does checkout work" → calls gn_query
|
||||
impact analysis for PaymentService → calls gn_impact
|
||||
```
|
||||
|
||||
### Using GitNexus with MCP directly (without AITM)
|
||||
|
||||
```bash
|
||||
# Claude Code
|
||||
claude mcp add gitnexus -- npx -y gitnexus@latest mcp
|
||||
|
||||
# or add to .mcp.json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gitnexus": {
|
||||
"command": "node",
|
||||
"args": ["aitimemachine/gitnexus/dist/cli/index.js", "mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. A2A Protocol
|
||||
|
||||
The A2A (Agent-to-Agent) protocol is a Google-authored open standard for agents to
|
||||
delegate tasks to other agents over HTTP using JSON-RPC 2.0. The implementation in
|
||||
`aitimemachine/a2a` provides TypeScript types and the `a2a_*` MCP tools.
|
||||
|
||||
### How it works
|
||||
|
||||
1. Every A2A agent exposes a `POST /a2a` endpoint that accepts JSON-RPC 2.0 requests.
|
||||
2. The caller sends a `tasks/send` request with a `message` (array of `Part` objects).
|
||||
3. The agent executes the task and returns a `Task` object with a `status` field
|
||||
(`submitted`, `working`, `completed`, `failed`, or `canceled`).
|
||||
4. The caller can poll with `tasks/get` using the same `id` until the task completes.
|
||||
|
||||
```
|
||||
Caller Agent
|
||||
│ │
|
||||
│ POST /a2a │
|
||||
│ { method: "tasks/send", │
|
||||
│ params: { id, message } } ──► │
|
||||
│ │ (executes)
|
||||
│ ◄─── { result: Task } │
|
||||
│ │
|
||||
│ POST /a2a │
|
||||
│ { method: "tasks/get", │
|
||||
│ params: { id } } ──► │
|
||||
│ ◄─── { result: Task{status} } │
|
||||
```
|
||||
|
||||
### Registering agents
|
||||
|
||||
Set the `AITM_A2A_AGENTS` environment variable before starting the AITM MCP server.
|
||||
It must be a JSON array of `{ name, url }` objects:
|
||||
|
||||
```bash
|
||||
export AITM_A2A_AGENTS='[
|
||||
{ "name": "code-reviewer", "url": "http://localhost:4001" },
|
||||
{ "name": "planner", "url": "http://localhost:4002" }
|
||||
]'
|
||||
npm run dev:aitm-mcp
|
||||
```
|
||||
|
||||
Or set it in `aitimemachine/mcp/mcp.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"aitm": {
|
||||
"command": "node",
|
||||
"args": ["dist/index.js"],
|
||||
"env": {
|
||||
"AITM_A2A_AGENTS": "[{\"name\":\"code-reviewer\",\"url\":\"http://localhost:4001\"}]"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Using A2A tools inside Claude Code
|
||||
|
||||
```
|
||||
# List registered agents
|
||||
a2a_list_agents
|
||||
|
||||
# Dispatch a task to an agent
|
||||
a2a_send_task
|
||||
agentUrl: "http://localhost:4001"
|
||||
taskId: "review-pr-42"
|
||||
message: "Review the auth module for security issues"
|
||||
|
||||
# Poll for completion
|
||||
a2a_get_task
|
||||
agentUrl: "http://localhost:4001"
|
||||
taskId: "review-pr-42"
|
||||
```
|
||||
|
||||
### Building an A2A-compatible agent
|
||||
|
||||
Any HTTP server that implements `POST /a2a` accepting JSON-RPC 2.0 qualifies. Import
|
||||
the shared types from the monorepo package:
|
||||
|
||||
```typescript
|
||||
import type { Task, TaskStatus, Part, TextPart } from 'aitimemachine/a2a';
|
||||
```
|
||||
|
||||
The `aitimemachine/a2a` package also exports `AGENT_CARD_PATH` (`/.well-known/agent.json`)
|
||||
and the `AgentCard` schema for agent discovery.
|
||||
|
||||
---
|
||||
|
||||
## 5. MCP Tools Reference
|
||||
|
||||
The AITM MCP server registers tools in eight groups. All tools are available to any
|
||||
MCP-compatible client pointing at `aitimemachine/mcp`.
|
||||
|
||||
### 5.1 TimeMachine core tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `tm_project_init` | Initialize or register a project for time tracking |
|
||||
| `tm_set_project` | Set the current working project |
|
||||
| `tm_checkpoint_create` | Create a checkpoint (snapshot of current state) |
|
||||
| `tm_checkpoint_list` | List all checkpoints/timepoints |
|
||||
| `tm_checkpoint_restore` | Restore project to a checkpoint |
|
||||
| `tm_checkpoint_preview` | Preview what restore would change |
|
||||
| `tm_diff` | Show diff between two checkpoints or checkpoint and current state |
|
||||
| `tm_diff_checkpoints` | Detailed diff between two checkpoints (files + chat + terminal) |
|
||||
| `tm_event_append` | Append an event to the project timeline |
|
||||
| `tm_timeline` | Get timeline of events for a project |
|
||||
| `tm_search` | Search across conversations and checkpoints |
|
||||
| `tm_find_restore` | Search conversations and find the best checkpoint to restore |
|
||||
| `tm_log_message` | Log a conversation message |
|
||||
| `tm_stats` | Get TimeMachine statistics |
|
||||
| `tm_tag` | Tag a checkpoint with a label |
|
||||
| `tm_ready` | Check if the TimeMachine daemon is ready |
|
||||
| `before_action` | Call before making file changes — creates an automatic checkpoint |
|
||||
| `after_action` | Call after making file changes — records what was done |
|
||||
|
||||
### 5.2 Session tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `tm_session_capture` | Capture current state as a session (used by the daemon) |
|
||||
| `tm_session_list` | List all captured sessions |
|
||||
| `tm_bisect` | Binary search to find when a test started failing |
|
||||
|
||||
### 5.3 Integration/environment tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `tm_container_state` | Get Docker/container state for a project |
|
||||
| `tm_database_state` | Get database state for a project |
|
||||
| `tm_gemini_sessions` | List Gemini CLI sessions |
|
||||
| `tm_git_state` | Get git state for a project |
|
||||
| `tm_env_state` | Get environment state (runtimes, package managers, dependencies) |
|
||||
| `tm_aider_sessions` | List Aider sessions |
|
||||
| `tm_cursor_workspaces` | List Cursor workspaces |
|
||||
| `tm_claude_projects` | List Claude Code projects |
|
||||
| `tm_claude_conversations` | Get Claude Code conversations for a project |
|
||||
|
||||
### 5.4 Storage / S3 / Docker capsule tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `tm_s3_config` | Configure S3 backup credentials |
|
||||
| `tm_s3_backup` | Backup all TimeMachine data to S3 |
|
||||
| `tm_s3_restore` | Restore all TimeMachine data from S3 |
|
||||
| `tm_capsule_create` | Create a Docker capsule for deterministic execution |
|
||||
| `tm_capsule_exec` | Execute a command inside a capsule container |
|
||||
| `tm_capsule_stop` | Stop and remove a capsule container |
|
||||
|
||||
### 5.5 File tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `tm_restore_files` | Restore specific files from a session (glob patterns supported) |
|
||||
| `tm_get_file_at` | Get file content at a specific checkpoint |
|
||||
| `tm_file_history` | Get history of a file across checkpoints |
|
||||
| `tm_prompt_debug_regression` | Generate a prompt to debug regressions between two checkpoints |
|
||||
| `tm_prompt_write_postmortem` | Generate a prompt to write an incident postmortem |
|
||||
| `tm_prompt_generate_repro_steps` | Generate reproduction steps from checkpoint history |
|
||||
| `tm_repo_to_text` | Convert a repository or directory to a single text block for LLM context |
|
||||
|
||||
### 5.6 Worktree tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `tm_worktree_list` | List active AITM worktrees for the current project |
|
||||
| `tm_worktree_restore` | Restore a worktree to a checkpoint |
|
||||
| `tm_worktree_cleanup` | Remove all AITM worktrees for the current project |
|
||||
|
||||
### 5.7 GitNexus proxy tools (prefix: none, routed to GitNexus server)
|
||||
|
||||
These tools forward calls to the GitNexus server at `GITNEXUS_URL`.
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `list_repos` | List indexed repositories (paginated) |
|
||||
| `query` | Query the code knowledge graph for execution flows related to a concept |
|
||||
| `cypher` | Execute a Cypher query directly against the knowledge graph |
|
||||
| `context` | 360-degree view of a single symbol: incoming/outgoing references, callers, callees |
|
||||
| `detect_changes` | Analyze uncommitted git changes and find affected execution flows |
|
||||
| `check` | Run read-only structural checks (circular imports, etc.) |
|
||||
| `rename` | Multi-file coordinated rename using the knowledge graph |
|
||||
| `impact` | Analyze the blast radius of changing a code symbol |
|
||||
| `explain` | Explain persisted taint findings from `gitnexus analyze --pdg` |
|
||||
| `pdg_query` | Query the Program Dependence Graph (control + data flow) |
|
||||
| `route_map` | Show API route mappings: which components fetch which endpoints |
|
||||
| `tool_map` | Show MCP/RPC tool definitions and their handlers |
|
||||
| `shape_check` | Check API response shapes against their consumers |
|
||||
| `api_impact` | Pre-change impact report for an API route handler |
|
||||
| `group_list` | List configured repository groups |
|
||||
| `group_sync` | Rebuild the Contract Registry for a group |
|
||||
| `trace` | Find the shortest directed path between two symbols |
|
||||
|
||||
### 5.8 Context7 documentation tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `tm_docs_resolve` | Resolve a library name (e.g. `"react"`) to its Context7 library ID |
|
||||
| `tm_docs_query` | Query documentation for a resolved Context7 library ID |
|
||||
| `tm_docs_for_imports` | Detect imports in a source file and fetch docs for each library |
|
||||
|
||||
### 5.9 A2A tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `a2a_send_task` | Send a task to an A2A agent via `tasks/send` |
|
||||
| `a2a_get_task` | Get the current status of an A2A task via `tasks/get` |
|
||||
| `a2a_list_agents` | List agents registered in `AITM_A2A_AGENTS` |
|
||||
|
||||
---
|
||||
|
||||
## 6. Quick-Start Guide
|
||||
|
||||
### Step 1 — Build companion tools
|
||||
|
||||
Run this once after cloning the repo or pulling major updates:
|
||||
|
||||
```bash
|
||||
bash scripts/setup-aitm-tools.sh
|
||||
```
|
||||
|
||||
This script builds four tools in sequence (a failure in one does not abort the others):
|
||||
|
||||
| Tool | What it does |
|
||||
|------|--------------|
|
||||
| `beads` | `go build ./cmd/bd/...` → binary at `aitimemachine/beads/bd` |
|
||||
| `gitnexus` | `npm install && npm run build` in `aitimemachine/gitnexus/gitnexus` |
|
||||
| `pal-mcp-server` | Creates Python venv and installs `requirements.txt` |
|
||||
| `context7-mcp` | `pnpm/npm install && build` in `aitimemachine/context7/packages/mcp` |
|
||||
|
||||
Prerequisites:
|
||||
- Node.js 18+ and npm
|
||||
- Python 3.10+ (for PAL MCP server)
|
||||
- Go 1.21+ (for Beads; skipped gracefully if missing)
|
||||
- pnpm (preferred for context7; falls back to npm)
|
||||
|
||||
### Step 2 — Start core dev services
|
||||
|
||||
```bash
|
||||
bash scripts/start-all-dev.sh
|
||||
```
|
||||
|
||||
Services started:
|
||||
|
||||
| Service | Default port |
|
||||
|---------|-------------|
|
||||
| `gitgram/backend` | 3000 |
|
||||
| `aitimemachine/api-server` | 3001 |
|
||||
| `gitgram/web` | 3002 |
|
||||
|
||||
Requires `concurrently` globally installed (`npm install -g concurrently`). Without it
|
||||
the script prints manual commands for three separate terminals.
|
||||
|
||||
### Step 3 — Start the AI tool layer
|
||||
|
||||
In a separate terminal (or add to your `concurrently` invocation):
|
||||
|
||||
```bash
|
||||
# AITM MCP server (required — hub for all AI tools)
|
||||
npm run dev:aitm-mcp
|
||||
|
||||
# GitNexus server (required for gn_* tools)
|
||||
npm run dev:gitnexus
|
||||
|
||||
# Context7 (optional — for tm_docs_* tools)
|
||||
npm run dev:context7
|
||||
|
||||
# PAL MCP (optional — for multi-model AI)
|
||||
npm run dev:pal-mcp
|
||||
```
|
||||
|
||||
### Step 4 — Index your codebase with GitNexus
|
||||
|
||||
```bash
|
||||
bash scripts/analyze-with-gitnexus.sh gitgram-backend
|
||||
bash scripts/analyze-with-gitnexus.sh aitm-mcp
|
||||
```
|
||||
|
||||
### Step 5 — Point your MCP client at the AITM server
|
||||
|
||||
Add the following to your MCP client config (e.g. `~/.claude/mcp.json` or Claude
|
||||
Code's `claude mcp add` command):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"aitm": {
|
||||
"command": "node",
|
||||
"args": ["/absolute/path/to/aitimemachine/mcp/dist/index.js"],
|
||||
"env": {
|
||||
"GITNEXUS_URL": "http://localhost:3001",
|
||||
"AITM_A2A_AGENTS": "[]"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Or use the pre-built `mcp.json` at `aitimemachine/mcp/mcp.json`, which also defines
|
||||
standalone entries for `gitnexus`, `context7`, and `pal`.
|
||||
|
||||
### Step 6 — Verify everything is running
|
||||
|
||||
```bash
|
||||
# Check the AITM API server
|
||||
curl http://localhost:3001/health
|
||||
|
||||
# Check the GitNexus server
|
||||
curl http://localhost:3001/health
|
||||
|
||||
# List indexed repos (from inside Claude Code)
|
||||
# > list_repos
|
||||
```
|
||||
59
docs/can be fork.md
Normal file
59
docs/can be fork.md
Normal file
@ -0,0 +1,59 @@
|
||||
# Actionable Reference Clones
|
||||
|
||||
Last updated: 2026-06-21
|
||||
|
||||
This file replaces the old starred-repos dump.
|
||||
|
||||
Purpose:
|
||||
- keep a small set of upstream reference repos inside this workspace
|
||||
- clone only repos that map to current Gitgram or AITM work
|
||||
- avoid cloning unrelated agent/social projects just because they look interesting
|
||||
|
||||
Clone root:
|
||||
- `/Users/arhansubasi/gitgram-ai/external`
|
||||
|
||||
## Cloned Now
|
||||
|
||||
| Repo | Local path | Why it matters now | Status |
|
||||
|---|---|---|---|
|
||||
| `abinthomasonline/repo2txt` | `external/repo2txt` | Direct reference for repo-to-text ingest/export UX and URL handling patterns. | `cloned 2026-05-12` |
|
||||
| `kirill-markin/repo-to-text` | `external/repo-to-text` | Simpler alternative repo-to-text implementation to compare parsing, file selection, and output shaping. | `cloned 2026-05-12` |
|
||||
| `a2aproject/a2a-js` | `external/a2a-js` | Official A2A SDK. Needed to align AITM transport and agent-card behavior with the spec instead of maintaining only hand-rolled protocol types. | `cloned 2026-05-12` |
|
||||
| `upstash/context7` | `external/context7` | Reference for production MCP HTTP patterns, transport wiring, and request-scoped context handling. | `cloned 2026-05-12` |
|
||||
| `BeehiveInnovations/pal-mcp-server` | `external/pal-mcp-server` | Reference for MCP tool organization, annotations, output envelopes, and tool disabling patterns. | `cloned 2026-05-12` |
|
||||
| `abhigyanpatwari/GitNexus` | `external/gitnexus` | Client-side code intelligence engine — zero-server knowledge graph + Graph RAG agent over any repo. Reference for Gitgram repo explore/visualisation surface and AITM code-context indexing. | `cloned 2026-06-21` |
|
||||
| `gastownhall/beads` | `external/beads` | Steve Yegge's git-native DAG issue tracker designed for AI agents. Reference for AITM task/issue tracking integration and multi-agent coordination patterns. `bd ready` shows unblocked work with dependency DAGs and hash-based IDs. | `cloned 2026-06-21` |
|
||||
| `codinginflow/nextjs-15-social-media-app` | `external/nextjs-15-social-media-app` | Exact same stack as Gitgram (Next.js 15 + Prisma + PG). Prisma schema maps 1:1 to Gitgram. Reference for infinite scroll, optimistic updates, and notification patterns. | `cloned 2026-06-21` |
|
||||
| `leandronorcio/munia` | `external/munia` | Most complete open-source social features: GitHub OAuth, @mentions, hashtags, nested comments, drag-drop media, S3 uploads, accessibility. | `cloned 2026-06-21` |
|
||||
| `TomDoesTech/t3-twitter-clone` | `external/t3-twitter-clone` | Only open-source Twitter clone with an Express backend branch — matches Gitgram's Express backend. Type-safe tRPC patterns. | `cloned 2026-06-21` |
|
||||
| `karanpratapsingh/Proximity` | `external/proximity` | Best React Native social app with Prisma. Real-time messaging via GraphQL subscriptions. Reference only (GPL-3). | `cloned 2026-06-21` |
|
||||
| `amirfakhrullah/gh-social` | `external/gh-social` | GitHub Social Platform — the closest open-source concept to Gitgram. Syncs GitHub follows/stars to a social feed. Next.js + tRPC + Clerk + Drizzle + Neon. | `cloned 2026-06-21` |
|
||||
| `bluesky-social/social-app` | `external/bluesky-social-app` | Production-scale feed algorithms, notifications, and moderation patterns. Architecture reference for Gitgram at scale. | `cloned 2026-06-21` |
|
||||
|
||||
## Watch Later
|
||||
|
||||
| Repo | Why not cloning now |
|
||||
|---|---|
|
||||
| `browserbase/stagehand` | Browser automation is not on the current launch-critical path. |
|
||||
| `daytonaio/daytona` | Infra-heavy and not needed for the current single-host launch. |
|
||||
| `mem0ai/mem0` | Memory layer work is post-launch, not a deploy blocker. |
|
||||
| `vercel-labs/open-agents` | Broad cloud-agent template, but not a direct gap in the current repos. |
|
||||
| `badlogic/sitegeist` | Useful browser-collaboration reference, but not tied to current shipping tasks. |
|
||||
| `agentgateway/agentgateway` | Worth reviewing later for A2A/MCP proxying, but not needed before the first launch. |
|
||||
| `GongRzhe/A2A-MCP-Server` | Useful bridge reference after the official A2A SDK pass. |
|
||||
| `Open-ACP/OpenACP` | Messaging-channel expansion is post-launch work. |
|
||||
|
||||
## Current Adoption Targets
|
||||
|
||||
| Reference | Product | Current status | What is already used | Next planned use in project |
|
||||
|---|---|---|---|---|
|
||||
| `repo2txt` + `repo-to-text` | Gitgram | `adopted` | Gitgram now ships a real repo-to-text export flow at `/api/v1/repositories/:owner/:name/export/text`, a public short-path text view at `/:owner/:name/text`, a raw plain-text shortcut at `/:owner/:name/text/raw`, queryable export sizing via `maxFiles` / `maxFileBytes`, and direct `Text` / `Raw` entry points from the repository page plus discovery cards in search, explore, and trending. | No launch-critical follow-up remains. Reuse only if Gitgram adds deeper compose/share/import workflows around repo text. |
|
||||
| `a2a-js` | AITM MCP | `adopted` | AITM now uses an `a2a-js`-derived contract layer in `aitimemachine/mcp/src/lib/a2a-contract.ts`, a canonical `message/send` JSON-RPC flow in `aitimemachine/mcp/src/http-transport.ts`, spec-shaped task responses, protocol-versioned agent cards, and a repeatable smoke gate in `aitimemachine/scripts/a2a-smoke-test.sh`. | No launch-critical follow-up remains beyond future expansion into real streaming or additional A2A task methods if the product needs them. |
|
||||
| `context7` | AITM MCP | `adopted` | AITM already exposes streamable HTTP transport and now also uses request-scoped HTTP context, stable `X-Request-Id` response headers, structured parser/protocol error mapping, per-request logging around `/mcp`, `/a2a`, `/.well-known/agent-card.json`, and `/health`, plus nested request-ID propagation from A2A into the internal `/mcp` bridge. | No launch-critical follow-up remains. Revisit only if AITM later needs deeper user/auth context propagation across remote downstream calls. |
|
||||
| `pal-mcp-server` | AITM MCP | `adopted` | AITM MCP now enforces a real tool registry with stable-vs-experimental exposure, `DISABLED_TOOLS` env support, aligned A2A/HTTP capability reporting, category-based tool registration modules, shared tool-annotation helpers, shared tool response helpers, and declarative `createToolRegistrar` / `defineTool` registration helpers instead of repeated `server.tool(...)` scaffolding. | No launch-critical follow-up remains. Revisit only if the tool surface grows enough to justify deeper output-schema or capability-family generation. |
|
||||
|
||||
## Refresh Policy
|
||||
|
||||
- Keep clones shallow unless a deeper history is required.
|
||||
- Treat `external/*` as upstream references, not as code to edit directly for product work.
|
||||
- When a reference repo becomes genuinely integrated, copy or adapt the needed pattern into `gitgram` or `aitimemachine` with explicit attribution in the relevant PR or commit.
|
||||
95
docs/deploy-pipeline.md
Normal file
95
docs/deploy-pipeline.md
Normal file
@ -0,0 +1,95 @@
|
||||
# Deployment Pipeline Status
|
||||
|
||||
Last updated: 2026-05-09
|
||||
|
||||
## Canonical Launch Contract
|
||||
|
||||
Launch is manual-first.
|
||||
|
||||
- Canonical deploy path: `docs/runbook.md`
|
||||
- Canonical control plane: `pm2`
|
||||
- Canonical rollback model: operator-managed rollback to a previous checkout or release directory, plus database restore from backup when migrations are involved
|
||||
|
||||
No GitHub Actions workflow is required for launch readiness.
|
||||
|
||||
## Workflow Inventory
|
||||
|
||||
### Shared CI
|
||||
|
||||
Current root workflows:
|
||||
|
||||
- `.github/workflows/ci.yml`
|
||||
- `.github/workflows/tests.yml`
|
||||
- `.github/workflows/integration-tests.yml`
|
||||
- `.github/workflows/smoke-tests.yml`
|
||||
- `.github/workflows/migrations.yml`
|
||||
- `.github/workflows/openapi-validation.yml`
|
||||
- `.github/workflows/verify-production-db.yml`
|
||||
|
||||
These are build and verification workflows, not the manual launch source of truth.
|
||||
|
||||
### Gitgram Automation
|
||||
|
||||
Workflow files present in the repo:
|
||||
|
||||
- `gitgram/.github/workflows/deploy.yml`
|
||||
- `gitgram/.github/workflows/deploy-production.yml`
|
||||
- `gitgram/.github/workflows/deploy-staging.yml`
|
||||
- `gitgram/.github/workflows/production-deploy.yml`
|
||||
|
||||
Status:
|
||||
|
||||
- `deploy.yml` is the newest automation candidate.
|
||||
- `deploy-production.yml`, `deploy-staging.yml`, and `production-deploy.yml` are legacy or incomplete variants.
|
||||
- None of the Gitgram deploy workflows should be treated as required for launch until they match the manual PM2 process-control path.
|
||||
|
||||
### AITM Automation
|
||||
|
||||
Workflow files present in the repo:
|
||||
|
||||
- `aitimemachine/.github/workflows/deploy.yml`
|
||||
- `aitimemachine/.github/workflows/ci.yml`
|
||||
- `aitimemachine/.github/workflows/pr-check.yml`
|
||||
|
||||
Status:
|
||||
|
||||
- `deploy.yml` is an automation candidate, not the launch source of truth.
|
||||
- `ci.yml` currently contains a tag-driven npm release step for `@gitgram/timemachine`.
|
||||
- The MCP package publish is still manual.
|
||||
|
||||
## Automation-Only Variables
|
||||
|
||||
These names exist in workflow files but are not part of the manual launch contract:
|
||||
|
||||
- `CURRENT_DEPLOY_TAG`
|
||||
- `GITGRAM_DATABASE_URL`
|
||||
- `GITGRAM_REDIS_URL`
|
||||
- `AITM_DATABASE_URL`
|
||||
- other workflow-scoped `GITGRAM_*` / `AITM_*` secrets
|
||||
|
||||
They are acceptable for future CI/CD, but the operator-managed launch path uses the root `.env.*` files and runtime process restarts described in `docs/runbook.md`.
|
||||
|
||||
## Rollback Policy
|
||||
|
||||
Rollback is manual-first.
|
||||
|
||||
Trigger rollback when any of these happen:
|
||||
|
||||
1. A service health gate fails after restart.
|
||||
2. A smoke test fails.
|
||||
3. A migration partially applies or produces broken behavior.
|
||||
4. A package publish is broken after public verification.
|
||||
|
||||
Manual rollback actions:
|
||||
|
||||
1. Revert to the previous known-good tag, commit, or release directory.
|
||||
2. Rebuild the affected service.
|
||||
3. Restart the affected PM2 process with `--update-env`.
|
||||
4. Re-run health gates.
|
||||
5. Restore the database from the pre-deploy backup when schema state is unsafe.
|
||||
|
||||
For npm packages:
|
||||
|
||||
1. Deprecate the bad version.
|
||||
2. Bump the version.
|
||||
3. Rebuild and republish.
|
||||
172
docs/environment-matrix.md
Normal file
172
docs/environment-matrix.md
Normal file
@ -0,0 +1,172 @@
|
||||
# Environment Matrix
|
||||
|
||||
Last updated: 2026-05-09
|
||||
|
||||
This is the canonical launch-time environment contract for the manual single-host deployment path.
|
||||
|
||||
Rules:
|
||||
|
||||
- Runtime env files live at repo root: `.env.gitgram`, `.env.gitgram-web`, `.env.aitm-api`, optional `.env.aitm-website`.
|
||||
- Service-local `.env.example` files remain the code-level reference for development.
|
||||
- `scripts/validate-prod-secrets.sh` accepts both unprefixed runtime names and `GITGRAM_*` / `AITM_*` aliases for CI-style validation.
|
||||
|
||||
## Gitgram Backend
|
||||
|
||||
Required before first launch:
|
||||
|
||||
- `DATABASE_URL`
|
||||
- `REDIS_URL`
|
||||
- `JWT_SECRET`
|
||||
- `JWT_REFRESH_SECRET`
|
||||
- `FRONTEND_URL`
|
||||
- `CORS_ORIGIN`
|
||||
- `GITHUB_CLIENT_ID`
|
||||
- `GITHUB_CLIENT_SECRET`
|
||||
- `POLAR_ACCESS_TOKEN`
|
||||
- `POLAR_WEBHOOK_SECRET`
|
||||
- `POLAR_PREMIUM_PRODUCT_ID`
|
||||
- `POLAR_CREATOR_PRODUCT_ID`
|
||||
- `POLAR_MODE`
|
||||
- `RESEND_API_KEY`
|
||||
- `SENTRY_DSN`
|
||||
- `STORAGE_TYPE`
|
||||
|
||||
Conditional requirements:
|
||||
|
||||
- `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_S3_BUCKET`, `AWS_REGION` when `STORAGE_TYPE=s3`
|
||||
|
||||
Optional after launch:
|
||||
|
||||
- `GOOGLE_CLIENT_ID`
|
||||
- `GOOGLE_CLIENT_SECRET`
|
||||
- `GITHUB_WEBHOOK_SECRET`
|
||||
- `GITHUB_TOKEN`
|
||||
- `CDN_URL`
|
||||
- `AITM_API_URL`
|
||||
- `AITM_ENCRYPTION_SECRET`
|
||||
- analytics and feature-flag keys
|
||||
|
||||
Code reference:
|
||||
|
||||
- `gitgram/backend/ENV_MATRIX.md`
|
||||
- `gitgram/backend/.env.example`
|
||||
- `gitgram/backend/src/config/env-contract.ts`
|
||||
|
||||
## Gitgram Web
|
||||
|
||||
Required before first launch:
|
||||
|
||||
- `NEXT_PUBLIC_API_URL`
|
||||
- `NEXT_PUBLIC_WS_URL` or legacy `NEXT_PUBLIC_SOCKET_URL`
|
||||
- `NEXT_PUBLIC_GITHUB_CLIENT_ID`
|
||||
|
||||
Optional after launch:
|
||||
|
||||
- `NEXT_PUBLIC_GOOGLE_CLIENT_ID`
|
||||
- `NEXT_PUBLIC_AITM_API_URL`
|
||||
- `NEXT_PUBLIC_SENTRY_DSN`
|
||||
- `NEXT_PUBLIC_GA_ID`
|
||||
- `NEXT_PUBLIC_MAPBOX_TOKEN`
|
||||
|
||||
Operational note:
|
||||
|
||||
- `NEXT_PUBLIC_*` values are build-time inputs. Rebuild the web app whenever they change.
|
||||
|
||||
Code reference:
|
||||
|
||||
- `gitgram/web/.env.example`
|
||||
- `gitgram/web/next.config.js`
|
||||
|
||||
## AITM API
|
||||
|
||||
Required before first launch:
|
||||
|
||||
- `DATABASE_URL`
|
||||
- `INTERNAL_SECRET`
|
||||
- `CORS_ORIGIN`
|
||||
- `WEBSITE_URL`
|
||||
- `POLAR_ACCESS_TOKEN`
|
||||
- `POLAR_WEBHOOK_SECRET`
|
||||
- `POLAR_PRO_PRODUCT_ID`
|
||||
- `POLAR_TEAM_PRODUCT_ID`
|
||||
- `RESEND_API_KEY`
|
||||
- `SENTRY_DSN`
|
||||
|
||||
Optional after launch:
|
||||
|
||||
- `CLERK_WEBHOOK_SECRET`
|
||||
- `REDIS_URL`
|
||||
- `OPENAI_API_KEY`
|
||||
- `ANTHROPIC_API_KEY`
|
||||
- `VOYAGE_API_KEY`
|
||||
- `BRAVE_SEARCH_API_KEY`
|
||||
- `SERPAPI_KEY`
|
||||
- `SERPER_API_KEY`
|
||||
- `FIRECRAWL_API_KEY`
|
||||
- `KB_S3_BUCKET`
|
||||
- `AWS_ACCESS_KEY_ID`
|
||||
- `AWS_SECRET_ACCESS_KEY`
|
||||
- worker toggles and cron expressions
|
||||
|
||||
Operational notes:
|
||||
|
||||
- `DATABASE_URL` must be valid before the API starts in `staging` or `production`.
|
||||
- Without LLM/search keys, AI-heavy routes degrade gracefully instead of blocking startup.
|
||||
- Worker env vars are only required if you enable the managed scheduler on launch day.
|
||||
|
||||
Code reference:
|
||||
|
||||
- `aitimemachine/api-server/.env.example`
|
||||
- `aitimemachine/api-server/src/lib/validateEnv.ts`
|
||||
- `aitimemachine/api-server/src/config/env-validation.ts`
|
||||
|
||||
## AITM npm Publish / Release Flow
|
||||
|
||||
Manual publish requires:
|
||||
|
||||
- authenticated npm session via `npm login` or `npm whoami`
|
||||
|
||||
Optional CI automation:
|
||||
|
||||
- GitHub secret `NPM_TOKEN`
|
||||
|
||||
Operational notes:
|
||||
|
||||
- The current CI release job publishes `@gitgram/timemachine`.
|
||||
- `@gitgram/timemachine-mcp` still requires manual publish.
|
||||
|
||||
## Optional Self-Hosted AITM Website
|
||||
|
||||
Only required if you decide to run `aitimemachine/website` on the launch host.
|
||||
|
||||
Required for self-host:
|
||||
|
||||
- `NEXT_PUBLIC_API_URL`
|
||||
- `API_URL`
|
||||
- `INTERNAL_SECRET`
|
||||
- `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`
|
||||
- `CLERK_SECRET_KEY`
|
||||
- `NEXT_PUBLIC_APP_URL`
|
||||
- `POLAR_ACCESS_TOKEN`
|
||||
- `NEXT_PUBLIC_POLAR_PRO_PRODUCT_ID`
|
||||
- `NEXT_PUBLIC_POLAR_TEAM_PRODUCT_ID`
|
||||
|
||||
Code reference:
|
||||
|
||||
- `.env.aitm-website.example`
|
||||
- `aitimemachine/website/.env.example`
|
||||
|
||||
## Validation Commands
|
||||
|
||||
```bash
|
||||
bash scripts/validate-prod-secrets.sh staging
|
||||
bash scripts/validate-prod-secrets.sh production
|
||||
```
|
||||
|
||||
These checks:
|
||||
|
||||
- validate the launch-critical variable set
|
||||
- support both prefixed and unprefixed naming
|
||||
- auto-load the root `.env.*` files when present
|
||||
- fail on placeholder values
|
||||
- enforce `POLAR_MODE=production` for a production Gitgram launch
|
||||
133
docs/launch-secrets-checklist.md
Normal file
133
docs/launch-secrets-checklist.md
Normal file
@ -0,0 +1,133 @@
|
||||
# Launch Secrets Checklist
|
||||
|
||||
Last updated: 2026-05-12
|
||||
|
||||
This file is the operator-facing checklist for filling the launch env files before deploy.
|
||||
|
||||
Preferred file layout:
|
||||
- staging: `.env.gitgram.staging`, `.env.gitgram-web.staging`, `.env.aitm-api.staging`
|
||||
- production: `.env.gitgram.production`, `.env.gitgram-web.production`, `.env.aitm-api.production`
|
||||
|
||||
Fallback layout:
|
||||
- `.env.gitgram`
|
||||
- `.env.gitgram-web`
|
||||
- `.env.aitm-api`
|
||||
|
||||
Current gate:
|
||||
- `npm run verify:launch` for deployable core readiness
|
||||
- `npm run verify:launch:full` for all third-party integrations live
|
||||
|
||||
Polar reference:
|
||||
- `docs/polar-payment-setup.md`
|
||||
|
||||
Current state:
|
||||
- deploy/readiness scripts are in place
|
||||
- AITM package dry-run verification passes
|
||||
- dedicated Neon databases now exist for `gitgram_staging`, `gitgram_production`, `aitm_staging`, and `aitm_production`
|
||||
- root staging/production env files now contain real database URLs and generated app-owned secrets
|
||||
- full-integration launch is still blocked by provider-issued values, not local infra placeholders
|
||||
|
||||
## Gitgram Backend Env
|
||||
|
||||
App-owned values now set:
|
||||
- `DATABASE_URL`
|
||||
- `JWT_SECRET`
|
||||
- `JWT_REFRESH_SECRET`
|
||||
|
||||
Still provider-issued:
|
||||
- `REDIS_URL`
|
||||
- `FRONTEND_URL`
|
||||
- `CORS_ORIGIN`
|
||||
- `GITHUB_CLIENT_ID`
|
||||
- `GITHUB_CLIENT_SECRET`
|
||||
- `POLAR_ACCESS_TOKEN`
|
||||
- `POLAR_MODE`
|
||||
- `POLAR_WEBHOOK_SECRET`
|
||||
- `POLAR_PREMIUM_PRODUCT_ID`
|
||||
- `POLAR_CREATOR_PRODUCT_ID`
|
||||
- `RESEND_API_KEY`
|
||||
- `SENTRY_DSN`
|
||||
|
||||
Optional depending on storage mode:
|
||||
- `AWS_ACCESS_KEY_ID`
|
||||
- `AWS_SECRET_ACCESS_KEY`
|
||||
- `AWS_S3_BUCKET`
|
||||
- `AWS_REGION`
|
||||
|
||||
Files:
|
||||
- staging: `.env.gitgram.staging`
|
||||
- production fallback: `.env.gitgram` or `.env.gitgram.production`
|
||||
|
||||
## Gitgram Web Env
|
||||
|
||||
Confirm or fill:
|
||||
- `NEXT_PUBLIC_API_URL`
|
||||
- `NEXT_PUBLIC_WS_URL`
|
||||
- `NEXT_PUBLIC_GITHUB_CLIENT_ID`
|
||||
- `NEXT_PUBLIC_GOOGLE_CLIENT_ID`
|
||||
- `NEXT_PUBLIC_AITM_API_URL`
|
||||
- `NEXT_PUBLIC_SENTRY_DSN`
|
||||
|
||||
Files:
|
||||
- staging: `.env.gitgram-web.staging`
|
||||
- production fallback: `.env.gitgram-web` or `.env.gitgram-web.production`
|
||||
|
||||
## AITM API Env
|
||||
|
||||
App-owned values now set:
|
||||
- `DATABASE_URL`
|
||||
- `INTERNAL_SECRET`
|
||||
|
||||
Still provider-issued:
|
||||
- `CORS_ORIGIN`
|
||||
- `WEBSITE_URL`
|
||||
- `POLAR_ACCESS_TOKEN`
|
||||
- `POLAR_MODE`
|
||||
- `POLAR_WEBHOOK_SECRET`
|
||||
- `POLAR_PRO_PRODUCT_ID`
|
||||
- `POLAR_TEAM_PRODUCT_ID`
|
||||
- `RESEND_API_KEY`
|
||||
- `SENTRY_DSN`
|
||||
|
||||
Optional:
|
||||
- `CLERK_WEBHOOK_SECRET`
|
||||
- `REDIS_URL`
|
||||
- `OPENAI_API_KEY`
|
||||
- `ANTHROPIC_API_KEY`
|
||||
- `VOYAGE_API_KEY`
|
||||
- `BRAVE_SEARCH_API_KEY`
|
||||
|
||||
Files:
|
||||
- staging: `.env.aitm-api.staging`
|
||||
- production fallback: `.env.aitm-api` or `.env.aitm-api.production`
|
||||
|
||||
## Provider Mapping
|
||||
|
||||
GitHub OAuth:
|
||||
- `GITHUB_CLIENT_ID`
|
||||
- `GITHUB_CLIENT_SECRET`
|
||||
- `NEXT_PUBLIC_GITHUB_CLIENT_ID`
|
||||
|
||||
Polar:
|
||||
- Gitgram: `POLAR_ACCESS_TOKEN`, `POLAR_MODE`, `POLAR_WEBHOOK_SECRET`, `POLAR_PREMIUM_PRODUCT_ID`, `POLAR_CREATOR_PRODUCT_ID`
|
||||
- AITM: `POLAR_ACCESS_TOKEN`, `POLAR_MODE`, `POLAR_WEBHOOK_SECRET`, `POLAR_PRO_PRODUCT_ID`, `POLAR_TEAM_PRODUCT_ID`
|
||||
|
||||
Email:
|
||||
- `RESEND_API_KEY`
|
||||
|
||||
Monitoring:
|
||||
- `SENTRY_DSN`
|
||||
- `NEXT_PUBLIC_SENTRY_DSN`
|
||||
|
||||
Core infra:
|
||||
- Gitgram: `DATABASE_URL`, `REDIS_URL`, `JWT_SECRET`, `JWT_REFRESH_SECRET`
|
||||
- AITM: `DATABASE_URL`, `INTERNAL_SECRET`
|
||||
|
||||
## Deploy Sequence
|
||||
|
||||
1. Run `npm run verify:launch` for the core deploy gate.
|
||||
2. Run `bash scripts/deploy-launch.sh staging --gitgram-only`.
|
||||
3. Run `bash scripts/deploy-launch.sh staging --aitm-only`.
|
||||
4. Configure nginx and DNS if not already live.
|
||||
5. Run `npm run verify:public-launch`.
|
||||
6. Once OAuth, Polar, Resend, and Sentry are configured, run `npm run verify:launch:full`.
|
||||
150
docs/ops-quickref.md
Normal file
150
docs/ops-quickref.md
Normal file
@ -0,0 +1,150 @@
|
||||
# Operations Quick Reference
|
||||
|
||||
Full source of truth: `docs/runbook.md`
|
||||
|
||||
## Validate Launch Env
|
||||
|
||||
```bash
|
||||
bash scripts/validate-prod-secrets.sh staging
|
||||
bash scripts/validate-prod-secrets.sh production
|
||||
```
|
||||
|
||||
## Gitgram Deploy
|
||||
|
||||
```bash
|
||||
cd gitgram/backend
|
||||
npm ci --legacy-peer-deps
|
||||
npx prisma generate
|
||||
npx prisma migrate deploy
|
||||
npm run build
|
||||
```
|
||||
|
||||
```bash
|
||||
(
|
||||
set -a
|
||||
source ../../.env.gitgram
|
||||
set +a
|
||||
pm2 restart gitgram-api --update-env || pm2 start ../ecosystem.config.js --only gitgram-api
|
||||
)
|
||||
```
|
||||
|
||||
```bash
|
||||
(
|
||||
set -a
|
||||
source .env.gitgram
|
||||
source .env.gitgram-web
|
||||
set +a
|
||||
cd gitgram/web
|
||||
npm ci --legacy-peer-deps
|
||||
npm run build
|
||||
cd ..
|
||||
pm2 restart gitgram-web --update-env || pm2 start ecosystem.config.js --only gitgram-web
|
||||
)
|
||||
```
|
||||
|
||||
## AITM API Deploy
|
||||
|
||||
```bash
|
||||
cd aitimemachine/api-server
|
||||
npm ci
|
||||
npm run db:migrate
|
||||
npm run build
|
||||
```
|
||||
|
||||
```bash
|
||||
(
|
||||
set -a
|
||||
source ../../.env.aitm-api
|
||||
set +a
|
||||
pm2 restart aitm-api --update-env || pm2 start ../deploy/ecosystem.config.cjs --only aitm-api
|
||||
)
|
||||
```
|
||||
|
||||
## AITM Package Publish
|
||||
|
||||
```bash
|
||||
cd aitimemachine
|
||||
npm ci
|
||||
npm run build
|
||||
npm test
|
||||
bash scripts/verify-npm-packages.sh
|
||||
npm publish --access public
|
||||
```
|
||||
|
||||
```bash
|
||||
cd aitimemachine/mcp
|
||||
npm ci
|
||||
npm run build
|
||||
npm publish --access public
|
||||
```
|
||||
|
||||
## Health Checks
|
||||
|
||||
```bash
|
||||
curl -sf http://127.0.0.1:4000/health | jq .
|
||||
curl -sf http://127.0.0.1:4000/health/ready | jq .
|
||||
curl -sf -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3000
|
||||
|
||||
curl -sf http://127.0.0.1:3001/health | jq .
|
||||
curl -sf http://127.0.0.1:3001/health/ready | jq .
|
||||
```
|
||||
|
||||
Worker status when enabled:
|
||||
|
||||
```bash
|
||||
(
|
||||
set -a
|
||||
source .env.aitm-api
|
||||
set +a
|
||||
curl -sf -H "X-Internal-Secret: ${INTERNAL_SECRET}" \
|
||||
http://127.0.0.1:3001/v1/workers/status | jq .
|
||||
)
|
||||
```
|
||||
|
||||
## Backups
|
||||
|
||||
```bash
|
||||
(
|
||||
set -a
|
||||
source .env.gitgram
|
||||
set +a
|
||||
cd gitgram
|
||||
./scripts/backup-database.sh
|
||||
)
|
||||
```
|
||||
|
||||
```bash
|
||||
(
|
||||
set -a
|
||||
source .env.aitm-api
|
||||
set +a
|
||||
pg_dump "$DATABASE_URL" | gzip > "/var/backups/aitm/aitm_$(date +%Y%m%d_%H%M%S).sql.gz"
|
||||
)
|
||||
```
|
||||
|
||||
## Rollback
|
||||
|
||||
```bash
|
||||
git checkout <previous-tag-or-commit>
|
||||
```
|
||||
|
||||
```bash
|
||||
pm2 restart gitgram-api --update-env
|
||||
pm2 restart gitgram-web --update-env
|
||||
pm2 restart aitm-api --update-env
|
||||
```
|
||||
|
||||
Database rollback policy:
|
||||
|
||||
- Gitgram: restore from pre-migration backup or provider PITR.
|
||||
- AITM: restore from pre-migration backup or provider PITR.
|
||||
|
||||
## Useful PM2 Commands
|
||||
|
||||
```bash
|
||||
pm2 ls
|
||||
pm2 logs gitgram-api --lines 200
|
||||
pm2 logs gitgram-web --lines 100
|
||||
pm2 logs aitm-api --lines 200
|
||||
pm2 save
|
||||
```
|
||||
112
docs/polar-payment-setup.md
Normal file
112
docs/polar-payment-setup.md
Normal file
@ -0,0 +1,112 @@
|
||||
# Polar Payment Setup
|
||||
|
||||
Last updated: 2026-05-12
|
||||
|
||||
This guide is based on the locally cloned Polar source in [external/polar](/Users/arhansubasi/gitgram-ai/external/polar).
|
||||
|
||||
Primary upstream references:
|
||||
- [sandbox.mdx](/Users/arhansubasi/gitgram-ai/external/polar/docs/integrate/sandbox.mdx)
|
||||
- [introduction.mdx](/Users/arhansubasi/gitgram-ai/external/polar/docs/integrate/oauth2/introduction.mdx)
|
||||
- [delivery.mdx](/Users/arhansubasi/gitgram-ai/external/polar/docs/integrate/webhooks/delivery.mdx)
|
||||
- [typescript.mdx](/Users/arhansubasi/gitgram-ai/external/polar/docs/integrate/sdk/typescript.mdx)
|
||||
- [security.yml](/Users/arhansubasi/gitgram-ai/external/polar/sdk/overlays/security.yml)
|
||||
|
||||
## What To Use
|
||||
|
||||
Use an **Organization Access Token** for Gitgram and AITM service-to-Polar integration.
|
||||
|
||||
Do not use OAuth/OpenID Connect unless you are building a third-party app that acts on behalf of other Polar users.
|
||||
|
||||
From Polar’s own docs:
|
||||
- service integrations should use an organization access token
|
||||
- sandbox has its own separate token and separate organization
|
||||
- the TS SDK should be configured with `server: 'sandbox'` or `server: 'production'`
|
||||
|
||||
This repo also now supports an optional `POLAR_SERVER_URL` override for Gitgram and AITM. Use it only if you are running a self-hosted/local Polar instance from the cloned source instead of hosted Polar.
|
||||
|
||||
## Staging Values
|
||||
|
||||
For staging/testing:
|
||||
- set `POLAR_MODE=sandbox`
|
||||
- create the token in the sandbox environment, not production
|
||||
- use sandbox product IDs from the sandbox organization
|
||||
- use the sandbox webhook secret from the sandbox endpoint config
|
||||
- if you are running a local/self-hosted Polar fork, leave `POLAR_MODE` as documentation only and set `POLAR_SERVER_URL` to that instance instead
|
||||
|
||||
Sandbox dashboard/API references from local Polar docs:
|
||||
- dashboard: `https://sandbox.polar.sh/start`
|
||||
- API base: `https://sandbox-api.polar.sh`
|
||||
|
||||
Successful test card from Polar’s sandbox docs:
|
||||
- `4242 4242 4242 4242`
|
||||
|
||||
## Production Values
|
||||
|
||||
For production:
|
||||
- set `POLAR_MODE=production`
|
||||
- use the live organization access token
|
||||
- use live product IDs from the live organization
|
||||
- use the live webhook secret from the production endpoint config
|
||||
|
||||
## Where Each Value Comes From
|
||||
|
||||
`POLAR_ACCESS_TOKEN`
|
||||
- generate an organization access token from your organization settings
|
||||
|
||||
`POLAR_SERVER_URL`
|
||||
- optional override for self-hosted/local Polar from `external/polar`
|
||||
- when unset, the SDK uses hosted `sandbox` or `production` based on `POLAR_MODE`
|
||||
|
||||
`POLAR_MODE`
|
||||
- `sandbox` for staging/test
|
||||
- `production` for live deploy
|
||||
|
||||
`POLAR_WEBHOOK_SECRET`
|
||||
- copy the webhook secret from the webhook endpoint setup in Polar
|
||||
- when verifying through the SDK, pass the raw secret value
|
||||
- Polar’s SDK handles the Standard Webhooks base64 requirement internally
|
||||
|
||||
`POLAR_*_PRODUCT_ID`
|
||||
- copy the exact product IDs from the corresponding Polar environment
|
||||
- sandbox and production product IDs are different because the environments are isolated
|
||||
|
||||
## Repo Mapping
|
||||
|
||||
Gitgram:
|
||||
- `.env.gitgram.staging` or `.env.gitgram`
|
||||
- `POLAR_ACCESS_TOKEN`
|
||||
- `POLAR_MODE`
|
||||
- `POLAR_WEBHOOK_SECRET`
|
||||
- `POLAR_PREMIUM_PRODUCT_ID`
|
||||
- `POLAR_CREATOR_PRODUCT_ID`
|
||||
|
||||
AITM API:
|
||||
- `.env.aitm-api.staging` or `.env.aitm-api`
|
||||
- `POLAR_ACCESS_TOKEN`
|
||||
- `POLAR_MODE`
|
||||
- `POLAR_WEBHOOK_SECRET`
|
||||
- `POLAR_PRO_PRODUCT_ID`
|
||||
- `POLAR_TEAM_PRODUCT_ID`
|
||||
|
||||
AITM website:
|
||||
- `.env.aitm-website`
|
||||
- `POLAR_ACCESS_TOKEN`
|
||||
- `POLAR_MODE`
|
||||
- `NEXT_PUBLIC_POLAR_PRO_PRODUCT_ID`
|
||||
- `NEXT_PUBLIC_POLAR_TEAM_PRODUCT_ID`
|
||||
|
||||
## Testing Flow
|
||||
|
||||
1. Fill staging envs with sandbox values.
|
||||
2. Run `npm run verify:launch:staging:full`.
|
||||
3. Deploy with `bash scripts/deploy-launch.sh staging`.
|
||||
4. Open the billing flow and complete a sandbox checkout with `4242 4242 4242 4242`.
|
||||
5. Confirm webhook delivery updates the local subscription state.
|
||||
|
||||
If you are only validating deployability before billing is wired, `npm run verify:launch:staging` is enough. Use the `:full` gate when you expect checkout and webhooks to work.
|
||||
|
||||
## Current Code Alignment
|
||||
|
||||
This repo now aligns to the Polar source in two important ways:
|
||||
- AITM and Gitgram Polar clients honor `POLAR_MODE`
|
||||
- AITM and Gitgram webhook verification use the SDK webhook validator instead of custom signature logic
|
||||
569
docs/runbook.md
Normal file
569
docs/runbook.md
Normal file
@ -0,0 +1,569 @@
|
||||
# Manual Launch Runbook
|
||||
|
||||
Last updated: 2026-05-12
|
||||
|
||||
This file is the launch source of truth for Gitgram and AITM.
|
||||
|
||||
- Primary topology: one operator-managed host.
|
||||
- Primary process manager: `pm2`.
|
||||
- AITM `systemd` unit: fallback only.
|
||||
- `docker-compose.prod.yml`, `deploy/DEPLOYMENT.md`, and GitHub deploy workflows are not the canonical launch path.
|
||||
|
||||
## Canonical Topology
|
||||
|
||||
| Service | Product | Runtime | Control Plane | Port | Health Gate |
|
||||
|---------|---------|---------|---------------|------|-------------|
|
||||
| `gitgram-api` | Gitgram | Node / Express | `pm2` | `4000` | `GET /health`, `GET /health/ready` |
|
||||
| `gitgram-web` | Gitgram | Node / Next.js | `pm2` | `3000` | `GET /` returns `<500` |
|
||||
| `aitm-api` | AITM | Node / Express | `pm2` primary, `systemd` fallback | `3001` | `GET /health`, `GET /health/ready` |
|
||||
| `postgres` | Shared infra | PostgreSQL 16 | operator-managed | `5432` | `pg_isready` |
|
||||
| `redis` | Shared infra | Redis 7 | operator-managed | `6379` | `redis-cli ping` |
|
||||
|
||||
Optional companion service:
|
||||
|
||||
| Service | Product | Runtime | Port | Notes |
|
||||
|---------|---------|---------|------|------|
|
||||
| `aitm-website` | AITM | Node / Next.js | `3002` | Self-host only if you want the hosted dashboard on the same machine. Not part of the launch-critical path in this repo. |
|
||||
|
||||
## Repo Paths
|
||||
|
||||
| Artifact | Path |
|
||||
|---------|------|
|
||||
| Gitgram PM2 config | `gitgram/ecosystem.config.js` |
|
||||
| AITM PM2 config | `aitimemachine/deploy/ecosystem.config.cjs` |
|
||||
| AITM `systemd` fallback unit | `aitimemachine/deploy/aitm-api.service` |
|
||||
| Gitgram backend env template | `.env.gitgram.example` |
|
||||
| Gitgram web env template | `.env.gitgram-web.example` |
|
||||
| AITM API env template | `.env.aitm-api.example` |
|
||||
| Optional AITM website env template | `.env.aitm-website.example` |
|
||||
| Gitgram backend schema | `gitgram/backend/prisma/schema.prisma` |
|
||||
| AITM API schema | `aitimemachine/api-server/src/db/schema.ts` |
|
||||
|
||||
## Preflight
|
||||
|
||||
Run these before any staging-like dry run or production launch:
|
||||
|
||||
```bash
|
||||
node -v
|
||||
npm -v
|
||||
pm2 -v
|
||||
```
|
||||
|
||||
Use Node 20.x for build and runtime consistency with the repo workflows.
|
||||
|
||||
Copy and fill the operator env files at repo root.
|
||||
|
||||
Preferred layout:
|
||||
|
||||
```bash
|
||||
cp .env.gitgram.example .env.gitgram.production
|
||||
cp .env.gitgram-web.example .env.gitgram-web.production
|
||||
cp .env.aitm-api.example .env.aitm-api.production
|
||||
|
||||
cp .env.gitgram.example .env.gitgram.staging
|
||||
cp .env.gitgram-web.example .env.gitgram-web.staging
|
||||
cp .env.aitm-api.example .env.aitm-api.staging
|
||||
# Optional:
|
||||
cp .env.aitm-website.example .env.aitm-website
|
||||
```
|
||||
|
||||
Fallback layout still works if you want one shared set of root files:
|
||||
|
||||
```bash
|
||||
cp .env.gitgram.example .env.gitgram
|
||||
cp .env.gitgram-web.example .env.gitgram-web
|
||||
cp .env.aitm-api.example .env.aitm-api
|
||||
```
|
||||
|
||||
Validate launch-critical env contracts:
|
||||
|
||||
```bash
|
||||
bash scripts/validate-prod-secrets.sh staging core
|
||||
bash scripts/validate-prod-secrets.sh production core
|
||||
```
|
||||
|
||||
One-command readiness gate:
|
||||
|
||||
```bash
|
||||
npm run verify:launch
|
||||
```
|
||||
|
||||
This is the deployable core profile: database, app secrets, routing URLs, storage mode, and PM2/deploy artifacts.
|
||||
|
||||
Optional deeper gate:
|
||||
|
||||
```bash
|
||||
npm run verify:launch:full
|
||||
```
|
||||
|
||||
This adds third-party integrations that are not required just to boot the services:
|
||||
- GitHub OAuth
|
||||
- Polar billing
|
||||
- Resend
|
||||
- Sentry
|
||||
|
||||
Manual deploy helper:
|
||||
|
||||
```bash
|
||||
bash scripts/deploy-launch.sh staging
|
||||
```
|
||||
|
||||
To require the full integrations gate before deploy:
|
||||
|
||||
```bash
|
||||
bash scripts/deploy-launch.sh staging --verify-profile full
|
||||
```
|
||||
|
||||
Secret entry reference:
|
||||
|
||||
- `docs/launch-secrets-checklist.md`
|
||||
|
||||
Notes:
|
||||
|
||||
- The validator accepts both unprefixed vars and `GITGRAM_*` / `AITM_*` aliases.
|
||||
- It prefers `.env.gitgram.<env>`, `.env.gitgram-web.<env>`, `.env.aitm-api.<env>`, and `.env.aitm-website.<env>` when those files exist, and falls back to the root files otherwise.
|
||||
- `verify:launch` uses the `core` profile by default so you can deploy the stack before every external provider account is wired.
|
||||
- `verify:launch:full` and `validate-prod-secrets.sh <env> full` enforce the full launch contract, including third-party integrations.
|
||||
- `verify:launch` also checks PM2 availability, required deploy artifacts, operator env file presence, and AITM package publishability.
|
||||
- `deploy-launch.sh` is the scripted PM2/manual deploy flow. It is the automation companion to this runbook, not a Docker deploy.
|
||||
|
||||
## Backup Gate
|
||||
|
||||
Take backups before any production migration.
|
||||
|
||||
Gitgram:
|
||||
|
||||
```bash
|
||||
(
|
||||
set -a
|
||||
source .env.gitgram
|
||||
set +a
|
||||
cd gitgram
|
||||
./scripts/backup-database.sh
|
||||
)
|
||||
```
|
||||
|
||||
AITM:
|
||||
|
||||
```bash
|
||||
(
|
||||
set -a
|
||||
source .env.aitm-api
|
||||
set +a
|
||||
mkdir -p /var/backups/aitm
|
||||
pg_dump "$DATABASE_URL" | gzip > "/var/backups/aitm/aitm_$(date +%Y%m%d_%H%M%S).sql.gz"
|
||||
)
|
||||
```
|
||||
|
||||
Redis snapshot:
|
||||
|
||||
```bash
|
||||
redis-cli -u "$(grep '^REDIS_URL=' .env.gitgram | cut -d= -f2-)" BGSAVE
|
||||
```
|
||||
|
||||
## AITM Package Release
|
||||
|
||||
Publish order matters:
|
||||
|
||||
1. `@gitgram/timemachine`
|
||||
2. `@gitgram/timemachine-mcp`
|
||||
|
||||
### Manual Publish Checklist
|
||||
|
||||
Core package:
|
||||
|
||||
```bash
|
||||
cd aitimemachine
|
||||
npm ci
|
||||
npm run build
|
||||
npm test
|
||||
bash scripts/verify-npm-packages.sh
|
||||
npm whoami
|
||||
npm publish --access public
|
||||
```
|
||||
|
||||
Post-publish verification:
|
||||
|
||||
```bash
|
||||
npm view @gitgram/timemachine version
|
||||
npx -y @gitgram/timemachine --version
|
||||
|
||||
tmpdir="$(mktemp -d)"
|
||||
(
|
||||
cd "$tmpdir"
|
||||
npx -y @gitgram/timemachine init
|
||||
npx -y @gitgram/timemachine checkpoint "launch-smoke"
|
||||
)
|
||||
rm -rf "$tmpdir"
|
||||
```
|
||||
|
||||
MCP package:
|
||||
|
||||
```bash
|
||||
cd aitimemachine/mcp
|
||||
npm ci
|
||||
npm run build
|
||||
npm publish --access public
|
||||
```
|
||||
|
||||
Post-publish verification:
|
||||
|
||||
```bash
|
||||
npm view @gitgram/timemachine-mcp version
|
||||
npx -y @gitgram/timemachine-mcp --help
|
||||
```
|
||||
|
||||
### Package Rollback Policy
|
||||
|
||||
Use manual deprecation plus a version bump. Do not rely on unpublish.
|
||||
|
||||
```bash
|
||||
npm deprecate @gitgram/timemachine@<bad-version> "broken release; use >=<fixed-version>"
|
||||
npm deprecate @gitgram/timemachine-mcp@<bad-version> "broken release; use >=<fixed-version>"
|
||||
```
|
||||
|
||||
Then publish a new patch or minor release:
|
||||
|
||||
```bash
|
||||
cd aitimemachine
|
||||
npm version patch --no-git-tag-version
|
||||
|
||||
cd mcp
|
||||
npm version patch --no-git-tag-version
|
||||
```
|
||||
|
||||
Automation status:
|
||||
|
||||
- `aitimemachine/.github/workflows/ci.yml` has a tag-driven npm publish step.
|
||||
- It currently publishes only `@gitgram/timemachine`.
|
||||
- The MCP publish remains manual until the workflow is brought into line with the manual launch process.
|
||||
- The GitHub secret name used there is `NPM_TOKEN`, passed to npm as `NODE_AUTH_TOKEN`.
|
||||
|
||||
## Gitgram Deploy
|
||||
|
||||
### Backend Build + Migrate
|
||||
|
||||
```bash
|
||||
cd gitgram/backend
|
||||
npm ci --legacy-peer-deps
|
||||
npx prisma generate
|
||||
npx prisma migrate deploy
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Backend Start / Restart
|
||||
|
||||
Initial start:
|
||||
|
||||
```bash
|
||||
(
|
||||
set -a
|
||||
source ../../.env.gitgram
|
||||
set +a
|
||||
pm2 start ../ecosystem.config.js --only gitgram-api
|
||||
)
|
||||
pm2 save
|
||||
```
|
||||
|
||||
Redeploy:
|
||||
|
||||
```bash
|
||||
(
|
||||
set -a
|
||||
source ../../.env.gitgram
|
||||
set +a
|
||||
pm2 restart gitgram-api --update-env
|
||||
)
|
||||
pm2 save
|
||||
```
|
||||
|
||||
Scripted equivalent:
|
||||
|
||||
```bash
|
||||
bash scripts/deploy-launch.sh staging --gitgram-only
|
||||
```
|
||||
|
||||
### Backend Health Gate
|
||||
|
||||
```bash
|
||||
curl -sf http://127.0.0.1:4000/health | jq .
|
||||
curl -sf http://127.0.0.1:4000/health/ready | jq .
|
||||
```
|
||||
|
||||
## Gitgram Web Deploy
|
||||
|
||||
### Build
|
||||
|
||||
`NEXT_PUBLIC_*` values are build-time inputs. Rebuild whenever they change.
|
||||
|
||||
```bash
|
||||
(
|
||||
set -a
|
||||
source .env.gitgram-web
|
||||
set +a
|
||||
cd gitgram/web
|
||||
npm ci --legacy-peer-deps
|
||||
npm run build
|
||||
)
|
||||
```
|
||||
|
||||
### Start / Restart
|
||||
|
||||
Initial start:
|
||||
|
||||
```bash
|
||||
(
|
||||
set -a
|
||||
source .env.gitgram-web
|
||||
set +a
|
||||
cd gitgram
|
||||
pm2 start ecosystem.config.js --only gitgram-web
|
||||
)
|
||||
pm2 save
|
||||
```
|
||||
|
||||
Redeploy:
|
||||
|
||||
```bash
|
||||
(
|
||||
set -a
|
||||
source .env.gitgram-web
|
||||
set +a
|
||||
pm2 restart gitgram-web --update-env
|
||||
)
|
||||
pm2 save
|
||||
```
|
||||
|
||||
Scripted equivalent:
|
||||
|
||||
```bash
|
||||
bash scripts/deploy-launch.sh staging --gitgram-only
|
||||
```
|
||||
|
||||
### Web Health Gate
|
||||
|
||||
```bash
|
||||
curl -sf -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3000
|
||||
```
|
||||
|
||||
## AITM API Deploy
|
||||
|
||||
### Build + Migrate
|
||||
|
||||
```bash
|
||||
cd aitimemachine/api-server
|
||||
npm ci
|
||||
npm run db:migrate
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Start / Restart With PM2
|
||||
|
||||
Initial start:
|
||||
|
||||
```bash
|
||||
(
|
||||
set -a
|
||||
source ../../.env.aitm-api
|
||||
set +a
|
||||
pm2 start ../deploy/ecosystem.config.cjs --only aitm-api
|
||||
)
|
||||
pm2 save
|
||||
```
|
||||
|
||||
Redeploy:
|
||||
|
||||
```bash
|
||||
(
|
||||
set -a
|
||||
source ../../.env.aitm-api
|
||||
set +a
|
||||
pm2 restart aitm-api --update-env
|
||||
)
|
||||
pm2 save
|
||||
```
|
||||
|
||||
Scripted equivalent:
|
||||
|
||||
```bash
|
||||
bash scripts/deploy-launch.sh staging --aitm-only
|
||||
```
|
||||
|
||||
### `systemd` Fallback
|
||||
|
||||
Use only if PM2 is unavailable or intentionally replaced.
|
||||
|
||||
```bash
|
||||
sudo cp aitimemachine/deploy/aitm-api.service /etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable aitm-api
|
||||
sudo systemctl restart aitm-api
|
||||
```
|
||||
|
||||
The checked-in unit assumes the repo lives at `/opt/aitimemachine/api-server`. Adjust `WorkingDirectory`, `ExecStart`, and `EnvironmentFile` if your server layout differs.
|
||||
|
||||
### API Health Gate
|
||||
|
||||
```bash
|
||||
curl -sf http://127.0.0.1:3001/health | jq .
|
||||
curl -sf http://127.0.0.1:3001/health/ready | jq .
|
||||
```
|
||||
|
||||
If `ENABLE_WORKERS=true`, also check worker status:
|
||||
|
||||
```bash
|
||||
(
|
||||
set -a
|
||||
source .env.aitm-api
|
||||
set +a
|
||||
curl -sf -H "X-Internal-Secret: ${INTERNAL_SECRET}" \
|
||||
http://127.0.0.1:3001/v1/workers/status | jq .
|
||||
)
|
||||
```
|
||||
|
||||
## Optional AITM Website
|
||||
|
||||
This repo includes `aitimemachine/website`, but it is not part of the launch-critical path defined here.
|
||||
|
||||
If you self-host it on the same machine:
|
||||
|
||||
```bash
|
||||
(
|
||||
set -a
|
||||
source .env.aitm-website
|
||||
set +a
|
||||
cd aitimemachine/website
|
||||
npm ci
|
||||
PORT=3002 npm run build
|
||||
PORT=3002 npm start
|
||||
)
|
||||
```
|
||||
|
||||
## Launch-Day Order
|
||||
|
||||
1. Freeze merges and confirm the intended commit or tag.
|
||||
2. Run `bash scripts/validate-prod-secrets.sh production`.
|
||||
3. Take Gitgram and AITM database backups.
|
||||
4. Publish `@gitgram/timemachine`.
|
||||
5. Verify install + smoke.
|
||||
6. Publish `@gitgram/timemachine-mcp`.
|
||||
7. Verify install + smoke.
|
||||
8. Deploy Gitgram backend.
|
||||
9. Wait for Gitgram backend health gates.
|
||||
10. Deploy Gitgram web.
|
||||
11. Wait for Gitgram web health gate.
|
||||
12. Deploy AITM API.
|
||||
13. Wait for AITM API health gates.
|
||||
14. Run smoke checks.
|
||||
15. Monitor for at least 30 minutes before declaring success.
|
||||
|
||||
## Smoke Checks
|
||||
|
||||
### Gitgram
|
||||
|
||||
Required:
|
||||
|
||||
- `curl -sf http://127.0.0.1:4000/health`
|
||||
- `curl -sf http://127.0.0.1:4000/health/ready`
|
||||
- `curl -sf -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3000`
|
||||
|
||||
Manual:
|
||||
|
||||
- Load the web app.
|
||||
- Confirm it can reach the API.
|
||||
- Exercise one login path.
|
||||
- Create one basic post.
|
||||
|
||||
### AITM
|
||||
|
||||
Required:
|
||||
|
||||
- `curl -sf http://127.0.0.1:3001/health`
|
||||
- `curl -sf http://127.0.0.1:3001/health/ready`
|
||||
- `npx -y @gitgram/timemachine --version`
|
||||
- `npx -y @gitgram/timemachine-mcp --help`
|
||||
|
||||
Manual:
|
||||
|
||||
- Create a temp project.
|
||||
- Run `init`.
|
||||
- Create a checkpoint.
|
||||
- If workers are enabled, verify `/v1/workers/status`.
|
||||
|
||||
Public-domain smoke:
|
||||
|
||||
- `npm run verify:public-launch`
|
||||
|
||||
## Rollback
|
||||
|
||||
### npm Packages
|
||||
|
||||
1. Deprecate the bad version.
|
||||
2. Bump the version.
|
||||
3. Rebuild and republish.
|
||||
4. Re-run the install smokes.
|
||||
|
||||
### Gitgram Backend / Web
|
||||
|
||||
Rollback is manual-first. Use the previous known-good git tag, commit, or release directory already present on the server.
|
||||
|
||||
Example with an in-place git checkout:
|
||||
|
||||
```bash
|
||||
git checkout <previous-tag-or-commit>
|
||||
|
||||
cd gitgram/backend
|
||||
npm ci --legacy-peer-deps
|
||||
npx prisma generate
|
||||
npm run build
|
||||
|
||||
cd ../web
|
||||
npm ci --legacy-peer-deps
|
||||
npm run build
|
||||
|
||||
pm2 restart gitgram-api --update-env
|
||||
pm2 restart gitgram-web --update-env
|
||||
```
|
||||
|
||||
### AITM API
|
||||
|
||||
```bash
|
||||
git checkout <previous-tag-or-commit>
|
||||
|
||||
cd aitimemachine/api-server
|
||||
npm ci
|
||||
npm run build
|
||||
|
||||
pm2 restart aitm-api --update-env
|
||||
```
|
||||
|
||||
### Database Rollback Policy
|
||||
|
||||
- Gitgram / Prisma: no automatic `down` migrations in this launch contract.
|
||||
- AITM / Drizzle: no automatic `down` migrations in this launch contract.
|
||||
- Production rollback policy is restore from backup or provider point-in-time restore unless you have already written and reviewed a reverse SQL plan.
|
||||
|
||||
If a migration fails after partial apply:
|
||||
|
||||
1. Stop the app deploy.
|
||||
2. Do not keep rolling forward blindly.
|
||||
3. Restore from the backup taken immediately before the migration, or use provider PITR.
|
||||
|
||||
## Monitoring Window
|
||||
|
||||
Watch for at least 30 minutes after launch:
|
||||
|
||||
```bash
|
||||
pm2 ls
|
||||
pm2 logs gitgram-api --lines 200
|
||||
pm2 logs gitgram-web --lines 100
|
||||
pm2 logs aitm-api --lines 200
|
||||
```
|
||||
|
||||
Recommended external checks:
|
||||
|
||||
- Sentry error volume
|
||||
- Polar webhook delivery success
|
||||
- PostgreSQL connection count
|
||||
- Redis availability
|
||||
- repeated `curl` probes against `/health` and `/health/ready`
|
||||
195
docs/secrets-contract.md
Normal file
195
docs/secrets-contract.md
Normal file
@ -0,0 +1,195 @@
|
||||
# Secrets Contract
|
||||
|
||||
Last updated: 2026-05-09
|
||||
|
||||
This file describes secret ownership, storage, and rotation for the manual launch path.
|
||||
|
||||
## Storage Rules
|
||||
|
||||
Primary runtime storage:
|
||||
|
||||
- server-side env files generated from `.env.gitgram.example`, `.env.gitgram-web.example`, `.env.aitm-api.example`
|
||||
- optional `.env.aitm-website` if you self-host the AITM dashboard
|
||||
|
||||
Optional storage for future automation:
|
||||
|
||||
- GitHub Actions secrets and environment variables
|
||||
|
||||
Rules:
|
||||
|
||||
1. Do not commit populated `.env` files.
|
||||
2. Do not rely on GitHub Actions secrets as the only production source of truth for a manual launch.
|
||||
3. Use separate values for staging and production.
|
||||
4. Use separate product-scoped credentials where providers allow it.
|
||||
|
||||
## Launch-Critical Secrets
|
||||
|
||||
### Gitgram
|
||||
|
||||
| Secret | Purpose | Rotate |
|
||||
|---|---|---|
|
||||
| `DATABASE_URL` | PostgreSQL connection | on DB credential change |
|
||||
| `REDIS_URL` | Redis connection | on Redis credential change |
|
||||
| `JWT_SECRET` | access-token signing | every 90 days |
|
||||
| `JWT_REFRESH_SECRET` | refresh-token signing | every 90 days |
|
||||
| `GITHUB_CLIENT_SECRET` | GitHub OAuth | on compromise |
|
||||
| `POLAR_ACCESS_TOKEN` | billing API | on compromise |
|
||||
| `POLAR_WEBHOOK_SECRET` | billing webhook verification | on endpoint re-creation |
|
||||
| `RESEND_API_KEY` | transactional email | on compromise |
|
||||
| `SENTRY_DSN` | error reporting | when project changes |
|
||||
|
||||
Conditional:
|
||||
|
||||
- `AWS_ACCESS_KEY_ID`
|
||||
- `AWS_SECRET_ACCESS_KEY`
|
||||
|
||||
These are required only when `STORAGE_TYPE=s3`.
|
||||
|
||||
### Gitgram Web
|
||||
|
||||
The launch-critical web vars are mostly public build inputs, not secrets.
|
||||
|
||||
Non-secret public values:
|
||||
|
||||
- `NEXT_PUBLIC_API_URL`
|
||||
- `NEXT_PUBLIC_WS_URL`
|
||||
- `NEXT_PUBLIC_GITHUB_CLIENT_ID`
|
||||
|
||||
Optional public values:
|
||||
|
||||
- `NEXT_PUBLIC_GOOGLE_CLIENT_ID`
|
||||
- `NEXT_PUBLIC_AITM_API_URL`
|
||||
- `NEXT_PUBLIC_SENTRY_DSN`
|
||||
|
||||
### AITM API
|
||||
|
||||
| Secret | Purpose | Rotate |
|
||||
|---|---|---|
|
||||
| `DATABASE_URL` | PostgreSQL / Neon connection | on DB credential change |
|
||||
| `INTERNAL_SECRET` | internal website-to-API auth | every 90 days |
|
||||
| `POLAR_ACCESS_TOKEN` | billing API | on compromise |
|
||||
| `POLAR_WEBHOOK_SECRET` | billing webhook verification | on endpoint re-creation |
|
||||
| `RESEND_API_KEY` | transactional email | on compromise |
|
||||
| `SENTRY_DSN` | error reporting | when project changes |
|
||||
|
||||
Optional after launch:
|
||||
|
||||
- `CLERK_WEBHOOK_SECRET`
|
||||
- `OPENAI_API_KEY`
|
||||
- `ANTHROPIC_API_KEY`
|
||||
- `VOYAGE_API_KEY`
|
||||
- `BRAVE_SEARCH_API_KEY`
|
||||
- `AWS_ACCESS_KEY_ID`
|
||||
- `AWS_SECRET_ACCESS_KEY`
|
||||
|
||||
### AITM npm Release Flow
|
||||
|
||||
Manual publish:
|
||||
|
||||
- operator npm session from `npm login`
|
||||
|
||||
CI release:
|
||||
|
||||
- GitHub secret `NPM_TOKEN`
|
||||
|
||||
Note:
|
||||
|
||||
- the release workflow maps `NPM_TOKEN` into `NODE_AUTH_TOKEN`
|
||||
- it currently covers `@gitgram/timemachine`, not the MCP package
|
||||
|
||||
### Optional Self-Hosted AITM Website
|
||||
|
||||
Only needed if you run `aitimemachine/website` yourself.
|
||||
|
||||
Secrets:
|
||||
|
||||
- `CLERK_SECRET_KEY`
|
||||
- `INTERNAL_SECRET`
|
||||
- `POLAR_ACCESS_TOKEN`
|
||||
|
||||
Public build inputs:
|
||||
|
||||
- `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`
|
||||
- `NEXT_PUBLIC_API_URL`
|
||||
- `API_URL`
|
||||
- `NEXT_PUBLIC_APP_URL`
|
||||
- `NEXT_PUBLIC_POLAR_PRO_PRODUCT_ID`
|
||||
- `NEXT_PUBLIC_POLAR_TEAM_PRODUCT_ID`
|
||||
|
||||
## Shared Secret Policy
|
||||
|
||||
### AWS
|
||||
|
||||
Prefer separate IAM users:
|
||||
|
||||
- Gitgram S3 user: media bucket only
|
||||
- AITM S3 user: knowledge-base bucket only
|
||||
|
||||
### Redis
|
||||
|
||||
A shared Redis instance is acceptable.
|
||||
|
||||
- Gitgram uses it for cache/session concerns.
|
||||
- AITM uses it only when optional distributed rate limiting is enabled.
|
||||
|
||||
### Resend
|
||||
|
||||
Prefer separate API keys under the same account:
|
||||
|
||||
- one key for Gitgram
|
||||
- one key for AITM
|
||||
|
||||
### Sentry
|
||||
|
||||
Use separate projects and DSNs for Gitgram and AITM.
|
||||
|
||||
## Rotation Checklist
|
||||
|
||||
JWT-style secrets:
|
||||
|
||||
```bash
|
||||
openssl rand -base64 64
|
||||
```
|
||||
|
||||
Recommended process:
|
||||
|
||||
1. rotate in staging first
|
||||
2. redeploy staging and verify
|
||||
3. rotate production
|
||||
4. redeploy production
|
||||
5. record the date and owner
|
||||
|
||||
Database URLs:
|
||||
|
||||
1. rotate credentials at the provider
|
||||
2. update the server env file
|
||||
3. restart the affected service
|
||||
4. verify health endpoints
|
||||
|
||||
Webhook secrets:
|
||||
|
||||
1. recreate or rotate in the provider dashboard
|
||||
2. update the matching env file
|
||||
3. restart the service
|
||||
4. verify one live webhook
|
||||
|
||||
## What Can Wait Until After Launch
|
||||
|
||||
These are explicitly not part of the first-launch blocker set:
|
||||
|
||||
- Google OAuth for Gitgram
|
||||
- AITM AI provider keys
|
||||
- AITM web-search provider keys
|
||||
- AITM Redis
|
||||
- AITM S3 / knowledge-base offload
|
||||
- optional self-hosted AITM website
|
||||
|
||||
## Validation
|
||||
|
||||
Use:
|
||||
|
||||
```bash
|
||||
bash scripts/validate-prod-secrets.sh production
|
||||
```
|
||||
|
||||
That script is the repo-level preflight check for the manual launch contract.
|
||||
22
external/README.md
vendored
Normal file
22
external/README.md
vendored
Normal file
@ -0,0 +1,22 @@
|
||||
# External Reference Repos
|
||||
|
||||
This directory holds shallow upstream clones used as implementation references for Gitgram and AITM.
|
||||
|
||||
Current expected clones:
|
||||
- `repo2txt`
|
||||
- `repo-to-text`
|
||||
- `a2a-js`
|
||||
- `context7`
|
||||
- `pal-mcp-server`
|
||||
|
||||
Rules:
|
||||
- do not treat these repos as part of the product source tree
|
||||
- do not make product changes inside these clones
|
||||
- pull patterns from them into `gitgram/` or `aitimemachine/` deliberately
|
||||
|
||||
Refresh example:
|
||||
|
||||
```bash
|
||||
git -C external/repo2txt fetch --depth 1 origin
|
||||
git -C external/repo2txt reset --hard origin/main
|
||||
```
|
||||
1
external/a2a-js
vendored
Submodule
1
external/a2a-js
vendored
Submodule
@ -0,0 +1 @@
|
||||
Subproject commit dbaccb964f9bb5d9ae7e993f797cebaeae52ac62
|
||||
1
external/beads
vendored
Submodule
1
external/beads
vendored
Submodule
@ -0,0 +1 @@
|
||||
Subproject commit 4d08edbeb77209d801daae42ba6de5484e7b95b8
|
||||
1
external/bluesky-social-app
vendored
Submodule
1
external/bluesky-social-app
vendored
Submodule
@ -0,0 +1 @@
|
||||
Subproject commit dd452a433638789618e875b96d511c9aeadb99ac
|
||||
1
external/context7
vendored
Submodule
1
external/context7
vendored
Submodule
@ -0,0 +1 @@
|
||||
Subproject commit 61de754d48e57d5c22dadd4540a74203fd55ecf1
|
||||
1
external/gh-social
vendored
Submodule
1
external/gh-social
vendored
Submodule
@ -0,0 +1 @@
|
||||
Subproject commit e5ec48e8e5efbc5140b2b023c08cc502525a01f8
|
||||
1
external/gitnexus
vendored
Submodule
1
external/gitnexus
vendored
Submodule
@ -0,0 +1 @@
|
||||
Subproject commit dbd4e1c9fb1d2fe6866c651873078029464663db
|
||||
1
external/munia
vendored
Submodule
1
external/munia
vendored
Submodule
@ -0,0 +1 @@
|
||||
Subproject commit 577868b63adf2b3d61e25809bd665f8c7687c141
|
||||
1
external/nextjs-15-social-media-app
vendored
Submodule
1
external/nextjs-15-social-media-app
vendored
Submodule
@ -0,0 +1 @@
|
||||
Subproject commit 2f407a5c8a6be333fdac54ac6d36b0c385348cb4
|
||||
1
external/pal-mcp-server
vendored
Submodule
1
external/pal-mcp-server
vendored
Submodule
@ -0,0 +1 @@
|
||||
Subproject commit 7afc7c1cc96e23992c8f105f960132c657883bb1
|
||||
1
external/polar
vendored
Submodule
1
external/polar
vendored
Submodule
@ -0,0 +1 @@
|
||||
Subproject commit c818d921dd6deee835410e065c78cf9365915876
|
||||
1
external/proximity
vendored
Submodule
1
external/proximity
vendored
Submodule
@ -0,0 +1 @@
|
||||
Subproject commit 768156dc84cd4381a5ebdbfd589b2e4624e1ae76
|
||||
1
external/repo-to-text
vendored
Submodule
1
external/repo-to-text
vendored
Submodule
@ -0,0 +1 @@
|
||||
Subproject commit eff5a5449ff32f8c6e3bf8a071a2cbadb47f04d6
|
||||
1
external/repo2txt
vendored
Submodule
1
external/repo2txt
vendored
Submodule
@ -0,0 +1 @@
|
||||
Subproject commit bba6c85c26e4273945fba6f6aaedf06607e18b6b
|
||||
1
external/t3-twitter-clone
vendored
Submodule
1
external/t3-twitter-clone
vendored
Submodule
@ -0,0 +1 @@
|
||||
Subproject commit b21c919986092f9c4e7cc6abf03648c74ba72d9b
|
||||
1
gitgram
Submodule
1
gitgram
Submodule
@ -0,0 +1 @@
|
||||
Subproject commit 108517d1608d13d82c670a2e4b3db9587b604214
|
||||
80
package.json
Normal file
80
package.json
Normal file
@ -0,0 +1,80 @@
|
||||
{
|
||||
"name": "gitgram-ai",
|
||||
"version": "1.0.0",
|
||||
"private": true,
|
||||
"description": "Gitgram AI monorepo — social platform for developers + AITimeMachine",
|
||||
"workspaces": [
|
||||
"gitgram/web",
|
||||
"gitgram/backend",
|
||||
"gitgram/gh-social",
|
||||
"gitgram/t3-base",
|
||||
"aitimemachine",
|
||||
"aitimemachine/api-server",
|
||||
"aitimemachine/mcp",
|
||||
"aitimemachine/gitnexus",
|
||||
"aitimemachine/gitnexus-web",
|
||||
"aitimemachine/gitnexus-shared",
|
||||
"aitimemachine/a2a",
|
||||
"aitimemachine/context7/packages/mcp",
|
||||
"aitimemachine/context7/packages/cli",
|
||||
"aitimemachine/context7/packages/sdk",
|
||||
"aitimemachine/tools/repo2txt"
|
||||
],
|
||||
"scripts": {
|
||||
"test:all": "npm run test:gitgram-backend && npm run test:gitgram-web && npm run test:aitm",
|
||||
"test:gitgram-backend": "cd gitgram/backend && npm test",
|
||||
"test:gitgram-web": "cd gitgram/web && npm test",
|
||||
"test:aitm": "cd aitimemachine/api-server && npm test",
|
||||
|
||||
"dev:gitgram": "concurrently \"npm run dev:gitgram-backend\" \"npm run dev:gitgram-web\"",
|
||||
"dev:gitgram-backend": "cd gitgram/backend && npm run dev",
|
||||
"dev:gitgram-web": "cd gitgram/web && npm run dev",
|
||||
"dev:gh-social": "cd gitgram/gh-social && npm run dev",
|
||||
"dev:t3": "cd gitgram/t3-base && npm run dev",
|
||||
"dev:proximity": "cd gitgram/mobile/proximity && npx expo start",
|
||||
|
||||
"dev:aitm": "concurrently \"npm run dev:aitm-api\" \"npm run dev:aitm-mcp\" \"npm run dev:gitnexus\"",
|
||||
"dev:aitm-api": "cd aitimemachine/api-server && npm run dev",
|
||||
"dev:aitm-api:clean": "npm --prefix aitimemachine/api-server run dev:clean",
|
||||
"dev:aitm-mcp": "cd aitimemachine/mcp && npm run dev",
|
||||
"dev:gitnexus": "cd aitimemachine/gitnexus && npm run dev",
|
||||
"dev:gitnexus-web": "cd aitimemachine/gitnexus-web && npm run dev",
|
||||
"dev:a2a": "cd aitimemachine/a2a && npm run dev 2>/dev/null || echo 'a2a has no dev script — build with: cd aitimemachine/a2a && npm run build'",
|
||||
"dev:context7": "cd aitimemachine/context7/packages/mcp && npm run dev 2>/dev/null || node aitimemachine/context7/packages/mcp/dist/index.js",
|
||||
"dev:pal-mcp": "cd aitimemachine/pal-mcp-server && ./run-server.sh",
|
||||
"dev:repo2txt": "cd aitimemachine/tools/repo2txt && npm run dev",
|
||||
"dev:repo-to-text": "cd aitimemachine/tools/repo-to-text && python -m repo_to_text",
|
||||
|
||||
"build:beads": "cd aitimemachine/beads && go build -o bd ./cmd/bd/ && echo 'beads bd binary built at aitimemachine/beads/bd'",
|
||||
"build:all": "npm run build:gitgram-backend && npm run build:gitgram-web && npm run build:aitm && npm run build:gitnexus",
|
||||
"build:gitgram-backend": "cd gitgram/backend && npm run build",
|
||||
"build:gitgram-web": "cd gitgram/web && npm run build",
|
||||
"build:aitm": "cd aitimemachine/api-server && npm run build",
|
||||
"build:gitnexus": "cd aitimemachine/gitnexus && npm run build",
|
||||
|
||||
"lint:all": "npm run lint:gitgram-backend && npm run lint:aitm",
|
||||
"lint:gitgram-backend": "cd gitgram/backend && npm run lint",
|
||||
"lint:aitm": "cd aitimemachine/api-server && npx tsc --noEmit",
|
||||
|
||||
"typecheck:all": "npm run typecheck:gitgram && npm run typecheck:aitm",
|
||||
"typecheck:gitgram": "npm run typecheck:gitgram-backend && npm run typecheck:gitgram-web",
|
||||
"typecheck:gitgram-backend": "cd gitgram/backend && npx tsc --noEmit",
|
||||
"typecheck:gitgram-web": "cd gitgram/web && npx tsc --noEmit",
|
||||
"typecheck:aitm": "cd aitimemachine && npx tsc --noEmit && cd api-server && npx tsc --noEmit",
|
||||
|
||||
"smoke:local-launch": "bash scripts/smoke-local-launch.sh",
|
||||
"deploy:launch:staging": "bash scripts/deploy-launch.sh staging",
|
||||
"deploy:launch:production": "bash scripts/deploy-launch.sh production",
|
||||
"verify:aitm-packages": "cd aitimemachine && npm run verify:packages",
|
||||
"verify:aitm-local": "bash scripts/validate-prod-secrets.sh local",
|
||||
"verify:launch": "bash scripts/verify-launch-readiness.sh all core",
|
||||
"verify:launch:staging": "bash scripts/verify-launch-readiness.sh staging core",
|
||||
"verify:launch:production": "bash scripts/verify-launch-readiness.sh production core",
|
||||
"verify:launch:full": "RUN_TYPECHECK=1 bash scripts/verify-launch-readiness.sh all full",
|
||||
"verify:launch:staging:full": "RUN_TYPECHECK=1 bash scripts/verify-launch-readiness.sh staging full",
|
||||
"verify:launch:production:full": "RUN_TYPECHECK=1 bash scripts/verify-launch-readiness.sh production full",
|
||||
"verify:public-launch": "bash scripts/verify-public-launch.sh",
|
||||
"verify:secrets:staging": "bash scripts/validate-prod-secrets.sh staging full",
|
||||
"verify:secrets:production": "bash scripts/validate-prod-secrets.sh production full"
|
||||
}
|
||||
}
|
||||
117
scripts/analyze-with-gitnexus.sh
Executable file
117
scripts/analyze-with-gitnexus.sh
Executable file
@ -0,0 +1,117 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# analyze-with-gitnexus.sh
|
||||
#
|
||||
# Usage: ./scripts/analyze-with-gitnexus.sh <REPO>
|
||||
#
|
||||
# REPO must be one of:
|
||||
# gitgram-backend gitgram-web aitm-api aitm-mcp
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
MONOREPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
GITNEXUS_DIR="${MONOREPO_ROOT}/aitimemachine/gitnexus"
|
||||
GITNEXUS_CLI="${GITNEXUS_DIR}/dist/cli/index.js"
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Argument handling
|
||||
# ---------------------------------------------------------------------------
|
||||
if [[ $# -lt 1 ]]; then
|
||||
echo "Usage: $0 <REPO>"
|
||||
echo ""
|
||||
echo "Available repos:"
|
||||
echo " gitgram-backend -> gitgram/backend"
|
||||
echo " gitgram-web -> gitgram/web"
|
||||
echo " aitm-api -> aitimemachine/api-server"
|
||||
echo " aitm-mcp -> aitimemachine/mcp"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
REPO="$1"
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Map repo name -> absolute path + display name
|
||||
# ---------------------------------------------------------------------------
|
||||
case "${REPO}" in
|
||||
gitgram-backend)
|
||||
REPO_PATH="${MONOREPO_ROOT}/gitgram/backend"
|
||||
REPO_NAME="gitgram-backend"
|
||||
;;
|
||||
gitgram-web)
|
||||
REPO_PATH="${MONOREPO_ROOT}/gitgram/web"
|
||||
REPO_NAME="gitgram-web"
|
||||
;;
|
||||
aitm-api)
|
||||
REPO_PATH="${MONOREPO_ROOT}/aitimemachine/api-server"
|
||||
REPO_NAME="aitm-api"
|
||||
;;
|
||||
aitm-mcp)
|
||||
REPO_PATH="${MONOREPO_ROOT}/aitimemachine/mcp"
|
||||
REPO_NAME="aitm-mcp"
|
||||
;;
|
||||
*)
|
||||
echo "ERROR: Unknown repo '${REPO}'"
|
||||
echo "Valid options: gitgram-backend, gitgram-web, aitm-api, aitm-mcp"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
if [[ ! -d "${REPO_PATH}" ]]; then
|
||||
echo "ERROR: Repo path does not exist: ${REPO_PATH}"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Build gitnexus if dist/cli/index.js is missing
|
||||
# ---------------------------------------------------------------------------
|
||||
if [[ ! -f "${GITNEXUS_CLI}" ]]; then
|
||||
echo "gitnexus CLI not built. Building now..."
|
||||
echo " -> ${GITNEXUS_DIR}"
|
||||
|
||||
if [[ ! -d "${GITNEXUS_DIR}/node_modules" ]]; then
|
||||
echo "Installing gitnexus dependencies..."
|
||||
(cd "${GITNEXUS_DIR}" && npm install)
|
||||
fi
|
||||
|
||||
(cd "${GITNEXUS_DIR}" && npm run build)
|
||||
|
||||
if [[ ! -f "${GITNEXUS_CLI}" ]]; then
|
||||
echo "ERROR: Build completed but ${GITNEXUS_CLI} still not found."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Build complete."
|
||||
else
|
||||
echo "gitnexus CLI already built: ${GITNEXUS_CLI}"
|
||||
fi
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Run analysis
|
||||
# ---------------------------------------------------------------------------
|
||||
echo ""
|
||||
echo "Analyzing '${REPO_NAME}' at:"
|
||||
echo " ${REPO_PATH}"
|
||||
echo ""
|
||||
|
||||
node "${GITNEXUS_CLI}" analyze "${REPO_PATH}" --name "${REPO_NAME}"
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Post-analysis instructions
|
||||
# ---------------------------------------------------------------------------
|
||||
echo ""
|
||||
echo "---------------------------------------------------------------------"
|
||||
echo "Analysis complete for '${REPO_NAME}'."
|
||||
echo ""
|
||||
echo "To start the gitnexus server and query the index:"
|
||||
echo ""
|
||||
echo " cd ${GITNEXUS_DIR}"
|
||||
echo " npm run serve"
|
||||
echo ""
|
||||
echo "The server listens on http://localhost:3001 by default."
|
||||
echo ""
|
||||
echo "To use it with the AITM MCP server:"
|
||||
echo ""
|
||||
echo " cd ${MONOREPO_ROOT}/aitimemachine/mcp"
|
||||
echo " npm run dev:with-gitnexus"
|
||||
echo "---------------------------------------------------------------------"
|
||||
8
scripts/deploy-gitgram.sh
Executable file
8
scripts/deploy-gitgram.sh
Executable file
@ -0,0 +1,8 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
|
||||
echo "scripts/deploy-gitgram.sh now wraps the PM2/manual launch flow."
|
||||
echo "For multi-service deploys use scripts/deploy-launch.sh directly."
|
||||
exec "${SCRIPT_DIR}/deploy-launch.sh" "$@" --gitgram-only
|
||||
222
scripts/deploy-launch.sh
Executable file
222
scripts/deploy-launch.sh
Executable file
@ -0,0 +1,222 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
ENVIRONMENT="${1:-}"
|
||||
if [[ -z "${ENVIRONMENT}" || ! "${ENVIRONMENT}" =~ ^(staging|production)$ ]]; then
|
||||
echo "Usage: $0 <staging|production> [--gitgram-only] [--aitm-only] [--skip-verify] [--verify-profile core|full] [--skip-install] [--skip-typecheck] [--dry-run]" >&2
|
||||
exit 1
|
||||
fi
|
||||
shift || true
|
||||
|
||||
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
GITGRAM_DIR="${ROOT_DIR}/gitgram"
|
||||
AITM_DIR="${ROOT_DIR}/aitimemachine"
|
||||
|
||||
GITGRAM_ONLY=0
|
||||
AITM_ONLY=0
|
||||
SKIP_VERIFY=0
|
||||
VERIFY_PROFILE="${VERIFY_PROFILE:-core}"
|
||||
SKIP_INSTALL=0
|
||||
SKIP_TYPECHECK=0
|
||||
DRY_RUN=0
|
||||
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--gitgram-only) GITGRAM_ONLY=1; shift ;;
|
||||
--aitm-only) AITM_ONLY=1; shift ;;
|
||||
--skip-verify) SKIP_VERIFY=1; shift ;;
|
||||
--verify-profile)
|
||||
VERIFY_PROFILE="${2:-}"
|
||||
if [[ "${VERIFY_PROFILE}" != "core" && "${VERIFY_PROFILE}" != "full" ]]; then
|
||||
echo "Invalid verify profile: ${VERIFY_PROFILE}" >&2
|
||||
exit 1
|
||||
fi
|
||||
shift 2
|
||||
;;
|
||||
--skip-install) SKIP_INSTALL=1; shift ;;
|
||||
--skip-typecheck) SKIP_TYPECHECK=1; shift ;;
|
||||
--dry-run) DRY_RUN=1; shift ;;
|
||||
*) echo "Unknown option: $1" >&2; exit 1 ;;
|
||||
esac
|
||||
done
|
||||
|
||||
if [[ "${GITGRAM_ONLY}" == "1" && "${AITM_ONLY}" == "1" ]]; then
|
||||
echo "Use either --gitgram-only or --aitm-only, not both." >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
run_cmd() {
|
||||
if [[ "${DRY_RUN}" == "1" ]]; then
|
||||
printf 'DRY_RUN '
|
||||
printf '%q ' "$@"
|
||||
printf '\n'
|
||||
return 0
|
||||
fi
|
||||
"$@"
|
||||
}
|
||||
|
||||
run_bash() {
|
||||
local cmd="$1"
|
||||
if [[ "${DRY_RUN}" == "1" ]]; then
|
||||
printf 'DRY_RUN bash -lc %q\n' "${cmd}"
|
||||
return 0
|
||||
fi
|
||||
bash -lc "${cmd}"
|
||||
}
|
||||
|
||||
log() {
|
||||
printf '%s\n' "$1"
|
||||
}
|
||||
|
||||
resolve_env_file() {
|
||||
local base="$1"
|
||||
local env_name="$2"
|
||||
local candidate="${base}.${env_name}"
|
||||
|
||||
if [[ -f "${candidate}" ]]; then
|
||||
printf '%s' "${candidate}"
|
||||
return 0
|
||||
fi
|
||||
|
||||
printf '%s' "${base}"
|
||||
}
|
||||
|
||||
check_cmd() {
|
||||
local cmd="$1"
|
||||
if ! command -v "${cmd}" >/dev/null 2>&1; then
|
||||
echo "Missing required command: ${cmd}" >&2
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
wait_for_http() {
|
||||
local label="$1"
|
||||
local url="$2"
|
||||
local retries="${3:-20}"
|
||||
local sleep_seconds="${4:-2}"
|
||||
|
||||
if [[ "${DRY_RUN}" == "1" ]]; then
|
||||
log "DRY_RUN health check ${label}: ${url}"
|
||||
return 0
|
||||
fi
|
||||
|
||||
for _ in $(seq 1 "${retries}"); do
|
||||
if curl -fsS --max-time 8 "${url}" >/dev/null 2>&1; then
|
||||
log "PASS ${label}: ${url}"
|
||||
return 0
|
||||
fi
|
||||
sleep "${sleep_seconds}"
|
||||
done
|
||||
|
||||
echo "Health check failed for ${label}: ${url}" >&2
|
||||
return 1
|
||||
}
|
||||
|
||||
pm2_apply() {
|
||||
local cwd="$1"
|
||||
local ecosystem_file="$2"
|
||||
local app_name="$3"
|
||||
shift 3
|
||||
|
||||
local source_lines=""
|
||||
local env_file
|
||||
for env_file in "$@"; do
|
||||
source_lines="${source_lines}source \"${env_file}\"\n"
|
||||
done
|
||||
|
||||
local script
|
||||
script="$(cat <<EOF
|
||||
set -euo pipefail
|
||||
set -a
|
||||
$(printf '%b' "${source_lines}")
|
||||
set +a
|
||||
cd "${cwd}"
|
||||
if pm2 describe "${app_name}" >/dev/null 2>&1; then
|
||||
pm2 restart "${app_name}" --update-env
|
||||
else
|
||||
pm2 start "${ecosystem_file}" --only "${app_name}"
|
||||
fi
|
||||
pm2 save
|
||||
EOF
|
||||
)"
|
||||
run_bash "${script}"
|
||||
}
|
||||
|
||||
log "=== Manual Launch Deploy ==="
|
||||
log "Environment: ${ENVIRONMENT}"
|
||||
log "Verify profile: ${VERIFY_PROFILE}"
|
||||
log "Root: ${ROOT_DIR}"
|
||||
|
||||
GITGRAM_ENV_FILE="$(resolve_env_file "${ROOT_DIR}/.env.gitgram" "${ENVIRONMENT}")"
|
||||
GITGRAM_WEB_ENV_FILE="$(resolve_env_file "${ROOT_DIR}/.env.gitgram-web" "${ENVIRONMENT}")"
|
||||
AITM_API_ENV_FILE="$(resolve_env_file "${ROOT_DIR}/.env.aitm-api" "${ENVIRONMENT}")"
|
||||
|
||||
check_cmd bash
|
||||
check_cmd node
|
||||
check_cmd npm
|
||||
check_cmd pm2
|
||||
check_cmd curl
|
||||
|
||||
if [[ "${SKIP_VERIFY}" != "1" ]]; then
|
||||
log ""
|
||||
log "1) Verifying launch readiness"
|
||||
run_cmd bash "${ROOT_DIR}/scripts/verify-launch-readiness.sh" "${ENVIRONMENT}" "${VERIFY_PROFILE}"
|
||||
else
|
||||
log ""
|
||||
log "1) Skipping launch readiness verification"
|
||||
fi
|
||||
|
||||
if [[ "${AITM_ONLY}" != "1" ]]; then
|
||||
log ""
|
||||
log "2) Deploying Gitgram backend"
|
||||
log "Gitgram backend env: ${GITGRAM_ENV_FILE}"
|
||||
run_cmd mkdir -p "${GITGRAM_DIR}/logs"
|
||||
if [[ "${SKIP_INSTALL}" != "1" ]]; then
|
||||
run_bash "cd \"${GITGRAM_DIR}/backend\" && npm ci --legacy-peer-deps"
|
||||
fi
|
||||
run_bash "set -a; source \"${GITGRAM_ENV_FILE}\"; set +a; cd \"${GITGRAM_DIR}/backend\" && npx prisma generate && npx prisma migrate deploy && npm run build"
|
||||
if [[ "${SKIP_TYPECHECK}" != "1" ]]; then
|
||||
run_bash "cd \"${GITGRAM_DIR}/backend\" && npx tsc --noEmit"
|
||||
fi
|
||||
pm2_apply "${GITGRAM_DIR}" "ecosystem.config.js" "gitgram-api" "${GITGRAM_ENV_FILE}"
|
||||
|
||||
log ""
|
||||
log "3) Deploying Gitgram web"
|
||||
log "Gitgram web env: ${GITGRAM_WEB_ENV_FILE}"
|
||||
if [[ "${SKIP_INSTALL}" != "1" ]]; then
|
||||
run_bash "cd \"${GITGRAM_DIR}/web\" && npm ci --legacy-peer-deps"
|
||||
fi
|
||||
run_bash "set -a; source \"${GITGRAM_WEB_ENV_FILE}\"; set +a; cd \"${GITGRAM_DIR}/web\" && npm run build"
|
||||
if [[ "${SKIP_TYPECHECK}" != "1" ]]; then
|
||||
run_bash "cd \"${GITGRAM_DIR}/web\" && npx tsc --noEmit"
|
||||
fi
|
||||
pm2_apply "${GITGRAM_DIR}" "ecosystem.config.js" "gitgram-web" "${GITGRAM_WEB_ENV_FILE}"
|
||||
|
||||
log ""
|
||||
log "4) Verifying Gitgram local health"
|
||||
wait_for_http "Gitgram backend health" "http://127.0.0.1:4000/health"
|
||||
wait_for_http "Gitgram backend readiness" "http://127.0.0.1:4000/health/ready"
|
||||
wait_for_http "Gitgram web" "http://127.0.0.1:3000/"
|
||||
fi
|
||||
|
||||
if [[ "${GITGRAM_ONLY}" != "1" ]]; then
|
||||
log ""
|
||||
log "5) Deploying AITM API"
|
||||
log "AITM API env: ${AITM_API_ENV_FILE}"
|
||||
if [[ "${SKIP_INSTALL}" != "1" ]]; then
|
||||
run_bash "cd \"${AITM_DIR}/api-server\" && npm ci"
|
||||
fi
|
||||
run_bash "set -a; source \"${AITM_API_ENV_FILE}\"; set +a; cd \"${AITM_DIR}/api-server\" && npm run db:migrate && npm run build"
|
||||
if [[ "${SKIP_TYPECHECK}" != "1" ]]; then
|
||||
run_bash "cd \"${AITM_DIR}\" && npx tsc --noEmit && cd api-server && npx tsc --noEmit"
|
||||
fi
|
||||
pm2_apply "${AITM_DIR}" "deploy/ecosystem.config.cjs" "aitm-api" "${AITM_API_ENV_FILE}"
|
||||
|
||||
log ""
|
||||
log "6) Verifying AITM local health"
|
||||
wait_for_http "AITM API health" "http://127.0.0.1:3001/health"
|
||||
wait_for_http "AITM API readiness" "http://127.0.0.1:3001/health/ready"
|
||||
fi
|
||||
|
||||
log ""
|
||||
log "Manual launch deploy flow completed."
|
||||
237
scripts/dev.sh
Executable file
237
scripts/dev.sh
Executable file
@ -0,0 +1,237 @@
|
||||
#!/usr/bin/env bash
|
||||
# =============================================================================
|
||||
# dev.sh — Developer onboarding script for the Gitgram + AITM monorepo
|
||||
# =============================================================================
|
||||
# Usage:
|
||||
# bash scripts/dev.sh # full setup (infra + deps + migrations)
|
||||
# bash scripts/dev.sh --infra # infra only (postgres + redis)
|
||||
# bash scripts/dev.sh --help # show this help
|
||||
# =============================================================================
|
||||
set -euo pipefail
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Colours
|
||||
# -----------------------------------------------------------------------------
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
CYAN='\033[0;36m'
|
||||
BOLD='\033[1m'
|
||||
RESET='\033[0m'
|
||||
|
||||
ok() { echo -e " ${GREEN}✔${RESET} $*"; }
|
||||
info() { echo -e " ${CYAN}→${RESET} $*"; }
|
||||
warn() { echo -e " ${YELLOW}⚠${RESET} $*"; }
|
||||
fail() { echo -e " ${RED}✘${RESET} $*"; exit 1; }
|
||||
step() { echo -e "\n${BOLD}${CYAN}[dev.sh]${RESET} ${BOLD}$*${RESET}"; }
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Helpers
|
||||
# -----------------------------------------------------------------------------
|
||||
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
|
||||
infra_only=false
|
||||
for arg in "$@"; do
|
||||
case "$arg" in
|
||||
--infra) infra_only=true ;;
|
||||
--help|-h)
|
||||
echo "Usage: bash scripts/dev.sh [--infra] [--help]"
|
||||
echo " --infra Start Postgres + Redis only, skip npm/migrations"
|
||||
exit 0
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# 1. Prerequisite checks
|
||||
# -----------------------------------------------------------------------------
|
||||
step "Checking prerequisites"
|
||||
|
||||
# Node >= 20
|
||||
if command -v node &>/dev/null; then
|
||||
NODE_MAJOR=$(node -e "process.stdout.write(process.versions.node.split('.')[0])")
|
||||
if [[ "$NODE_MAJOR" -ge 20 ]]; then
|
||||
ok "node $(node --version)"
|
||||
else
|
||||
fail "Node.js 20+ required (found $(node --version)). Use nvm: nvm install 20"
|
||||
fi
|
||||
else
|
||||
fail "node not found. Install Node.js 20+: https://nodejs.org"
|
||||
fi
|
||||
|
||||
# npm
|
||||
if command -v npm &>/dev/null; then
|
||||
ok "npm $(npm --version)"
|
||||
else
|
||||
fail "npm not found"
|
||||
fi
|
||||
|
||||
# Docker
|
||||
if command -v docker &>/dev/null; then
|
||||
if docker info &>/dev/null 2>&1; then
|
||||
ok "docker $(docker --version | awk '{print $3}' | tr -d ',')"
|
||||
else
|
||||
fail "Docker daemon is not running. Start Docker Desktop (or your daemon) and retry."
|
||||
fi
|
||||
else
|
||||
fail "docker not found. Install Docker Desktop: https://docs.docker.com/get-docker/"
|
||||
fi
|
||||
|
||||
# docker compose (v2 plugin)
|
||||
if docker compose version &>/dev/null 2>&1; then
|
||||
ok "docker compose $(docker compose version --short 2>/dev/null || echo 'v2')"
|
||||
else
|
||||
fail "docker compose (v2) not found. Update Docker Desktop or install the plugin."
|
||||
fi
|
||||
|
||||
# git
|
||||
if command -v git &>/dev/null; then
|
||||
ok "git $(git --version | awk '{print $3}')"
|
||||
else
|
||||
warn "git not found — version control features will be limited."
|
||||
fi
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# 2. Copy .env.example → .env (never overwrites existing files)
|
||||
# -----------------------------------------------------------------------------
|
||||
step "Setting up environment files"
|
||||
|
||||
copy_env() {
|
||||
local example="$REPO_ROOT/$1"
|
||||
local target="$REPO_ROOT/$2"
|
||||
if [[ ! -f "$example" ]]; then
|
||||
warn "Example not found: $1 (skipping)"
|
||||
return
|
||||
fi
|
||||
if [[ -f "$target" ]]; then
|
||||
ok "$2 already exists — skipping"
|
||||
else
|
||||
cp "$example" "$target"
|
||||
ok "Created $2 from $1"
|
||||
warn " Edit $2 and fill in any required secrets before running services."
|
||||
fi
|
||||
}
|
||||
|
||||
copy_env ".env.gitgram.example" ".env.gitgram"
|
||||
copy_env ".env.gitgram-web.example" ".env.gitgram-web"
|
||||
copy_env ".env.aitm-api.example" ".env.aitm-api"
|
||||
copy_env ".env.aitm-website.example" ".env.aitm-website"
|
||||
copy_env ".env.postgres.example" ".env.postgres"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# 3. Start infrastructure (postgres + redis)
|
||||
# -----------------------------------------------------------------------------
|
||||
step "Starting infrastructure (postgres + redis)"
|
||||
|
||||
cd "$REPO_ROOT"
|
||||
|
||||
docker compose up -d postgres redis
|
||||
|
||||
info "Waiting for postgres to be healthy…"
|
||||
RETRIES=20
|
||||
until docker compose exec -T postgres pg_isready -U gitgram -d gitgram &>/dev/null; do
|
||||
RETRIES=$((RETRIES - 1))
|
||||
if [[ $RETRIES -le 0 ]]; then
|
||||
fail "Postgres did not become healthy after 100 s. Check: docker compose logs postgres"
|
||||
fi
|
||||
sleep 5
|
||||
done
|
||||
ok "Postgres is healthy"
|
||||
|
||||
info "Waiting for redis to be healthy…"
|
||||
RETRIES=10
|
||||
until docker compose exec -T redis redis-cli ping 2>/dev/null | grep -q PONG; do
|
||||
RETRIES=$((RETRIES - 1))
|
||||
if [[ $RETRIES -le 0 ]]; then
|
||||
fail "Redis did not become healthy after 50 s. Check: docker compose logs redis"
|
||||
fi
|
||||
sleep 5
|
||||
done
|
||||
ok "Redis is healthy"
|
||||
|
||||
if $infra_only; then
|
||||
echo ""
|
||||
echo -e "${GREEN}${BOLD}Infrastructure is up.${RESET}"
|
||||
echo -e " Postgres → ${CYAN}postgresql://gitgram:gitgram_dev@localhost:5432/gitgram${RESET}"
|
||||
echo -e " Redis → ${CYAN}redis://localhost:6379${RESET}"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# 4. Install npm dependencies
|
||||
# -----------------------------------------------------------------------------
|
||||
step "Installing npm dependencies"
|
||||
|
||||
PACKAGES=(
|
||||
"gitgram/backend"
|
||||
"gitgram/web"
|
||||
"aitimemachine/api-server"
|
||||
"aitimemachine/mcp"
|
||||
)
|
||||
|
||||
for pkg in "${PACKAGES[@]}"; do
|
||||
pkg_path="$REPO_ROOT/$pkg"
|
||||
if [[ -f "$pkg_path/package.json" ]]; then
|
||||
info "npm ci → $pkg"
|
||||
npm ci --prefix "$pkg_path" --silent
|
||||
ok "$pkg"
|
||||
else
|
||||
warn "$pkg/package.json not found — skipping"
|
||||
fi
|
||||
done
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# 5. Run database migrations
|
||||
# -----------------------------------------------------------------------------
|
||||
step "Running database migrations"
|
||||
|
||||
# Gitgram backend — Prisma
|
||||
GITGRAM_BACKEND="$REPO_ROOT/gitgram/backend"
|
||||
if [[ -f "$GITGRAM_BACKEND/package.json" ]]; then
|
||||
info "Prisma migrate deploy → gitgram/backend"
|
||||
DATABASE_URL="postgresql://gitgram:gitgram_dev@localhost:5432/gitgram" \
|
||||
npx --prefix "$GITGRAM_BACKEND" prisma migrate deploy 2>&1 | tail -5
|
||||
ok "Gitgram migrations applied"
|
||||
else
|
||||
warn "gitgram/backend not found — skipping Prisma migration"
|
||||
fi
|
||||
|
||||
# AITM API — Drizzle
|
||||
AITM_API="$REPO_ROOT/aitimemachine/api-server"
|
||||
if [[ -f "$AITM_API/package.json" ]]; then
|
||||
AITM_MIGRATE_SCRIPT=$(node -e "const p=require('$AITM_API/package.json'); process.stdout.write(p.scripts&&p.scripts['db:migrate']?'db:migrate':p.scripts&&p.scripts['migrate']?'migrate':'')" 2>/dev/null || true)
|
||||
if [[ -n "$AITM_MIGRATE_SCRIPT" ]]; then
|
||||
info "npm run $AITM_MIGRATE_SCRIPT → aitimemachine/api-server"
|
||||
DATABASE_URL="postgresql://gitgram:gitgram_dev@localhost:5432/gitgram" \
|
||||
npm run "$AITM_MIGRATE_SCRIPT" --prefix "$AITM_API" 2>&1 | tail -5
|
||||
ok "AITM migrations applied"
|
||||
else
|
||||
warn "No migrate script found in aitimemachine/api-server/package.json — skipping"
|
||||
fi
|
||||
else
|
||||
warn "aitimemachine/api-server not found — skipping Drizzle migration"
|
||||
fi
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Done
|
||||
# -----------------------------------------------------------------------------
|
||||
echo ""
|
||||
echo -e "${GREEN}${BOLD}Dev environment is ready.${RESET}"
|
||||
echo ""
|
||||
echo -e " ${BOLD}Infrastructure${RESET}"
|
||||
echo -e " Postgres → ${CYAN}postgresql://gitgram:gitgram_dev@localhost:5432/gitgram${RESET}"
|
||||
echo -e " Redis → ${CYAN}redis://localhost:6379${RESET}"
|
||||
echo ""
|
||||
echo -e " ${BOLD}Start all services${RESET}"
|
||||
echo -e " ${CYAN}docker compose up${RESET}"
|
||||
echo -e " ${CYAN}docker compose --profile tools up${RESET} (+ GitNexus + Context7)"
|
||||
echo ""
|
||||
echo -e " ${BOLD}Start individual services (native, hot-reload)${RESET}"
|
||||
echo -e " ${CYAN}npm run dev:gitgram-backend${RESET} → http://localhost:4000"
|
||||
echo -e " ${CYAN}npm run dev:gitgram-web${RESET} → http://localhost:3000"
|
||||
echo -e " ${CYAN}npm run dev:aitm-api${RESET} → http://localhost:3001"
|
||||
echo -e " ${CYAN}npm run dev:aitm-mcp${RESET} → stdio / http://localhost:3003"
|
||||
echo ""
|
||||
echo -e " ${BOLD}Tear down${RESET}"
|
||||
echo -e " ${CYAN}docker compose down -v${RESET} (removes volumes too)"
|
||||
echo ""
|
||||
216
scripts/setup-aitm-tools.sh
Executable file
216
scripts/setup-aitm-tools.sh
Executable file
@ -0,0 +1,216 @@
|
||||
#!/usr/bin/env bash
|
||||
# setup-aitm-tools.sh
|
||||
# Builds and configures all AITM companion tools:
|
||||
# - beads (Go binary, external/beads/cmd/bd)
|
||||
# - gitnexus (npm, external/gitnexus/gitnexus)
|
||||
# - pal-mcp-server (Python venv, external/pal-mcp-server)
|
||||
# - context7 mcp (pnpm/npm, external/context7/packages/mcp)
|
||||
#
|
||||
# Designed to be defensive: a failure in one tool does NOT abort the others.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
EXTERNAL="$ROOT/external"
|
||||
|
||||
# ── colours ──────────────────────────────────────────────────────────────────
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
CYAN='\033[0;36m'
|
||||
RESET='\033[0m'
|
||||
|
||||
ok() { echo -e "${GREEN}[ok]${RESET} $*"; }
|
||||
warn() { echo -e "${YELLOW}[warn]${RESET} $*"; }
|
||||
fail() { echo -e "${RED}[fail]${RESET} $*"; }
|
||||
step() { echo -e "\n${CYAN}==> $*${RESET}"; }
|
||||
|
||||
ERRORS=()
|
||||
|
||||
# ── helpers ───────────────────────────────────────────────────────────────────
|
||||
require_dir() {
|
||||
local dir="$1" name="$2"
|
||||
if [[ ! -d "$dir" ]]; then
|
||||
fail "$name directory not found: $dir"
|
||||
return 1
|
||||
fi
|
||||
return 0
|
||||
}
|
||||
|
||||
# Run a named build function; record failure but continue
|
||||
run_step() {
|
||||
local name="$1"; shift
|
||||
if "$@"; then
|
||||
ok "$name done"
|
||||
else
|
||||
fail "$name FAILED (exit $?)"
|
||||
ERRORS+=("$name")
|
||||
fi
|
||||
}
|
||||
|
||||
# ── 1. beads (Go) ─────────────────────────────────────────────────────────────
|
||||
build_beads() {
|
||||
step "beads — Go binary (cmd/bd)"
|
||||
|
||||
if ! command -v go &>/dev/null; then
|
||||
warn "Go not found — skipping beads build"
|
||||
warn "Install from https://go.dev/dl/"
|
||||
return 0
|
||||
fi
|
||||
|
||||
local beads_dir="$EXTERNAL/beads"
|
||||
require_dir "$beads_dir" "beads" || return 1
|
||||
|
||||
# Prefer cmd/bd; fall back to cmd/beads or root package
|
||||
local cmd_path=""
|
||||
if [[ -f "$beads_dir/cmd/bd/main.go" ]]; then
|
||||
cmd_path="./cmd/bd"
|
||||
elif [[ -f "$beads_dir/cmd/beads/main.go" ]]; then
|
||||
cmd_path="./cmd/beads"
|
||||
else
|
||||
warn "No cmd/bd or cmd/beads found — attempting root package build"
|
||||
cmd_path="."
|
||||
fi
|
||||
|
||||
local out_bin="$beads_dir/bd"
|
||||
(
|
||||
cd "$beads_dir"
|
||||
go build -o "$out_bin" "$cmd_path"
|
||||
)
|
||||
ok "beads binary at $out_bin"
|
||||
echo " run: $out_bin --help"
|
||||
}
|
||||
|
||||
# ── 2. gitnexus (npm) ─────────────────────────────────────────────────────────
|
||||
build_gitnexus() {
|
||||
step "gitnexus — npm install + build"
|
||||
|
||||
local gnx_dir="$EXTERNAL/gitnexus"
|
||||
require_dir "$gnx_dir" "gitnexus" || return 1
|
||||
|
||||
# The main CLI lives in the gitnexus/ sub-package
|
||||
local pkg_dir="$gnx_dir/gitnexus"
|
||||
if [[ ! -d "$pkg_dir" ]]; then
|
||||
warn "gitnexus/gitnexus sub-directory not found; trying root"
|
||||
pkg_dir="$gnx_dir"
|
||||
fi
|
||||
|
||||
if ! command -v npm &>/dev/null; then
|
||||
fail "npm not found — cannot build gitnexus"
|
||||
return 1
|
||||
fi
|
||||
|
||||
(
|
||||
cd "$pkg_dir"
|
||||
echo " Installing dependencies..."
|
||||
npm install --prefer-offline --no-fund --no-audit 2>&1 | tail -3
|
||||
echo " Building..."
|
||||
npm run build 2>&1 | tail -5
|
||||
)
|
||||
ok "gitnexus built in $pkg_dir"
|
||||
}
|
||||
|
||||
# ── 3. pal-mcp-server (Python venv) ───────────────────────────────────────────
|
||||
setup_pal_mcp() {
|
||||
step "pal-mcp-server — Python venv + requirements"
|
||||
|
||||
local pal_dir="$EXTERNAL/pal-mcp-server"
|
||||
require_dir "$pal_dir" "pal-mcp-server" || return 1
|
||||
|
||||
if ! command -v python3 &>/dev/null; then
|
||||
fail "python3 not found — cannot set up pal-mcp-server"
|
||||
fail "Install Python 3.10+ from https://python.org"
|
||||
return 1
|
||||
fi
|
||||
|
||||
local python_version
|
||||
python_version="$(python3 --version 2>&1)"
|
||||
echo " Using $python_version"
|
||||
|
||||
local venv_dir="$pal_dir/.venv"
|
||||
|
||||
if [[ ! -d "$venv_dir" ]]; then
|
||||
echo " Creating venv at $venv_dir ..."
|
||||
python3 -m venv "$venv_dir"
|
||||
else
|
||||
echo " venv already exists, reusing"
|
||||
fi
|
||||
|
||||
local pip="$venv_dir/bin/pip"
|
||||
|
||||
if [[ -f "$pal_dir/requirements.txt" ]]; then
|
||||
echo " Installing requirements.txt ..."
|
||||
"$pip" install --quiet -r "$pal_dir/requirements.txt"
|
||||
else
|
||||
warn "requirements.txt not found in $pal_dir"
|
||||
fi
|
||||
|
||||
if [[ -f "$pal_dir/requirements-dev.txt" ]]; then
|
||||
echo " Installing requirements-dev.txt ..."
|
||||
"$pip" install --quiet -r "$pal_dir/requirements-dev.txt"
|
||||
fi
|
||||
|
||||
ok "pal-mcp-server venv ready at $venv_dir"
|
||||
echo " activate: source $venv_dir/bin/activate"
|
||||
echo " run: $venv_dir/bin/python $pal_dir/server.py"
|
||||
}
|
||||
|
||||
# ── 4. context7 packages/mcp ──────────────────────────────────────────────────
|
||||
build_context7_mcp() {
|
||||
step "context7 — packages/mcp build"
|
||||
|
||||
local ctx7_dir="$EXTERNAL/context7"
|
||||
require_dir "$ctx7_dir" "context7" || return 1
|
||||
|
||||
local mcp_dir="$ctx7_dir/packages/mcp"
|
||||
require_dir "$mcp_dir" "context7/packages/mcp" || return 1
|
||||
|
||||
# Prefer pnpm (the repo uses pnpm workspaces), fall back to npm
|
||||
local pkg_cmd
|
||||
if command -v pnpm &>/dev/null; then
|
||||
pkg_cmd="pnpm"
|
||||
elif command -v npm &>/dev/null; then
|
||||
pkg_cmd="npm"
|
||||
warn "pnpm not found; falling back to npm (workspace installs may be incomplete)"
|
||||
else
|
||||
fail "Neither pnpm nor npm found — cannot build context7"
|
||||
return 1
|
||||
fi
|
||||
|
||||
(
|
||||
cd "$mcp_dir"
|
||||
echo " Installing dependencies (${pkg_cmd})..."
|
||||
"$pkg_cmd" install --prefer-offline 2>&1 | tail -3
|
||||
echo " Building..."
|
||||
"$pkg_cmd" run build 2>&1 | tail -5
|
||||
)
|
||||
ok "context7/packages/mcp built"
|
||||
echo " run: node $mcp_dir/dist/index.js --transport http"
|
||||
}
|
||||
|
||||
# ── main ──────────────────────────────────────────────────────────────────────
|
||||
echo -e "\n${CYAN}AITM companion tools setup${RESET}"
|
||||
echo "Repository root: $ROOT"
|
||||
echo "External tools: $EXTERNAL"
|
||||
|
||||
run_step "beads" build_beads
|
||||
run_step "gitnexus" build_gitnexus
|
||||
run_step "pal-mcp-server" setup_pal_mcp
|
||||
run_step "context7-mcp" build_context7_mcp
|
||||
|
||||
echo ""
|
||||
echo "----------------------------------------------"
|
||||
if [[ ${#ERRORS[@]} -eq 0 ]]; then
|
||||
echo -e "${GREEN}All tools set up successfully.${RESET}"
|
||||
else
|
||||
echo -e "${RED}Setup completed with errors in: ${ERRORS[*]}${RESET}"
|
||||
echo "Review the output above, fix the issues, then re-run."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "Quick reference:"
|
||||
echo " beads: $EXTERNAL/beads/bd --help"
|
||||
echo " gitnexus: cd $EXTERNAL/gitnexus/gitnexus && npm run serve"
|
||||
echo " pal-mcp-server: source $EXTERNAL/pal-mcp-server/.venv/bin/activate && python $EXTERNAL/pal-mcp-server/server.py"
|
||||
echo " context7-mcp: node $EXTERNAL/context7/packages/mcp/dist/index.js --transport http"
|
||||
113
scripts/smoke-local-launch.sh
Executable file
113
scripts/smoke-local-launch.sh
Executable file
@ -0,0 +1,113 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
|
||||
GITGRAM_BACKEND_HEALTH_URL="${GITGRAM_BACKEND_HEALTH_URL:-http://localhost:4000/health}"
|
||||
GITGRAM_WEB_URL="${GITGRAM_WEB_URL:-http://localhost:3000}"
|
||||
AITM_API_HEALTH_URL="${AITM_API_HEALTH_URL:-http://localhost:3001/health}"
|
||||
|
||||
SKIP_HTTP="${SKIP_HTTP:-0}"
|
||||
RUN_AITM_CLI_SMOKE="${RUN_AITM_CLI_SMOKE:-0}"
|
||||
RUN_AITM_MCP_SMOKE="${RUN_AITM_MCP_SMOKE:-0}"
|
||||
AUTO_START="${AUTO_START:-0}"
|
||||
|
||||
log() {
|
||||
printf '%s\n' "$1"
|
||||
}
|
||||
|
||||
check_cmd() {
|
||||
local cmd="$1"
|
||||
if ! command -v "${cmd}" >/dev/null 2>&1; then
|
||||
log "Missing required command: ${cmd}"
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
check_http() {
|
||||
local label="$1"
|
||||
local url="$2"
|
||||
if curl -fsS --max-time 8 "${url}" >/dev/null; then
|
||||
log "PASS ${label}: ${url}"
|
||||
else
|
||||
log "FAIL ${label}: ${url}"
|
||||
return 1
|
||||
fi
|
||||
}
|
||||
|
||||
start_services_if_requested() {
|
||||
if [[ "${AUTO_START}" != "1" ]]; then
|
||||
return 0
|
||||
fi
|
||||
|
||||
check_cmd docker
|
||||
log ""
|
||||
log "Starting local services via docker compose (AUTO_START=1)"
|
||||
(
|
||||
cd "${ROOT_DIR}"
|
||||
docker compose up -d postgres redis gitgram-backend gitgram-web aitm-api
|
||||
)
|
||||
}
|
||||
|
||||
wait_for_http() {
|
||||
local label="$1"
|
||||
local url="$2"
|
||||
local retries="${3:-30}"
|
||||
local sleep_seconds="${4:-2}"
|
||||
|
||||
for _ in $(seq 1 "${retries}"); do
|
||||
if curl -fsS --max-time 8 "${url}" >/dev/null 2>&1; then
|
||||
return 0
|
||||
fi
|
||||
sleep "${sleep_seconds}"
|
||||
done
|
||||
|
||||
log "FAIL ${label}: ${url} did not become ready after ${retries} attempts"
|
||||
return 1
|
||||
}
|
||||
|
||||
log "=== Stage A Local Smoke Check ==="
|
||||
log "Repo: ${ROOT_DIR}"
|
||||
|
||||
check_cmd npm
|
||||
check_cmd curl
|
||||
|
||||
log ""
|
||||
log "1) Validating local AITM env minimums"
|
||||
npm --prefix "${ROOT_DIR}" run verify:aitm-local
|
||||
|
||||
log ""
|
||||
log "2) Verifying AITM npm package tarballs"
|
||||
npm --prefix "${ROOT_DIR}" run verify:aitm-packages
|
||||
|
||||
if [[ "${SKIP_HTTP}" == "1" ]]; then
|
||||
log ""
|
||||
log "3) HTTP health checks skipped (SKIP_HTTP=1)"
|
||||
else
|
||||
start_services_if_requested
|
||||
log ""
|
||||
log "3) Checking live local service health endpoints"
|
||||
if [[ "${AUTO_START}" == "1" ]]; then
|
||||
wait_for_http "Gitgram backend health" "${GITGRAM_BACKEND_HEALTH_URL}"
|
||||
wait_for_http "Gitgram web" "${GITGRAM_WEB_URL}"
|
||||
wait_for_http "AITM API health" "${AITM_API_HEALTH_URL}"
|
||||
fi
|
||||
check_http "Gitgram backend health" "${GITGRAM_BACKEND_HEALTH_URL}"
|
||||
check_http "Gitgram web" "${GITGRAM_WEB_URL}"
|
||||
check_http "AITM API health" "${AITM_API_HEALTH_URL}"
|
||||
fi
|
||||
|
||||
if [[ "${RUN_AITM_CLI_SMOKE}" == "1" ]]; then
|
||||
log ""
|
||||
log "4) Running AITM CLI smoke test"
|
||||
bash "${ROOT_DIR}/aitimemachine/scripts/cli-smoke-test.sh"
|
||||
fi
|
||||
|
||||
if [[ "${RUN_AITM_MCP_SMOKE}" == "1" ]]; then
|
||||
log ""
|
||||
log "5) Running AITM MCP smoke test"
|
||||
bash "${ROOT_DIR}/aitimemachine/scripts/mcp-smoke-test.sh"
|
||||
fi
|
||||
|
||||
log ""
|
||||
log "Stage A local smoke checks completed."
|
||||
145
scripts/start-all-dev.sh
Executable file
145
scripts/start-all-dev.sh
Executable file
@ -0,0 +1,145 @@
|
||||
#!/usr/bin/env bash
|
||||
# start-all-dev.sh
|
||||
# Starts all core dev services for the Gitgram-AI monorepo:
|
||||
#
|
||||
# Service Port / URL
|
||||
# ──────────────────────── ─────────────────────────────
|
||||
# gitgram/backend http://localhost:3000
|
||||
# gitgram/web (Next.js) http://localhost:3001 (next dev default = 3000,
|
||||
# but backend already owns that, so web uses 3001
|
||||
# via PORT env — or the Next.js default if unset)
|
||||
# aitimemachine/api-server http://localhost:3001 (its own default)
|
||||
#
|
||||
# NOTE: gitgram/backend defaults to PORT 3000.
|
||||
# aitimemachine/api-server defaults to PORT 3001.
|
||||
# gitgram/web (Next.js) defaults to PORT 3000; to avoid clash it is
|
||||
# started on PORT 3002 here. Override with GITGRAM_WEB_PORT env var.
|
||||
#
|
||||
# Uses `concurrently` when available (npm install -g concurrently).
|
||||
# Falls back to printing manual commands.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
|
||||
# ── colours ──────────────────────────────────────────────────────────────────
|
||||
CYAN='\033[0;36m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
RESET='\033[0m'
|
||||
|
||||
# ── configurable ports ────────────────────────────────────────────────────────
|
||||
BACKEND_PORT="${GITGRAM_BACKEND_PORT:-3000}"
|
||||
WEB_PORT="${GITGRAM_WEB_PORT:-3002}"
|
||||
AITM_PORT="${AITM_API_PORT:-3001}"
|
||||
|
||||
# ── service directories ───────────────────────────────────────────────────────
|
||||
BACKEND_DIR="$ROOT/gitgram/backend"
|
||||
WEB_DIR="$ROOT/gitgram/web"
|
||||
AITM_DIR="$ROOT/aitimemachine/api-server"
|
||||
|
||||
# ── banner ────────────────────────────────────────────────────────────────────
|
||||
echo -e "\n${CYAN}Gitgram-AI — dev services${RESET}"
|
||||
echo ""
|
||||
echo " Service Command URL"
|
||||
echo " ─────────────────────────────────────────────────────────────────────"
|
||||
echo " gitgram/backend npm run dev http://localhost:${BACKEND_PORT}"
|
||||
echo " gitgram/web (Next.js) npm run dev http://localhost:${WEB_PORT}"
|
||||
echo " aitimemachine/api-server npm run dev http://localhost:${AITM_PORT}"
|
||||
echo ""
|
||||
|
||||
# ── preflight checks ─────────────────────────────────────────────────────────
|
||||
MISSING=()
|
||||
for pair in "gitgram/backend:$BACKEND_DIR" "gitgram/web:$WEB_DIR" "aitimemachine/api-server:$AITM_DIR"; do
|
||||
name="${pair%%:*}"
|
||||
dir="${pair#*:}"
|
||||
if [[ ! -d "$dir" ]]; then
|
||||
echo -e "${YELLOW}[warn]${RESET} Directory not found: $dir (${name} will be skipped)"
|
||||
MISSING+=("$name")
|
||||
fi
|
||||
done
|
||||
|
||||
if [[ ${#MISSING[@]} -gt 0 ]]; then
|
||||
echo ""
|
||||
fi
|
||||
|
||||
# Build the npm dev commands with explicit PORT assignments
|
||||
BACKEND_CMD="cd \"$BACKEND_DIR\" && PORT=$BACKEND_PORT npm run dev"
|
||||
WEB_CMD="cd \"$WEB_DIR\" && PORT=$WEB_PORT npm run dev"
|
||||
AITM_CMD="cd \"$AITM_DIR\" && PORT=$AITM_PORT npm run dev"
|
||||
|
||||
# ── try concurrently ─────────────────────────────────────────────────────────
|
||||
if command -v concurrently &>/dev/null; then
|
||||
echo -e "${GREEN}Starting all services with concurrently...${RESET}"
|
||||
echo "(Press Ctrl+C to stop all)"
|
||||
echo ""
|
||||
|
||||
# Build argument list; skip missing service dirs
|
||||
CONC_ARGS=()
|
||||
CONC_NAMES=()
|
||||
|
||||
[[ ! " ${MISSING[*]} " =~ " gitgram/backend " ]] && {
|
||||
CONC_ARGS+=("$BACKEND_CMD")
|
||||
CONC_NAMES+=("backend")
|
||||
}
|
||||
[[ ! " ${MISSING[*]} " =~ " gitgram/web " ]] && {
|
||||
CONC_ARGS+=("$WEB_CMD")
|
||||
CONC_NAMES+=("web")
|
||||
}
|
||||
[[ ! " ${MISSING[*]} " =~ " aitimemachine/api-server " ]] && {
|
||||
CONC_ARGS+=("$AITM_CMD")
|
||||
CONC_NAMES+=("aitm-api")
|
||||
}
|
||||
|
||||
if [[ ${#CONC_ARGS[@]} -eq 0 ]]; then
|
||||
echo "No service directories found. Nothing to start."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Build --names flag
|
||||
NAMES_FLAG="$(IFS=','; echo "${CONC_NAMES[*]}")"
|
||||
|
||||
concurrently \
|
||||
--kill-others-on-fail \
|
||||
--prefix "[{name}]" \
|
||||
--names "$NAMES_FLAG" \
|
||||
--prefix-colors "cyan,magenta,green" \
|
||||
"${CONC_ARGS[@]}"
|
||||
|
||||
else
|
||||
# ── fallback: print manual commands ────────────────────────────────────────
|
||||
echo -e "${YELLOW}concurrently not found.${RESET}"
|
||||
echo "Install it globally to start all services in one terminal:"
|
||||
echo " npm install -g concurrently"
|
||||
echo ""
|
||||
echo "To start services manually, open three terminal windows and run:"
|
||||
echo ""
|
||||
echo " # Terminal 1 — gitgram/backend"
|
||||
if [[ ! " ${MISSING[*]} " =~ " gitgram/backend " ]]; then
|
||||
echo " cd $BACKEND_DIR"
|
||||
echo " PORT=$BACKEND_PORT npm run dev"
|
||||
else
|
||||
echo " (directory not found: $BACKEND_DIR)"
|
||||
fi
|
||||
echo ""
|
||||
echo " # Terminal 2 — gitgram/web"
|
||||
if [[ ! " ${MISSING[*]} " =~ " gitgram/web " ]]; then
|
||||
echo " cd $WEB_DIR"
|
||||
echo " PORT=$WEB_PORT npm run dev"
|
||||
else
|
||||
echo " (directory not found: $WEB_DIR)"
|
||||
fi
|
||||
echo ""
|
||||
echo " # Terminal 3 — aitimemachine/api-server"
|
||||
if [[ ! " ${MISSING[*]} " =~ " aitimemachine/api-server " ]]; then
|
||||
echo " cd $AITM_DIR"
|
||||
echo " PORT=$AITM_PORT npm run dev"
|
||||
else
|
||||
echo " (directory not found: $AITM_DIR)"
|
||||
fi
|
||||
echo ""
|
||||
echo "Port overrides (set before running this script):"
|
||||
echo " GITGRAM_BACKEND_PORT=3000 (default)"
|
||||
echo " GITGRAM_WEB_PORT=3002 (default)"
|
||||
echo " AITM_API_PORT=3001 (default)"
|
||||
fi
|
||||
423
scripts/validate-openapi-routes.ts
Normal file
423
scripts/validate-openapi-routes.ts
Normal file
@ -0,0 +1,423 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* OpenAPI Route Coverage Validator
|
||||
*
|
||||
* Parses Express route registrations from source code, compares them against
|
||||
* the OpenAPI spec, and reports coverage gaps.
|
||||
*
|
||||
* Usage:
|
||||
* npx tsx scripts/validate-openapi-routes.ts
|
||||
*
|
||||
* Exit codes:
|
||||
* 0 - All routes covered
|
||||
* 1 - Undocumented routes found
|
||||
*/
|
||||
|
||||
import * as fs from "fs";
|
||||
import * as path from "path";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Types
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
interface RouteInfo {
|
||||
method: string;
|
||||
path: string;
|
||||
file: string;
|
||||
}
|
||||
|
||||
interface SpecRoute {
|
||||
method: string;
|
||||
path: string;
|
||||
}
|
||||
|
||||
interface ProductConfig {
|
||||
name: string;
|
||||
routeDir: string;
|
||||
entryFile: string;
|
||||
specFile: string;
|
||||
basePrefix: string;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Route extraction from source code
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Extract route registrations from an Express router file.
|
||||
* Matches patterns like: router.get("/path", ...) or router.post("/path", ...)
|
||||
*/
|
||||
function extractRoutesFromFile(filePath: string): Array<{ method: string; subPath: string }> {
|
||||
const routes: Array<{ method: string; subPath: string }> = [];
|
||||
|
||||
if (!fs.existsSync(filePath)) {
|
||||
return routes;
|
||||
}
|
||||
|
||||
const content = fs.readFileSync(filePath, "utf-8");
|
||||
|
||||
// Match router.METHOD("path" or router.METHOD( followed by newline + "path"
|
||||
const routeRegex = /router\.(get|post|put|patch|delete)\(\s*["'`]([^"'`]+)["'`]/gi;
|
||||
|
||||
let match: RegExpExecArray | null;
|
||||
while ((match = routeRegex.exec(content)) !== null) {
|
||||
const method = match[1].toUpperCase();
|
||||
const subPath = match[2];
|
||||
routes.push({ method, subPath });
|
||||
}
|
||||
|
||||
// Also match multiline patterns like router.get(\n "/path",
|
||||
const multilineRegex = /router\.(get|post|put|patch|delete)\(\s*\n\s*["'`]([^"'`]+)["'`]/gi;
|
||||
while ((match = multilineRegex.exec(content)) !== null) {
|
||||
const method = match[1].toUpperCase();
|
||||
const subPath = match[2];
|
||||
// Avoid duplicates
|
||||
if (!routes.some((r) => r.method === method && r.subPath === subPath)) {
|
||||
routes.push({ method, subPath });
|
||||
}
|
||||
}
|
||||
|
||||
return routes;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse the entry file (index.ts) to find route mount points.
|
||||
* Matches patterns like: app.use("/v1/sync", syncRoutes);
|
||||
*/
|
||||
function extractMountPoints(entryFile: string): Map<string, string> {
|
||||
const mounts = new Map<string, string>();
|
||||
|
||||
if (!fs.existsSync(entryFile)) {
|
||||
return mounts;
|
||||
}
|
||||
|
||||
const content = fs.readFileSync(entryFile, "utf-8");
|
||||
|
||||
// Match import statements to map variable names to file names
|
||||
const importMap = new Map<string, string>();
|
||||
const importRegex = /import\s+(\w+)\s+from\s+["'`]\.\/routes\/([^"'`]+)["'`]/g;
|
||||
let match: RegExpExecArray | null;
|
||||
while ((match = importRegex.exec(content)) !== null) {
|
||||
importMap.set(match[1], match[2].replace(/\.js$/, ""));
|
||||
}
|
||||
|
||||
// Also handle CommonJS requires
|
||||
const requireRegex = /(?:const|let|var)\s+(\w+)\s*=\s*require\(\s*["'`]\.\/routes\/([^"'`]+)["'`]\s*\)/g;
|
||||
while ((match = requireRegex.exec(content)) !== null) {
|
||||
importMap.set(match[1], match[2].replace(/\.js$/, ""));
|
||||
}
|
||||
|
||||
// Match app.use("/path", variableName)
|
||||
const useRegex = /app\.use\(\s*["'`]([^"'`]+)["'`]\s*,\s*(?:[^,)]*,\s*)*(\w+Routes?)\s*\)/g;
|
||||
while ((match = useRegex.exec(content)) !== null) {
|
||||
const mountPath = match[1];
|
||||
const varName = match[2];
|
||||
const routeFile = importMap.get(varName);
|
||||
if (routeFile) {
|
||||
// Use the first mount point for each route file (prefer v1 routes)
|
||||
if (!mounts.has(routeFile) || mountPath.startsWith("/v1") || mountPath.startsWith("/api/v1")) {
|
||||
mounts.set(routeFile, mountPath);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return mounts;
|
||||
}
|
||||
|
||||
/**
|
||||
* Build the full list of implemented routes for a product.
|
||||
*/
|
||||
function getImplementedRoutes(config: ProductConfig): RouteInfo[] {
|
||||
const routes: RouteInfo[] = [];
|
||||
const mounts = extractMountPoints(config.entryFile);
|
||||
|
||||
// Also handle inline routes defined directly in the entry file
|
||||
const entryContent = fs.existsSync(config.entryFile)
|
||||
? fs.readFileSync(config.entryFile, "utf-8")
|
||||
: "";
|
||||
|
||||
// Match app.get/post directly in entry file
|
||||
const inlineRegex = /app\.(get|post|put|patch|delete)\(\s*["'`]([^"'`]+)["'`]/gi;
|
||||
let inlineMatch: RegExpExecArray | null;
|
||||
while ((inlineMatch = inlineRegex.exec(entryContent)) !== null) {
|
||||
const method = inlineMatch[1].toUpperCase();
|
||||
const fullPath = inlineMatch[2];
|
||||
routes.push({ method, path: fullPath, file: path.basename(config.entryFile) });
|
||||
}
|
||||
|
||||
// Get route files
|
||||
if (!fs.existsSync(config.routeDir)) {
|
||||
console.error(`Route directory not found: ${config.routeDir}`);
|
||||
return routes;
|
||||
}
|
||||
|
||||
const routeFiles = fs.readdirSync(config.routeDir).filter((f) => f.endsWith(".ts"));
|
||||
|
||||
for (const file of routeFiles) {
|
||||
const filePath = path.join(config.routeDir, file);
|
||||
const routeName = file.replace(/\.ts$/, "");
|
||||
const mountPath = mounts.get(routeName);
|
||||
|
||||
if (!mountPath) {
|
||||
// Try to find mount via various naming conventions
|
||||
continue;
|
||||
}
|
||||
|
||||
const fileRoutes = extractRoutesFromFile(filePath);
|
||||
|
||||
for (const { method, subPath } of fileRoutes) {
|
||||
// Build full path
|
||||
let fullPath = mountPath;
|
||||
if (subPath === "/") {
|
||||
// Root of the mount
|
||||
} else {
|
||||
fullPath = mountPath + subPath;
|
||||
}
|
||||
|
||||
// Normalize: remove trailing slash, collapse double slashes
|
||||
fullPath = fullPath.replace(/\/+/g, "/").replace(/\/$/, "") || "/";
|
||||
|
||||
routes.push({ method, path: fullPath, file });
|
||||
}
|
||||
}
|
||||
|
||||
return routes;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// OpenAPI spec parsing
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Parse OpenAPI YAML spec to extract paths.
|
||||
* Simple YAML parser for our specific use case (no external deps).
|
||||
*/
|
||||
function parseOpenAPIRoutes(specFile: string): SpecRoute[] {
|
||||
if (!fs.existsSync(specFile)) {
|
||||
console.error(`OpenAPI spec not found: ${specFile}`);
|
||||
return [];
|
||||
}
|
||||
|
||||
const content = fs.readFileSync(specFile, "utf-8");
|
||||
const routes: SpecRoute[] = [];
|
||||
const lines = content.split("\n");
|
||||
|
||||
let currentPath = "";
|
||||
let inPaths = false;
|
||||
let pathIndent = -1;
|
||||
let methodIndent = -1;
|
||||
|
||||
for (const line of lines) {
|
||||
const trimmed = line.trimEnd();
|
||||
|
||||
// Detect paths: section
|
||||
if (/^paths:\s*$/.test(trimmed)) {
|
||||
inPaths = true;
|
||||
pathIndent = -1;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (!inPaths) continue;
|
||||
|
||||
// If we hit a top-level key that's not a path, end paths section
|
||||
if (/^\S/.test(line) && !line.startsWith(" ") && !line.startsWith("#")) {
|
||||
inPaths = false;
|
||||
continue;
|
||||
}
|
||||
|
||||
// Match path entries (indented with spaces)
|
||||
const pathMatch = trimmed.match(/^(\s+)(\/[^:]*)\s*:\s*$/);
|
||||
if (pathMatch) {
|
||||
const indent = pathMatch[1].length;
|
||||
if (pathIndent === -1 || indent <= pathIndent) {
|
||||
pathIndent = indent;
|
||||
currentPath = pathMatch[2].trim();
|
||||
methodIndent = -1;
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
// Match HTTP methods under a path
|
||||
if (currentPath) {
|
||||
const methodMatch = trimmed.match(/^(\s+)(get|post|put|patch|delete)\s*:\s*$/);
|
||||
if (methodMatch) {
|
||||
const indent = methodMatch[1].length;
|
||||
if (indent > pathIndent) {
|
||||
routes.push({
|
||||
method: methodMatch[2].toUpperCase(),
|
||||
path: currentPath,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return routes;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Normalization and comparison
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Normalize a route path for comparison.
|
||||
* Express :param becomes {param}, wildcards are handled, etc.
|
||||
*/
|
||||
function normalizePath(routePath: string): string {
|
||||
return routePath
|
||||
.replace(/:(\w+)/g, "{$1}") // :param -> {param}
|
||||
.replace(/\/\*/g, "/{path}") // wildcard
|
||||
.replace(/\/+/g, "/") // collapse slashes
|
||||
.replace(/\/$/, "") // remove trailing slash
|
||||
.toLowerCase();
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a route key for comparison (METHOD:normalizedPath)
|
||||
*/
|
||||
function routeKey(method: string, routePath: string): string {
|
||||
return `${method}:${normalizePath(routePath)}`;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Report generation
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
function printTable(title: string, rows: Array<{ method: string; path: string; detail?: string }>) {
|
||||
if (rows.length === 0) return;
|
||||
|
||||
console.log(`\n${"=".repeat(80)}`);
|
||||
console.log(` ${title}`);
|
||||
console.log(`${"=".repeat(80)}`);
|
||||
console.log(` ${"Method".padEnd(10)} ${"Path".padEnd(55)} ${rows[0].detail ? "Detail" : ""}`);
|
||||
console.log(` ${"-".repeat(10)} ${"-".repeat(55)} ${rows[0].detail ? "-".repeat(10) : ""}`);
|
||||
|
||||
for (const row of rows) {
|
||||
console.log(` ${row.method.padEnd(10)} ${row.path.padEnd(55)} ${row.detail || ""}`);
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Main
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
function validateProduct(config: ProductConfig): { undocumented: number; stale: number; covered: number } {
|
||||
console.log(`\n${"#".repeat(80)}`);
|
||||
console.log(` Validating: ${config.name}`);
|
||||
console.log(`${"#".repeat(80)}`);
|
||||
|
||||
// Get implemented routes
|
||||
const implemented = getImplementedRoutes(config);
|
||||
console.log(` Found ${implemented.length} implemented routes`);
|
||||
|
||||
// Get spec routes
|
||||
const specRoutes = parseOpenAPIRoutes(config.specFile);
|
||||
console.log(` Found ${specRoutes.length} routes in OpenAPI spec`);
|
||||
|
||||
// Build lookup sets
|
||||
const implKeys = new Set(implemented.map((r) => routeKey(r.method, r.path)));
|
||||
const specKeys = new Set(specRoutes.map((r) => routeKey(r.method, r.path)));
|
||||
|
||||
// Find undocumented routes (in code but not spec)
|
||||
const undocumented = implemented.filter((r) => !specKeys.has(routeKey(r.method, r.path)));
|
||||
|
||||
// Find stale routes (in spec but not code)
|
||||
const stale = specRoutes.filter((r) => !implKeys.has(routeKey(r.method, r.path)));
|
||||
|
||||
// Find covered routes (in both)
|
||||
const covered = implemented.filter((r) => specKeys.has(routeKey(r.method, r.path)));
|
||||
|
||||
// Print results
|
||||
const total = new Set([...implKeys, ...specKeys]).size;
|
||||
const coveragePercent = total > 0 ? ((covered.length / total) * 100).toFixed(1) : "0";
|
||||
|
||||
console.log(`\n Coverage: ${covered.length}/${total} routes (${coveragePercent}%)`);
|
||||
|
||||
if (undocumented.length > 0) {
|
||||
printTable(
|
||||
`UNDOCUMENTED (${undocumented.length}) - Routes in code but NOT in spec`,
|
||||
undocumented.map((r) => ({ method: r.method, path: r.path, detail: r.file }))
|
||||
);
|
||||
} else {
|
||||
console.log(`\n All implemented routes are documented in the OpenAPI spec.`);
|
||||
}
|
||||
|
||||
if (stale.length > 0) {
|
||||
printTable(
|
||||
`STALE (${stale.length}) - Routes in spec but NOT in code`,
|
||||
stale.map((r) => ({ method: r.method, path: r.path }))
|
||||
);
|
||||
}
|
||||
|
||||
if (covered.length > 0) {
|
||||
printTable(
|
||||
`COVERED (${covered.length}) - Routes in both code and spec`,
|
||||
covered.map((r) => ({ method: r.method, path: r.path }))
|
||||
);
|
||||
}
|
||||
|
||||
return {
|
||||
undocumented: undocumented.length,
|
||||
stale: stale.length,
|
||||
covered: covered.length,
|
||||
};
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Product configurations
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const rootDir = path.resolve(__dirname, "..");
|
||||
|
||||
const products: ProductConfig[] = [
|
||||
{
|
||||
name: "AITimeMachine API",
|
||||
routeDir: path.join(rootDir, "aitimemachine/api-server/src/routes"),
|
||||
entryFile: path.join(rootDir, "aitimemachine/api-server/src/index.ts"),
|
||||
specFile: path.join(rootDir, "aitimemachine/api-server/docs/openapi.yaml"),
|
||||
basePrefix: "/v1",
|
||||
},
|
||||
{
|
||||
name: "Gitgram Backend",
|
||||
routeDir: path.join(rootDir, "gitgram/backend/src/routes"),
|
||||
entryFile: path.join(rootDir, "gitgram/backend/src/index.ts"),
|
||||
specFile: path.join(rootDir, "gitgram/backend/docs/openapi.yaml"),
|
||||
basePrefix: "/api/v1",
|
||||
},
|
||||
];
|
||||
|
||||
// Run validation
|
||||
let hasFailures = false;
|
||||
const results: Array<{ name: string; undocumented: number; stale: number; covered: number }> = [];
|
||||
|
||||
for (const product of products) {
|
||||
const result = validateProduct(product);
|
||||
results.push({ name: product.name, ...result });
|
||||
|
||||
if (result.undocumented > 0) {
|
||||
hasFailures = true;
|
||||
}
|
||||
}
|
||||
|
||||
// Print summary
|
||||
console.log(`\n${"=".repeat(80)}`);
|
||||
console.log(" SUMMARY");
|
||||
console.log(`${"=".repeat(80)}`);
|
||||
console.log(` ${"Product".padEnd(30)} ${"Covered".padEnd(12)} ${"Undocumented".padEnd(15)} ${"Stale".padEnd(10)}`);
|
||||
console.log(` ${"-".repeat(30)} ${"-".repeat(12)} ${"-".repeat(15)} ${"-".repeat(10)}`);
|
||||
|
||||
for (const r of results) {
|
||||
const total = r.covered + r.undocumented;
|
||||
const pct = total > 0 ? `(${((r.covered / total) * 100).toFixed(0)}%)` : "";
|
||||
console.log(
|
||||
` ${r.name.padEnd(30)} ${(r.covered + " " + pct).padEnd(12)} ${String(r.undocumented).padEnd(15)} ${String(r.stale).padEnd(10)}`
|
||||
);
|
||||
}
|
||||
|
||||
if (hasFailures) {
|
||||
console.log(`\n FAIL: Undocumented routes found. Update OpenAPI specs to achieve full coverage.\n`);
|
||||
process.exit(1);
|
||||
} else {
|
||||
console.log(`\n PASS: All implemented routes are documented.\n`);
|
||||
process.exit(0);
|
||||
}
|
||||
498
scripts/validate-openapi-spec.ts
Normal file
498
scripts/validate-openapi-spec.ts
Normal file
@ -0,0 +1,498 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* OpenAPI Spec Validator
|
||||
*
|
||||
* Validates OpenAPI YAML files for:
|
||||
* - Valid YAML syntax
|
||||
* - Required OpenAPI structure (info, paths, etc.)
|
||||
* - Common issues: missing descriptions, missing response codes
|
||||
* - Consistent naming conventions
|
||||
* - Resolvable schema references
|
||||
*
|
||||
* Usage:
|
||||
* npx tsx scripts/validate-openapi-spec.ts
|
||||
*
|
||||
* Exit codes:
|
||||
* 0 - All specs valid
|
||||
* 1 - Validation errors found
|
||||
*/
|
||||
|
||||
import * as fs from "fs";
|
||||
import * as path from "path";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Types
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
interface ValidationIssue {
|
||||
severity: "error" | "warning";
|
||||
path: string;
|
||||
message: string;
|
||||
}
|
||||
|
||||
interface ParsedSpec {
|
||||
openapi?: string;
|
||||
info?: { title?: string; version?: string; description?: string };
|
||||
paths?: Record<string, Record<string, any>>;
|
||||
components?: {
|
||||
schemas?: Record<string, any>;
|
||||
securitySchemes?: Record<string, any>;
|
||||
};
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Simple YAML parser (enough for OpenAPI validation without dependencies)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
function parseYAML(content: string): ParsedSpec {
|
||||
const result: any = {};
|
||||
const lines = content.split("\n");
|
||||
const stack: Array<{ indent: number; obj: any; key?: string }> = [
|
||||
{ indent: -1, obj: result },
|
||||
];
|
||||
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
const line = lines[i];
|
||||
|
||||
// Skip empty lines and comments
|
||||
if (/^\s*$/.test(line) || /^\s*#/.test(line)) continue;
|
||||
|
||||
const indentMatch = line.match(/^(\s*)/);
|
||||
const indent = indentMatch ? indentMatch[1].length : 0;
|
||||
const trimmed = line.trim();
|
||||
|
||||
// Pop stack until we find the right parent
|
||||
while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
|
||||
stack.pop();
|
||||
}
|
||||
|
||||
const parent = stack[stack.length - 1];
|
||||
|
||||
// Match key: value
|
||||
const kvMatch = trimmed.match(/^([^:]+?):\s*(.*)$/);
|
||||
if (kvMatch) {
|
||||
const key = kvMatch[1].trim().replace(/^["']|["']$/g, "");
|
||||
const value = kvMatch[2].trim();
|
||||
|
||||
if (value === "" || value === "|" || value === ">") {
|
||||
// Object or block scalar
|
||||
const newObj: any = {};
|
||||
if (Array.isArray(parent.obj)) {
|
||||
parent.obj.push({ [key]: newObj });
|
||||
} else {
|
||||
parent.obj[key] = newObj;
|
||||
}
|
||||
stack.push({ indent, obj: newObj, key });
|
||||
} else {
|
||||
// Simple value
|
||||
let parsedValue: any = value;
|
||||
if (value === "true") parsedValue = true;
|
||||
else if (value === "false") parsedValue = false;
|
||||
else if (/^\d+$/.test(value)) parsedValue = parseInt(value, 10);
|
||||
else parsedValue = value.replace(/^["']|["']$/g, "");
|
||||
|
||||
if (Array.isArray(parent.obj)) {
|
||||
parent.obj.push({ [key]: parsedValue });
|
||||
} else {
|
||||
parent.obj[key] = parsedValue;
|
||||
}
|
||||
}
|
||||
} else if (trimmed.startsWith("- ")) {
|
||||
// Array item
|
||||
const itemValue = trimmed.slice(2).trim();
|
||||
if (!Array.isArray(parent.obj)) {
|
||||
// Convert parent's value to array
|
||||
const parentParent = stack.length > 1 ? stack[stack.length - 2] : null;
|
||||
if (parentParent && parent.key) {
|
||||
const arr: any[] = [];
|
||||
parentParent.obj[parent.key] = arr;
|
||||
parent.obj = arr;
|
||||
}
|
||||
}
|
||||
if (Array.isArray(parent.obj)) {
|
||||
parent.obj.push(itemValue.replace(/^["']|["']$/g, ""));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Validation rules
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
function validateSpecStructure(content: string, filePath: string): ValidationIssue[] {
|
||||
const issues: ValidationIssue[] = [];
|
||||
const fileName = path.basename(filePath);
|
||||
|
||||
// Check YAML can be parsed without errors
|
||||
let spec: ParsedSpec;
|
||||
try {
|
||||
spec = parseYAML(content);
|
||||
} catch (err: any) {
|
||||
issues.push({
|
||||
severity: "error",
|
||||
path: fileName,
|
||||
message: `YAML parse error: ${err.message}`,
|
||||
});
|
||||
return issues;
|
||||
}
|
||||
|
||||
// Check required top-level fields
|
||||
if (!spec.openapi) {
|
||||
issues.push({
|
||||
severity: "error",
|
||||
path: `${fileName}/openapi`,
|
||||
message: "Missing required field: openapi (version string)",
|
||||
});
|
||||
} else if (!spec.openapi.toString().startsWith("3.")) {
|
||||
issues.push({
|
||||
severity: "warning",
|
||||
path: `${fileName}/openapi`,
|
||||
message: `OpenAPI version ${spec.openapi} may not be widely supported. Consider 3.0.x or 3.1.x`,
|
||||
});
|
||||
}
|
||||
|
||||
if (!spec.info) {
|
||||
issues.push({
|
||||
severity: "error",
|
||||
path: `${fileName}/info`,
|
||||
message: "Missing required field: info",
|
||||
});
|
||||
} else {
|
||||
if (!spec.info.title) {
|
||||
issues.push({
|
||||
severity: "error",
|
||||
path: `${fileName}/info/title`,
|
||||
message: "Missing required field: info.title",
|
||||
});
|
||||
}
|
||||
if (!spec.info.version) {
|
||||
issues.push({
|
||||
severity: "error",
|
||||
path: `${fileName}/info/version`,
|
||||
message: "Missing required field: info.version",
|
||||
});
|
||||
}
|
||||
if (!spec.info.description) {
|
||||
issues.push({
|
||||
severity: "warning",
|
||||
path: `${fileName}/info/description`,
|
||||
message: "Missing recommended field: info.description",
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
if (!spec.paths || Object.keys(spec.paths).length === 0) {
|
||||
issues.push({
|
||||
severity: "error",
|
||||
path: `${fileName}/paths`,
|
||||
message: "No paths defined in spec",
|
||||
});
|
||||
}
|
||||
|
||||
return issues;
|
||||
}
|
||||
|
||||
function validatePaths(content: string, filePath: string): ValidationIssue[] {
|
||||
const issues: ValidationIssue[] = [];
|
||||
const fileName = path.basename(filePath);
|
||||
const lines = content.split("\n");
|
||||
|
||||
let inPaths = false;
|
||||
let currentPath = "";
|
||||
let currentMethod = "";
|
||||
let pathIndent = -1;
|
||||
let hasResponses = false;
|
||||
let hasSummary = false;
|
||||
let hasOperationId = false;
|
||||
let methodStartLine = 0;
|
||||
|
||||
const operationIds = new Set<string>();
|
||||
const pathsFound = new Set<string>();
|
||||
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
const line = lines[i];
|
||||
const trimmed = line.trim();
|
||||
|
||||
if (/^paths:\s*$/.test(trimmed)) {
|
||||
inPaths = true;
|
||||
pathIndent = -1;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (!inPaths) continue;
|
||||
|
||||
// End of paths section
|
||||
if (/^\S/.test(line) && !line.startsWith(" ") && !line.startsWith("#") && trimmed !== "") {
|
||||
inPaths = false;
|
||||
continue;
|
||||
}
|
||||
|
||||
// Detect path entry
|
||||
const pathMatch = trimmed.match(/^(\/[^:]*)\s*:\s*$/);
|
||||
if (pathMatch && line.match(/^\s{2}\//)) {
|
||||
// Save previous method check
|
||||
if (currentMethod && !hasResponses) {
|
||||
issues.push({
|
||||
severity: "warning",
|
||||
path: `${fileName}#${currentPath}/${currentMethod}`,
|
||||
message: `Missing responses for ${currentMethod.toUpperCase()} ${currentPath}`,
|
||||
});
|
||||
}
|
||||
|
||||
currentPath = pathMatch[1].trim();
|
||||
currentMethod = "";
|
||||
hasResponses = false;
|
||||
hasSummary = false;
|
||||
hasOperationId = false;
|
||||
|
||||
if (pathsFound.has(currentPath)) {
|
||||
issues.push({
|
||||
severity: "error",
|
||||
path: `${fileName}#${currentPath}`,
|
||||
message: `Duplicate path: ${currentPath}`,
|
||||
});
|
||||
}
|
||||
pathsFound.add(currentPath);
|
||||
|
||||
// Check path naming convention
|
||||
if (/[A-Z]/.test(currentPath) && !currentPath.includes("{")) {
|
||||
issues.push({
|
||||
severity: "warning",
|
||||
path: `${fileName}#${currentPath}`,
|
||||
message: `Path contains uppercase characters. Use lowercase with hyphens for consistency.`,
|
||||
});
|
||||
}
|
||||
|
||||
continue;
|
||||
}
|
||||
|
||||
// Detect HTTP method
|
||||
const methodMatch = trimmed.match(/^(get|post|put|patch|delete)\s*:\s*$/);
|
||||
if (methodMatch && currentPath) {
|
||||
// Save previous method check
|
||||
if (currentMethod && !hasResponses) {
|
||||
issues.push({
|
||||
severity: "warning",
|
||||
path: `${fileName}#${currentPath}/${currentMethod}`,
|
||||
message: `Missing responses for ${currentMethod.toUpperCase()} ${currentPath}`,
|
||||
});
|
||||
}
|
||||
|
||||
currentMethod = methodMatch[1];
|
||||
methodStartLine = i;
|
||||
hasResponses = false;
|
||||
hasSummary = false;
|
||||
hasOperationId = false;
|
||||
continue;
|
||||
}
|
||||
|
||||
// Check for summary
|
||||
if (currentMethod && trimmed.startsWith("summary:")) {
|
||||
hasSummary = true;
|
||||
const summary = trimmed.replace(/^summary:\s*/, "").replace(/^["']|["']$/g, "");
|
||||
if (summary.length === 0) {
|
||||
issues.push({
|
||||
severity: "warning",
|
||||
path: `${fileName}#${currentPath}/${currentMethod}`,
|
||||
message: `Empty summary for ${currentMethod.toUpperCase()} ${currentPath}`,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Check for operationId
|
||||
if (currentMethod && trimmed.startsWith("operationId:")) {
|
||||
hasOperationId = true;
|
||||
const opId = trimmed.replace(/^operationId:\s*/, "").replace(/^["']|["']$/g, "");
|
||||
if (operationIds.has(opId)) {
|
||||
issues.push({
|
||||
severity: "error",
|
||||
path: `${fileName}#${currentPath}/${currentMethod}`,
|
||||
message: `Duplicate operationId: ${opId}`,
|
||||
});
|
||||
}
|
||||
operationIds.add(opId);
|
||||
}
|
||||
|
||||
// Check for responses
|
||||
if (currentMethod && trimmed === "responses:") {
|
||||
hasResponses = true;
|
||||
}
|
||||
}
|
||||
|
||||
// Check last method
|
||||
if (currentMethod && !hasResponses) {
|
||||
issues.push({
|
||||
severity: "warning",
|
||||
path: `${fileName}#${currentPath}/${currentMethod}`,
|
||||
message: `Missing responses for ${currentMethod.toUpperCase()} ${currentPath}`,
|
||||
});
|
||||
}
|
||||
|
||||
return issues;
|
||||
}
|
||||
|
||||
function validateSchemaRefs(content: string, filePath: string): ValidationIssue[] {
|
||||
const issues: ValidationIssue[] = [];
|
||||
const fileName = path.basename(filePath);
|
||||
|
||||
// Find all $ref references
|
||||
const refRegex = /\$ref:\s*["']?#\/components\/schemas\/(\w+)["']?/g;
|
||||
let match: RegExpExecArray | null;
|
||||
const referencedSchemas = new Set<string>();
|
||||
|
||||
while ((match = refRegex.exec(content)) !== null) {
|
||||
referencedSchemas.add(match[1]);
|
||||
}
|
||||
|
||||
// Find all defined schemas
|
||||
const definedSchemas = new Set<string>();
|
||||
const schemaDefRegex = /^\s{4}(\w+):\s*$/gm;
|
||||
let inComponents = false;
|
||||
let inSchemas = false;
|
||||
|
||||
const lines = content.split("\n");
|
||||
for (const line of lines) {
|
||||
const trimmed = line.trim();
|
||||
if (trimmed === "components:") {
|
||||
inComponents = true;
|
||||
continue;
|
||||
}
|
||||
if (inComponents && trimmed === "schemas:") {
|
||||
inSchemas = true;
|
||||
continue;
|
||||
}
|
||||
if (inSchemas && /^\s{4}\w+:/.test(line)) {
|
||||
const schemaName = line.trim().replace(/:.*$/, "");
|
||||
definedSchemas.add(schemaName);
|
||||
}
|
||||
// End of schemas section
|
||||
if (inSchemas && /^\s{2}\w+:/.test(line) && !line.trim().startsWith("-")) {
|
||||
if (!line.match(/^\s{4}/)) {
|
||||
inSchemas = false;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Check for unresolvable references
|
||||
for (const ref of referencedSchemas) {
|
||||
if (!definedSchemas.has(ref)) {
|
||||
issues.push({
|
||||
severity: "error",
|
||||
path: `${fileName}/components/schemas/${ref}`,
|
||||
message: `Unresolvable schema reference: #/components/schemas/${ref}`,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Check for unused schemas (warning only)
|
||||
for (const schema of definedSchemas) {
|
||||
if (!referencedSchemas.has(schema)) {
|
||||
issues.push({
|
||||
severity: "warning",
|
||||
path: `${fileName}/components/schemas/${schema}`,
|
||||
message: `Schema "${schema}" is defined but never referenced`,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return issues;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Main
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
interface SpecConfig {
|
||||
name: string;
|
||||
file: string;
|
||||
}
|
||||
|
||||
const rootDir = path.resolve(__dirname, "..");
|
||||
|
||||
const specs: SpecConfig[] = [
|
||||
{
|
||||
name: "AITimeMachine API",
|
||||
file: path.join(rootDir, "aitimemachine/api-server/docs/openapi.yaml"),
|
||||
},
|
||||
{
|
||||
name: "Gitgram Backend",
|
||||
file: path.join(rootDir, "gitgram/backend/docs/openapi.yaml"),
|
||||
},
|
||||
];
|
||||
|
||||
let totalErrors = 0;
|
||||
let totalWarnings = 0;
|
||||
|
||||
for (const spec of specs) {
|
||||
console.log(`\n${"=".repeat(80)}`);
|
||||
console.log(` Validating: ${spec.name}`);
|
||||
console.log(` File: ${spec.file}`);
|
||||
console.log(`${"=".repeat(80)}`);
|
||||
|
||||
if (!fs.existsSync(spec.file)) {
|
||||
console.log(` ERROR: File not found: ${spec.file}`);
|
||||
totalErrors++;
|
||||
continue;
|
||||
}
|
||||
|
||||
const content = fs.readFileSync(spec.file, "utf-8");
|
||||
|
||||
// Run all validation checks
|
||||
const allIssues: ValidationIssue[] = [
|
||||
...validateSpecStructure(content, spec.file),
|
||||
...validatePaths(content, spec.file),
|
||||
...validateSchemaRefs(content, spec.file),
|
||||
];
|
||||
|
||||
const errors = allIssues.filter((i) => i.severity === "error");
|
||||
const warnings = allIssues.filter((i) => i.severity === "warning");
|
||||
|
||||
totalErrors += errors.length;
|
||||
totalWarnings += warnings.length;
|
||||
|
||||
if (errors.length > 0) {
|
||||
console.log(`\n ERRORS (${errors.length}):`);
|
||||
for (const issue of errors) {
|
||||
console.log(` [ERROR] ${issue.path}`);
|
||||
console.log(` ${issue.message}`);
|
||||
}
|
||||
}
|
||||
|
||||
if (warnings.length > 0) {
|
||||
console.log(`\n WARNINGS (${warnings.length}):`);
|
||||
for (const issue of warnings) {
|
||||
console.log(` [WARN] ${issue.path}`);
|
||||
console.log(` ${issue.message}`);
|
||||
}
|
||||
}
|
||||
|
||||
if (errors.length === 0 && warnings.length === 0) {
|
||||
console.log(`\n All checks passed.`);
|
||||
}
|
||||
|
||||
// Count paths and methods
|
||||
const pathRegex = /^\s{2}\/[^:]+:\s*$/gm;
|
||||
const methodRegex = /^\s{4}(get|post|put|patch|delete):\s*$/gm;
|
||||
const pathCount = (content.match(pathRegex) || []).length;
|
||||
const methodCount = (content.match(methodRegex) || []).length;
|
||||
|
||||
console.log(`\n Stats: ${pathCount} paths, ${methodCount} operations`);
|
||||
}
|
||||
|
||||
// Summary
|
||||
console.log(`\n${"=".repeat(80)}`);
|
||||
console.log(" VALIDATION SUMMARY");
|
||||
console.log(`${"=".repeat(80)}`);
|
||||
console.log(` Errors: ${totalErrors}`);
|
||||
console.log(` Warnings: ${totalWarnings}`);
|
||||
|
||||
if (totalErrors > 0) {
|
||||
console.log(`\n FAIL: ${totalErrors} error(s) found. Fix errors before merging.\n`);
|
||||
process.exit(1);
|
||||
} else {
|
||||
console.log(`\n PASS: All OpenAPI specs are structurally valid.\n`);
|
||||
process.exit(0);
|
||||
}
|
||||
382
scripts/validate-prod-secrets.sh
Executable file
382
scripts/validate-prod-secrets.sh
Executable file
@ -0,0 +1,382 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
TARGET_ENV="${1:-production}"
|
||||
if [[ "${TARGET_ENV}" != "production" && "${TARGET_ENV}" != "staging" && "${TARGET_ENV}" != "local" ]]; then
|
||||
echo "Usage: $0 [production|staging|local] [core|full]" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
VALIDATION_PROFILE="${2:-full}"
|
||||
if [[ "${VALIDATION_PROFILE}" != "core" && "${VALIDATION_PROFILE}" != "full" ]]; then
|
||||
echo "Usage: $0 [production|staging|local] [core|full]" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
|
||||
resolve_env_file() {
|
||||
local base="$1"
|
||||
local env_name="$2"
|
||||
local candidate="${base}.${env_name}"
|
||||
|
||||
if [[ -f "${candidate}" ]]; then
|
||||
printf '%s' "${candidate}"
|
||||
return 0
|
||||
fi
|
||||
|
||||
printf '%s' "${base}"
|
||||
}
|
||||
|
||||
MISSING=()
|
||||
INVALID=()
|
||||
|
||||
if [[ "${TARGET_ENV}" == "local" ]]; then
|
||||
AITM_ENV_FILE="${ROOT_DIR}/aitimemachine/api-server/.env"
|
||||
if [[ -f "${AITM_ENV_FILE}" ]]; then
|
||||
set -a
|
||||
# shellcheck source=/dev/null
|
||||
source "${AITM_ENV_FILE}"
|
||||
set +a
|
||||
fi
|
||||
fi
|
||||
|
||||
load_prefixed_env_file() {
|
||||
local product_prefix="$1"
|
||||
local file="$2"
|
||||
|
||||
if [[ ! -f "${file}" ]]; then
|
||||
return 0
|
||||
fi
|
||||
|
||||
while IFS='=' read -r key _; do
|
||||
if [[ ! "${key}" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
|
||||
continue
|
||||
fi
|
||||
|
||||
local prefixed="${product_prefix}_${key}"
|
||||
if [[ -n "${!prefixed:-}" ]]; then
|
||||
continue
|
||||
fi
|
||||
|
||||
local value
|
||||
value="$(
|
||||
bash -c '
|
||||
set -a
|
||||
source "$1"
|
||||
printf "%s" "${!2}"
|
||||
' _ "${file}" "${key}"
|
||||
)"
|
||||
|
||||
export "${prefixed}=${value}"
|
||||
done < <(grep -E '^[A-Za-z_][A-Za-z0-9_]*=' "${file}" || true)
|
||||
}
|
||||
|
||||
if [[ "${TARGET_ENV}" != "local" ]]; then
|
||||
GITGRAM_ENV_FILE="$(resolve_env_file "${ROOT_DIR}/.env.gitgram" "${TARGET_ENV}")"
|
||||
GITGRAM_WEB_ENV_FILE="$(resolve_env_file "${ROOT_DIR}/.env.gitgram-web" "${TARGET_ENV}")"
|
||||
AITM_API_ENV_FILE="$(resolve_env_file "${ROOT_DIR}/.env.aitm-api" "${TARGET_ENV}")"
|
||||
AITM_WEBSITE_ENV_FILE="$(resolve_env_file "${ROOT_DIR}/.env.aitm-website" "${TARGET_ENV}")"
|
||||
|
||||
load_prefixed_env_file "GITGRAM" "${GITGRAM_ENV_FILE}"
|
||||
load_prefixed_env_file "GITGRAM" "${GITGRAM_WEB_ENV_FILE}"
|
||||
load_prefixed_env_file "AITM" "${AITM_API_ENV_FILE}"
|
||||
load_prefixed_env_file "AITM" "${AITM_WEBSITE_ENV_FILE}"
|
||||
fi
|
||||
|
||||
add_missing() {
|
||||
MISSING+=("$1")
|
||||
}
|
||||
|
||||
add_invalid() {
|
||||
INVALID+=("$1")
|
||||
}
|
||||
|
||||
resolve_value() {
|
||||
local product_prefix="$1"
|
||||
local key="$2"
|
||||
local prefixed="${product_prefix}_${key}"
|
||||
|
||||
if [[ -n "${!prefixed:-}" ]]; then
|
||||
printf '%s' "${!prefixed}"
|
||||
return 0
|
||||
fi
|
||||
|
||||
if [[ -n "${!key:-}" ]]; then
|
||||
printf '%s' "${!key}"
|
||||
return 0
|
||||
fi
|
||||
|
||||
printf ''
|
||||
}
|
||||
|
||||
validate_not_placeholder() {
|
||||
local label="$1"
|
||||
local value="$2"
|
||||
local lowered
|
||||
lowered="$(printf '%s' "${value}" | tr '[:upper:]' '[:lower:]')"
|
||||
|
||||
local patterns=(
|
||||
"change_me"
|
||||
"replace-with"
|
||||
"your_"
|
||||
"your-"
|
||||
"example"
|
||||
"placeholder"
|
||||
"xxx"
|
||||
"todo"
|
||||
"user:password@"
|
||||
"project.neon.tech"
|
||||
)
|
||||
|
||||
for pattern in "${patterns[@]}"; do
|
||||
if [[ "${lowered}" == *"${pattern}"* ]]; then
|
||||
add_invalid "${label} looks like a placeholder value"
|
||||
return
|
||||
fi
|
||||
done
|
||||
}
|
||||
|
||||
assert_allowed_value() {
|
||||
local product_prefix="$1"
|
||||
local key="$2"
|
||||
shift 2
|
||||
local allowed=("$@")
|
||||
local label="${product_prefix}_${key}"
|
||||
local value
|
||||
value="$(resolve_value "${product_prefix}" "${key}")"
|
||||
|
||||
if [[ -z "${value}" ]]; then
|
||||
return 0
|
||||
fi
|
||||
|
||||
for candidate in "${allowed[@]}"; do
|
||||
if [[ "${value}" == "${candidate}" ]]; then
|
||||
return 0
|
||||
fi
|
||||
done
|
||||
|
||||
add_invalid "${label} must be one of: ${allowed[*]} (found ${value})"
|
||||
}
|
||||
|
||||
assert_required() {
|
||||
local product_prefix="$1"
|
||||
local key="$2"
|
||||
local label="${product_prefix}_${key}"
|
||||
local value
|
||||
value="$(resolve_value "${product_prefix}" "${key}")"
|
||||
|
||||
if [[ -z "${value}" ]]; then
|
||||
add_missing "${label} (or unprefixed ${key})"
|
||||
return
|
||||
fi
|
||||
|
||||
validate_not_placeholder "${label}" "${value}"
|
||||
}
|
||||
|
||||
assert_one_of() {
|
||||
local product_prefix="$1"
|
||||
local key_a="$2"
|
||||
local key_b="$3"
|
||||
local label_a="${product_prefix}_${key_a}"
|
||||
local label_b="${product_prefix}_${key_b}"
|
||||
local value_a value_b
|
||||
value_a="$(resolve_value "${product_prefix}" "${key_a}")"
|
||||
value_b="$(resolve_value "${product_prefix}" "${key_b}")"
|
||||
|
||||
if [[ -z "${value_a}" && -z "${value_b}" ]]; then
|
||||
add_missing "one of ${label_a} or ${label_b} (or unprefixed variants)"
|
||||
return
|
||||
fi
|
||||
|
||||
if [[ -n "${value_a}" ]]; then
|
||||
validate_not_placeholder "${label_a}" "${value_a}"
|
||||
fi
|
||||
if [[ -n "${value_b}" ]]; then
|
||||
validate_not_placeholder "${label_b}" "${value_b}"
|
||||
fi
|
||||
}
|
||||
|
||||
assert_example_has_keys() {
|
||||
local file="$1"
|
||||
shift
|
||||
local keys=("$@")
|
||||
local missing_local=()
|
||||
|
||||
for key in "${keys[@]}"; do
|
||||
if ! rg -q "^[[:space:]]*${key}=" "${file}"; then
|
||||
missing_local+=("${key}")
|
||||
fi
|
||||
done
|
||||
|
||||
if [[ "${#missing_local[@]}" -gt 0 ]]; then
|
||||
add_invalid "Missing keys in ${file}: ${missing_local[*]}"
|
||||
fi
|
||||
}
|
||||
|
||||
assert_pair_if_either_present() {
|
||||
local product_prefix="$1"
|
||||
local key_a="$2"
|
||||
local key_b="$3"
|
||||
local label_a="${product_prefix}_${key_a}"
|
||||
local label_b="${product_prefix}_${key_b}"
|
||||
local value_a value_b
|
||||
value_a="$(resolve_value "${product_prefix}" "${key_a}")"
|
||||
value_b="$(resolve_value "${product_prefix}" "${key_b}")"
|
||||
|
||||
if [[ -z "${value_a}" && -z "${value_b}" ]]; then
|
||||
return 0
|
||||
fi
|
||||
|
||||
if [[ -z "${value_a}" ]]; then
|
||||
add_missing "${label_a} (required when ${label_b} is set)"
|
||||
else
|
||||
validate_not_placeholder "${label_a}" "${value_a}"
|
||||
fi
|
||||
|
||||
if [[ -z "${value_b}" ]]; then
|
||||
add_missing "${label_b} (required when ${label_a} is set)"
|
||||
else
|
||||
validate_not_placeholder "${label_b}" "${value_b}"
|
||||
fi
|
||||
}
|
||||
|
||||
if [[ "${TARGET_ENV}" == "local" ]]; then
|
||||
# Minimal keys to run AITM API in local development without paid integrations.
|
||||
assert_required "AITM" "DATABASE_URL"
|
||||
else
|
||||
# Gitgram backend + web core deploy requirements
|
||||
assert_required "GITGRAM" "DATABASE_URL"
|
||||
assert_required "GITGRAM" "REDIS_URL"
|
||||
assert_required "GITGRAM" "JWT_SECRET"
|
||||
assert_required "GITGRAM" "JWT_REFRESH_SECRET"
|
||||
assert_required "GITGRAM" "FRONTEND_URL"
|
||||
assert_required "GITGRAM" "CORS_ORIGIN"
|
||||
assert_required "GITGRAM" "STORAGE_TYPE"
|
||||
assert_allowed_value "GITGRAM" "STORAGE_TYPE" "local" "s3"
|
||||
assert_required "GITGRAM" "NEXT_PUBLIC_API_URL"
|
||||
assert_one_of "GITGRAM" "NEXT_PUBLIC_WS_URL" "NEXT_PUBLIC_SOCKET_URL"
|
||||
|
||||
storage_type="$(resolve_value "GITGRAM" "STORAGE_TYPE")"
|
||||
if [[ "${storage_type}" == "s3" ]]; then
|
||||
assert_required "GITGRAM" "AWS_ACCESS_KEY_ID"
|
||||
assert_required "GITGRAM" "AWS_SECRET_ACCESS_KEY"
|
||||
assert_required "GITGRAM" "AWS_S3_BUCKET"
|
||||
assert_required "GITGRAM" "AWS_REGION"
|
||||
fi
|
||||
|
||||
# AITM API core deploy requirements
|
||||
assert_required "AITM" "DATABASE_URL"
|
||||
assert_required "AITM" "INTERNAL_SECRET"
|
||||
assert_required "AITM" "CORS_ORIGIN"
|
||||
assert_required "AITM" "WEBSITE_URL"
|
||||
|
||||
# Optional AITM website/self-hosted dashboard vars: validate pairs if present.
|
||||
assert_pair_if_either_present "AITM" "CLERK_SECRET_KEY" "NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY"
|
||||
assert_pair_if_either_present "AITM" "API_URL" "NEXT_PUBLIC_API_URL"
|
||||
assert_pair_if_either_present "AITM" "NEXT_PUBLIC_POLAR_PRO_PRODUCT_ID" "NEXT_PUBLIC_POLAR_TEAM_PRODUCT_ID"
|
||||
|
||||
if [[ "${VALIDATION_PROFILE}" == "full" ]]; then
|
||||
# Third-party integrations needed for a full launch contract.
|
||||
assert_required "GITGRAM" "GITHUB_CLIENT_ID"
|
||||
assert_required "GITGRAM" "GITHUB_CLIENT_SECRET"
|
||||
assert_required "GITGRAM" "NEXT_PUBLIC_GITHUB_CLIENT_ID"
|
||||
assert_required "GITGRAM" "POLAR_ACCESS_TOKEN"
|
||||
assert_required "GITGRAM" "POLAR_WEBHOOK_SECRET"
|
||||
assert_required "GITGRAM" "POLAR_PREMIUM_PRODUCT_ID"
|
||||
assert_required "GITGRAM" "POLAR_CREATOR_PRODUCT_ID"
|
||||
assert_required "GITGRAM" "POLAR_MODE"
|
||||
assert_allowed_value "GITGRAM" "POLAR_MODE" "sandbox" "production"
|
||||
assert_required "GITGRAM" "RESEND_API_KEY"
|
||||
assert_required "GITGRAM" "SENTRY_DSN"
|
||||
|
||||
assert_required "AITM" "POLAR_ACCESS_TOKEN"
|
||||
assert_required "AITM" "POLAR_MODE"
|
||||
assert_allowed_value "AITM" "POLAR_MODE" "sandbox" "production"
|
||||
assert_required "AITM" "POLAR_WEBHOOK_SECRET"
|
||||
assert_required "AITM" "POLAR_PRO_PRODUCT_ID"
|
||||
assert_required "AITM" "POLAR_TEAM_PRODUCT_ID"
|
||||
assert_required "AITM" "RESEND_API_KEY"
|
||||
assert_required "AITM" "SENTRY_DSN"
|
||||
else
|
||||
# Core mode still validates provider mode if it is already set.
|
||||
assert_allowed_value "GITGRAM" "POLAR_MODE" "sandbox" "production"
|
||||
assert_allowed_value "AITM" "POLAR_MODE" "sandbox" "production"
|
||||
fi
|
||||
fi
|
||||
|
||||
if [[ "${TARGET_ENV}" == "production" ]]; then
|
||||
polar_mode="$(resolve_value "GITGRAM" "POLAR_MODE")"
|
||||
if [[ -n "${polar_mode}" && "${polar_mode}" != "production" ]]; then
|
||||
add_invalid "GITGRAM_POLAR_MODE must be production for a production launch"
|
||||
fi
|
||||
|
||||
aitm_polar_mode="$(resolve_value "AITM" "POLAR_MODE")"
|
||||
if [[ -n "${aitm_polar_mode}" && "${aitm_polar_mode}" != "production" ]]; then
|
||||
add_invalid "AITM_POLAR_MODE must be production for a production launch"
|
||||
fi
|
||||
|
||||
clerk_pub="$(resolve_value "AITM" "NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY")"
|
||||
if [[ -n "${clerk_pub}" && "${clerk_pub}" == pk_test_* ]]; then
|
||||
add_invalid "AITM_NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY must be live key in production (found test key pattern)"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Keep env templates aligned with required contract keys.
|
||||
assert_example_has_keys "${ROOT_DIR}/gitgram/backend/.env.example" \
|
||||
DATABASE_URL JWT_SECRET JWT_REFRESH_SECRET FRONTEND_URL REDIS_URL \
|
||||
GITHUB_CLIENT_ID GITHUB_CLIENT_SECRET GOOGLE_CLIENT_ID GOOGLE_CLIENT_SECRET \
|
||||
POLAR_ACCESS_TOKEN POLAR_WEBHOOK_SECRET POLAR_PREMIUM_PRODUCT_ID POLAR_CREATOR_PRODUCT_ID \
|
||||
RESEND_API_KEY SENTRY_DSN STORAGE_TYPE
|
||||
|
||||
assert_example_has_keys "${ROOT_DIR}/aitimemachine/api-server/.env.example" \
|
||||
DATABASE_URL INTERNAL_SECRET CORS_ORIGIN WEBSITE_URL \
|
||||
POLAR_ACCESS_TOKEN POLAR_MODE POLAR_WEBHOOK_SECRET POLAR_PRO_PRODUCT_ID POLAR_TEAM_PRODUCT_ID
|
||||
|
||||
assert_example_has_keys "${ROOT_DIR}/gitgram/web/.env.example" \
|
||||
NEXT_PUBLIC_API_URL NEXT_PUBLIC_WS_URL NEXT_PUBLIC_GITHUB_CLIENT_ID
|
||||
|
||||
assert_example_has_keys "${ROOT_DIR}/aitimemachine/website/.env.example" \
|
||||
CLERK_SECRET_KEY NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY NEXT_PUBLIC_API_URL API_URL INTERNAL_SECRET \
|
||||
POLAR_ACCESS_TOKEN POLAR_MODE NEXT_PUBLIC_POLAR_PRO_PRODUCT_ID NEXT_PUBLIC_POLAR_TEAM_PRODUCT_ID
|
||||
|
||||
assert_example_has_keys "${ROOT_DIR}/.env.gitgram.example" \
|
||||
DATABASE_URL REDIS_URL JWT_SECRET JWT_REFRESH_SECRET FRONTEND_URL CORS_ORIGIN \
|
||||
GITHUB_CLIENT_ID GITHUB_CLIENT_SECRET POLAR_ACCESS_TOKEN POLAR_WEBHOOK_SECRET \
|
||||
POLAR_PREMIUM_PRODUCT_ID POLAR_CREATOR_PRODUCT_ID POLAR_MODE STORAGE_TYPE
|
||||
|
||||
assert_example_has_keys "${ROOT_DIR}/.env.gitgram-web.example" \
|
||||
NEXT_PUBLIC_API_URL NEXT_PUBLIC_WS_URL NEXT_PUBLIC_GITHUB_CLIENT_ID
|
||||
|
||||
assert_example_has_keys "${ROOT_DIR}/.env.aitm-api.example" \
|
||||
DATABASE_URL INTERNAL_SECRET CORS_ORIGIN WEBSITE_URL POLAR_ACCESS_TOKEN POLAR_MODE POLAR_WEBHOOK_SECRET \
|
||||
POLAR_PRO_PRODUCT_ID POLAR_TEAM_PRODUCT_ID
|
||||
|
||||
assert_example_has_keys "${ROOT_DIR}/.env.aitm-website.example" \
|
||||
NEXT_PUBLIC_API_URL API_URL INTERNAL_SECRET NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY CLERK_SECRET_KEY \
|
||||
POLAR_ACCESS_TOKEN POLAR_MODE NEXT_PUBLIC_POLAR_PRO_PRODUCT_ID NEXT_PUBLIC_POLAR_TEAM_PRODUCT_ID
|
||||
|
||||
if [[ "${#MISSING[@]}" -eq 0 && "${#INVALID[@]}" -eq 0 ]]; then
|
||||
echo "Secrets validation passed for ${TARGET_ENV} (${VALIDATION_PROFILE})."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
echo "Secrets validation failed for ${TARGET_ENV} (${VALIDATION_PROFILE})."
|
||||
|
||||
if [[ "${#MISSING[@]}" -gt 0 ]]; then
|
||||
echo ""
|
||||
echo "Missing variables:"
|
||||
for item in "${MISSING[@]}"; do
|
||||
echo " - ${item}"
|
||||
done
|
||||
fi
|
||||
|
||||
if [[ "${#INVALID[@]}" -gt 0 ]]; then
|
||||
echo ""
|
||||
echo "Invalid values/config:"
|
||||
for item in "${INVALID[@]}"; do
|
||||
echo " - ${item}"
|
||||
done
|
||||
fi
|
||||
|
||||
exit 1
|
||||
463
scripts/verify-gitgram-db.ts
Normal file
463
scripts/verify-gitgram-db.ts
Normal file
@ -0,0 +1,463 @@
|
||||
#!/usr/bin/env npx tsx
|
||||
/**
|
||||
* Gitgram PostgreSQL Production Verification Script
|
||||
*
|
||||
* Connects to the gitgram backend PostgreSQL database using DATABASE_URL,
|
||||
* then runs:
|
||||
* 1. Connection probe
|
||||
* 2. Latency probe
|
||||
* 3. Prisma migration status check (via prisma CLI)
|
||||
* 4. Core table existence checks (Account, User, Post, etc.)
|
||||
* 5. Schema drift detection (expected columns vs actual)
|
||||
*
|
||||
* Uses @prisma/client for database access (must run prisma generate first).
|
||||
*
|
||||
* Exit codes:
|
||||
* 0 - All checks passed
|
||||
* 1 - One or more checks failed
|
||||
* 2 - Configuration error (missing DATABASE_URL)
|
||||
*
|
||||
* Usage:
|
||||
* DATABASE_URL=postgres://... npx tsx scripts/verify-gitgram-db.ts
|
||||
* DATABASE_URL=postgres://... npx tsx scripts/verify-gitgram-db.ts --json
|
||||
*/
|
||||
|
||||
import { execSync } from "child_process";
|
||||
|
||||
// ============================================================================
|
||||
// Configuration
|
||||
// ============================================================================
|
||||
|
||||
const DATABASE_URL = process.env.DATABASE_URL;
|
||||
const OUTPUT_JSON = process.argv.includes("--json");
|
||||
|
||||
if (!DATABASE_URL) {
|
||||
console.error("ERROR: DATABASE_URL environment variable is required");
|
||||
process.exit(2);
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Expected Prisma models -> table names and key columns
|
||||
// Derived from gitgram/backend/prisma/schema.prisma
|
||||
// ============================================================================
|
||||
|
||||
const EXPECTED_TABLES: Record<string, { columns: string[] }> = {
|
||||
Account: {
|
||||
columns: [
|
||||
"id", "type", "username", "displayName", "avatar", "bio", "verified",
|
||||
"createdAt", "updatedAt", "userId", "repositoryId", "organizationId",
|
||||
],
|
||||
},
|
||||
User: {
|
||||
columns: [
|
||||
"id", "email", "password", "username", "displayName", "avatar",
|
||||
"bio", "role", "githubId", "githubUsername", "emailVerified",
|
||||
"verified", "isPrivate", "isBanned", "createdAt",
|
||||
],
|
||||
},
|
||||
Repository: {
|
||||
columns: ["id", "name", "fullName", "description", "language", "createdAt"],
|
||||
},
|
||||
Organization: {
|
||||
columns: ["id", "name", "description", "createdAt"],
|
||||
},
|
||||
Post: {
|
||||
columns: ["id", "type", "caption", "createdAt", "updatedAt", "accountId"],
|
||||
},
|
||||
Comment: {
|
||||
columns: ["id", "content", "createdAt", "updatedAt", "accountId", "postId"],
|
||||
},
|
||||
Like: {
|
||||
columns: ["id", "createdAt", "accountId", "postId"],
|
||||
},
|
||||
Follow: {
|
||||
columns: ["id", "createdAt", "followerId", "followingId"],
|
||||
},
|
||||
Story: {
|
||||
columns: ["id", "createdAt", "expiresAt", "accountId"],
|
||||
},
|
||||
Message: {
|
||||
columns: ["id", "content", "createdAt", "senderId", "receiverId"],
|
||||
},
|
||||
Notification: {
|
||||
columns: ["id", "type", "message", "read", "createdAt", "userId"],
|
||||
},
|
||||
};
|
||||
|
||||
// ============================================================================
|
||||
// Probe functions using PrismaClient.$queryRawUnsafe
|
||||
// ============================================================================
|
||||
|
||||
interface ProbeResult {
|
||||
name: string;
|
||||
status: "pass" | "fail" | "warn";
|
||||
message: string;
|
||||
duration_ms: number;
|
||||
details?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
// Dynamic import of PrismaClient to handle cases where it hasn't been generated
|
||||
let prisma: any = null;
|
||||
|
||||
async function initPrisma(): Promise<boolean> {
|
||||
try {
|
||||
const { PrismaClient } = await import("@prisma/client");
|
||||
prisma = new PrismaClient({ datasources: { db: { url: DATABASE_URL } } });
|
||||
return true;
|
||||
} catch (error) {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
async function disconnectPrisma(): Promise<void> {
|
||||
if (prisma) {
|
||||
await prisma.$disconnect();
|
||||
}
|
||||
}
|
||||
|
||||
async function probeConnection(): Promise<ProbeResult> {
|
||||
const start = Date.now();
|
||||
try {
|
||||
await prisma.$queryRawUnsafe("SELECT 1 AS ping");
|
||||
return {
|
||||
name: "connection",
|
||||
status: "pass",
|
||||
message: "Database connection successful",
|
||||
duration_ms: Date.now() - start,
|
||||
};
|
||||
} catch (error) {
|
||||
return {
|
||||
name: "connection",
|
||||
status: "fail",
|
||||
message: `Connection failed: ${error instanceof Error ? error.message : "unknown"}`,
|
||||
duration_ms: Date.now() - start,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
async function probeLatency(): Promise<ProbeResult> {
|
||||
const start = Date.now();
|
||||
try {
|
||||
await prisma.$queryRawUnsafe("SELECT now() AS server_time");
|
||||
const ms = Date.now() - start;
|
||||
const status = ms > 2000 ? "fail" : ms > 500 ? "warn" : "pass";
|
||||
return {
|
||||
name: "latency",
|
||||
status,
|
||||
message: `Query latency: ${ms}ms`,
|
||||
duration_ms: ms,
|
||||
};
|
||||
} catch (error) {
|
||||
return {
|
||||
name: "latency",
|
||||
status: "fail",
|
||||
message: `Latency probe failed: ${error instanceof Error ? error.message : "unknown"}`,
|
||||
duration_ms: Date.now() - start,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
async function probePrismaMigrations(): Promise<ProbeResult> {
|
||||
const start = Date.now();
|
||||
try {
|
||||
// Check if _prisma_migrations table exists
|
||||
const tableCheck: any[] = await prisma.$queryRawUnsafe(
|
||||
`SELECT EXISTS (
|
||||
SELECT FROM information_schema.tables
|
||||
WHERE table_schema = 'public' AND table_name = '_prisma_migrations'
|
||||
) AS "exists"`
|
||||
);
|
||||
|
||||
if (!tableCheck[0]?.exists) {
|
||||
return {
|
||||
name: "prisma_migrations",
|
||||
status: "warn",
|
||||
message: "Prisma migrations table not found (fresh database or using db push)",
|
||||
duration_ms: Date.now() - start,
|
||||
};
|
||||
}
|
||||
|
||||
// Get migration status
|
||||
const migrations: any[] = await prisma.$queryRawUnsafe(
|
||||
`SELECT migration_name, finished_at, applied_steps_count,
|
||||
CASE WHEN rolled_back_at IS NOT NULL THEN true ELSE false END AS rolled_back
|
||||
FROM "_prisma_migrations"
|
||||
ORDER BY started_at`
|
||||
);
|
||||
|
||||
const totalMigrations = migrations.length;
|
||||
const failedMigrations = migrations.filter(
|
||||
(m: any) => m.finished_at === null && !m.rolled_back
|
||||
);
|
||||
const rolledBack = migrations.filter((m: any) => m.rolled_back);
|
||||
|
||||
if (failedMigrations.length > 0) {
|
||||
return {
|
||||
name: "prisma_migrations",
|
||||
status: "fail",
|
||||
message: `${failedMigrations.length} migration(s) incomplete: [${failedMigrations.map((m: any) => m.migration_name).join(", ")}]`,
|
||||
duration_ms: Date.now() - start,
|
||||
details: {
|
||||
total: totalMigrations,
|
||||
failed: failedMigrations.map((m: any) => m.migration_name),
|
||||
rolledBack: rolledBack.map((m: any) => m.migration_name),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
if (rolledBack.length > 0) {
|
||||
return {
|
||||
name: "prisma_migrations",
|
||||
status: "warn",
|
||||
message: `${totalMigrations} migrations applied, ${rolledBack.length} rolled back`,
|
||||
duration_ms: Date.now() - start,
|
||||
details: {
|
||||
total: totalMigrations,
|
||||
rolledBack: rolledBack.map((m: any) => m.migration_name),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
name: "prisma_migrations",
|
||||
status: "pass",
|
||||
message: `${totalMigrations} migrations applied successfully`,
|
||||
duration_ms: Date.now() - start,
|
||||
details: {
|
||||
total: totalMigrations,
|
||||
latest: migrations[migrations.length - 1]?.migration_name || "none",
|
||||
},
|
||||
};
|
||||
} catch (error) {
|
||||
return {
|
||||
name: "prisma_migrations",
|
||||
status: "fail",
|
||||
message: `Migration check failed: ${error instanceof Error ? error.message : "unknown"}`,
|
||||
duration_ms: Date.now() - start,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
async function probeTable(
|
||||
tableName: string,
|
||||
expectedColumns: string[]
|
||||
): Promise<ProbeResult> {
|
||||
const start = Date.now();
|
||||
try {
|
||||
// Prisma uses the model name as-is for the table name by default
|
||||
let actualColumns: string[] = [];
|
||||
|
||||
// Try the exact table name first
|
||||
const colResult: any[] = await prisma.$queryRawUnsafe(
|
||||
`SELECT column_name FROM information_schema.columns
|
||||
WHERE table_schema = 'public' AND table_name = $1
|
||||
ORDER BY ordinal_position`,
|
||||
tableName
|
||||
);
|
||||
actualColumns = colResult.map((r: any) => r.column_name);
|
||||
|
||||
// If not found, try with double-quote escaped version
|
||||
if (actualColumns.length === 0) {
|
||||
const quotedResult: any[] = await prisma.$queryRawUnsafe(
|
||||
`SELECT column_name FROM information_schema.columns
|
||||
WHERE table_schema = 'public' AND table_name = $1
|
||||
ORDER BY ordinal_position`,
|
||||
tableName
|
||||
);
|
||||
actualColumns = quotedResult.map((r: any) => r.column_name);
|
||||
}
|
||||
|
||||
if (actualColumns.length === 0) {
|
||||
return {
|
||||
name: `schema:${tableName}`,
|
||||
status: "fail",
|
||||
message: `Table '${tableName}' does not exist`,
|
||||
duration_ms: Date.now() - start,
|
||||
};
|
||||
}
|
||||
|
||||
// Check for missing columns (Prisma column names match model field names)
|
||||
const missingCols = expectedColumns.filter((col) => {
|
||||
return !actualColumns.includes(col);
|
||||
});
|
||||
|
||||
let status: "pass" | "fail" | "warn" = "pass";
|
||||
if (missingCols.length > 0) {
|
||||
status = missingCols.length > expectedColumns.length / 2 ? "fail" : "warn";
|
||||
}
|
||||
|
||||
return {
|
||||
name: `schema:${tableName}`,
|
||||
status,
|
||||
message:
|
||||
missingCols.length > 0
|
||||
? `${tableName}: missing columns [${missingCols.join(", ")}]`
|
||||
: `${tableName}: OK (${actualColumns.length} columns)`,
|
||||
duration_ms: Date.now() - start,
|
||||
details: {
|
||||
actualColumnCount: actualColumns.length,
|
||||
missingColumns: missingCols,
|
||||
},
|
||||
};
|
||||
} catch (error) {
|
||||
return {
|
||||
name: `schema:${tableName}`,
|
||||
status: "fail",
|
||||
message: `Schema probe for '${tableName}' failed: ${error instanceof Error ? error.message : "unknown"}`,
|
||||
duration_ms: Date.now() - start,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Prisma CLI migration status check
|
||||
// ============================================================================
|
||||
|
||||
async function probePrismaCLIMigrationStatus(): Promise<ProbeResult> {
|
||||
const start = Date.now();
|
||||
try {
|
||||
const output = execSync("npx prisma migrate status 2>&1", {
|
||||
encoding: "utf-8",
|
||||
timeout: 30000,
|
||||
env: { ...process.env, DATABASE_URL },
|
||||
});
|
||||
|
||||
const hasPending = output.includes("Following migration(s) have not yet been applied");
|
||||
const hasFailed = output.includes("failed to apply");
|
||||
const isUpToDate =
|
||||
output.includes("Database schema is up to date") ||
|
||||
output.includes("migrations found in prisma/migrations");
|
||||
|
||||
if (hasFailed) {
|
||||
return {
|
||||
name: "prisma_cli_status",
|
||||
status: "fail",
|
||||
message: "Prisma reports failed migrations",
|
||||
duration_ms: Date.now() - start,
|
||||
details: { output: output.trim() },
|
||||
};
|
||||
}
|
||||
|
||||
if (hasPending) {
|
||||
return {
|
||||
name: "prisma_cli_status",
|
||||
status: "warn",
|
||||
message: "Prisma reports pending (unapplied) migrations",
|
||||
duration_ms: Date.now() - start,
|
||||
details: { output: output.trim() },
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
name: "prisma_cli_status",
|
||||
status: "pass",
|
||||
message: "Prisma migration status: up to date",
|
||||
duration_ms: Date.now() - start,
|
||||
};
|
||||
} catch (error) {
|
||||
// prisma migrate status exits non-zero when there are pending migrations
|
||||
const stderr = error instanceof Error ? (error as any).stderr || error.message : "unknown";
|
||||
const stdout = error instanceof Error ? (error as any).stdout || "" : "";
|
||||
|
||||
return {
|
||||
name: "prisma_cli_status",
|
||||
status: "warn",
|
||||
message: `Prisma CLI status check: ${stdout || stderr}`.slice(0, 200),
|
||||
duration_ms: Date.now() - start,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Main
|
||||
// ============================================================================
|
||||
|
||||
async function main() {
|
||||
const results: ProbeResult[] = [];
|
||||
|
||||
console.log("=== Gitgram DB Production Verification ===\n");
|
||||
|
||||
// Initialize Prisma Client
|
||||
console.log("Initializing Prisma Client...");
|
||||
const prismaReady = await initPrisma();
|
||||
|
||||
if (!prismaReady) {
|
||||
console.error("Failed to initialize Prisma Client. Ensure 'prisma generate' has been run.");
|
||||
results.push({
|
||||
name: "prisma_init",
|
||||
status: "fail",
|
||||
message: "Failed to initialize PrismaClient (run prisma generate first)",
|
||||
duration_ms: 0,
|
||||
});
|
||||
|
||||
// Fall back to CLI-only checks
|
||||
console.log("[1/1] Prisma CLI migration status...");
|
||||
results.push(await probePrismaCLIMigrationStatus());
|
||||
} else {
|
||||
// Connection probe
|
||||
console.log("[1/5] Connection probe...");
|
||||
const connResult = await probeConnection();
|
||||
results.push(connResult);
|
||||
|
||||
if (connResult.status === "fail") {
|
||||
console.error("Connection failed, cannot continue with DB probes.");
|
||||
} else {
|
||||
// Latency probe
|
||||
console.log("[2/5] Latency probe...");
|
||||
results.push(await probeLatency());
|
||||
|
||||
// Prisma migration status (via SQL)
|
||||
console.log("[3/5] Prisma migration status (SQL)...");
|
||||
results.push(await probePrismaMigrations());
|
||||
|
||||
// Prisma CLI migration status
|
||||
console.log("[4/5] Prisma CLI migration status...");
|
||||
results.push(await probePrismaCLIMigrationStatus());
|
||||
|
||||
// Schema probes
|
||||
console.log("[5/5] Schema probes...");
|
||||
for (const [tableName, def] of Object.entries(EXPECTED_TABLES)) {
|
||||
results.push(await probeTable(tableName, def.columns));
|
||||
}
|
||||
}
|
||||
|
||||
await disconnectPrisma();
|
||||
}
|
||||
|
||||
// Output
|
||||
if (OUTPUT_JSON) {
|
||||
const passed = results.filter((r) => r.status === "pass").length;
|
||||
const warned = results.filter((r) => r.status === "warn").length;
|
||||
const failed = results.filter((r) => r.status === "fail").length;
|
||||
console.log(
|
||||
JSON.stringify(
|
||||
{
|
||||
timestamp: new Date().toISOString(),
|
||||
overall: failed > 0 ? "unhealthy" : warned > 0 ? "degraded" : "healthy",
|
||||
summary: { total: results.length, passed, warned, failed },
|
||||
results,
|
||||
},
|
||||
null,
|
||||
2
|
||||
)
|
||||
);
|
||||
} else {
|
||||
console.log("\n=== Results ===\n");
|
||||
for (const r of results) {
|
||||
const icon = r.status === "pass" ? "PASS" : r.status === "warn" ? "WARN" : "FAIL";
|
||||
console.log(` [${icon}] ${r.name}: ${r.message} (${r.duration_ms}ms)`);
|
||||
}
|
||||
const passed = results.filter((r) => r.status === "pass").length;
|
||||
const warned = results.filter((r) => r.status === "warn").length;
|
||||
const failed = results.filter((r) => r.status === "fail").length;
|
||||
console.log(`\nTotal: ${results.length} | Passed: ${passed} | Warnings: ${warned} | Failed: ${failed}`);
|
||||
}
|
||||
|
||||
const hasFails = results.some((r) => r.status === "fail");
|
||||
process.exit(hasFails ? 1 : 0);
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
console.error("Fatal error:", err);
|
||||
process.exit(1);
|
||||
});
|
||||
185
scripts/verify-launch-readiness.sh
Executable file
185
scripts/verify-launch-readiness.sh
Executable file
@ -0,0 +1,185 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
TARGET_ENV="${1:-all}"
|
||||
if [[ "${TARGET_ENV}" != "all" && "${TARGET_ENV}" != "staging" && "${TARGET_ENV}" != "production" ]]; then
|
||||
echo "Usage: $0 [all|staging|production] [core|full]" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
VALIDATION_PROFILE="${2:-core}"
|
||||
if [[ "${VALIDATION_PROFILE}" != "core" && "${VALIDATION_PROFILE}" != "full" ]]; then
|
||||
echo "Usage: $0 [all|staging|production] [core|full]" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
RUN_TYPECHECK="${RUN_TYPECHECK:-0}"
|
||||
RUN_LOCAL_SMOKE="${RUN_LOCAL_SMOKE:-0}"
|
||||
|
||||
MISSING_FILES=()
|
||||
FAILED_STEPS=()
|
||||
|
||||
log() {
|
||||
printf '%s\n' "$1"
|
||||
}
|
||||
|
||||
check_cmd() {
|
||||
local cmd="$1"
|
||||
if ! command -v "${cmd}" >/dev/null 2>&1; then
|
||||
log "Missing required command: ${cmd}"
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
require_file() {
|
||||
local path="$1"
|
||||
if [[ ! -f "${path}" ]]; then
|
||||
MISSING_FILES+=("${path}")
|
||||
fi
|
||||
}
|
||||
|
||||
resolve_env_file() {
|
||||
local base="$1"
|
||||
local env_name="$2"
|
||||
local candidate="${base}.${env_name}"
|
||||
|
||||
if [[ -f "${candidate}" ]]; then
|
||||
printf '%s' "${candidate}"
|
||||
return 0
|
||||
fi
|
||||
|
||||
printf '%s' "${base}"
|
||||
}
|
||||
|
||||
require_env_set() {
|
||||
local env_name="$1"
|
||||
require_file "$(resolve_env_file "${ROOT_DIR}/.env.gitgram" "${env_name}")"
|
||||
require_file "$(resolve_env_file "${ROOT_DIR}/.env.gitgram-web" "${env_name}")"
|
||||
require_file "$(resolve_env_file "${ROOT_DIR}/.env.aitm-api" "${env_name}")"
|
||||
}
|
||||
|
||||
log "=== Launch Readiness Gate ==="
|
||||
log "Repo: ${ROOT_DIR}"
|
||||
log "Profile: ${VALIDATION_PROFILE}"
|
||||
|
||||
log ""
|
||||
log "1) Checking required commands"
|
||||
check_cmd bash
|
||||
check_cmd node
|
||||
check_cmd npm
|
||||
check_cmd pm2
|
||||
|
||||
log "PASS node: $(node -v)"
|
||||
log "PASS npm: $(npm -v)"
|
||||
log "PASS pm2 command: $(command -v pm2)"
|
||||
|
||||
log ""
|
||||
log "2) Checking launch artifacts"
|
||||
require_file "${ROOT_DIR}/gitgram/ecosystem.config.js"
|
||||
require_file "${ROOT_DIR}/aitimemachine/deploy/ecosystem.config.cjs"
|
||||
require_file "${ROOT_DIR}/.env.gitgram.example"
|
||||
require_file "${ROOT_DIR}/.env.gitgram-web.example"
|
||||
require_file "${ROOT_DIR}/.env.aitm-api.example"
|
||||
|
||||
if [[ "${#MISSING_FILES[@]}" -gt 0 ]]; then
|
||||
log "Missing launch artifacts:"
|
||||
for item in "${MISSING_FILES[@]}"; do
|
||||
log " - ${item}"
|
||||
done
|
||||
exit 1
|
||||
fi
|
||||
log "PASS launch artifacts present"
|
||||
|
||||
log ""
|
||||
log "3) Checking operator env files"
|
||||
MISSING_FILES=()
|
||||
if [[ "${TARGET_ENV}" == "all" ]]; then
|
||||
require_env_set "staging"
|
||||
require_env_set "production"
|
||||
else
|
||||
require_env_set "${TARGET_ENV}"
|
||||
fi
|
||||
|
||||
if [[ "${#MISSING_FILES[@]}" -gt 0 ]]; then
|
||||
log "Missing operator env files:"
|
||||
for item in "${MISSING_FILES[@]}"; do
|
||||
log " - ${item}"
|
||||
done
|
||||
log ""
|
||||
log "Create them from the templates. Preferred layout:"
|
||||
log " cp .env.gitgram.example .env.gitgram.production"
|
||||
log " cp .env.gitgram-web.example .env.gitgram-web.production"
|
||||
log " cp .env.aitm-api.example .env.aitm-api.production"
|
||||
log " cp .env.gitgram.example .env.gitgram.staging"
|
||||
log " cp .env.gitgram-web.example .env.gitgram-web.staging"
|
||||
log " cp .env.aitm-api.example .env.aitm-api.staging"
|
||||
log "Fallback layout still supported:"
|
||||
log " cp .env.gitgram.example .env.gitgram"
|
||||
log " cp .env.gitgram-web.example .env.gitgram-web"
|
||||
log " cp .env.aitm-api.example .env.aitm-api"
|
||||
log " # optional"
|
||||
log " cp .env.aitm-website.example .env.aitm-website"
|
||||
exit 1
|
||||
fi
|
||||
log "PASS operator env files present"
|
||||
|
||||
validate_env() {
|
||||
local env_name="$1"
|
||||
log ""
|
||||
log "4) Validating ${VALIDATION_PROFILE} secrets contract for ${env_name}"
|
||||
if ! bash "${ROOT_DIR}/scripts/validate-prod-secrets.sh" "${env_name}" "${VALIDATION_PROFILE}"; then
|
||||
FAILED_STEPS+=("secrets:${env_name}:${VALIDATION_PROFILE}")
|
||||
fi
|
||||
}
|
||||
|
||||
if [[ "${TARGET_ENV}" == "all" ]]; then
|
||||
validate_env "staging"
|
||||
validate_env "production"
|
||||
else
|
||||
validate_env "${TARGET_ENV}"
|
||||
fi
|
||||
|
||||
log ""
|
||||
log "5) Verifying AITM npm package publishability"
|
||||
if ! npm --prefix "${ROOT_DIR}" run verify:aitm-packages; then
|
||||
FAILED_STEPS+=("aitm-packages")
|
||||
fi
|
||||
|
||||
if [[ "${RUN_TYPECHECK}" == "1" ]]; then
|
||||
log ""
|
||||
log "6) Running typechecks"
|
||||
if ! npm --prefix "${ROOT_DIR}" run typecheck:gitgram; then
|
||||
FAILED_STEPS+=("typecheck:gitgram")
|
||||
fi
|
||||
if ! npm --prefix "${ROOT_DIR}" run typecheck:aitm; then
|
||||
FAILED_STEPS+=("typecheck:aitm")
|
||||
fi
|
||||
else
|
||||
log ""
|
||||
log "6) Skipping typechecks (set RUN_TYPECHECK=1 to enable)"
|
||||
fi
|
||||
|
||||
if [[ "${RUN_LOCAL_SMOKE}" == "1" ]]; then
|
||||
log ""
|
||||
log "7) Running local smoke script"
|
||||
if ! bash "${ROOT_DIR}/scripts/smoke-local-launch.sh"; then
|
||||
FAILED_STEPS+=("local-smoke")
|
||||
fi
|
||||
else
|
||||
log ""
|
||||
log "7) Skipping local smoke (set RUN_LOCAL_SMOKE=1 to enable)"
|
||||
fi
|
||||
|
||||
if [[ "${#FAILED_STEPS[@]}" -gt 0 ]]; then
|
||||
log ""
|
||||
log "Launch readiness failed."
|
||||
log "Failed checks:"
|
||||
for item in "${FAILED_STEPS[@]}"; do
|
||||
log " - ${item}"
|
||||
done
|
||||
exit 1
|
||||
fi
|
||||
|
||||
log ""
|
||||
log "Launch readiness checks passed."
|
||||
415
scripts/verify-neon.ts
Normal file
415
scripts/verify-neon.ts
Normal file
@ -0,0 +1,415 @@
|
||||
#!/usr/bin/env npx tsx
|
||||
/**
|
||||
* Neon PostgreSQL Production Verification Script
|
||||
*
|
||||
* Connects to the Neon database using DATABASE_URL, then runs:
|
||||
* 1. Connection probe (SELECT 1)
|
||||
* 2. Latency probe (SELECT now())
|
||||
* 3. Replication lag check
|
||||
* 4. Schema probes (table existence, columns, indexes)
|
||||
* 5. Migration drift check
|
||||
*
|
||||
* Exit codes:
|
||||
* 0 - All checks passed
|
||||
* 1 - One or more checks failed
|
||||
* 2 - Configuration error (missing DATABASE_URL)
|
||||
*
|
||||
* Usage:
|
||||
* DATABASE_URL=postgres://... npx tsx scripts/verify-neon.ts
|
||||
* DATABASE_URL=postgres://... npx tsx scripts/verify-neon.ts --json
|
||||
*/
|
||||
|
||||
import { neon } from "@neondatabase/serverless";
|
||||
import { drizzle } from "drizzle-orm/neon-http";
|
||||
import { sql } from "drizzle-orm";
|
||||
|
||||
// ============================================================================
|
||||
// Configuration
|
||||
// ============================================================================
|
||||
|
||||
const DATABASE_URL = process.env.DATABASE_URL;
|
||||
const OUTPUT_JSON = process.argv.includes("--json");
|
||||
|
||||
if (!DATABASE_URL) {
|
||||
console.error("ERROR: DATABASE_URL environment variable is required");
|
||||
process.exit(2);
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Expected schema definition (mirrored from db-health.ts for standalone use)
|
||||
// ============================================================================
|
||||
|
||||
const EXPECTED_TABLES: Record<string, { columns: string[]; indexes: string[] }> = {
|
||||
users: {
|
||||
columns: ["id", "email", "name", "plan", "polar_customer_id", "storage_used_bytes", "created_at", "updated_at"],
|
||||
indexes: ["users_pkey"],
|
||||
},
|
||||
api_keys: {
|
||||
columns: ["id", "user_id", "key_hash", "key_prefix", "name", "scopes", "expires_at", "allowed_ips", "last_used_at", "created_at", "revoked_at"],
|
||||
indexes: ["api_keys_pkey"],
|
||||
},
|
||||
sessions: {
|
||||
columns: ["id", "user_id", "token_hash", "ip_address", "user_agent", "device_info", "last_active_at", "expires_at", "revoked", "revoked_at", "created_at"],
|
||||
indexes: ["sessions_pkey", "idx_auth_sessions_user", "idx_auth_sessions_token_hash", "idx_auth_sessions_expires", "idx_auth_sessions_revoked"],
|
||||
},
|
||||
subscriptions: {
|
||||
columns: ["id", "user_id", "polar_customer_id", "polar_product_id", "status", "plan", "current_period_start", "current_period_end", "cancel_at_period_end", "canceled_at", "created_at", "updated_at"],
|
||||
indexes: ["subscriptions_pkey", "idx_subscriptions_user", "idx_subscriptions_status", "idx_subscriptions_polar_customer"],
|
||||
},
|
||||
organizations: {
|
||||
columns: ["id", "name", "slug", "owner_id", "plan", "metadata", "created_at", "updated_at"],
|
||||
indexes: ["organizations_pkey", "idx_organizations_slug", "idx_organizations_owner"],
|
||||
},
|
||||
projects: {
|
||||
columns: ["id", "user_id", "org_id", "name", "root_path", "created_at", "updated_at", "last_synced_at"],
|
||||
indexes: ["projects_pkey", "idx_projects_user", "idx_projects_org"],
|
||||
},
|
||||
checkpoints: {
|
||||
columns: ["id", "project_id", "user_id", "org_id", "parent_id", "name", "description", "scope", "manifest_hash", "root_tree_hash", "trigger_type", "linked_checkpoint_id", "created_at", "metadata"],
|
||||
indexes: ["checkpoints_pkey", "idx_checkpoints_project", "idx_checkpoints_user", "idx_checkpoints_org", "idx_checkpoints_created"],
|
||||
},
|
||||
checkpoint_files: {
|
||||
columns: ["checkpoint_id", "file_path", "blob_hash", "size", "mode", "mtime_ms", "change_type"],
|
||||
indexes: ["checkpoint_files_pkey", "idx_checkpoint_files_path"],
|
||||
},
|
||||
blobs: {
|
||||
columns: ["hash", "user_id", "size", "mime_type", "content", "storage_type", "created_at"],
|
||||
indexes: ["blobs_pkey"],
|
||||
},
|
||||
trees: {
|
||||
columns: ["id", "project_id", "hash", "parent_path", "entries", "created_at"],
|
||||
indexes: ["trees_pkey", "idx_trees_project_hash", "idx_trees_hash", "idx_trees_parent_path"],
|
||||
},
|
||||
chat_sessions: {
|
||||
columns: ["id", "project_id", "user_id", "tool", "started_at", "ended_at", "metadata"],
|
||||
indexes: ["chat_sessions_pkey", "idx_sessions_project", "idx_sessions_user"],
|
||||
},
|
||||
chat_messages: {
|
||||
columns: ["id", "session_id", "project_id", "user_id", "checkpoint_id", "role", "content", "content_hash", "is_context_injection", "timestamp", "metadata"],
|
||||
indexes: ["chat_messages_pkey", "idx_messages_session", "idx_messages_project", "idx_messages_timestamp"],
|
||||
},
|
||||
webhooks: {
|
||||
columns: ["id", "user_id", "url", "secret", "events", "is_active", "created_at", "updated_at", "last_triggered_at", "failure_count"],
|
||||
indexes: ["webhooks_pkey", "idx_webhooks_user", "idx_webhooks_active"],
|
||||
},
|
||||
repositories: {
|
||||
columns: ["id", "project_id", "user_id", "name", "root_path", "last_indexed_at", "index_status", "file_count", "symbol_count", "created_at", "updated_at", "metadata"],
|
||||
indexes: ["repositories_pkey", "idx_repositories_project", "idx_repositories_user"],
|
||||
},
|
||||
audit_logs: {
|
||||
columns: ["id", "user_id", "action", "resource_type", "resource_id", "ip_address", "user_agent", "metadata", "created_at"],
|
||||
indexes: ["audit_logs_pkey", "idx_audit_logs_user", "idx_audit_logs_action", "idx_audit_logs_resource_type", "idx_audit_logs_created_at"],
|
||||
},
|
||||
posts: {
|
||||
columns: ["id", "author_user_id", "repository_id", "project_id", "type", "caption", "code_snippet", "language", "linked_checkpoint_id", "visibility", "published_at", "created_at", "updated_at"],
|
||||
indexes: ["posts_pkey", "idx_posts_repo_created", "idx_posts_author_created"],
|
||||
},
|
||||
follows: {
|
||||
columns: ["id", "follower_user_id", "target_type", "target_user_id", "target_repository_id", "created_at"],
|
||||
indexes: ["follows_pkey", "idx_follows_target_user", "idx_follows_target_repo"],
|
||||
},
|
||||
trend_scores: {
|
||||
columns: ["id", "repository_id", "window_start", "window_end", "score", "signals", "created_at"],
|
||||
indexes: ["trend_scores_pkey", "idx_trend_scores_repo_window"],
|
||||
},
|
||||
};
|
||||
|
||||
const EXPECTED_MIGRATIONS = [
|
||||
"0001_add_storage_used_bytes",
|
||||
"0002_add_knowledge_base_tables",
|
||||
"0003_add_canonical_time_context_governance",
|
||||
"0004_add_gitgram_social_layer",
|
||||
];
|
||||
|
||||
// ============================================================================
|
||||
// Database connection
|
||||
// ============================================================================
|
||||
|
||||
const neonSql = neon(DATABASE_URL);
|
||||
const db = drizzle(neonSql);
|
||||
|
||||
// ============================================================================
|
||||
// Probe functions
|
||||
// ============================================================================
|
||||
|
||||
interface ProbeResult {
|
||||
name: string;
|
||||
status: "pass" | "fail" | "warn";
|
||||
message: string;
|
||||
duration_ms: number;
|
||||
details?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
async function probeConnection(): Promise<ProbeResult> {
|
||||
const start = Date.now();
|
||||
try {
|
||||
await db.execute(sql`SELECT 1 AS ping`);
|
||||
return {
|
||||
name: "connection",
|
||||
status: "pass",
|
||||
message: "Database connection successful",
|
||||
duration_ms: Date.now() - start,
|
||||
};
|
||||
} catch (error) {
|
||||
return {
|
||||
name: "connection",
|
||||
status: "fail",
|
||||
message: `Connection failed: ${error instanceof Error ? error.message : "unknown"}`,
|
||||
duration_ms: Date.now() - start,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
async function probeLatency(): Promise<ProbeResult> {
|
||||
const start = Date.now();
|
||||
try {
|
||||
await db.execute(sql`SELECT now() AS server_time`);
|
||||
const ms = Date.now() - start;
|
||||
const status = ms > 2000 ? "fail" : ms > 500 ? "warn" : "pass";
|
||||
return {
|
||||
name: "latency",
|
||||
status,
|
||||
message: `Query latency: ${ms}ms`,
|
||||
duration_ms: ms,
|
||||
};
|
||||
} catch (error) {
|
||||
return {
|
||||
name: "latency",
|
||||
status: "fail",
|
||||
message: `Latency probe failed: ${error instanceof Error ? error.message : "unknown"}`,
|
||||
duration_ms: Date.now() - start,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
async function probeReplication(): Promise<ProbeResult> {
|
||||
const start = Date.now();
|
||||
try {
|
||||
const result = await db.execute(
|
||||
sql`SELECT CASE
|
||||
WHEN pg_is_in_recovery() THEN
|
||||
EXTRACT(EPOCH FROM (now() - pg_last_xact_replay_timestamp()))
|
||||
ELSE 0
|
||||
END AS lag_seconds`
|
||||
);
|
||||
const ms = Date.now() - start;
|
||||
const lag = parseFloat((result as any[])[0]?.lag_seconds ?? "0");
|
||||
const status = lag > 30 ? "fail" : lag > 5 ? "warn" : "pass";
|
||||
return {
|
||||
name: "replication",
|
||||
status,
|
||||
message: `Replication lag: ${lag.toFixed(1)}s`,
|
||||
duration_ms: ms,
|
||||
details: { lag_seconds: lag },
|
||||
};
|
||||
} catch {
|
||||
return {
|
||||
name: "replication",
|
||||
status: "pass",
|
||||
message: "Replication check: not available (Neon serverless mode)",
|
||||
duration_ms: Date.now() - start,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
async function probeTable(
|
||||
tableName: string,
|
||||
expectedColumns: string[],
|
||||
expectedIndexes: string[]
|
||||
): Promise<ProbeResult> {
|
||||
const start = Date.now();
|
||||
try {
|
||||
const colResult = await db.execute(
|
||||
sql`SELECT column_name FROM information_schema.columns
|
||||
WHERE table_schema = 'public' AND table_name = ${tableName}
|
||||
ORDER BY ordinal_position`
|
||||
);
|
||||
const actualColumns = (colResult as any[]).map((r: any) => r.column_name);
|
||||
|
||||
if (actualColumns.length === 0) {
|
||||
return {
|
||||
name: `schema:${tableName}`,
|
||||
status: "fail",
|
||||
message: `Table '${tableName}' does not exist`,
|
||||
duration_ms: Date.now() - start,
|
||||
};
|
||||
}
|
||||
|
||||
const missingCols = expectedColumns.filter((c) => !actualColumns.includes(c));
|
||||
|
||||
const idxResult = await db.execute(
|
||||
sql`SELECT indexname FROM pg_indexes
|
||||
WHERE schemaname = 'public' AND tablename = ${tableName}
|
||||
ORDER BY indexname`
|
||||
);
|
||||
const actualIndexes = (idxResult as any[]).map((r: any) => r.indexname);
|
||||
const missingIdxs = expectedIndexes.filter((i) => !actualIndexes.includes(i));
|
||||
|
||||
const messages: string[] = [];
|
||||
let status: "pass" | "fail" | "warn" = "pass";
|
||||
|
||||
if (missingCols.length > 0) {
|
||||
status = "fail";
|
||||
messages.push(`missing columns: [${missingCols.join(", ")}]`);
|
||||
}
|
||||
if (missingIdxs.length > 0) {
|
||||
if (status !== "fail") status = "warn";
|
||||
messages.push(`missing indexes: [${missingIdxs.join(", ")}]`);
|
||||
}
|
||||
|
||||
return {
|
||||
name: `schema:${tableName}`,
|
||||
status,
|
||||
message: messages.length > 0
|
||||
? `${tableName}: ${messages.join("; ")}`
|
||||
: `${tableName}: OK (${actualColumns.length} columns, ${actualIndexes.length} indexes)`,
|
||||
duration_ms: Date.now() - start,
|
||||
details: {
|
||||
columns: actualColumns.length,
|
||||
indexes: actualIndexes.length,
|
||||
missingColumns: missingCols,
|
||||
missingIndexes: missingIdxs,
|
||||
},
|
||||
};
|
||||
} catch (error) {
|
||||
return {
|
||||
name: `schema:${tableName}`,
|
||||
status: "fail",
|
||||
message: `Schema probe for '${tableName}' failed: ${error instanceof Error ? error.message : "unknown"}`,
|
||||
duration_ms: Date.now() - start,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
async function probeMigrationDrift(): Promise<ProbeResult> {
|
||||
const start = Date.now();
|
||||
try {
|
||||
const tableCheck = await db.execute(
|
||||
sql`SELECT EXISTS (
|
||||
SELECT FROM information_schema.tables
|
||||
WHERE table_schema = 'public' AND table_name = '__drizzle_migrations'
|
||||
) AS exists`
|
||||
);
|
||||
|
||||
if (!(tableCheck as any[])[0]?.exists) {
|
||||
return {
|
||||
name: "migration_drift",
|
||||
status: "warn",
|
||||
message: "Migration tracking table not found (may use db:push)",
|
||||
duration_ms: Date.now() - start,
|
||||
};
|
||||
}
|
||||
|
||||
const migResult = await db.execute(
|
||||
sql`SELECT tag FROM __drizzle_migrations ORDER BY created_at`
|
||||
);
|
||||
const applied = (migResult as any[]).map((r: any) => r.tag);
|
||||
const missing = EXPECTED_MIGRATIONS.filter((m) => !applied.includes(m));
|
||||
const extra = applied.filter((m: string) => !EXPECTED_MIGRATIONS.includes(m));
|
||||
|
||||
if (missing.length > 0) {
|
||||
return {
|
||||
name: "migration_drift",
|
||||
status: "fail",
|
||||
message: `Missing migrations: [${missing.join(", ")}]`,
|
||||
duration_ms: Date.now() - start,
|
||||
details: { applied, missing, extra },
|
||||
};
|
||||
}
|
||||
|
||||
if (extra.length > 0) {
|
||||
return {
|
||||
name: "migration_drift",
|
||||
status: "warn",
|
||||
message: `Unexpected migrations: [${extra.join(", ")}]`,
|
||||
duration_ms: Date.now() - start,
|
||||
details: { applied, missing, extra },
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
name: "migration_drift",
|
||||
status: "pass",
|
||||
message: `All ${EXPECTED_MIGRATIONS.length} expected migrations applied`,
|
||||
duration_ms: Date.now() - start,
|
||||
details: { applied },
|
||||
};
|
||||
} catch (error) {
|
||||
return {
|
||||
name: "migration_drift",
|
||||
status: "fail",
|
||||
message: `Migration drift check failed: ${error instanceof Error ? error.message : "unknown"}`,
|
||||
duration_ms: Date.now() - start,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Main
|
||||
// ============================================================================
|
||||
|
||||
async function main() {
|
||||
const results: ProbeResult[] = [];
|
||||
|
||||
// Health probes
|
||||
console.log("=== Neon Production Verification ===\n");
|
||||
|
||||
console.log("[1/4] Connection probe...");
|
||||
results.push(await probeConnection());
|
||||
|
||||
console.log("[2/4] Latency probe...");
|
||||
results.push(await probeLatency());
|
||||
|
||||
console.log("[3/4] Replication probe...");
|
||||
results.push(await probeReplication());
|
||||
|
||||
// Schema probes
|
||||
console.log("[4/4] Schema probes...");
|
||||
const tableNames = Object.keys(EXPECTED_TABLES);
|
||||
for (const tableName of tableNames) {
|
||||
const def = EXPECTED_TABLES[tableName];
|
||||
results.push(await probeTable(tableName, def.columns, def.indexes));
|
||||
}
|
||||
|
||||
// Migration drift
|
||||
console.log(" Migration drift check...");
|
||||
results.push(await probeMigrationDrift());
|
||||
|
||||
// Output
|
||||
if (OUTPUT_JSON) {
|
||||
const passed = results.filter((r) => r.status === "pass").length;
|
||||
const warned = results.filter((r) => r.status === "warn").length;
|
||||
const failed = results.filter((r) => r.status === "fail").length;
|
||||
console.log(
|
||||
JSON.stringify(
|
||||
{
|
||||
timestamp: new Date().toISOString(),
|
||||
overall: failed > 0 ? "unhealthy" : warned > 0 ? "degraded" : "healthy",
|
||||
summary: { total: results.length, passed, warned, failed },
|
||||
results,
|
||||
},
|
||||
null,
|
||||
2
|
||||
)
|
||||
);
|
||||
} else {
|
||||
console.log("\n=== Results ===\n");
|
||||
for (const r of results) {
|
||||
const icon = r.status === "pass" ? "PASS" : r.status === "warn" ? "WARN" : "FAIL";
|
||||
console.log(` [${icon}] ${r.name}: ${r.message} (${r.duration_ms}ms)`);
|
||||
}
|
||||
const passed = results.filter((r) => r.status === "pass").length;
|
||||
const warned = results.filter((r) => r.status === "warn").length;
|
||||
const failed = results.filter((r) => r.status === "fail").length;
|
||||
console.log(`\nTotal: ${results.length} | Passed: ${passed} | Warnings: ${warned} | Failed: ${failed}`);
|
||||
}
|
||||
|
||||
// Exit code
|
||||
const hasFails = results.some((r) => r.status === "fail");
|
||||
process.exit(hasFails ? 1 : 0);
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
console.error("Fatal error:", err);
|
||||
process.exit(1);
|
||||
});
|
||||
39
scripts/verify-public-launch.sh
Executable file
39
scripts/verify-public-launch.sh
Executable file
@ -0,0 +1,39 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
GITGRAM_PUBLIC_URL="${GITGRAM_PUBLIC_URL:-https://gitgram.app}"
|
||||
AITM_API_PUBLIC_URL="${AITM_API_PUBLIC_URL:-https://timemachine-api.gitgram.app}"
|
||||
AITM_WEBSITE_PUBLIC_URL="${AITM_WEBSITE_PUBLIC_URL:-https://timemachine.gitgram.app}"
|
||||
SKIP_AITM_WEBSITE="${SKIP_AITM_WEBSITE:-0}"
|
||||
|
||||
log() {
|
||||
printf '%s\n' "$1"
|
||||
}
|
||||
|
||||
check_http_ok() {
|
||||
local label="$1"
|
||||
local url="$2"
|
||||
if curl -fsSL --max-time 15 "${url}" >/dev/null; then
|
||||
log "PASS ${label}: ${url}"
|
||||
else
|
||||
log "FAIL ${label}: ${url}"
|
||||
return 1
|
||||
fi
|
||||
}
|
||||
|
||||
log "=== Public Launch Verification ==="
|
||||
log "Gitgram: ${GITGRAM_PUBLIC_URL}"
|
||||
log "AITM API: ${AITM_API_PUBLIC_URL}"
|
||||
|
||||
check_http_ok "Gitgram web" "${GITGRAM_PUBLIC_URL}"
|
||||
check_http_ok "Gitgram backend health" "${GITGRAM_PUBLIC_URL}/api/health"
|
||||
check_http_ok "Gitgram backend readiness" "${GITGRAM_PUBLIC_URL}/api/health/ready"
|
||||
check_http_ok "AITM API health" "${AITM_API_PUBLIC_URL}/health"
|
||||
check_http_ok "AITM API readiness" "${AITM_API_PUBLIC_URL}/health/ready"
|
||||
|
||||
if [[ "${SKIP_AITM_WEBSITE}" != "1" ]]; then
|
||||
check_http_ok "AITM website" "${AITM_WEBSITE_PUBLIC_URL}"
|
||||
fi
|
||||
|
||||
log ""
|
||||
log "Public launch verification passed."
|
||||
Reference in New Issue
Block a user