Merge branch 'claude/postgres-quality-framework-FOIwg' into 'main'

Add PostgreSQL quality engineering framework

Closes #158

See merge request postgres-ai/postgresai!231

Author: Sarumyan

.claude/CLAUDE.md

@@ -17,6 +17,10 @@ git submodule update --remote .cursor
 
 - **README.md** — Project overview, features, and quick start
 - **CONTRIBUTING.md** — Local development workflow, Docker setup, debugging
+- **quality/QUALITY_ENGINEERING_GUIDE.md** — Quality standards, processes, automated gates
+- **quality/pr-review-prompt.md** — AI PR review system prompt (PostgreSQL-specific)
+- **quality/failure-modes.md** — Critical failure modes with required test coverage
+- **quality/checklists/** — PR review and release checklists
 
 ### Commands
 
@@ -44,3 +48,15 @@ postgresai mon local-install --demo
 | H004 | Redundant indexes |
 | F004 | Table bloat |
 | K003 | Top queries |
+
+## Quality
+
+```bash
+# Run release readiness check
+./quality/scripts/release-readiness.sh
+
+# Full check (includes integration tests)
+./quality/scripts/release-readiness.sh --full
+```
+
+See `quality/QUALITY_ENGINEERING_GUIDE.md` for the full quality framework.

.gitlab-ci.yml

@@ -1,5 +1,6 @@
 include:
   - local: 'components/index_pilot/.gitlab-ci.yml'
+  - local: 'quality/gitlab-ci-quality.yml'
   - template: Security/SAST.gitlab-ci.yml
   - project: 'postgres-ai/infra'
     file: '/ci/templates/approval-check.yml'

.pre-commit-config.yaml

@@ -3,3 +3,42 @@ repos:
     rev: v8.30.0
     hooks:
       - id: gitleaks
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      # Prevent large files from being committed
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+      # Ensure JSON files are valid
+      - id: check-json
+      # Ensure YAML files are valid
+      - id: check-yaml
+        args: ['--allow-multiple-documents']
+      # Prevent committing to main directly
+      - id: no-commit-to-branch
+        args: ['--branch', 'main']
+      # Ensure files end with newline
+      - id: end-of-file-fixer
+      # Remove trailing whitespace
+      - id: trailing-whitespace
+        args: ['--markdown-linebreak-ext=md']
+
+  - repo: local
+    hooks:
+      # Catch potential SQL injection patterns in TypeScript
+      - id: sql-injection-check
+        name: SQL injection check (TypeScript)
+        entry: bash -c 'grep -rn --include="*.ts" -E "(\`SELECT|\`INSERT|\`UPDATE|\`DELETE|\`DROP|\`ALTER|\`CREATE).*\$\{" "$@" && echo "ERROR: Possible SQL injection — use parameterized queries" && exit 1 || exit 0' --
+        language: system
+        files: '\.(ts|js)$'
+        exclude: '(test|spec|__tests__)'
+        pass_filenames: false
+
+      # Verify JSON schemas are valid
+      - id: validate-schemas
+        name: Validate JSON schemas
+        entry: python3 -c "import json, sys; [json.load(open(f)) for f in sys.argv[1:]]"
+        language: system
+        files: '\.schema\.json$'
+        types: [json]

cli/bin/postgres-ai.ts

@@ -2452,16 +2452,20 @@ mon
 
         // Test connection
         console.log("Testing connection to the added instance...");
-        try {
-          const client = new Client({ connectionString: connStr });
-          await client.connect();
-          const result = await client.query("select version();");
-          console.log("✓ Connection successful");
-          console.log(`${result.rows[0].version}\n`);
-          await client.end();
-        } catch (error) {
-          const message = error instanceof Error ? error.message : String(error);
-          console.error(`✗ Connection failed: ${message}\n`);
+        {
+          let testClient: InstanceType<typeof Client> | null = null;
+          try {
+            testClient = new Client({ connectionString: connStr, connectionTimeoutMillis: 10000 });
+            await testClient.connect();
+            const result = await testClient.query("select version();");
+            console.log("✓ Connection successful");
+            console.log(`${result.rows[0].version}\n`);
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`✗ Connection failed: ${message}\n`);
+          } finally {
+            if (testClient) await testClient.end();
+          }
         }
       } else if (opts.yes) {
         // Auto-yes mode without database URL - skip database setup
@@ -2496,16 +2500,20 @@ mon
 
               // Test connection
               console.log("Testing connection to the added instance...");
-              try {
-                const client = new Client({ connectionString: connStr });
-                await client.connect();
-                const result = await client.query("select version();");
-                console.log("✓ Connection successful");
-                console.log(`${result.rows[0].version}\n`);
-                await client.end();
-              } catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                console.error(`✗ Connection failed: ${message}\n`);
+              {
+                let testClient: InstanceType<typeof Client> | null = null;
+                try {
+                  testClient = new Client({ connectionString: connStr, connectionTimeoutMillis: 10000 });
+                  await testClient.connect();
+                  const result = await testClient.query("select version();");
+                  console.log("✓ Connection successful");
+                  console.log(`${result.rows[0].version}\n`);
+                } catch (error) {
+                  const message = error instanceof Error ? error.message : String(error);
+                  console.error(`✗ Connection failed: ${message}\n`);
+                } finally {
+                  if (testClient) await testClient.end();
+                }
               }
             }
           } else {
@@ -3292,7 +3300,7 @@ targets
       console.log(`Testing connection to monitoring target '${name}'...`);
 
       // Use native pg client instead of requiring psql to be installed
-      const client = new Client({ connectionString: instance.conn_str });
+      const client = new Client({ connectionString: instance.conn_str, connectionTimeoutMillis: 10000 });
 
       try {
         await client.connect();

cli/lib/init.ts

@@ -127,8 +127,10 @@ export async function connectWithSslFallback(
   verbose?: boolean
 ): Promise<{ client: PgClient; usedSsl: boolean }> {
   const tryConnect = async (config: PgClientConfig): Promise<PgClient> => {
-    const client = new ClientClass(config);
+    const client = new ClientClass({ ...config, connectionTimeoutMillis: 10_000 } as any);
     await client.connect();
+    // Set a default statement timeout to prevent runaway queries
+    await client.query("SET statement_timeout = '30s'");
     return client;
   };
 
@@ -454,8 +456,18 @@ export function resolveAdminConnection(opts: {
   return { clientConfig: cfg, display: describePgConfig(cfg), sslFallbackEnabled: true };
 }
 
+/**
+ * Generate a cryptographically secure random password for the monitoring role.
+ *
+ * Encoding note — bytes vs output length:
+ *   - hex:      N bytes → 2N characters  (24 bytes → 48 hex chars)
+ *   - base64:   N bytes → ⌈4N/3⌉ chars   (24 bytes → 32 base64url chars, no padding)
+ *
+ * We use base64url (RFC 4648 §5) because it is shorter than hex and safe in URLs,
+ * connection strings, and shell variables without quoting.
+ */
 function generateMonitoringPassword(): string {
-  // URL-safe and easy to copy/paste; 24 bytes => 32 base64url chars (no padding).
+  // 24 random bytes → 32 base64url characters (no padding).
   // Note: randomBytes() throws on failure; we add a tiny sanity check for unexpected output.
   const password = randomBytes(24).toString("base64url");
   if (password.length < 30) {

cli/test/init.test.ts

@@ -1314,3 +1314,56 @@ describe.skipIf(!dockerAvailable)("imageTag priority behavior", () => {
     expect(envContent).toMatch(/GF_SECURITY_ADMIN_PASSWORD=secret123/);
   }, 60000);
 });
+
+// ---------------------------------------------------------------------------
+// connectWithSslFallback — connectionTimeoutMillis and statement_timeout
+// Issues 9 & 10
+// ---------------------------------------------------------------------------
+describe("connectWithSslFallback", () => {
+  // Issue 9: Verify that connectionTimeoutMillis is forwarded to the pg Client
+  // constructor so slow-responding servers don't hang the CLI indefinitely.
+  // Direct integration testing against a real TCP timeout would be flaky in CI,
+  // so we use a mock ClientClass and assert the config passed to its constructor.
+  test("passes connectionTimeoutMillis: 10_000 to the pg Client constructor", async () => {
+    const receivedConfigs: any[] = [];
+
+    class MockClient {
+      constructor(config: any) {
+        receivedConfigs.push(config);
+      }
+      async connect() {}
+      async query() { return {}; }
+    }
+
+    const adminConn = init.resolveAdminConnection({ conn: "postgresql://u:p@localhost:5432/d" });
+    // Disable SSL fallback so we exercise the simple (non-retry) path.
+    (adminConn as any).sslFallbackEnabled = false;
+
+    await init.connectWithSslFallback(MockClient as any, adminConn);
+
+    expect(receivedConfigs.length).toBeGreaterThanOrEqual(1);
+    expect(receivedConfigs[0].connectionTimeoutMillis).toBe(10_000);
+  });
+
+  // Issue 10: Verify that SET statement_timeout is issued after every successful
+  // connection to prevent runaway queries from blocking the CLI.
+  test("issues SET statement_timeout = '30s' after connecting", async () => {
+    const queriesSent: string[] = [];
+
+    class MockClient {
+      constructor(_config: any) {}
+      async connect() {}
+      async query(sql: string) {
+        queriesSent.push(sql);
+        return {};
+      }
+    }
+
+    const adminConn = init.resolveAdminConnection({ conn: "postgresql://u:p@localhost:5432/d" });
+    (adminConn as any).sslFallbackEnabled = false;
+
+    await init.connectWithSslFallback(MockClient as any, adminConn);
+
+    expect(queriesSent.some((q) => /SET\s+statement_timeout/i.test(q))).toBe(true);
+  });
+});