feat: update schema generation scripts to prevent data loss and enhance eager loading

Author: hotlong

packages/spec/package.json

@@ -98,7 +98,7 @@
     "build": "pnpm gen:schema && pnpm gen:openapi && tsup && NODE_OPTIONS=\"--max-old-space-size=4096\" BUILD_DTS=true tsup",
     "dev": "tsc --watch",
     "clean": "rm -rf dist",
-    "gen:schema": "tsx scripts/build-schemas.ts",
+    "gen:schema": "OBJECTSTACK_EAGER_SCHEMAS=1 tsx scripts/build-schemas.ts",
     "gen:openapi": "tsx scripts/build-openapi.ts",
     "gen:docs": "tsx scripts/build-docs.ts",
     "gen:skill-refs": "tsx scripts/build-skill-references.ts",

packages/spec/scripts/build-docs.ts

@@ -266,12 +266,22 @@ function generateZodFileMarkdown(zodFile: string, schemas: Array<{name: string,
 
 console.log('Building documentation...');
 
-// 1. Clean existing category folders from DOCS_ROOT
+// 1. Clean existing category folders from DOCS_ROOT — but only when there are
+// JSON schemas to regenerate from. Otherwise we'd silently delete every .mdx
+// file when the upstream `gen:schema` step produced nothing (data loss).
 Object.keys(CATEGORIES).forEach(category => {
   const dir = path.join(DOCS_ROOT, category);
+  const schemaDir = path.join(SCHEMA_DIR, category);
+  const hasSchemas = fs.existsSync(schemaDir)
+    && fs.readdirSync(schemaDir).some(f => f.endsWith('.json'));
+  if (!hasSchemas) {
+    if (fs.existsSync(dir)) {
+      console.warn(`⚠ Skipping clean of ${category}/ — no JSON schemas found in ${schemaDir}. Run \`pnpm gen:schema\` first.`);
+    }
+    return;
+  }
   if (fs.existsSync(dir)) {
     fs.rmSync(dir, { recursive: true, force: true });
-    // console.log(`Cleaned ${dir}`);
   }
 });
 

packages/spec/scripts/build-schemas.ts

@@ -8,7 +8,29 @@ process.env.OBJECTSTACK_EAGER_SCHEMAS = '1';
 import fs from 'fs';
 import path from 'path';
 import { z } from 'zod';
-import * as Protocol from '../src/index';
+import * as AI from '../src/ai';
+import * as API from '../src/api';
+import * as Automation from '../src/automation';
+import * as Cloud from '../src/cloud';
+import * as Contracts from '../src/contracts';
+import * as Data from '../src/data';
+import * as Identity from '../src/identity';
+import * as Integration from '../src/integration';
+import * as Kernel from '../src/kernel';
+import * as QA from '../src/qa';
+import * as Security from '../src/security';
+import * as Shared from '../src/shared';
+import * as Studio from '../src/studio';
+import * as System from '../src/system';
+import * as UI from '../src/ui';
+
+// Root index no longer re-exports namespaces (removed for tree-shaking — see
+// packages/spec/src/index.ts). Build subpath-by-subpath instead so every
+// category folder under json-schema/ gets populated.
+const Protocol: Record<string, Record<string, unknown>> = {
+  AI, API, Automation, Cloud, Contracts, Data, Identity, Integration,
+  Kernel, QA, Security, Shared, Studio, System, UI,
+};
 
 const OUT_DIR = path.resolve(__dirname, '../json-schema');
 const SPEC_VERSION = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../package.json'), 'utf-8')).version;