chadstart 1.0.0

package/core/functions-engine.js

@@ -0,0 +1,353 @@
+'use strict';
+
+/**
+ * ChadStart Functions Engine
+ *
+ * Supports multiple runtimes (js, bash, python, go, c++, ruby, php),
+ * multiple trigger types (http, event, cron), and multiple JS formats
+ * (universal, aws lambda, cloudflare workers).
+ * Scripted runtimes (python, ruby, php) use persistent worker processes.
+ */
+
+const path    = require('path');
+const fs      = require('fs');
+const { EventEmitter } = require('events');
+const { execa } = require('execa');
+const cron    = require('node-cron');
+const logger  = require('../utils/logger');
+
+// ── Predefined cron schedule aliases ──────────────────────────────────────────
+const PREDEFINED = {
+  '@yearly':   '0 0 1 1 *',
+  '@annually': '0 0 1 1 *',
+  '@monthly':  '0 0 1 * *',
+  '@weekly':   '0 0 * * 0',
+  '@daily':    '0 0 * * *',
+  '@midnight': '0 0 * * *',
+  '@hourly':   '0 * * * *',
+};
+
+const SUPPORTED_RUNTIMES = new Set(['js', 'bash', 'python', 'go', 'c++', 'ruby', 'php']);
+
+function resolveSchedule(s) {
+  return PREDEFINED[s] || s;
+}
+
+// ── Shared event bus ───────────────────────────────────────────────────────────
+const eventBus = new EventEmitter();
+eventBus.setMaxListeners(100);
+
+// ── Worker process pool (one process per runtime) ─────────────────────────────
+const _workers = new Map();
+
+function getWorkerScript(runtime) {
+  const dir = path.join(__dirname, 'workers');
+  const map = {
+    python: path.join(dir, 'python_worker.py'),
+    ruby:   path.join(dir, 'ruby_worker.rb'),
+    php:    path.join(dir, 'php_worker.php'),
+  };
+  return map[runtime] || null;
+}
+
+function getRuntimeCmd(runtime) {
+  const cmds = { python: 'python3', ruby: 'ruby', php: 'php' };
+  return cmds[runtime] || runtime;
+}
+
+/**
+ * Get (or spawn) a persistent worker process for the given runtime.
+ * Returns null for runtimes that don't use persistent workers.
+ */
+function getWorker(runtime) {
+  if (_workers.has(runtime)) return _workers.get(runtime);
+
+  const script = getWorkerScript(runtime);
+  if (!script) return null;
+
+  const proc = execa(getRuntimeCmd(runtime), [script], {
+    stdin: 'pipe',
+    stdout: 'pipe',
+    stderr: 'pipe',
+    buffer: false,
+    reject: false,
+  });
+
+  let buf = '';
+  const pending = new Map();
+  let idCounter  = 0;
+
+  proc.stdout.on('data', (chunk) => {
+    buf += chunk.toString();
+    let nl;
+    while ((nl = buf.indexOf('\n')) !== -1) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (!line) continue;
+      try {
+        const msg = JSON.parse(line);
+        const p = pending.get(msg.id);
+        if (p) {
+          pending.delete(msg.id);
+          if (msg.error) p.reject(new Error(msg.error));
+          else p.resolve(msg.result);
+        }
+      } catch { /* ignore parse errors */ }
+    }
+  });
+
+  proc.stderr.on('data', (d) => logger.warn(`[${runtime} worker] ${d.toString().trim()}`));
+
+  proc.on('close', () => {
+    _workers.delete(runtime);
+    for (const p of pending.values()) p.reject(new Error(`${runtime} worker exited`));
+    pending.clear();
+    logger.warn(`[functions] ${runtime} worker exited — will restart on next invocation`);
+  });
+
+  const worker = {
+    invoke(entry, event, ctx) {
+      return new Promise((resolve, reject) => {
+        const id = ++idCounter;
+        pending.set(id, { resolve, reject });
+        proc.stdin.write(JSON.stringify({ id, entry, event, ctx }) + '\n');
+      });
+    },
+    proc,
+  };
+
+  _workers.set(runtime, worker);
+  return worker;
+}
+
+// ── JS function format adapters ───────────────────────────────────────────────
+
+/**
+ * Load a JS module with cache-busting for hot reload.
+ * Returns a normalised object with `default` and/or `handler` properties.
+ */
+function loadJsModule(entry) {
+  delete require.cache[require.resolve(entry)];
+  const raw = require(entry);
+  const mod = (raw && typeof raw === 'object') ? raw : { default: raw };
+  if (!mod.default && typeof raw === 'function') mod.default = raw;
+  return mod;
+}
+
+/**
+ * Run a JS function — auto-detects format: Universal, AWS Lambda, Cloudflare Workers.
+ * Called as fn(event, ctx) for Universal; module.handler(event, {}) for Lambda;
+ * module.default.fetch(request) for Cloudflare Workers.
+ */
+async function runJsFunction(entry, event, ctx) {
+  const mod = loadJsModule(entry);
+
+  // Resolve the primary callable; handle module.exports = { default: fn } (CJS wrapped default)
+  let defaultExport = mod.default;
+  if (defaultExport && typeof defaultExport !== 'function' && typeof defaultExport.default === 'function') {
+    defaultExport = defaultExport.default;
+  }
+
+  // 1. Cloudflare / edge style: { default: { fetch(request) } }
+  if (defaultExport && typeof defaultExport.fetch === 'function') {
+    const req = event.request || new Request(`http://localhost${ctx.path || '/'}`);
+    const result = await defaultExport.fetch(req);
+    return result.json ? await result.json() : await result.text();
+  }
+
+  // 2. AWS Lambda style: exports.handler (named export, not default)
+  if (typeof mod.handler === 'function') {
+    const result = await mod.handler(event, {});
+    if (result && result.body) { try { return JSON.parse(result.body); } catch { return result.body; } }
+    return result;
+  }
+
+  // 3. Universal: default export called as fn(event, ctx)
+  if (typeof defaultExport === 'function') {
+    return defaultExport(event, ctx);
+  }
+
+  throw new Error(`No recognised export in ${entry}`);
+}
+
+// ── External runtime invocation ───────────────────────────────────────────────
+
+async function runExternal(runtime, entry, event, ctx) {
+  // Strip the Express request object — it has circular references and cannot be
+  // serialised to JSON. The serialised event still contains body, query, params,
+  // and headers, which are all a function needs to handle the request.
+  const { req: _req, ...safeEvent } = (event || {});
+
+  const worker = getWorker(runtime);
+  if (worker) return worker.invoke(entry, safeEvent, ctx);
+
+  const input = JSON.stringify({ event: safeEvent, ctx });
+  const ts = Date.now();
+  const safeEntry = entry.replace(/'/g, "'\\''"); // single-quote escape for shell
+  const cmds = {
+    bash: ['bash', [entry]],
+    go:   ['go', ['run', entry]],
+    'c++': ['sh', ['-c', `g++ -o /tmp/cs_fn_${ts} '${safeEntry}' && /tmp/cs_fn_${ts}`]],
+  };
+
+  if (!cmds[runtime]) throw new Error(`No command mapping for runtime: "${runtime}"`);
+  const [cmd, args] = cmds[runtime];
+  try {
+    const { stdout } = await execa(cmd, args, { input, reject: false });
+    return JSON.parse(stdout);
+  } catch (e) {
+    throw new Error(`${runtime} runtime error: ${e.message}`);
+  }
+}
+
+// ── Unified function runner ────────────────────────────────────────────────────
+
+function resolveFnEntry(fnFile) {
+  const entry = path.resolve(process.env.CHADSTART_FUNCTIONS_FOLDER || 'functions', fnFile);
+  return fs.existsSync(entry) ? entry : null;
+}
+
+async function runFunction(fn, event, ctx) {
+  const runtime = fn.runtime || 'js';
+  if (!SUPPORTED_RUNTIMES.has(runtime)) throw new Error(`Unsupported runtime: "${runtime}"`);
+  const entry = resolveFnEntry(fn.function);
+  if (!entry) {
+    logger.warn(`Function file not found: ${fn.function}`);
+    return { error: `Function not found: ${fn.function}` };
+  }
+  if (runtime === 'js') return runJsFunction(entry, event, ctx);
+  return runExternal(runtime, entry, event, ctx);
+}
+
+// ── Trigger registration ──────────────────────────────────────────────────────
+
+const _cronTasks = [];
+
+/** Register all function triggers on the Express app. */
+function setupFunctions(app, functions) {
+  if (!functions || !Object.keys(functions).length) return;
+  for (const [name, fn] of Object.entries(functions)) {
+    for (const trigger of (fn.triggers || [])) {
+      registerTrigger(app, name, fn, trigger);
+    }
+  }
+}
+
+/** Stop all active cron tasks and worker processes (call before hot reload). */
+function cleanup() {
+  for (const task of _cronTasks) { try { task.stop(); } catch { /* */ } }
+  _cronTasks.length = 0;
+  for (const [, w] of _workers) { try { w.proc.kill(); } catch { /* */ } }
+  _workers.clear();
+}
+
+function registerTrigger(app, name, fn, trigger) {
+  switch (trigger.type) {
+    case 'http':  registerHttp(app, name, fn, trigger);  break;
+    case 'cron':  registerCron(name, fn, trigger);        break;
+    case 'event': registerEvent(name, fn, trigger);       break;
+    default: logger.warn(`[functions] Unknown trigger type "${trigger.type}" for "${name}"`);
+  }
+}
+
+function registerHttp(app, name, fn, trigger) {
+  const method = (trigger.method || 'GET').toLowerCase();
+  const epPath = trigger.path;
+  const middlewares = buildPolicyMiddlewares(trigger.policies);
+
+  app[method](epPath, ...middlewares, async (req, res) => {
+    const entry = resolveFnEntry(fn.function);
+    if (!entry) {
+      logger.warn(`[functions] File not found for "${name}": ${fn.function}`);
+      return res.status(404).json({ error: `Function not found: ${fn.function}` });
+    }
+    try {
+      const event  = { req, body: req.body, query: req.query, params: req.params, headers: req.headers };
+      const ctx    = { trigger: 'http', method: req.method, path: epPath, name };
+      const result = await runFunction(fn, event, ctx);
+      if (!res.headersSent) {
+        if (result && typeof result === 'object') return res.json(result);
+        res.send(result ?? '');
+      }
+    } catch (e) {
+      logger.error(`[functions] ${name} http error: ${e.message}`);
+      if (!res.headersSent) res.status(500).json({ error: e.message });
+    }
+  });
+
+  logger.info(`  Registered function: ${trigger.method || 'GET'} ${epPath} (${name})`);
+}
+
+// ── Policy middleware for HTTP triggers ───────────────────────────────────────
+
+/**
+ * Build Express middleware array from a policies definition.
+ * With no policies (or `access: public`) the route is open to everyone.
+ * Supports: public | restricted | admin | forbidden
+ */
+function buildPolicyMiddlewares(policies) {
+  const { optionalAuth, requireAuth, JWT_SECRET } = require('./auth');
+  const jwt = require('jsonwebtoken');
+  if (!policies || !policies.length) return [optionalAuth];
+  const p = policies[0];
+  switch (p.access) {
+    case 'public':
+    case '🌐':
+      return [optionalAuth];
+    case 'restricted':
+    case '🔒': {
+      if (!p.allow) return [requireAuth()];
+      const allowed = Array.isArray(p.allow) ? p.allow : [p.allow];
+      return [(req, res, next) => {
+        const h = req.headers.authorization;
+        if (!h || !h.startsWith('Bearer ')) return res.status(401).json({ error: 'Authorization required' });
+        try {
+          req.user = jwt.verify(h.slice(7), JWT_SECRET);
+          if (!allowed.includes(req.user.entity)) return res.status(403).json({ error: 'Access denied' });
+          next();
+        } catch { res.status(401).json({ error: 'Invalid or expired token' }); }
+      }];
+    }
+    case 'admin':
+    case '👨🏻‍💻':
+      return [requireAuth()];
+    case 'forbidden':
+    case '🚫':
+      return [(_r, res) => res.status(403).json({ error: 'Access forbidden' })];
+    default:
+      return [optionalAuth];
+  }
+}
+
+function registerCron(name, fn, trigger) {
+  const schedule = resolveSchedule(trigger.schedule);
+  if (!cron.validate(schedule)) {
+    logger.warn(`[functions] Invalid cron schedule "${trigger.schedule}" for "${name}"`);
+    return;
+  }
+  const task = cron.schedule(schedule, async () => {
+    try {
+      await runFunction(fn, {}, { trigger: 'cron', schedule: trigger.schedule, name });
+    } catch (e) {
+      logger.error(`[functions] ${name} cron error: ${e.message}`);
+    }
+  });
+  _cronTasks.push(task);
+  logger.info(`  Registered cron: "${trigger.schedule}" → ${name}`);
+}
+
+function registerEvent(name, fn, trigger) {
+  const eventName = trigger.name || trigger.event;
+  if (!eventName) { logger.warn(`[functions] Event trigger for "${name}" has no name`); return; }
+  eventBus.on(eventName, async (payload) => {
+    try {
+      await runFunction(fn, payload || {}, { trigger: 'event', event: eventName, name });
+    } catch (e) {
+      logger.error(`[functions] ${name} event error: ${e.message}`);
+    }
+  });
+  logger.info(`  Registered event: "${eventName}" → ${name}`);
+}
+
+module.exports = { setupFunctions, cleanup, eventBus, resolveSchedule };
+

package/core/openapi.js

@@ -0,0 +1,171 @@
+'use strict';
+
+const OPENAPI_TYPE = {
+  text: 'string', string: 'string', richText: 'string',
+  integer: 'integer', int: 'integer',
+  number: 'number', float: 'number', real: 'number', money: 'number',
+  boolean: 'boolean', bool: 'boolean',
+  date: 'string', timestamp: 'string', email: 'string', link: 'string',
+  password: 'string', choice: 'string', location: 'string',
+  file: 'string', image: 'string', group: 'string', json: 'string',
+};
+
+function generateOpenApiSpec(core) {
+  const spec = {
+    openapi: '3.0.0',
+    info: { title: core.name, version: '1.0.0', description: `API generated by ChadStart for "${core.name}"` },
+    paths: {},
+    components: {
+      schemas: {},
+      securitySchemes: { bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' } },
+    },
+  };
+
+  // Auth endpoints for authenticable entities
+  for (const e of Object.values(core.authenticableEntities || {})) {
+    const slug = e.slug;
+    spec.components.schemas[e.name] = authSchema(e);
+    spec.components.schemas[`${e.name}Input`] = authInputSchema(e);
+    spec.components.schemas[`${e.name}LoginInput`] = loginSchema();
+    spec.components.schemas[`${e.name}AuthResponse`] = { type: 'object', properties: { token: { type: 'string' }, user: { $ref: `#/components/schemas/${e.name}` } } };
+
+    spec.paths[`/api/auth/${slug}/signup`] = { post: { tags: [`Auth – ${e.name}`], summary: `Sign up as ${e.name}`, requestBody: jsonBody(`${e.name}Input`), responses: { 201: jsonResp(e.name + 'AuthResponse'), 400: desc('Validation error'), 409: desc('Email already registered') } } };
+    spec.paths[`/api/auth/${slug}/login`]  = { post: { tags: [`Auth – ${e.name}`], summary: `Login as ${e.name}`, requestBody: jsonBody(`${e.name}LoginInput`), responses: { 200: jsonResp(e.name + 'AuthResponse'), 401: desc('Invalid credentials') } } };
+    spec.paths[`/api/auth/${slug}/me`]     = { get: { tags: [`Auth – ${e.name}`], summary: `Get current ${e.name}`, security: [{ bearerAuth: [] }], responses: { 200: jsonResp(e.name), 401: desc('Unauthorized') } } };
+  }
+
+  // Entity CRUD endpoints
+  for (const e of Object.values(core.entities)) {
+    const tag = e.name;
+    const sec = (rule) => hasSecurity(e, rule) ? { security: [{ bearerAuth: [] }] } : {};
+
+    if (!e.authenticable) {
+      spec.components.schemas[e.name] = entitySchema(e, core.entities);
+      spec.components.schemas[`${e.name}Input`] = entityInputSchema(e, core.entities);
+    }
+
+    if (e.single) {
+      const base = `/api/singles/${e.slug}`;
+      spec.paths[base] = {
+        get:   { tags: [tag], summary: `Get ${e.name}`, ...sec('read'), responses: { 200: jsonResp(e.name), 404: desc('Not Found') } },
+        put:   { tags: [tag], summary: `Replace ${e.name}`, ...sec('update'), requestBody: jsonBody(`${e.name}Input`), responses: { 200: jsonResp(e.name), 404: desc('Not Found') } },
+        patch: { tags: [tag], summary: `Update ${e.name}`, ...sec('update'), requestBody: jsonBody(`${e.name}Input`), responses: { 200: jsonResp(e.name), 404: desc('Not Found') } },
+      };
+    } else {
+      const base = `/api/collections/${e.slug}`;
+      const paginatedResp = {
+        description: 'OK',
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              properties: {
+                data: { type: 'array', items: { $ref: `#/components/schemas/${e.name}` } },
+                currentPage: { type: 'integer' },
+                lastPage: { type: 'integer' },
+                from: { type: 'integer' },
+                to: { type: 'integer' },
+                total: { type: 'integer' },
+                perPage: { type: 'integer' },
+              },
+            },
+          },
+        },
+      };
+
+      spec.paths[base] = {
+        get: {
+          tags: [tag],
+          summary: `List all ${e.name}s`,
+          ...sec('read'),
+          parameters: [
+            ...e.properties.filter((p) => !p.hidden).map((p) => ({ name: p.name, in: 'query', required: false, schema: { type: 'string' } })),
+            { name: 'page', in: 'query', schema: { type: 'integer', default: 1 } },
+            { name: 'perPage', in: 'query', schema: { type: 'integer', default: 10 } },
+            { name: 'orderBy', in: 'query', schema: { type: 'string' } },
+            { name: 'order', in: 'query', schema: { type: 'string', enum: ['ASC', 'DESC'] } },
+            { name: 'relations', in: 'query', schema: { type: 'string' }, description: 'Comma-separated relation names to load' },
+          ],
+          responses: { 200: paginatedResp },
+        },
+        post: { tags: [tag], summary: `Create a ${e.name}`, ...sec('create'), requestBody: jsonBody(`${e.name}Input`), responses: { 201: jsonResp(e.name), 400: desc('Bad Request') } },
+      };
+      spec.paths[`${base}/{id}`] = {
+        get:    { tags: [tag], summary: `Get ${e.name} by id`, ...sec('read'), parameters: [idParam()], responses: { 200: jsonResp(e.name), 404: desc('Not Found') } },
+        put:    { tags: [tag], summary: `Replace ${e.name}`, ...sec('update'), parameters: [idParam()], requestBody: jsonBody(`${e.name}Input`), responses: { 200: jsonResp(e.name), 404: desc('Not Found') } },
+        patch:  { tags: [tag], summary: `Update ${e.name}`, ...sec('update'), parameters: [idParam()], requestBody: jsonBody(`${e.name}Input`), responses: { 200: jsonResp(e.name), 404: desc('Not Found') } },
+        delete: { tags: [tag], summary: `Delete ${e.name}`, ...sec('delete'), parameters: [idParam()], responses: { 200: desc('Deleted'), 404: desc('Not Found') } },
+      };
+    }
+  }
+
+  // Custom functions
+  for (const [name, ep] of Object.entries(core.functions || {})) {
+    for (const trigger of (ep.triggers || []).filter((t) => t.type === 'http')) {
+      const method = (trigger.method || 'GET').toLowerCase();
+      spec.paths[trigger.path] = spec.paths[trigger.path] || {};
+      spec.paths[trigger.path][method] = { tags: ['Functions'], summary: ep.description || name, responses: { 200: desc('OK') } };
+    }
+  }
+
+  // File storage
+  for (const [bucket] of Object.entries(core.files || {})) {
+    spec.paths[`/files/${bucket}`] = { post: { tags: ['Files'], summary: `Upload to ${bucket}`, requestBody: { required: true, content: { 'multipart/form-data': { schema: { type: 'object', properties: { file: { type: 'string', format: 'binary' } } } } } }, responses: { 200: desc('Uploaded') } } };
+    spec.paths[`/files/${bucket}/{file}`] = { get: { tags: ['Files'], summary: `Download from ${bucket}`, parameters: [{ name: 'file', in: 'path', required: true, schema: { type: 'string' } }], responses: { 200: desc('File content'), 404: desc('Not Found') } } };
+  }
+
+  return spec;
+}
+
+// ─── Schema helpers ─────────────────────────────────────────────────────────
+
+function entitySchema(e, all) {
+  const props = { id: { type: 'string', format: 'uuid', readOnly: true }, createdAt: { type: 'string', format: 'date-time', readOnly: true }, updatedAt: { type: 'string', format: 'date-time', readOnly: true } };
+  for (const p of e.properties) {
+    if (!p.hidden) props[p.name] = { type: OPENAPI_TYPE[p.type] || 'string' };
+  }
+  for (const r of e.belongsTo || []) {
+    const ref = all[typeof r === 'string' ? r : (r.entity || r.name)];
+    if (ref) props[`${ref.tableName}_id`] = { type: 'string', format: 'uuid' };
+  }
+  return { type: 'object', properties: props };
+}
+
+function entityInputSchema(e, all) {
+  const s = entitySchema(e, all);
+  const { id, createdAt, updatedAt, ...rest } = s.properties;
+  return { type: 'object', properties: rest };
+}
+
+function authSchema(e) {
+  const props = { id: { type: 'string', format: 'uuid', readOnly: true }, email: { type: 'string', format: 'email' }, createdAt: { type: 'string', format: 'date-time' }, updatedAt: { type: 'string', format: 'date-time' } };
+  for (const p of e.properties) {
+    if (!p.hidden) props[p.name] = { type: OPENAPI_TYPE[p.type] || 'string' };
+  }
+  return { type: 'object', properties: props };
+}
+
+function authInputSchema(e) {
+  const props = { email: { type: 'string', format: 'email' }, password: { type: 'string', format: 'password' } };
+  for (const p of e.properties) {
+    if (!p.hidden) props[p.name] = { type: OPENAPI_TYPE[p.type] || 'string' };
+  }
+  return { type: 'object', required: ['email', 'password'], properties: props };
+}
+
+function loginSchema() {
+  return { type: 'object', required: ['email', 'password'], properties: { email: { type: 'string', format: 'email' }, password: { type: 'string', format: 'password' } } };
+}
+
+function hasSecurity(e, rule) {
+  const list = (e.policies || {})[rule];
+  if (list && list.length) return list[0].access !== 'public';
+  return true; // default: requires auth
+}
+
+function jsonBody(schema) { return { required: true, content: { 'application/json': { schema: { $ref: `#/components/schemas/${schema}` } } } }; }
+function jsonResp(schema) { return { description: 'OK', content: { 'application/json': { schema: { $ref: `#/components/schemas/${schema}` } } } }; }
+function desc(d) { return { description: d }; }
+function idParam() { return { name: 'id', in: 'path', required: true, schema: { type: 'string', format: 'uuid' } }; }
+
+module.exports = { generateOpenApiSpec };

package/core/plugin-loader.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const logger = require('../utils/logger');
+
+/**
+ * Load and register plugins defined in core.plugins.
+ *
+ * Supported sources:
+ *   - { path: './my-plugin' }  — local path (relative to cwd)
+ *   - { repo: 'https://github.com/...' }  — clones the repo and loads index.js
+ *
+ * Plugin module interface:
+ *   module.exports = {
+ *     name: 'plugin-name',
+ *     register(app, core) { ... }
+ *   }
+ */
+async function loadPlugins(app, core) {
+  for (const pluginDef of core.plugins) {
+    if (pluginDef.repo) {
+      logger.warn(
+        `  ⚠️  Loading remote plugin from "${pluginDef.repo}". ` +
+          'Remote plugins execute arbitrary code. Only load plugins from trusted sources.'
+      );
+    }
+    try {
+      const plugin = await resolvePlugin(pluginDef);
+      if (typeof plugin.register === 'function') {
+        await plugin.register(app, core);
+        logger.info(`  Plugin "${plugin.name || 'unnamed'}" loaded`);
+      } else {
+        logger.warn(`  Plugin "${pluginDef.repo || pluginDef.path}" has no register() function`);
+      }
+    } catch (err) {
+      logger.error(`  Failed to load plugin "${pluginDef.repo || pluginDef.path}": ${err.message}`);
+    }
+  }
+}
+
+async function resolvePlugin(pluginDef) {
+  if (pluginDef.path) {
+    const resolved = path.resolve(pluginDef.path);
+    return require(resolved);
+  }
+
+  if (pluginDef.repo) {
+    return loadRepoPlugin(pluginDef.repo);
+  }
+
+  throw new Error('Plugin must have "path" or "repo" field');
+}
+
+// Allow only HTTPS and SSH git URLs to prevent command injection
+const SAFE_REPO_RE = /^(https:\/\/[a-zA-Z0-9._\-/:%@]+|git@[a-zA-Z0-9._-]+:[a-zA-Z0-9._\-/]+)(\.git)?$/;
+
+async function loadRepoPlugin(repoUrl) {
+  if (!SAFE_REPO_RE.test(repoUrl)) {
+    throw new Error(`Plugin repo URL is not a valid git URL: ${repoUrl}`);
+  }
+
+  // Derive a directory name from the repo URL
+  const repoName = repoUrl.replace(/\.git$/, '').split('/').pop();
+  if (!repoName || repoName === '.' || repoName === '..') {
+    throw new Error(`Cannot derive a safe directory name from repo URL: ${repoUrl}`);
+  }
+  const pluginDir = path.resolve(`.chadstart-plugins/${repoName}`);
+
+  if (!fs.existsSync(pluginDir)) {
+    logger.info(`  Cloning plugin from ${repoUrl}...`);
+    const { execFileSync } = require('child_process');
+    fs.mkdirSync(path.dirname(pluginDir), { recursive: true });
+    // Use execFileSync with an argument array to avoid shell injection
+    execFileSync('git', ['clone', '--depth', '1', repoUrl, pluginDir], { stdio: 'pipe' });
+
+    // Install plugin dependencies if package.json exists.
+    // NOTE: --ignore-scripts prevents execution of preinstall/postinstall scripts,
+    // but plugins may still contain arbitrary code that runs at require() time.
+    // Only load plugins from sources you trust.
+    if (fs.existsSync(path.join(pluginDir, 'package.json'))) {
+      execFileSync('npm', ['install', '--omit=dev', '--ignore-scripts'], {
+        cwd: pluginDir,
+        stdio: 'pipe',
+      });
+    }
+  }
+
+  return require(pluginDir);
+}
+
+module.exports = { loadPlugins };