chadstart 1.0.1 → 1.0.3

package/.env.example

@@ -53,3 +53,23 @@ TOKEN_SECRET_KEY=replace-with-a-long-random-secret
 # 💡 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
+
+# Optional: OAuth / Social Login (powered by grant)
+# For each provider, set OAUTH_<PROVIDER>_KEY and OAUTH_<PROVIDER>_SECRET.
+# Provider names must be uppercase (e.g. GOOGLE, GITHUB, FACEBOOK).
+# See docs/oauth.md for the full list of 200+ supported providers.
+#
+# OAUTH_GOOGLE_KEY=your-google-client-id
+# OAUTH_GOOGLE_SECRET=your-google-client-secret
+# OAUTH_GITHUB_KEY=your-github-client-id
+# OAUTH_GITHUB_SECRET=your-github-client-secret
+# OAUTH_FACEBOOK_KEY=your-facebook-app-id
+# OAUTH_FACEBOOK_SECRET=your-facebook-app-secret
+# OAUTH_DISCORD_KEY=your-discord-client-id
+# OAUTH_DISCORD_SECRET=your-discord-client-secret
+# OAUTH_APPLE_KEY=your-apple-client-id
+# OAUTH_APPLE_SECRET=your-apple-client-secret
+# OAUTH_MICROSOFT_KEY=your-microsoft-client-id
+# OAUTH_MICROSOFT_SECRET=your-microsoft-client-secret
+# OAUTH_TWITTER_KEY=your-twitter-api-key
+# OAUTH_TWITTER_SECRET=your-twitter-api-secret

package/chadstart.example.yml

@@ -414,3 +414,55 @@ sentry:
   environment: production     # Label sent to Sentry. Defaults to NODE_ENV.
   tracesSampleRate: 1.0       # Fraction of transactions to sample (0.0–1.0)
   debug: false                # Enable Sentry SDK debug logging
+
+# ── OAuth / Social Login ─────────────────────────────────────────────────────
+# Powered by the "grant" library — supports 200+ OAuth providers.
+# Secrets (client keys / secrets) MUST be set via environment variables:
+#   OAUTH_<PROVIDER>_KEY    — client / app ID
+#   OAUTH_<PROVIDER>_SECRET — client / app secret
+# See docs/oauth.md for the full provider list and setup guides.
+
+oauth:
+  # Which authenticable entity to create/find users in (default: first authenticable entity).
+  entity: User
+
+  # Where to redirect after successful login. The JWT token is appended as ?token=...
+  # If omitted, the callback returns JSON instead.
+  successRedirect: /login?success=true
+
+  # Where to redirect on error. The error message is appended as ?error=...
+  errorRedirect: /login?error=true
+
+  # Default settings applied to all providers.
+  defaults:
+    transport: querystring
+
+  # Configure each provider you want to support.
+  # The provider names must match grant's provider names (lowercase).
+  # Full list: https://github.com/simov/grant#200-supported-providers
+  providers:
+    google:
+      scope:
+        - openid
+        - email
+        - profile
+      custom_params:
+        access_type: offline
+      # key and secret via: OAUTH_GOOGLE_KEY, OAUTH_GOOGLE_SECRET
+
+    github:
+      scope:
+        - user:email
+      # key and secret via: OAUTH_GITHUB_KEY, OAUTH_GITHUB_SECRET
+
+    # facebook:
+    #   scope:
+    #     - email
+    #     - public_profile
+    #   key and secret via: OAUTH_FACEBOOK_KEY, OAUTH_FACEBOOK_SECRET
+
+    # discord:
+    #   scope:
+    #     - identify
+    #     - email
+    #   key and secret via: OAUTH_DISCORD_KEY, OAUTH_DISCORD_SECRET

package/chadstart.schema.json

@@ -124,6 +124,43 @@
           "description": "Enable Sentry SDK debug logging."
         }
       }
+    },
+    "oauth": {
+      "type": "object",
+      "description": "OAuth / social login configuration powered by the grant library. Secrets (client keys and secrets) must be supplied via OAUTH_<PROVIDER>_KEY and OAUTH_<PROVIDER>_SECRET environment variables.",
+      "additionalProperties": false,
+      "properties": {
+        "entity": {
+          "type": "string",
+          "description": "Name of the authenticable entity to use for OAuth users (e.g. 'User'). Defaults to the first authenticable entity."
+        },
+        "successRedirect": {
+          "type": "string",
+          "description": "URL to redirect to after successful OAuth login. The JWT token is appended as a ?token= query parameter. If omitted, returns JSON."
+        },
+        "errorRedirect": {
+          "type": "string",
+          "description": "URL to redirect to on OAuth error. The error message is appended as an ?error= query parameter. If omitted, returns JSON error."
+        },
+        "defaults": {
+          "type": "object",
+          "description": "Default settings applied to all providers (e.g. transport, scope).",
+          "properties": {
+            "transport": {
+              "type": "string",
+              "enum": ["querystring", "session"],
+              "default": "querystring"
+            }
+          }
+        },
+        "providers": {
+          "type": "object",
+          "description": "Map of OAuth provider names to their configuration. Provider names must match grant's supported provider list (e.g. google, github, facebook). See https://www.npmjs.com/package/grant for all 200+ supported providers.",
+          "additionalProperties": {
+            "$ref": "#/$defs/oauthProvider"
+          }
+        }
+      }
     }
   },
   "$defs": {
@@ -362,6 +399,31 @@
         "limit": { "type": "integer", "description": "Maximum number of requests allowed in the time window." },
         "ttl":   { "type": "integer", "description": "Time window in milliseconds." }
       }
+    },
+    "oauthProvider": {
+      "type": "object",
+      "description": "Configuration for a single OAuth provider. The key and secret should be set via OAUTH_<PROVIDER>_KEY and OAUTH_<PROVIDER>_SECRET environment variables.",
+      "properties": {
+        "key":            { "type": "string", "description": "OAuth client/app ID. Prefer using OAUTH_<PROVIDER>_KEY env var instead." },
+        "secret":         { "type": "string", "description": "OAuth client/app secret. Prefer using OAUTH_<PROVIDER>_SECRET env var instead." },
+        "scope":          {
+          "oneOf": [
+            { "type": "string" },
+            { "type": "array", "items": { "type": "string" } }
+          ],
+          "description": "OAuth scopes to request (e.g. 'openid email profile')."
+        },
+        "callback":       { "type": "string", "description": "Custom callback URL path. Defaults to /api/auth/oauth/callback." },
+        "custom_params":  { "type": "object", "description": "Extra query parameters to send to the authorization URL." },
+        "subdomain":      { "type": "string", "description": "Subdomain for providers that require one (e.g. Shopify)." },
+        "nonce":          { "type": "boolean", "description": "Enable nonce generation (required by some OIDC providers)." },
+        "pkce":           { "type": "boolean", "description": "Enable PKCE (Proof Key for Code Exchange) for enhanced security." },
+        "response":       {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Data to include in the callback (e.g. ['tokens', 'profile'])."
+        }
+      }
     }
   }
 }

package/cli/cli.js

@@ -14,19 +14,26 @@ function printUsage() {
 ChadStart - YAML-first Backend as a Service
 
 Usage:
-  npx chadstart dev     Start server with hot-reload on YAML changes
-  npx chadstart start   Start server (production mode)
-  npx chadstart build   Validate YAML config and print schema summary
-  npx chadstart seed    Seed the database with dummy data
+  npx chadstart dev               Start server with hot-reload on YAML changes
+  npx chadstart start             Start server (production mode)
+  npx chadstart build             Validate YAML config and print schema summary
+  npx chadstart seed              Seed the database with dummy data
+  npx chadstart migrate           Run pending database migrations
+  npx chadstart migrate:generate  Generate migration from YAML diff (git-based)
+  npx chadstart migrate:status    Show current migration status
 
 Options:
-  --config <file>   Path to YAML config (default: chadstart.yaml)
-  --port <number>   Override port from config
+  --config <file>         Path to YAML config (default: chadstart.yaml)
+  --port <number>         Override port from config
+  --migrations-dir <dir>  Path to migrations directory (default: migrations)
+  --description <text>    Description for generated migration
 
 Examples:
   npx chadstart dev
   npx chadstart dev --config my-backend.yaml
   npx chadstart start --port 8080
+  npx chadstart migrate:generate --description add-posts-table
+  npx chadstart migrate
 `);
 }
 
@@ -53,6 +60,12 @@ if (command === 'create') {
   runBuild();
 } else if (command === 'seed') {
   runSeed();
+} else if (command === 'migrate') {
+  runMigrate();
+} else if (command === 'migrate:generate') {
+  runMigrateGenerate();
+} else if (command === 'migrate:status') {
+  runMigrateStatus();
 } else {
   console.error(`Unknown command: ${command}`);
   printUsage();
@@ -273,6 +286,122 @@ function runBuild() {
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
+const migrationsDir = path.resolve(getOption('--migrations-dir') || 'migrations');
+const migrationDescription = getOption('--description') || null;
+
+async function runMigrate() {
+  if (!fs.existsSync(yamlPath)) {
+    console.error(`Config not found: ${yamlPath}`);
+    process.exit(1);
+  }
+
+  try {
+    const { loadYaml } = require('../core/yaml-loader');
+    const { validateSchema } = require('../core/schema-validator');
+    const { buildCore } = require('../core/entity-engine');
+    const { initDb, closeDb } = require('../core/db');
+    const { runMigrations, buildExecQueryFn } = require('../core/migrations');
+    const dbModule = require('../core/db');
+
+    const config = loadYaml(yamlPath);
+    validateSchema(config);
+    const core = buildCore(config);
+    await initDb(core);
+
+    console.log('\n🔄 Running database migrations...\n');
+
+    const execQueryFn = buildExecQueryFn(dbModule);
+
+    const applied = await runMigrations(migrationsDir, execQueryFn);
+
+    if (applied.length === 0) {
+      console.log('  ✅ Database is up to date — no pending migrations.\n');
+    } else {
+      for (const m of applied) {
+        console.log(`  ✅ Applied: ${m.version}.${m.action}${m.name ? '.' + m.name : ''}`);
+      }
+      console.log(`\n  ${applied.length} migration${applied.length !== 1 ? 's' : ''} applied.\n`);
+    }
+
+    await closeDb();
+  } catch (err) {
+    console.error(`\n❌ ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+async function runMigrateGenerate() {
+  if (!fs.existsSync(yamlPath)) {
+    console.error(`Config not found: ${yamlPath}`);
+    process.exit(1);
+  }
+
+  try {
+    const { generateMigration } = require('../core/migrations');
+
+    console.log('\n📝 Generating migration from YAML diff...\n');
+
+    const result = generateMigration(yamlPath, migrationsDir, migrationDescription);
+
+    if (result.isEmpty) {
+      console.log('  ℹ️  No schema changes detected — nothing to generate.\n');
+    } else {
+      console.log(`  ✅ Migration v${String(result.version).padStart(3, '0')} generated:`);
+      console.log(`     DO:   ${result.doPath}`);
+      console.log(`     UNDO: ${result.undoPath}`);
+      console.log('\n  Run `npx chadstart migrate` to apply.\n');
+    }
+  } catch (err) {
+    console.error(`\n❌ ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+async function runMigrateStatus() {
+  if (!fs.existsSync(yamlPath)) {
+    console.error(`Config not found: ${yamlPath}`);
+    process.exit(1);
+  }
+
+  try {
+    const { loadYaml } = require('../core/yaml-loader');
+    const { validateSchema } = require('../core/schema-validator');
+    const { buildCore } = require('../core/entity-engine');
+    const { initDb, closeDb } = require('../core/db');
+    const { getMigrationStatus, buildExecQueryFn } = require('../core/migrations');
+    const dbModule = require('../core/db');
+
+    const config = loadYaml(yamlPath);
+    validateSchema(config);
+    const core = buildCore(config);
+    await initDb(core);
+
+    const execQueryFn = buildExecQueryFn(dbModule);
+
+    const status = await getMigrationStatus(migrationsDir, execQueryFn);
+
+    console.log(`\n📊 Migration Status\n`);
+    console.log(`  Current version: ${status.currentVersion}`);
+    console.log(`  Applied:         ${status.applied.length}`);
+    console.log(`  Pending:         ${status.pending.length}`);
+
+    if (status.pending.length > 0) {
+      console.log('\n  Pending migrations:');
+      for (const m of status.pending) {
+        console.log(`    - ${m.version}.${m.action}${m.name ? '.' + m.name : ''}`);
+      }
+    }
+
+    console.log('');
+    await closeDb();
+  } catch (err) {
+    console.error(`\n❌ ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+// ─── Other helpers ───────────────────────────────────────────────────────────
+
 function applyPortOverride() {
   if (portOverride) {
     process.env.CHADSTART_PORT = portOverride;

package/core/entity-engine.js

@@ -155,6 +155,7 @@ function buildCore(config) {
     port: parseInt(process.env.CHADSTART_PORT || process.env.PORT || config.port || 3000, 10),
     rateLimits,
     telemetry,
+    oauth: config.oauth || null,
     admin: {
       enable_app: adminCfg.enable_app !== false,
       enable_entity: adminCfg.enable_entity !== false,