@the-open-engine/zeroshot 5.4.0

package/scripts/record-demo.sh

@@ -0,0 +1,279 @@
+#!/bin/bash
+# record-demo.sh - Create ephemeral project, run zeroshot demo, record it, cleanup
+#
+# Usage:
+#   ./scripts/record-demo.sh              # Interactive mode (you run zeroshot manually)
+#   ./scripts/record-demo.sh --record     # Record with asciinema automatically
+#
+# Output: zeroshot-demo.cast (asciinema recording)
+# Convert to gif: agg zeroshot-demo.cast zeroshot-demo.gif --idle-time-limit 2
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+DEMO_DIR=""
+RECORD_MODE=false
+FORCE_MODE=false
+LOCK_FILE="/tmp/zeroshot-demo-recording.lock"
+CAST_FILE="$REPO_ROOT/zeroshot-demo.cast"
+
+# Check for existing recording session
+check_existing_session() {
+    # Check lock file
+    if [[ -f "$LOCK_FILE" ]]; then
+        local old_pid
+        old_pid=$(cat "$LOCK_FILE" 2>/dev/null || echo "")
+        if [[ -n "$old_pid" ]] && kill -0 "$old_pid" 2>/dev/null; then
+            echo "ERROR: Recording already in progress (PID $old_pid)"
+            echo "Kill it with: kill $old_pid"
+            exit 1
+        fi
+        # Stale lock file
+        rm -f "$LOCK_FILE"
+    fi
+
+    # Check for any asciinema processes recording to our file
+    local existing_asciinema
+    existing_asciinema=$(pgrep -f "asciinema.*zeroshot-demo.cast" 2>/dev/null || true)
+    if [[ -n "$existing_asciinema" ]]; then
+        echo "ERROR: Existing asciinema process(es) found: $existing_asciinema"
+        echo "Kill them with: pkill -f 'asciinema.*zeroshot-demo.cast'"
+        exit 1
+    fi
+
+    # Check for any running zeroshot clusters
+    local existing_zeroshot
+    existing_zeroshot=$(pgrep -f "zeroshot.*rate limiting" 2>/dev/null || true)
+    if [[ -n "$existing_zeroshot" ]]; then
+        echo "ERROR: Existing zeroshot process(es) found: $existing_zeroshot"
+        echo "Kill them with: pkill -f 'zeroshot.*rate limiting'"
+        exit 1
+    fi
+}
+
+# Parse args
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --record) RECORD_MODE=true; shift ;;
+        --force|-f) FORCE_MODE=true; shift ;;
+        *) echo "Unknown option: $1"; exit 1 ;;
+    esac
+done
+
+# Cleanup on exit
+cleanup() {
+    # Remove lock file
+    rm -f "$LOCK_FILE"
+
+    if [[ -n "$DEMO_DIR" && -d "$DEMO_DIR" ]]; then
+        echo ""
+        echo "Cleaning up $DEMO_DIR..."
+        rm -rf "$DEMO_DIR"
+        echo "Done."
+    fi
+}
+trap cleanup EXIT
+
+# Check for conflicts before doing anything
+check_existing_session
+
+# Create temp project
+DEMO_DIR=$(mktemp -d -t zeroshot-demo-XXXXXX)
+echo "Creating demo project in $DEMO_DIR"
+
+cd "$DEMO_DIR"
+
+# Initialize package.json
+cat > package.json << 'EOF'
+{
+  "name": "demo-api",
+  "version": "1.0.0",
+  "type": "commonjs",
+  "scripts": {
+    "dev": "ts-node src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js"
+  }
+}
+EOF
+
+# Install dependencies (quiet)
+echo "Installing dependencies..."
+npm install --silent express typescript ts-node @types/express @types/node
+
+# Create tsconfig
+cat > tsconfig.json << 'EOF'
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "strict": true,
+    "esModuleInterop": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"]
+}
+EOF
+
+# Create minimal server with users "database"
+mkdir -p src
+
+cat > src/db.ts << 'EOF'
+// Simple in-memory database
+export interface User {
+  id: number;
+  username: string;
+  email: string;
+  password_hash: string;
+  avatar: string;
+  created_at: Date;
+}
+
+export const users: User[] = [
+  {
+    id: 1,
+    username: "alice",
+    email: "alice@example.com",
+    password_hash: "$2b$10$X7VYKzPQ...",
+    avatar: "https://example.com/alice.jpg",
+    created_at: new Date("2024-01-15"),
+  },
+  {
+    id: 2,
+    username: "bob",
+    email: "bob@example.com",
+    password_hash: "$2b$10$Y8WZLaQR...",
+    avatar: "https://example.com/bob.jpg",
+    created_at: new Date("2024-02-20"),
+  },
+];
+EOF
+
+cat > src/index.ts << 'EOF'
+import express from "express";
+
+const app = express();
+const PORT = 3000;
+
+app.use(express.json());
+
+// Health check
+app.get("/health", (_, res) => {
+  res.json({ status: "ok" });
+});
+
+app.listen(PORT, () => {
+  console.log(`Server running on http://localhost:${PORT}`);
+});
+EOF
+
+# Initialize git repo
+git init --quiet
+git add -A
+git commit --quiet -m "Initial commit: Express API with users database"
+
+echo ""
+echo "=========================================="
+echo "Demo project ready!"
+echo "=========================================="
+echo ""
+echo "Directory: $DEMO_DIR"
+echo ""
+echo "Suggested demo task:"
+echo "  zeroshot 'Add PUT /users/:id endpoint to update user profile'"
+echo ""
+
+if [[ "$RECORD_MODE" == "true" ]]; then
+    echo "Recording with asciinema..."
+    echo ""
+
+    # Check asciinema is installed
+    if ! command -v asciinema &> /dev/null; then
+        echo "Error: asciinema not installed. Run: pip install asciinema"
+        exit 1
+    fi
+
+    # Warn if cast file exists (skip with --force)
+    if [[ -f "$CAST_FILE" ]] && [[ "$FORCE_MODE" != "true" ]]; then
+        echo "WARNING: $CAST_FILE already exists!"
+        echo "Previous recording will be OVERWRITTEN."
+        echo ""
+        read -p "Continue? [y/N] " -n 1 -r
+        echo ""
+        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+            echo "Aborted."
+            exit 1
+        fi
+    fi
+
+    # Create lock file with our PID
+    echo $$ > "$LOCK_FILE"
+
+    # Record the session
+    # CRITICAL: Use bash -l -c to get full PATH (includes npm global binaries)
+    ZEROSHOT_PATH=$(which zeroshot)
+    TASK="Add rate limiting middleware: sliding window algorithm (not fixed window), per-IP tracking with in-memory store and automatic TTL cleanup to prevent memory leaks, configurable limits per endpoint. Return 429 Too Many Requests with Retry-After header (seconds until reset) and X-RateLimit-Remaining header on ALL responses. Must handle both IPv4 and IPv6, normalizing IPv6 to consistent format."
+
+    # SIGNAL ISOLATION: Use setsid to create new session, completely immune to terminal signals
+    # The recording process will NOT be killed by Ctrl+C or signals to this script
+    # We wait for it explicitly and only cleanup AFTER it naturally completes
+    echo "Starting recording in isolated session (immune to Ctrl+C)..."
+    echo "To kill it manually: pkill -f 'asciinema.*zeroshot-demo.cast'"
+    echo ""
+
+    # Disable cleanup trap during recording - we'll handle it manually
+    trap - EXIT
+
+    # Start asciinema in new session (setsid) so it's immune to our signals
+    # Save the session leader PID so we can wait for it
+    setsid bash -c "
+        # Ignore all signals - this recording WILL NOT DIE
+        trap '' INT TERM HUP QUIT
+
+        cd '$DEMO_DIR'
+        asciinema rec \
+            --overwrite \
+            --title 'Zeroshot Demo' \
+            --command \"bash -l -c '$ZEROSHOT_PATH \\\"$TASK\\\"'\" \
+            '$CAST_FILE'
+    " &
+    RECORDING_PID=$!
+
+    # Update lock file with the actual recording PID
+    echo $RECORDING_PID > "$LOCK_FILE"
+
+    echo "Recording started (session PID: $RECORDING_PID)"
+    echo "Waiting for recording to complete..."
+    echo ""
+
+    # Wait for recording to finish - this script will NOT kill it on Ctrl+C
+    # Ignore signals while waiting
+    trap '' INT TERM HUP
+    wait $RECORDING_PID 2>/dev/null || true
+
+    # Recording finished naturally - now cleanup
+    echo ""
+    echo "Recording saved to: $CAST_FILE"
+    echo ""
+    echo "Convert to gif with:"
+    echo "  agg $CAST_FILE $REPO_ROOT/zeroshot-demo.gif --idle-time-limit 2"
+
+    # Now do cleanup
+    rm -f "$LOCK_FILE"
+    if [[ -n "$DEMO_DIR" && -d "$DEMO_DIR" ]]; then
+        echo ""
+        echo "Cleaning up $DEMO_DIR..."
+        rm -rf "$DEMO_DIR"
+        echo "Done."
+    fi
+else
+    echo "Interactive mode - run zeroshot manually:"
+    echo ""
+    echo "  cd $DEMO_DIR"
+    echo "  zeroshot 'Add PUT /users/:id endpoint to update user profile'"
+    echo ""
+    echo "Press Enter when done to cleanup..."
+    read -r
+fi

package/scripts/setup-merge-queue.sh

@@ -0,0 +1,170 @@
+#!/bin/bash
+# Setup GitHub merge queue and branch protection for zeroshot
+# Run once after creating the repo or to update settings
+
+set -e
+
+REPO="the-open-engine/zeroshot"
+
+echo "╔═══════════════════════════════════════════════════════════════════╗"
+echo "║  Setting up merge queue for $REPO                         ║"
+echo "╚═══════════════════════════════════════════════════════════════════╝"
+echo ""
+
+# Check gh is authenticated
+if ! gh auth status &>/dev/null; then
+  echo "❌ ERROR: Not authenticated with GitHub CLI"
+  echo "   Run: gh auth login"
+  exit 1
+fi
+
+# Check we have admin access
+if ! gh api "repos/$REPO" --jq '.permissions.admin' | grep -q true; then
+  echo "❌ ERROR: You need admin access to $REPO"
+  exit 1
+fi
+
+echo "✓ Authenticated with admin access"
+echo ""
+
+# ============================================================================
+# Configure 'dev' branch protection (merge target)
+# ============================================================================
+
+echo "→ Configuring 'dev' branch protection..."
+
+gh api --method PUT "repos/$REPO/branches/dev/protection" \
+  --input - <<EOF
+{
+  "required_status_checks": {
+    "strict": true,
+    "contexts": ["check", "install-matrix (ubuntu-latest, 20)", "install-matrix (macos-latest, 20)"]
+  },
+  "enforce_admins": false,
+  "required_pull_request_reviews": null,
+  "restrictions": null,
+  "allow_force_pushes": false,
+  "allow_deletions": false,
+  "required_linear_history": true,
+  "required_conversation_resolution": false
+}
+EOF
+
+echo "✓ 'dev' branch protection configured"
+
+# Enable merge queue for dev branch
+echo "→ Enabling merge queue for 'dev' branch..."
+
+# Note: Merge queue requires GitHub Enterprise or public repos with Actions
+# Using the ruleset API which supports merge queue
+gh api --method POST "repos/$REPO/rulesets" \
+  --input - <<EOF 2>/dev/null || echo "   (ruleset may already exist)"
+{
+  "name": "dev-merge-queue",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "include": ["refs/heads/dev"],
+      "exclude": []
+    }
+  },
+  "rules": [
+    {
+      "type": "merge_queue",
+      "parameters": {
+        "check_response_timeout_minutes": 30,
+        "grouping_strategy": "ALLGREEN",
+        "max_entries_to_build": 5,
+        "max_entries_to_merge": 5,
+        "merge_method": "SQUASH",
+        "min_entries_to_merge": 1,
+        "min_entries_to_merge_wait_minutes": 1
+      }
+    }
+  ]
+}
+EOF
+
+echo "✓ Merge queue enabled for 'dev'"
+
+# ============================================================================
+# Configure 'main' branch protection (release branch)
+# ============================================================================
+
+echo "→ Configuring 'main' branch protection..."
+
+gh api --method PUT "repos/$REPO/branches/main/protection" \
+  --input - <<EOF
+{
+  "required_status_checks": {
+    "strict": true,
+    "contexts": ["check", "install-matrix (ubuntu-latest, 20)", "install-matrix (macos-latest, 20)"]
+  },
+  "enforce_admins": false,
+  "required_pull_request_reviews": {
+    "required_approving_review_count": 1,
+    "dismiss_stale_reviews": true,
+    "require_code_owner_reviews": false
+  },
+  "restrictions": null,
+  "allow_force_pushes": false,
+  "allow_deletions": false,
+  "required_linear_history": true,
+  "required_conversation_resolution": false
+}
+EOF
+
+echo "✓ 'main' branch protection configured"
+
+# ============================================================================
+# Configure repository settings
+# ============================================================================
+
+echo "→ Configuring repository settings..."
+
+gh api --method PATCH "repos/$REPO" \
+  --input - <<EOF
+{
+  "allow_squash_merge": true,
+  "allow_merge_commit": false,
+  "allow_rebase_merge": false,
+  "squash_merge_commit_title": "PR_TITLE",
+  "squash_merge_commit_message": "PR_BODY",
+  "delete_branch_on_merge": true,
+  "allow_auto_merge": true
+}
+EOF
+
+echo "✓ Repository settings configured"
+
+# ============================================================================
+# Summary
+# ============================================================================
+
+echo ""
+echo "╔═══════════════════════════════════════════════════════════════════╗"
+echo "║  ✓ Merge queue setup complete!                                    ║"
+echo "╚═══════════════════════════════════════════════════════════════════╝"
+echo ""
+echo "Workflow:"
+echo "  feature-branch (local)"
+echo "  ↓"
+echo "  pre-push hook → lint + typecheck (~5s)"
+echo "  ↓"
+echo "  push to origin/feature-branch"
+echo "  ↓"
+echo "  gh pr create --base dev"
+echo "  ↓"
+echo "  CI runs tests on PR branch"
+echo "  ↓"
+echo "  gh pr merge --auto --squash → enters merge queue"
+echo "  ↓"
+echo "  Queue rebases PR on latest dev + runs CI again"
+echo "  ↓"
+echo "  Merge to dev (only if CI passes on rebased code)"
+echo ""
+echo "Release workflow:"
+echo "  gh pr create --base main --head dev --title \"Release\""
+echo "  → CI passes → merge → semantic-release publishes"
+echo ""

package/scripts/test-install.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# Test zeroshot installation on any platform
+# Run: ./scripts/test-install.sh
+
+set -e
+
+echo "=== Zeroshot Install Test ==="
+echo "Platform: $(uname -s) $(uname -m)"
+echo "Node: $(node --version)"
+echo "npm: $(npm --version)"
+echo ""
+
+echo "1. Installing dependencies..."
+npm install
+
+echo ""
+echo "2. Linking CLI..."
+npm link
+
+echo ""
+echo "3. Testing CLI commands..."
+
+echo "   zeroshot --version"
+zeroshot --version
+
+echo ""
+echo "   zeroshot --help"
+zeroshot --help | head -20
+
+echo ""
+echo "   zeroshot list"
+zeroshot list 2>/dev/null || echo "   (no clusters yet - this is expected)"
+
+echo ""
+echo "   zeroshot config list"
+zeroshot config list
+
+echo ""
+echo "=== ALL TESTS PASSED ==="
+echo "Zeroshot installed successfully on $(uname -s)!"

package/scripts/validate-templates.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * Validate all cluster templates for config errors
+ * Run in CI to prevent broken templates from being merged
+ *
+ * Usage: node scripts/validate-templates.js
+ * Exit codes: 0 = all valid, 1 = validation errors found
+ */
+
+const path = require('path');
+const { validateTemplates } = require('../src/template-validation');
+
+const TEMPLATES_DIR = path.join(__dirname, '../cluster-templates');
+
+function parseArgs(argv) {
+  const simModeArg = argv.find((arg) => arg.startsWith('--sim='));
+  const simMode = simModeArg ? simModeArg.split('=')[1] : process.env.ZEROSHOT_TEMPLATE_SIM;
+  const randomScopeArg = argv.find((arg) => arg.startsWith('--random-scope='));
+  const randomScope = randomScopeArg
+    ? randomScopeArg.split('=')[1]
+    : process.env.ZEROSHOT_TEMPLATE_RANDOM_SCOPE || 'resolved';
+  const samplesArg = argv.find((arg) => arg.startsWith('--samples='));
+  const sampleStepsArg = argv.find((arg) => arg.startsWith('--sample-steps='));
+  const sampleMsArg = argv.find((arg) => arg.startsWith('--sample-ms='));
+
+  const sampleCount = Number(
+    samplesArg ? samplesArg.split('=')[1] : process.env.ZEROSHOT_TEMPLATE_SIM_SAMPLES
+  );
+  const sampleSteps = Number(
+    sampleStepsArg ? sampleStepsArg.split('=')[1] : process.env.ZEROSHOT_TEMPLATE_SIM_STEPS
+  );
+  const sampleMs = Number(
+    sampleMsArg ? sampleMsArg.split('=')[1] : process.env.ZEROSHOT_TEMPLATE_SIM_MS
+  );
+
+  const deep =
+    argv.includes('--deep') ||
+    argv.includes('--sim=deep') ||
+    simMode === 'deep' ||
+    simMode === 'all';
+  const randomSampling = argv.includes('--sim=random') || simMode === 'random' || simMode === 'all';
+
+  return {
+    deep,
+    randomSampling,
+    randomScope,
+    randomOptions: {
+      samples: Number.isFinite(sampleCount) && sampleCount > 0 ? sampleCount : undefined,
+      maxSteps: Number.isFinite(sampleSteps) && sampleSteps > 0 ? sampleSteps : undefined,
+      maxScenarioMs: Number.isFinite(sampleMs) && sampleMs > 0 ? sampleMs : undefined,
+    },
+  };
+}
+
+async function main() {
+  console.log('Validating cluster templates...\n');
+
+  const { deep, randomSampling, randomScope, randomOptions } = parseArgs(process.argv.slice(2));
+  const report = await validateTemplates({
+    templatesDir: TEMPLATES_DIR,
+    deep,
+    randomSampling,
+    randomScope,
+    randomOptions,
+  });
+
+  let hasErrors = false;
+
+  for (const { filePath, result } of report.results) {
+    const relativePath = path.relative(process.cwd(), filePath);
+
+    if (!result.valid) {
+      hasErrors = true;
+      console.error(`\n❌ ${relativePath}`);
+      for (const error of result.errors) {
+        console.error(`   ERROR: ${error}`);
+      }
+      continue;
+    }
+
+    if (result.warnings.length > 0) {
+      console.warn(`\n⚠️  ${relativePath}`);
+      for (const warning of result.warnings) {
+        console.warn(`   WARN: ${warning}`);
+      }
+      continue;
+    }
+
+    console.log(`✓ ${relativePath}`);
+  }
+
+  console.log(`\n${'='.repeat(60)}`);
+  console.log(`Validated: ${report.validated} templates, Skipped: ${report.skipped} files`);
+
+  if (hasErrors) {
+    console.error('\n❌ VALIDATION FAILED - Fix errors above before merging\n');
+    process.exit(1);
+  } else {
+    console.log('\n✓ All templates valid\n');
+    process.exit(0);
+  }
+}
+
+main().catch((err) => {
+  console.error(`\n❌ Template validation crashed: ${err.message}\n`);
+  process.exit(1);
+});