@nullix/zod-mongoose-studio 0.0.1

package/.output/server/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@nullix/zod-mongoose-studio-prod",
+  "version": "0.0.1",
+  "type": "module",
+  "private": true,
+  "dependencies": {
+    "@babel/parser": "7.29.2",
+    "@esbuild/darwin-arm64": "0.28.0",
+    "@iconify/utils": "3.1.0",
+    "@mongodb-js/saslprep": "1.4.6",
+    "@vue/compiler-core": "3.5.32",
+    "@vue/compiler-dom": "3.5.32",
+    "@vue/compiler-ssr": "3.5.32",
+    "@vue/reactivity": "3.5.32",
+    "@vue/runtime-core": "3.5.32",
+    "@vue/runtime-dom": "3.5.32",
+    "@vue/server-renderer": "3.5.32",
+    "@vue/shared": "3.5.32",
+    "bson": "6.10.4",
+    "consola": "3.4.2",
+    "debug": "4.4.3",
+    "devalue": "5.6.4",
+    "entities": "7.0.1",
+    "esbuild": "0.28.0",
+    "estree-walker": "2.0.2",
+    "hookable": "6.1.0",
+    "ip-address": "10.1.0",
+    "kareem": "2.6.3",
+    "memory-pager": "1.5.0",
+    "mongodb": "6.20.0",
+    "mongodb-connection-string-url": "3.0.2",
+    "mongoose": "8.23.0",
+    "mpath": "0.9.0",
+    "mquery": "5.0.0",
+    "ms": "2.1.3",
+    "punycode": "2.3.1",
+    "sift": "17.1.3",
+    "smart-buffer": "4.2.0",
+    "socks": "2.8.7",
+    "source-map-js": "1.2.1",
+    "sparse-bitfield": "3.0.3",
+    "supports-color": "10.2.2",
+    "tailwindcss": "4.2.2",
+    "tr46": "5.1.1",
+    "ufo": "1.6.3",
+    "unhead": "2.1.12",
+    "vue": "3.5.32",
+    "vue-bundle-renderer": "2.2.0",
+    "webidl-conversions": "7.0.0",
+    "whatwg-url": "14.2.0",
+    "zod": "4.3.6"
+  }
+}

package/README.md

@@ -0,0 +1,131 @@
+# @nullix/zod-mongoose-studio
+
+A Monaco-powered TypeScript playground for [@nullix/mongoose-zod](https://github.com/nullix/mongoose-zod). 
+
+The Studio provides a powerful web-integrated interface to experiment with Zod-to-Mongoose transformations. It supports local development via a CLI with full filesystem access and a sandboxed mode for documentation and live demos.
+
+## Goal
+
+Create a CLI tool and web-integrated "Studio" that provides:
+- A Monaco-powered TypeScript editor for Zod schemas.
+- Real-time transformation to Mongoose schema definitions and POJOs.
+- **Local Mode**: Runs via `npx` with full filesystem bridge for IntelliSense in your project.
+- **Docs Mode**: A secure, sandboxed environment for embedding in documentation or static deployments.
+
+## Technical Stack
+
+- **Framework**: Nuxt 4 (Vue 3)
+- **UI**: [Nuxt UI](https://ui.nuxt.com/) (Tailwind CSS)
+- **Editor**: [Monaco Editor](https://microsoft.github.io/monaco-editor/)
+- **Server**: Nitro (Nuxt built-in server)
+- **CLI**: Commander.js
+- **Logic**: [@nullix/mongoose-zod](https://www.npmjs.com/package/@nullix/mongoose-zod) for the transformation engine.
+
+## Usage
+
+### 🚀 CLI (Local Mode)
+
+Run the studio locally in any project to test your schemas with your actual local types.
+
+```shell
+npx @nullix/zod-mongoose-studio
+```
+
+Optional parameters:
+```shell
+# Custom port
+npx @nullix/zod-mongoose-studio --port 30045
+
+# Disable local filesystem access
+npx @nullix/zod-mongoose-studio --no-fs
+```
+
+In Local Mode, the Studio provides a bridge to your local files using `ts-morph`, allowing Monaco to provide IntelliSense for your project's custom types.
+
+### 🧩 Nuxt Integration (Docs Mode)
+
+To embed the Studio into your own documentation or Nuxt application:
+
+1. Install the package:
+```shell
+pnpm install @nullix/zod-mongoose-studio
+```
+
+2. Extend your `nuxt.config.ts`:
+```ts
+export default defineNuxtConfig({
+  extends: ['@nullix/zod-mongoose-studio'],
+  
+  // Turn on docs mode securely
+  runtimeConfig: {
+    public: {
+      isDocsMode: true,
+      isLocalMode: false
+    }
+  }
+})
+```
+
+3. Use the component in your pages:
+```vue
+<template>
+  <UContainer>
+    <h1 class="text-2xl font-bold my-4">Try it live!</h1>
+    
+    <!-- Automatically connects to the injected /api/parse route -->
+    <ZodMongooseStudio class="h-[600px] border rounded-lg shadow-sm" />
+  </UContainer>
+</template>
+```
+
+## Features & Configuration
+
+### Transformation Engine (`/api/parse`)
+
+The core logic executes Zod schemas in a controlled environment. It automatically injects the necessary imports for `zod/v4` and `@nullix/mongoose-zod`:
+
+```ts
+import * as zod from 'zod/v4';
+const z = zod.z;
+import { toMongooseScheme, extractMongooseDefinition } from '@nullix/mongoose-zod';
+```
+
+### Filesystem Bridge (`/api/resolve`)
+
+Available only in **Local Mode** (`LOCAL_MODE=true`). It uses Node's `fs` or `ts-morph` to resolve local files based on your current working directory, providing high-quality IntelliSense for your actual project files inside the Monaco editor.
+
+### Sandboxing & Security
+
+When running in **Docs Mode** (`DOCS_MODE=true`), several security layers are enforced:
+
+- **Isolated Execution**: Code transformations occur in a virtual machine context (using `isolated-vm` or equivalent workers) to prevent access to the host `process.env`, `window`, or `document`.
+- **Disabled Resolvers**: The `/api/resolve` endpoint is completely disabled.
+- **Rate Limiting**: Built-in Nitro middleware tracks IP addresses and limits requests (default: 2 per second) to prevent abuse.
+- **UI Hardening**: Elements related to the local filesystem are automatically hidden.
+
+## Project Structure
+
+```text
+@nullix/studio
+├── bin/                # CLI entry point (npx wrapper)
+├── server/
+│   ├── api/
+│   │   ├── parse.post.ts    # Transform logic (Zod -> Mongoose)
+│   │   └── resolve.get.ts  # FS bridge (IntelliSense resolver)
+│   └── middleware/
+│       └── security.ts      # Rate limiting & sandbox enforcement
+├── components/
+│   ├── StudioEditor.vue     # Monaco wrapper for input
+│   └── StudioOutput.vue     # Monaco wrapper for read-only output
+├── pages/
+│   └── index.vue            # Main UI (Split-pane view)
+└── nuxt.config.ts           # Layer configuration
+```
+
+## Contributing
+
+Please refer to the monorepo root for development and contribution guidelines.
+
+## License
+
+MIT

package/app/app.vue

@@ -0,0 +1,7 @@
+<script setup lang="ts"></script>
+<template>
+  <UApp>
+    <NuxtRouteAnnouncer />
+    <NuxtPage />
+  </UApp>
+</template>

package/app/assets/css/main.css

@@ -0,0 +1,2 @@
+@import "tailwindcss";
+@import "@nuxt/ui";

package/app/components/StudioEditor.vue

@@ -0,0 +1,114 @@
+<script setup lang="ts">
+import { ref, shallowRef, onMounted, onBeforeUnmount, watch } from "vue";
+
+const props = defineProps<{ modelValue: string }>();
+const emit = defineEmits(["update:modelValue"]);
+
+const editorContainer = ref<HTMLElement | null>(null);
+// shallowRef is REQUIRED for Monaco instances in Vue 3!
+const editorInstance = shallowRef<any>(null);
+
+onMounted(async () => {
+  if (!editorContainer.value) return;
+
+  // Dynamically import monaco
+  const monaco = await import("monaco-editor");
+
+  monaco.typescript.typescriptDefaults.setCompilerOptions({
+    target: monaco.typescript.ScriptTarget.ESNext,
+    allowNonTsExtensions: true,
+    moduleResolution: monaco.typescript.ModuleResolutionKind.NodeJs,
+    module: monaco.typescript.ModuleKind.ESNext, // Allow ES6 exports
+    noEmit: true,
+  });
+
+  // 1. Zod v4 shim (so imports don't error in the editor)
+  monaco.typescript.typescriptDefaults.addExtraLib(
+    `
+    declare module 'zod/v4' {
+      export const z: any;
+      export type ZodTypeAny = any;
+      export type ZodObject<T> = any;
+      export type ZodString = any;
+      export type ZodNumber = any;
+    }
+  `,
+    "file:///node_modules/@types/zod-v4/index.d.ts",
+  );
+
+  monaco.typescript.typescriptDefaults.addExtraLib(
+    `
+    declare module '@nullix/zod-mongoose' {
+      import { z } from 'zod/v4';
+      import mongoose, { SchemaOptions } from 'mongoose';
+      import * as hookable from 'hookable';
+
+      interface MongooseMeta extends Record<string, any> {
+          explicitId?: boolean;
+      }
+      declare const mongooseRegistry: z.core.$ZodRegistry<MongooseMeta, z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+      declare function withMongoose<T extends z.ZodTypeAny>(schema: T, meta: MongooseMeta): T;
+
+      type ToMongooseType<T extends z.ZodTypeAny> = any; // Simplified for Monaco perf
+
+      export declare function extractMongooseDef<T extends z.ZodTypeAny>(schema: T, visited?: Map<z.ZodTypeAny, any>, isField?: boolean): ToMongooseType<T> & Record<string, any>;
+
+      interface ToMongooseSchemaOptions extends SchemaOptions {
+          plugins?: Array<(schema: mongoose.Schema, options?: any) => void>;
+      }
+
+      export declare function toMongooseSchema<T extends z.ZodTypeAny>(schema: T, options?: ToMongooseSchemaOptions): mongoose.Schema<z.infer<T>>;
+
+      export declare const zObjectId: (options?: MongooseMeta) => any;
+      export declare const zBuffer: (options?: MongooseMeta) => any;
+      export declare const zPopulated: <T extends z.ZodTypeAny>(ref: string, schema: T, options?: MongooseMeta) => any;
+      export declare const genTimestampsSchema: <CrAt = "createdAt", UpAt = "updatedAt">(createdAtField?: any, updatedAtField?: any) => any;
+
+      export type PopulatedSchema<T, K extends keyof T> = any;
+      export declare const bufferMongooseGetter: (value: unknown) => any;
+      export declare const getMongoose: () => any;
+      export declare const setFrontendMode: (enabled: boolean) => void;
+      export declare const getFrontendMode: () => boolean;
+
+      export type MongooseZodHooks = any;
+      export declare const hooks: any;
+      export declare function callHookSync<Name extends keyof MongooseZodHooks>(name: Name, ...args: Parameters<MongooseZodHooks[Name]>): void;
+    }
+  `,
+    "file:///node_modules/@nullix/zod-mongoose/index.d.ts",
+  );
+
+  editorInstance.value = monaco.editor.create(editorContainer.value, {
+    value: props.modelValue,
+    language: "typescript",
+    theme: "vs-dark",
+    minimap: { enabled: false },
+    automaticLayout: true,
+    fontSize: 14,
+    padding: { top: 16 },
+  });
+
+  editorInstance.value.onDidChangeModelContent(() => {
+    emit("update:modelValue", editorInstance.value?.getValue() || "");
+  });
+});
+
+watch(
+  () => props.modelValue,
+  (newValue) => {
+    if (editorInstance.value && editorInstance.value.getValue() !== newValue) {
+      editorInstance.value.setValue(newValue);
+    }
+  },
+);
+
+onBeforeUnmount(() => {
+  if (editorInstance.value) {
+    editorInstance.value.dispose();
+  }
+});
+</script>
+
+<template>
+  <div ref="editorContainer" class="w-full h-full" />
+</template>

package/app/components/StudioOutput.vue

@@ -0,0 +1,43 @@
+<script setup lang="ts">
+import { ref, shallowRef, onMounted, onBeforeUnmount, watch } from "vue";
+
+const props = defineProps<{ modelValue: string }>();
+const outputContainer = ref<HTMLElement | null>(null);
+const editorInstance = shallowRef<any>(null);
+
+onMounted(async () => {
+  if (!outputContainer.value) return;
+
+  const monaco = await import("monaco-editor");
+
+  editorInstance.value = monaco.editor.create(outputContainer.value, {
+    value: props.modelValue,
+    language: "typescript",
+    theme: "vs-dark",
+    minimap: { enabled: false },
+    automaticLayout: true,
+    readOnly: true,
+    fontSize: 14,
+    padding: { top: 16 },
+  });
+});
+
+watch(
+  () => props.modelValue,
+  (newValue) => {
+    if (editorInstance.value) {
+      editorInstance.value.setValue(newValue);
+    }
+  },
+);
+
+onBeforeUnmount(() => {
+  if (editorInstance.value) {
+    editorInstance.value.dispose();
+  }
+});
+</script>
+
+<template>
+  <div ref="outputContainer" class="w-full h-full" />
+</template>

package/app/components/ZodMongooseStudio.vue

@@ -0,0 +1,121 @@
+<script setup lang="ts">
+import { ref, watch } from "vue";
+// Use lodash/debounce or vueuse in a real app, but setTimeout works for now
+let debounceTimer: any;
+
+const config = useRuntimeConfig();
+const isLocalMode = ref(config.public.isLocalMode);
+
+const sourceCode = ref(`import { z } from 'zod/v4';
+import { extractMongooseDef, toMongooseSchema } from '@nullix/zod-mongoose';
+
+const UserSchema = z.object({
+  name: z.string(),
+  age: z.number().optional()
+});
+
+// Export your schema so the Studio can transform it
+export default UserSchema;`);
+
+const outputDef = ref("// Definition output...");
+const outputSchema = ref("// Mongoose Schema output...");
+
+const isCompiling = ref(false);
+
+const handleCompile = async () => {
+  isCompiling.value = true;
+  try {
+    const response = await $fetch("/api/parse", {
+      method: "POST",
+      body: { sourceCode: sourceCode.value },
+    });
+    outputDef.value = `// Result of extractMongooseDef()\nconst definition = ${response.definition};`;
+    outputSchema.value = `// Result of toMongooseSchema().obj\nconst schemaObj = ${response.schemaObj};`;
+  } catch (error: any) {
+    const errText = `// Error\n${error.data?.message || error.message}`;
+    outputDef.value = errText;
+    outputSchema.value = errText;
+  } finally {
+    isCompiling.value = false;
+  }
+};
+
+// Auto-compile with a slight delay as they type
+watch(
+  sourceCode,
+  () => {
+    clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(handleCompile, 600);
+  },
+  { immediate: true },
+);
+</script>
+
+<template>
+  <div class="h-screen flex flex-col bg-gray-50 dark:bg-gray-950">
+    <header
+      class="bg-white dark:bg-gray-900 border-b border-gray-200 dark:border-gray-800 py-3 px-4 flex justify-between items-center shrink-0"
+    >
+      <div class="flex items-center gap-4">
+        <h1 class="text-xl font-bold text-primary">
+          @nullix/zod-mongoose Studio
+        </h1>
+        <UBadge v-if="isLocalMode" color="success" variant="soft"
+          >Local Mode</UBadge
+        >
+        <UBadge v-else color="info" variant="soft">Docs Mode</UBadge>
+      </div>
+      <div class="flex items-center gap-2">
+        <span v-if="isCompiling" class="text-sm text-gray-500"
+          >Transforming...</span
+        >
+      </div>
+    </header>
+
+    <div
+      class="flex-1 grid grid-cols-2 gap-px bg-gray-200 dark:bg-gray-800 min-h-0"
+    >
+      <!-- Left: Editor -->
+      <div class="bg-white dark:bg-gray-950 h-full relative">
+        <ClientOnly>
+          <StudioEditor v-model="sourceCode" />
+        </ClientOnly>
+      </div>
+
+      <!-- Right: Split Outputs -->
+      <div class="flex flex-col h-full gap-px bg-gray-200 dark:bg-gray-800">
+        <!-- Top Right: Definition -->
+        <div
+          class="flex-1 bg-white dark:bg-gray-950 relative flex flex-col min-h-0"
+        >
+          <div
+            class="px-3 py-1 bg-gray-100 dark:bg-gray-900 text-xs font-semibold text-gray-600 dark:text-gray-400 border-b border-gray-200 dark:border-gray-800 z-10"
+          >
+            extractMongooseDef()
+          </div>
+          <div class="flex-1 relative">
+            <ClientOnly>
+              <StudioOutput :model-value="outputDef" />
+            </ClientOnly>
+          </div>
+        </div>
+
+        <!-- Bottom Right: Schema -->
+        <div
+          class="flex-1 bg-white dark:bg-gray-950 relative flex flex-col min-h-0"
+        >
+          <div
+            class="px-3 py-1 bg-gray-100 dark:bg-gray-900 text-xs font-semibold text-gray-600 dark:text-gray-400 border-b border-gray-200 dark:border-gray-800 z-10"
+          >
+            toMongooseSchema()
+          </div>
+          <div class="flex-1 relative">
+            <ClientOnly>
+              <StudioOutput :model-value="outputSchema" />
+            </ClientOnly>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>

package/app/pages/index.vue

@@ -0,0 +1,3 @@
+<template>
+  <ZodMongooseStudio />
+</template>

package/app/plugins/monaco.client.ts

@@ -0,0 +1,14 @@
+import editorWorker from "monaco-editor/esm/vs/editor/editor.worker?worker";
+import tsWorker from "monaco-editor/esm/vs/language/typescript/ts.worker?worker";
+
+export default defineNuxtPlugin(() => {
+  // Tell Monaco how to load its Web Workers via Vite
+  self.MonacoEnvironment = {
+    getWorker(_, label) {
+      if (label === "typescript" || label === "javascript") {
+        return new tsWorker();
+      }
+      return new editorWorker();
+    },
+  };
+});

package/bin/index.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { getPort } from "get-port-please";
+import open from "open";
+import { fork } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const serverEntry = path.join(__dirname, "../.output/server/index.mjs");
+
+async function startStudio() {
+  // 1. Parse CLI Arguments
+  const { values } = parseArgs({
+    options: {
+      port: { type: "string", short: "p" },
+      "no-fs": { type: "boolean" }, // Optional opt-out flag
+    },
+    strict: false, // Allow other random args without crashing
+  });
+
+  console.log("🚀 Starting @nullix/zod-mongoose Studio...");
+
+  // 2. Determine Port
+  let port = values.port ? parseInt(values.port, 10) : undefined;
+  if (!port || isNaN(port)) {
+    port = await getPort({ portRange: [3000, 4000] });
+  }
+
+  // 3. Determine Modes
+  const enableFs = !values["no-fs"];
+
+  // 4. Set strict environment variables for the Nitro server
+  const env = {
+    ...process.env,
+    PORT: port.toString(),
+    DOCS_MODE: "false", // CLI is NEVER docs mode
+    LOCAL_MODE: enableFs ? "true" : "false", // Enable FS unless opted out
+    NODE_ENV: "production",
+  };
+
+  // 5. Fork the Nuxt Nitro server
+  const serverProcess = fork(serverEntry, [], { env });
+
+  const url = `http://localhost:${port}`;
+  console.log(`⏳ Starting server on ${url}...`);
+
+  setTimeout(() => {
+    console.log(`✅ Studio running!`);
+    if (enableFs) {
+      console.log(
+        `📁 Filesystem Access: ENABLED (Workspace root: ${process.cwd()})`,
+      );
+    } else {
+      console.log(`🔒 Filesystem Access: DISABLED (--no-fs flag provided)`);
+    }
+    open(url);
+  }, 1500);
+
+  process.on("SIGINT", () => {
+    serverProcess.kill();
+    process.exit(0);
+  });
+}
+
+startStudio().catch((err) => {
+  console.error("Failed to start studio:", err);
+  process.exit(1);
+});

package/nuxt.config.ts

@@ -0,0 +1,18 @@
+export default defineNuxtConfig({
+  modules: ["@nuxt/ui"],
+
+  runtimeConfig: {
+    public: {
+      // By default, assume we are in a safe, sandboxed documentation environment.
+      // The CLI script will explicitly pass DOCS_MODE="false" to disable this.
+      isDocsMode: process.env.DOCS_MODE !== "false",
+
+      // By default, local file system access is OFF.
+      // The CLI script will explicitly pass LOCAL_MODE="true" to enable it.
+      isLocalMode: process.env.LOCAL_MODE === "true",
+    },
+  },
+  css: ["~/assets/css/main.css"],
+
+  compatibilityDate: "2026-04-01",
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@nullix/zod-mongoose-studio",
+  "version": "0.0.1",
+  "description": "Monaco-powered TypeScript playground for @nullix/zod-mongoose",
+  "main": "./nuxt.config.ts",
+  "bin": {
+    "zod-mongoose-studio": "./bin/index.mjs"
+  },
+  "type": "module",
+  "files": [
+    "app",
+    "server",
+    "bin",
+    "nuxt.config.ts",
+    ".output"
+  ],
+  "author": "harm@nullix.nl",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "esbuild": "0.28.0",
+    "get-port-please": "3.2.0",
+    "open": "11.0.0",
+    "zod": "4.3.6",
+    "@nullix/zod-mongoose": "0.0.1"
+  },
+  "devDependencies": {
+    "@nuxt/ui": "4.6.0",
+    "@types/node": "24.12.1",
+    "monaco-editor": "0.55.1",
+    "nuxt": "4.4.2",
+    "tailwindcss": "4.2.2",
+    "typescript": "5.9.3",
+    "vue": "3.5.32",
+    "vue-tsc": "3.2.6"
+  },
+  "scripts": {
+    "build": "nuxt build",
+    "dev": "nuxt dev -p 34003",
+    "generate": "nuxt generate",
+    "preview": "nuxt preview",
+    "postinstall": "nuxt prepare"
+  }
+}