chadstart 1.0.0

package/.dockerignore

@@ -0,0 +1,10 @@
+node_modules
+npm-debug.log
+.git
+.gitignore
+*.db
+*.db-wal
+*.db-shm
+uploads/
+public/
+.chadstart-plugins/

package/.env.example

@@ -0,0 +1,46 @@
+# Copy this file to .env and fill in the values
+
+# General
+# TOKEN_SECRET_KEY (or JWT_SECRET) is required in production
+TOKEN_SECRET_KEY=replace-with-a-long-random-secret
+# JWT_SECRET=replace-with-a-long-random-secret  # alias for TOKEN_SECRET_KEY
+# NODE_ENV=production
+# PORT=3000
+# BASE_URL=http://localhost:3000
+# OPEN_API_DOCS=true
+
+# Paths
+# CHADSTART_FILE_PATH=chadstart.yaml
+# CHADSTART_FUNCTIONS_FOLDER=functions
+
+# Database (SQLite default)
+# DB_PATH=data/chadstart.db
+
+# Optional: S3-compatible storage (when set, files are stored in S3 instead of the local filesystem)
+# S3_BUCKET=my-bucket-name
+# S3_ENDPOINT=https://your-s3-provider.com
+# S3_REGION=XXX
+# S3_ACCESS_KEY_ID=XXX
+# S3_SECRET_ACCESS_KEY=XXX
+# S3_FOLDER_PREFIX=development/chadstart  # Optional folder prefix prepended to every object path
+
+# Optional: AI assistant (set ONE of the following to enable the AI chat button in the Admin UI)
+# OPENAI_API_KEY=sk-...
+# ANTHROPIC_API_KEY=sk-ant-...
+# GOOGLE_API_KEY=...          # Google Gemini
+# GEMINI_API_KEY=...          # alias for GOOGLE_API_KEY
+# OPENROUTER_API_KEY=sk-or-...
+
+# Optional: OpenTelemetry tracing
+# Non-secret values can also be set in chadstart.yaml under settings.telemetry
+# OTEL_ENABLED=true
+# OTEL_SERVICE_NAME=my-app
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+# OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer <token>  # Secrets — env var only, never in YAML
+
+# Error Reporting — Sentry / Bugsink
+# Set SENTRY_DSN to enable automatic error reporting.
+# The DSN is a secret; keep it here in .env and never commit it to source control.
+# 💡 Bugsink (https://www.bugsink.com) is a self-hosted alternative to Sentry
+#    that uses the same Sentry SDK — just point SENTRY_DSN at your Bugsink instance.
+# SENTRY_DSN=https://xxxxx@oXXXXX.ingest.sentry.io/XXXXXXX

package/.github/workflows/browser-test.yml

@@ -0,0 +1,34 @@
+name: Browser Tests
+
+on:
+  pull_request:
+    paths:
+      - 'admin/index.html'
+  push:
+    paths:
+      - 'admin/index.html'
+
+jobs:
+  browser-test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "lts/*"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Run browser tests
+        run: npm run test:browser

package/.github/workflows/docker-publish.yml

@@ -0,0 +1,54 @@
+name: Publish Docker image
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

package/.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install MkDocs Material
+        run: pip install mkdocs-material
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

package/.github/workflows/npm-chadstart.yml

@@ -0,0 +1,27 @@
+name: NPM chadstart
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  publish:
+    name: NPM Publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # required for npm provenance
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Publish to npm
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/npm-sdk.yml

@@ -0,0 +1,38 @@
+name: NPM sdk
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'sdk/**'
+
+jobs:
+  publish:
+    name: NPM Publish
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: sdk
+    permissions:
+      contents: read
+      id-token: write  # required for npm provenance
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Build SDK
+        run: node scripts/build.js
+
+      - name: Run SDK tests
+        run: node test/sdk.test.cjs
+
+      - name: Publish to npm
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/test.yml

@@ -0,0 +1,85 @@
+name: Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "lts/*"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests with coverage
+        id: coverage
+        run: npm run test:coverage
+
+      - name: Post coverage comment
+        if: always()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+
+            let body = '';
+
+            // Read c8 JSON summary if available
+            const summaryPath = path.join(process.env.GITHUB_WORKSPACE, 'coverage', 'coverage-summary.json');
+            if (fs.existsSync(summaryPath)) {
+              const summary = JSON.parse(fs.readFileSync(summaryPath, 'utf8')).total;
+              const fmt = (v) => `${v.pct}% (${v.covered}/${v.total})`;
+              body = [
+                '## 🧪 Test Coverage Report',
+                '',
+                '| Category    | Coverage |',
+                '|-------------|----------|',
+                `| Statements  | ${fmt(summary.statements)} |`,
+                `| Branches    | ${fmt(summary.branches)} |`,
+                `| Functions   | ${fmt(summary.functions)} |`,
+                `| Lines       | ${fmt(summary.lines)} |`,
+              ].join('\n');
+            } else {
+              body = '## 🧪 Test Coverage Report\n\nCoverage data not available.';
+            }
+
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const existing = comments.find(c =>
+              c.user.type === 'Bot' && c.body.startsWith('## 🧪 Test Coverage Report')
+            );
+
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }

package/.weblate

@@ -0,0 +1,9 @@
+[weblate]
+project = chadstart
+version = 2
+
+[component: admin]
+filemask = locales/*/admin.json
+template = locales/en/admin.json
+file_format = json-nested
+source_language = en

package/Dockerfile

@@ -0,0 +1,23 @@
+# Stage 1: Install production dependencies (requires build tools for native modules)
+FROM node:lts-alpine AS deps
+WORKDIR /app
+RUN apk add --no-cache make g++
+COPY package*.json ./
+RUN npm ci --omit=dev
+
+# Stage 2: Production image
+FROM node:lts-alpine AS runner
+WORKDIR /app
+# Runtime dependencies
+RUN apk add --no-cache bash python3 go ruby g++ \
+  && addgroup -S nodejs && adduser -S nodejs -G nodejs \
+  && mkdir -p /app/{uploads,public,functions} && chown -R nodejs:nodejs /app
+COPY --from=deps --chown=nodejs:nodejs /app/node_modules ./node_modules
+COPY --chown=nodejs:nodejs . .
+
+USER nodejs
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD node -e "fetch('http://localhost:3000/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+
+CMD ["node", "cli/cli.js", "start"]