@zveltio/sdk 2.0.8 → 3.0.0-beta.2

package/dist/validate/index.js

@@ -0,0 +1,201 @@
+/**
+ * Pre-publish validators for Zveltio extensions (S4-04).
+ *
+ * Pure functions — no Node-specific imports, no Zod runtime. Designed so the
+ * CLI (`zveltio extension validate`) can call them on file contents read from
+ * disk, the engine can call them on uploaded archives, and registry code can
+ * call them on publish. Each returns a `ValidationResult` with structured
+ * diagnostics instead of throwing, so the CLI can print all problems at once.
+ *
+ * What's checked:
+ *   - manifest.json shape (required fields, semver, sane category)
+ *   - name matches the folder path it lives in
+ *   - peerDependencies appear on the platform allow-list
+ *   - migration SQL files parse + table coverage looks sane
+ *   - destructive DDL in migrations has a `-- DOWN` section
+ *   - bundle size stays within quota
+ *
+ * Out of scope (deferred):
+ *   - Loading the extension module to inspect its default export. Requires
+ *     a Bun runtime + sandbox. CLI's `validate` cannot guarantee correctness
+ *     for runtime contracts; that's what `extension types` (S4-01) + `tsc`
+ *     gives you locally.
+ *   - Building the Studio bundle. Too slow; pair with `zveltio extension build`
+ *     which can call validate as a sub-step.
+ */
+import { parseMigrationSql } from './migration-parse.js';
+// ─── Helpers ───────────────────────────────────────────────────────────────
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/;
+const KNOWN_CATEGORIES = new Set([
+    'auth',
+    'content',
+    'crm',
+    'finance',
+    'hr',
+    'operations',
+    'developer',
+    'compliance',
+    'communications',
+    'analytics',
+    'geospatial',
+    'ai',
+    'integrations',
+    'i18n',
+    'workflow',
+    'storage',
+    'ecommerce',
+    'projects',
+    'sms',
+    'forms',
+    'billing',
+    'intelligence',
+    'business',
+    'search',
+    'data',
+    'custom',
+]);
+// Sub-set of the engine's safety regexes — kept identical so the two paths
+// agree. If we drift, an extension that validates clean would still be
+// rejected at install time.
+const SAFE_PACKAGE_NAME = /^(@[a-z0-9-_]+\/)?[a-z0-9-_.]+$/;
+const SAFE_VERSION_RANGE = /^[\d.*^~>=<| -]+$/;
+function err(code, message, file) {
+    return file ? { code, message, file } : { code, message };
+}
+export function validateManifest(input) {
+    const out = [];
+    const m = input.manifest;
+    if (m === null || typeof m !== 'object' || Array.isArray(m)) {
+        out.push(err('MANIFEST_NOT_OBJECT', 'manifest.json must be a JSON object'));
+        return out;
+    }
+    const obj = m;
+    // Required string fields
+    for (const k of ['name', 'displayName', 'category', 'description', 'version']) {
+        if (typeof obj[k] !== 'string' || obj[k].trim() === '') {
+            out.push(err('MANIFEST_MISSING_FIELD', `manifest.json missing required string field "${k}"`));
+        }
+    }
+    const name = typeof obj.name === 'string' ? obj.name : '';
+    if (input.expectedName && name && name !== input.expectedName) {
+        out.push(err('MANIFEST_NAME_MISMATCH', `manifest "name": "${name}" does not match folder path "${input.expectedName}"`));
+    }
+    if (typeof obj.version === 'string' && !SEMVER_RE.test(obj.version)) {
+        out.push(err('MANIFEST_BAD_VERSION', `version "${obj.version}" is not valid semver (x.y.z)`));
+    }
+    if (typeof obj.zveltioMinVersion === 'string' && !SEMVER_RE.test(obj.zveltioMinVersion)) {
+        out.push(err('MANIFEST_BAD_MIN_VERSION', `zveltioMinVersion "${obj.zveltioMinVersion}" is not valid semver`));
+    }
+    if (typeof obj.zveltioMaxVersion === 'string' && !SEMVER_RE.test(obj.zveltioMaxVersion)) {
+        out.push(err('MANIFEST_BAD_MAX_VERSION', `zveltioMaxVersion "${obj.zveltioMaxVersion}" is not valid semver`));
+    }
+    if (typeof obj.category === 'string' && !KNOWN_CATEGORIES.has(obj.category)) {
+        // Warning rather than error — categories are open-ended in practice.
+        // Surface so authors notice typos like "finanace".
+        out.push(err('MANIFEST_UNKNOWN_CATEGORY', `category "${obj.category}" isn't in the known set — typo? Known: ${[...KNOWN_CATEGORIES].sort().join(', ')}`));
+    }
+    return out;
+}
+export function validatePeerDependencies(input) {
+    const out = [];
+    const deps = input.peerDependencies ?? {};
+    for (const [pkg, version] of Object.entries(deps)) {
+        if (typeof version !== 'string') {
+            out.push(err('PEERDEP_BAD_VERSION', `peerDependency "${pkg}" version must be a string, got ${typeof version}`));
+            continue;
+        }
+        if (!SAFE_PACKAGE_NAME.test(pkg)) {
+            out.push(err('PEERDEP_UNSAFE_NAME', `peerDependency "${pkg}" uses an unsupported name format (file:, git:, etc. are forbidden)`));
+            continue;
+        }
+        if (!SAFE_VERSION_RANGE.test(version)) {
+            out.push(err('PEERDEP_UNSAFE_VERSION', `peerDependency "${pkg}" version range "${version}" is not a plain semver range`));
+            continue;
+        }
+        if (!input.allowedPackages.has(pkg)) {
+            out.push(err('PEERDEP_NOT_ALLOWED', `peerDependency "${pkg}" is not on the platform allow-list — open a PR to peer-deps-allowlist.ts to request inclusion`));
+        }
+    }
+    return out;
+}
+/**
+ * Detect "destructive" DDL statements in an UP section. Heuristic — we want
+ * to catch the easy cases (DROP TABLE, DROP COLUMN, ALTER COLUMN ... DROP)
+ * without false positives on benign DROP IF EXISTS in DOWN sections (which
+ * we don't scan).
+ */
+function hasDestructiveDdl(upSql) {
+    // Strip strings and comments-light: this is a heuristic; full SQL parsing
+    // is overkill for a pre-publish lint.
+    const s = upSql.replace(/--[^\n]*/g, '').replace(/\/\*[\s\S]*?\*\//g, '');
+    if (/\bDROP\s+TABLE\b/i.test(s))
+        return true;
+    if (/\bDROP\s+COLUMN\b/i.test(s))
+        return true;
+    if (/\bALTER\s+COLUMN\b[\s\S]*?\bDROP\s+(NOT\s+NULL|DEFAULT)\b/i.test(s))
+        return true;
+    return false;
+}
+export function validateMigrations(input) {
+    const out = [];
+    for (const file of input.files) {
+        if (file.sql.trim() === '') {
+            out.push(err('MIGRATION_EMPTY', 'migration file is empty', file.filename));
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = parseMigrationSql(file.sql);
+        }
+        catch (e) {
+            out.push(err('MIGRATION_PARSE', `could not parse migration: ${e.message}`, file.filename));
+            continue;
+        }
+        if (parsed.up.trim() === '') {
+            out.push(err('MIGRATION_NO_UP', 'migration has no UP section (everything before -- DOWN)', file.filename));
+            continue;
+        }
+        if (input.requireDownForDestructive && hasDestructiveDdl(parsed.up) && !parsed.down) {
+            out.push(err('MIGRATION_DESTRUCTIVE_NO_DOWN', 'migration contains destructive DDL (DROP TABLE/COLUMN or ALTER ... DROP) but has no "-- DOWN" section. Add one so uninstall --purgeData can roll back.', file.filename));
+        }
+    }
+    return out;
+}
+export function validateFilePresence(input) {
+    const out = [];
+    for (const p of input.required) {
+        if (!input.paths[p]) {
+            out.push(err('FILE_MISSING', `required file is missing`, p));
+        }
+    }
+    return out;
+}
+const DEFAULT_BUNDLE_KB_MAX = 50_000;
+export function validateBundleSize(input) {
+    const cap = input.bundleSizeKbMax ?? DEFAULT_BUNDLE_KB_MAX;
+    const observedKb = Math.ceil(input.bundleBytes / 1024);
+    if (observedKb > cap) {
+        return [
+            err('BUNDLE_TOO_LARGE', `extension bundle is ${observedKb} KB; quota is ${cap} KB. Reduce the bundle or raise the quota in manifest.quotas.bundleSizeKbMax.`),
+        ];
+    }
+    return [];
+}
+export function validateExtension(input) {
+    const errors = [
+        ...validateManifest(input.manifest),
+        ...validatePeerDependencies(input.peerDeps),
+        ...validateMigrations(input.migrations),
+        ...validateFilePresence(input.filePresence),
+        ...(input.bundleSize ? validateBundleSize(input.bundleSize) : []),
+    ];
+    return {
+        ok: errors.length === 0,
+        errors,
+        stats: {
+            tables: input.stats.tables,
+            migrations: input.stats.migrations,
+            peerDeps: Object.keys(input.peerDeps.peerDependencies ?? {}).length,
+        },
+    };
+}

package/dist/validate/migration-parse.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Parse a single SQL migration file into its UP and DOWN sections.
+ *
+ * The DOWN section starts at the first line matching `-- DOWN` (case
+ * insensitive). Everything before that marker is UP; everything after the
+ * marker line is DOWN. If the marker is absent, the whole file is UP.
+ *
+ * Mirror of `packages/engine/src/lib/extension-loader.ts:parseMigrationSql`
+ * — kept in the SDK so validators and tooling can call it without depending
+ * on engine internals.
+ */
+export interface ParsedMigration {
+    up: string;
+    down: string | null;
+}
+export declare function parseMigrationSql(raw: string): ParsedMigration;
+//# sourceMappingURL=migration-parse.d.ts.map

package/dist/validate/migration-parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-parse.d.ts","sourceRoot":"","sources":["../../src/validate/migration-parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAU9D"}

package/dist/validate/migration-parse.js

@@ -0,0 +1,11 @@
+export function parseMigrationSql(raw) {
+    const downIdx = raw.search(/^--\s*DOWN\b/im);
+    if (downIdx < 0) {
+        return { up: raw.trim(), down: null };
+    }
+    const up = raw.slice(0, downIdx).trim();
+    const downSection = raw.slice(downIdx);
+    const firstNewline = downSection.indexOf('\n');
+    const downBody = firstNewline >= 0 ? downSection.slice(firstNewline + 1).trim() : '';
+    return { up, down: downBody.length > 0 ? downBody : null };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zveltio/sdk",
-  "version": "2.0.8",
+  "version": "3.0.0-beta.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,6 +12,42 @@
     "./extension": {
       "types": "./dist/extension/index.d.ts",
       "import": "./dist/extension/index.js"
+    },
+    "./codegen": {
+      "types": "./dist/schema-codegen.d.ts",
+      "import": "./dist/schema-codegen.js"
+    },
+    "./validate": {
+      "types": "./dist/validate/index.d.ts",
+      "import": "./dist/validate/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./publish": {
+      "types": "./dist/publish/index.d.ts",
+      "import": "./dist/publish/index.js"
+    },
+    "./build": {
+      "types": "./dist/build/index.d.ts",
+      "import": "./dist/build/index.js"
+    },
+    "./studio": {
+      "types": "./dist/studio/index.d.ts",
+      "import": "./dist/studio/index.js"
+    },
+    "./ddl": {
+      "types": "./dist/ddl/index.d.ts",
+      "import": "./dist/ddl/index.js"
+    },
+    "./rpc": {
+      "types": "./dist/rpc/index.d.ts",
+      "import": "./dist/rpc/index.js"
+    },
+    "./offline": {
+      "types": "./dist/offline/index.d.ts",
+      "import": "./dist/offline/index.js"
     }
   },
   "files": [
@@ -28,10 +64,26 @@
     "idb": "^8.0.0"
   },
   "devDependencies": {
+    "@testcontainers/postgresql": "^11.0.0",
+    "@types/pg": "^8.11.0",
     "fake-indexeddb": "^6.2.5",
     "hono": "^4.12.5",
+    "kysely": "^0.27.0",
+    "pg": "^8.13.0",
     "typescript": "^5.4.0"
   },
+  "peerDependencies": {
+    "@testcontainers/postgresql": "^11.0.0",
+    "pg": "^8.13.0"
+  },
+  "peerDependenciesMeta": {
+    "@testcontainers/postgresql": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    }
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/zveltio-devs/zveltio.git"