@atscript/db-mongo 0.1.38

package/dist/mongo-filter-C8w5by9H.cjs

@@ -0,0 +1,65 @@
+"use strict";
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __atscript_db = __toESM(require("@atscript/db"));
+
+//#region packages/db-mongo/src/lib/mongo-filter.ts
+const EMPTY = {};
+const mongoVisitor = {
+	comparison(field, op, value) {
+		if (op === "$eq") return { [field]: value };
+		return { [field]: { [op]: value } };
+	},
+	and(children) {
+		if (children.length === 0) return EMPTY;
+		if (children.length === 1) return children[0];
+		return { $and: children };
+	},
+	or(children) {
+		if (children.length === 0) return { _impossible: true };
+		if (children.length === 1) return children[0];
+		return { $or: children };
+	},
+	not(child) {
+		return { $nor: [child] };
+	}
+};
+function buildMongoFilter(filter) {
+	if (!filter || Object.keys(filter).length === 0) return EMPTY;
+	return (0, __atscript_db.walkFilter)(filter, mongoVisitor) ?? EMPTY;
+}
+
+//#endregion
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});
+Object.defineProperty(exports, 'buildMongoFilter', {
+  enumerable: true,
+  get: function () {
+    return buildMongoFilter;
+  }
+});

package/dist/mongo-filter-CL69Yhcm.mjs

@@ -0,0 +1,30 @@
+import { walkFilter } from "@atscript/db";
+
+//#region packages/db-mongo/src/lib/mongo-filter.ts
+const EMPTY = {};
+const mongoVisitor = {
+	comparison(field, op, value) {
+		if (op === "$eq") return { [field]: value };
+		return { [field]: { [op]: value } };
+	},
+	and(children) {
+		if (children.length === 0) return EMPTY;
+		if (children.length === 1) return children[0];
+		return { $and: children };
+	},
+	or(children) {
+		if (children.length === 0) return { _impossible: true };
+		if (children.length === 1) return children[0];
+		return { $or: children };
+	},
+	not(child) {
+		return { $nor: [child] };
+	}
+};
+function buildMongoFilter(filter) {
+	if (!filter || Object.keys(filter).length === 0) return EMPTY;
+	return walkFilter(filter, mongoVisitor) ?? EMPTY;
+}
+
+//#endregion
+export { buildMongoFilter };

package/dist/plugin.cjs

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, '__esModule', { value: true });
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __atscript_core = __toESM(require("@atscript/core"));
+
+//#region packages/db-mongo/src/plugin/annotations.ts
+const analyzers = [
+	"lucene.standard",
+	"lucene.simple",
+	"lucene.whitespace",
+	"lucene.english",
+	"lucene.french",
+	"lucene.german",
+	"lucene.italian",
+	"lucene.portuguese",
+	"lucene.spanish",
+	"lucene.chinese",
+	"lucene.hindi",
+	"lucene.bengali",
+	"lucene.russian",
+	"lucene.arabic"
+];
+const annotations = {
+	collection: new __atscript_core.AnnotationSpec({
+		description: "Marks an interface as a **MongoDB collection**.\n\n- Use together with `@db.table \"name\"` which provides the collection name.\n- Automatically injects a **non-optional** `_id` field if not explicitly defined.\n- `_id` must be of type **`string`**, **`number`**, or **`mongo.objectId`**.\n\n**Example:**\n```atscript\n@db.table \"users\"\n@db.mongo.collection\nexport interface User {\n    _id: mongo.objectId\n    email: string.email\n}\n```\n",
+		nodeType: ["interface"],
+		validate(token, args, doc) {
+			const parent = token.parentNode;
+			const struc = parent?.getDefinition();
+			const errors = [];
+			if ((0, __atscript_core.isInterface)(parent) && parent.props.has("_id") && (0, __atscript_core.isStructure)(struc)) {
+				const _id = parent.props.get("_id");
+				const isOptional = !!_id.token("optional");
+				if (isOptional) errors.push({
+					message: `[db.mongo] _id can't be optional in Mongo Collection`,
+					severity: 1,
+					range: _id.token("identifier").range
+				});
+				const definition = _id.getDefinition();
+				if (!definition) return errors;
+				let wrongType = false;
+				if ((0, __atscript_core.isRef)(definition)) {
+					const def = doc.unwindType(definition.id, definition.chain)?.def;
+					if ((0, __atscript_core.isPrimitive)(def) && !["string", "number"].includes(def.config.type)) wrongType = true;
+				} else wrongType = true;
+				if (wrongType) errors.push({
+					message: `[db.mongo] _id must be of type string, number or mongo.objectId`,
+					severity: 1,
+					range: _id.token("identifier").range
+				});
+			}
+			return errors;
+		},
+		modify(token, args, doc) {
+			const parent = token.parentNode;
+			const struc = parent?.getDefinition();
+			if ((0, __atscript_core.isInterface)(parent) && !parent.props.has("_id") && (0, __atscript_core.isStructure)(struc)) struc.addVirtualProp({
+				name: "_id",
+				type: "mongo.objectId",
+				documentation: "Mongodb Primary Key ObjectId"
+			});
+		}
+	}),
+	capped: new __atscript_core.AnnotationSpec({
+		description: "Creates a **capped collection** with a fixed maximum size.\n\n- Capped collections have fixed size and maintain insertion order.\n- Ideal for logs, event streams, and cache-like data.\n- Changing the cap size requires dropping and recreating the collection — use `@db.sync.method \"drop\"` to allow this.\n\n**Example:**\n```atscript\n@db.table \"logs\"\n@db.mongo.collection\n@db.mongo.capped 10485760, 10000\n@db.sync.method \"drop\"\nexport interface LogEntry {\n    message: string\n    timestamp: number\n}\n```\n",
+		nodeType: ["interface"],
+		multiple: false,
+		argument: [{
+			optional: false,
+			name: "size",
+			type: "number",
+			description: "Maximum size of the collection in **bytes**."
+		}, {
+			optional: true,
+			name: "max",
+			type: "number",
+			description: "Maximum number of documents in the collection. If omitted, only the byte size limit applies."
+		}]
+	}),
+	search: {
+		dynamic: new __atscript_core.AnnotationSpec({
+			description: "Creates a **dynamic MongoDB Search Index** that applies to the entire collection.\n\n- **Indexes all text fields automatically** (no need to specify fields).\n- Supports **language analyzers** for text tokenization.\n- Enables **fuzzy search** (typo tolerance) if needed.\n\n**Example:**\n```atscript\n@db.mongo.search.dynamic \"lucene.english\", 1\nexport interface MongoCollection {}\n```\n",
+			nodeType: ["interface"],
+			multiple: false,
+			argument: [{
+				optional: true,
+				name: "analyzer",
+				type: "string",
+				description: "The **text analyzer** for tokenization. Defaults to `\"lucene.standard\"`.\n\n**Available options:** `\"lucene.standard\"`, `\"lucene.english\"`, `\"lucene.spanish\"`, etc.",
+				values: analyzers
+			}, {
+				optional: true,
+				name: "fuzzy",
+				type: "number",
+				description: "Maximum typo tolerance (`0-2`). Defaults to `0` (no fuzzy search).\n\n- `0` → Exact match required.\n- `1` → Allows small typos (e.g., `\"mongo\"` ≈ `\"mango\"`).\n- `2` → More typo tolerance (e.g., `\"mongodb\"` ≈ `\"mangodb\"`)."
+			}]
+		}),
+		static: new __atscript_core.AnnotationSpec({
+			description: "Defines a **MongoDB Atlas Search Index** for the collection. The props can refer to this index using `@db.mongo.search.text` annotation.\n\n- **Creates a named search index** for full-text search.\n- **Specify analyzers and fuzzy search** behavior at the index level.\n- **Fields must explicitly use `@db.mongo.search.text`** to be included in this search index.\n\n**Example:**\n```atscript\n@db.mongo.search.static \"lucene.english\", 1, \"mySearchIndex\"\nexport interface MongoCollection {}\n```\n",
+			nodeType: ["interface"],
+			multiple: true,
+			argument: [
+				{
+					optional: true,
+					name: "analyzer",
+					type: "string",
+					description: "The text analyzer for tokenization. Defaults to `\"lucene.standard\"`.\n\n**Available options:** `\"lucene.standard\"`, `\"lucene.english\"`, `\"lucene.spanish\"`, `\"lucene.german\"`, etc.",
+					values: analyzers
+				},
+				{
+					optional: true,
+					name: "fuzzy",
+					type: "number",
+					description: "Maximum typo tolerance (`0-2`). **Defaults to `0` (no fuzzy matching).**\n\n- `0` → No typos allowed (exact match required).\n- `1` → Allows small typos (e.g., \"mongo\" ≈ \"mango\").\n- `2` → More typo tolerance (e.g., \"mongodb\" ≈ \"mangodb\")."
+				},
+				{
+					optional: true,
+					name: "indexName",
+					type: "string",
+					description: "The name of the search index. Fields must reference this name using `@db.mongo.search.text`. If not set, defaults to `\"DEFAULT\"`."
+				}
+			]
+		}),
+		text: new __atscript_core.AnnotationSpec({
+			description: "Marks a field to be **included in a MongoDB Atlas Search Index** defined by `@db.mongo.search.static`.\n\n- **The field has to reference an existing search index name**.\n- If index name is not defined, a new search index with default attributes will be created.\n\n**Example:**\n```atscript\n@db.mongo.search.text \"lucene.english\", \"mySearchIndex\"\nfirstName: string\n```\n",
+			nodeType: ["prop"],
+			multiple: true,
+			argument: [{
+				optional: true,
+				name: "analyzer",
+				type: "string",
+				description: "The text analyzer for tokenization. Defaults to `\"lucene.standard\"`.\n\n**Available options:** `\"lucene.standard\"`, `\"lucene.english\"`, `\"lucene.spanish\"`, `\"lucene.german\"`, etc.",
+				values: analyzers
+			}, {
+				optional: true,
+				name: "indexName",
+				type: "string",
+				description: "The **name of the search index** defined in `@db.mongo.search.static`. This links the field to the correct index. If not set, defaults to `\"DEFAULT\"`."
+			}]
+		})
+	}
+};
+
+//#endregion
+//#region packages/db-mongo/src/plugin/primitives.ts
+const primitives = { mongo: { extensions: { objectId: {
+	type: "string",
+	documentation: "Represents a **MongoDB ObjectId**.\n\n- Stored as a **string** but can be converted to an ObjectId at runtime.\n- Useful for handling `_id` fields and queries that require ObjectId conversion.\n- Automatically converts string `_id` values into **MongoDB ObjectId** when needed.\n\n**Example:**\n```atscript\nuserId: mongo.objectId\n```\n",
+	annotations: { "expect.pattern": { pattern: "^[a-fA-F0-9]{24}$" } }
+} } } };
+
+//#endregion
+//#region packages/db-mongo/src/plugin/index.ts
+const MongoPlugin = () => ({
+	name: "mongo",
+	config() {
+		return {
+			primitives,
+			annotations: { db: { mongo: annotations } }
+		};
+	}
+});
+
+//#endregion
+exports.MongoPlugin = MongoPlugin
+exports.default = MongoPlugin

package/dist/plugin.d.ts

@@ -0,0 +1,5 @@
+import { TAtscriptPlugin } from '@atscript/core';
+
+declare const MongoPlugin: () => TAtscriptPlugin;
+
+export { MongoPlugin, MongoPlugin as default };

package/dist/plugin.mjs

@@ -0,0 +1,162 @@
+import { AnnotationSpec, isInterface, isPrimitive, isRef, isStructure } from "@atscript/core";
+
+//#region packages/db-mongo/src/plugin/annotations.ts
+const analyzers = [
+	"lucene.standard",
+	"lucene.simple",
+	"lucene.whitespace",
+	"lucene.english",
+	"lucene.french",
+	"lucene.german",
+	"lucene.italian",
+	"lucene.portuguese",
+	"lucene.spanish",
+	"lucene.chinese",
+	"lucene.hindi",
+	"lucene.bengali",
+	"lucene.russian",
+	"lucene.arabic"
+];
+const annotations = {
+	collection: new AnnotationSpec({
+		description: "Marks an interface as a **MongoDB collection**.\n\n- Use together with `@db.table \"name\"` which provides the collection name.\n- Automatically injects a **non-optional** `_id` field if not explicitly defined.\n- `_id` must be of type **`string`**, **`number`**, or **`mongo.objectId`**.\n\n**Example:**\n```atscript\n@db.table \"users\"\n@db.mongo.collection\nexport interface User {\n    _id: mongo.objectId\n    email: string.email\n}\n```\n",
+		nodeType: ["interface"],
+		validate(token, args, doc) {
+			const parent = token.parentNode;
+			const struc = parent?.getDefinition();
+			const errors = [];
+			if (isInterface(parent) && parent.props.has("_id") && isStructure(struc)) {
+				const _id = parent.props.get("_id");
+				const isOptional = !!_id.token("optional");
+				if (isOptional) errors.push({
+					message: `[db.mongo] _id can't be optional in Mongo Collection`,
+					severity: 1,
+					range: _id.token("identifier").range
+				});
+				const definition = _id.getDefinition();
+				if (!definition) return errors;
+				let wrongType = false;
+				if (isRef(definition)) {
+					const def = doc.unwindType(definition.id, definition.chain)?.def;
+					if (isPrimitive(def) && !["string", "number"].includes(def.config.type)) wrongType = true;
+				} else wrongType = true;
+				if (wrongType) errors.push({
+					message: `[db.mongo] _id must be of type string, number or mongo.objectId`,
+					severity: 1,
+					range: _id.token("identifier").range
+				});
+			}
+			return errors;
+		},
+		modify(token, args, doc) {
+			const parent = token.parentNode;
+			const struc = parent?.getDefinition();
+			if (isInterface(parent) && !parent.props.has("_id") && isStructure(struc)) struc.addVirtualProp({
+				name: "_id",
+				type: "mongo.objectId",
+				documentation: "Mongodb Primary Key ObjectId"
+			});
+		}
+	}),
+	capped: new AnnotationSpec({
+		description: "Creates a **capped collection** with a fixed maximum size.\n\n- Capped collections have fixed size and maintain insertion order.\n- Ideal for logs, event streams, and cache-like data.\n- Changing the cap size requires dropping and recreating the collection — use `@db.sync.method \"drop\"` to allow this.\n\n**Example:**\n```atscript\n@db.table \"logs\"\n@db.mongo.collection\n@db.mongo.capped 10485760, 10000\n@db.sync.method \"drop\"\nexport interface LogEntry {\n    message: string\n    timestamp: number\n}\n```\n",
+		nodeType: ["interface"],
+		multiple: false,
+		argument: [{
+			optional: false,
+			name: "size",
+			type: "number",
+			description: "Maximum size of the collection in **bytes**."
+		}, {
+			optional: true,
+			name: "max",
+			type: "number",
+			description: "Maximum number of documents in the collection. If omitted, only the byte size limit applies."
+		}]
+	}),
+	search: {
+		dynamic: new AnnotationSpec({
+			description: "Creates a **dynamic MongoDB Search Index** that applies to the entire collection.\n\n- **Indexes all text fields automatically** (no need to specify fields).\n- Supports **language analyzers** for text tokenization.\n- Enables **fuzzy search** (typo tolerance) if needed.\n\n**Example:**\n```atscript\n@db.mongo.search.dynamic \"lucene.english\", 1\nexport interface MongoCollection {}\n```\n",
+			nodeType: ["interface"],
+			multiple: false,
+			argument: [{
+				optional: true,
+				name: "analyzer",
+				type: "string",
+				description: "The **text analyzer** for tokenization. Defaults to `\"lucene.standard\"`.\n\n**Available options:** `\"lucene.standard\"`, `\"lucene.english\"`, `\"lucene.spanish\"`, etc.",
+				values: analyzers
+			}, {
+				optional: true,
+				name: "fuzzy",
+				type: "number",
+				description: "Maximum typo tolerance (`0-2`). Defaults to `0` (no fuzzy search).\n\n- `0` → Exact match required.\n- `1` → Allows small typos (e.g., `\"mongo\"` ≈ `\"mango\"`).\n- `2` → More typo tolerance (e.g., `\"mongodb\"` ≈ `\"mangodb\"`)."
+			}]
+		}),
+		static: new AnnotationSpec({
+			description: "Defines a **MongoDB Atlas Search Index** for the collection. The props can refer to this index using `@db.mongo.search.text` annotation.\n\n- **Creates a named search index** for full-text search.\n- **Specify analyzers and fuzzy search** behavior at the index level.\n- **Fields must explicitly use `@db.mongo.search.text`** to be included in this search index.\n\n**Example:**\n```atscript\n@db.mongo.search.static \"lucene.english\", 1, \"mySearchIndex\"\nexport interface MongoCollection {}\n```\n",
+			nodeType: ["interface"],
+			multiple: true,
+			argument: [
+				{
+					optional: true,
+					name: "analyzer",
+					type: "string",
+					description: "The text analyzer for tokenization. Defaults to `\"lucene.standard\"`.\n\n**Available options:** `\"lucene.standard\"`, `\"lucene.english\"`, `\"lucene.spanish\"`, `\"lucene.german\"`, etc.",
+					values: analyzers
+				},
+				{
+					optional: true,
+					name: "fuzzy",
+					type: "number",
+					description: "Maximum typo tolerance (`0-2`). **Defaults to `0` (no fuzzy matching).**\n\n- `0` → No typos allowed (exact match required).\n- `1` → Allows small typos (e.g., \"mongo\" ≈ \"mango\").\n- `2` → More typo tolerance (e.g., \"mongodb\" ≈ \"mangodb\")."
+				},
+				{
+					optional: true,
+					name: "indexName",
+					type: "string",
+					description: "The name of the search index. Fields must reference this name using `@db.mongo.search.text`. If not set, defaults to `\"DEFAULT\"`."
+				}
+			]
+		}),
+		text: new AnnotationSpec({
+			description: "Marks a field to be **included in a MongoDB Atlas Search Index** defined by `@db.mongo.search.static`.\n\n- **The field has to reference an existing search index name**.\n- If index name is not defined, a new search index with default attributes will be created.\n\n**Example:**\n```atscript\n@db.mongo.search.text \"lucene.english\", \"mySearchIndex\"\nfirstName: string\n```\n",
+			nodeType: ["prop"],
+			multiple: true,
+			argument: [{
+				optional: true,
+				name: "analyzer",
+				type: "string",
+				description: "The text analyzer for tokenization. Defaults to `\"lucene.standard\"`.\n\n**Available options:** `\"lucene.standard\"`, `\"lucene.english\"`, `\"lucene.spanish\"`, `\"lucene.german\"`, etc.",
+				values: analyzers
+			}, {
+				optional: true,
+				name: "indexName",
+				type: "string",
+				description: "The **name of the search index** defined in `@db.mongo.search.static`. This links the field to the correct index. If not set, defaults to `\"DEFAULT\"`."
+			}]
+		})
+	}
+};
+
+//#endregion
+//#region packages/db-mongo/src/plugin/primitives.ts
+const primitives = { mongo: { extensions: { objectId: {
+	type: "string",
+	documentation: "Represents a **MongoDB ObjectId**.\n\n- Stored as a **string** but can be converted to an ObjectId at runtime.\n- Useful for handling `_id` fields and queries that require ObjectId conversion.\n- Automatically converts string `_id` values into **MongoDB ObjectId** when needed.\n\n**Example:**\n```atscript\nuserId: mongo.objectId\n```\n",
+	annotations: { "expect.pattern": { pattern: "^[a-fA-F0-9]{24}$" } }
+} } } };
+
+//#endregion
+//#region packages/db-mongo/src/plugin/index.ts
+const MongoPlugin = () => ({
+	name: "mongo",
+	config() {
+		return {
+			primitives,
+			annotations: { db: { mongo: annotations } }
+		};
+	}
+});
+
+//#endregion
+export { MongoPlugin, MongoPlugin as default };

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@atscript/db-mongo",
+  "version": "0.1.38",
+  "description": "Mongodb plugin for atscript.",
+  "keywords": [
+    "atscript",
+    "mongodb",
+    "plugin"
+  ],
+  "homepage": "https://github.com/moostjs/atscript/tree/main/packages/db-mongo#readme",
+  "bugs": {
+    "url": "https://github.com/moostjs/atscript/issues"
+  },
+  "license": "MIT",
+  "author": "Artem Maltsev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moostjs/atscript.git",
+    "directory": "packages/db-mongo"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "scripts/setup-skills.js"
+  ],
+  "type": "module",
+  "bin": {
+    "atscript-db-mongo-skill": "./scripts/setup-skills.js"
+  },
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "plugin": [
+        "dist/plugin.d.ts"
+      ],
+      "agg": [
+        "dist/agg.d.ts"
+      ],
+      "": [
+        "dist/index.d.ts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.mjs",
+      "require": "./dist/plugin.cjs"
+    },
+    "./agg": {
+      "types": "./dist/agg.d.ts",
+      "import": "./dist/agg.mjs",
+      "require": "./dist/agg.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "vitest": "3.2.4"
+  },
+  "peerDependencies": {
+    "mongodb": "^6.17.0",
+    "@atscript/core": "^0.1.38",
+    "@atscript/db": "^0.1.38",
+    "@atscript/typescript": "^0.1.38"
+  },
+  "build": [
+    {},
+    {
+      "entries": [
+        "src/plugin.ts"
+      ],
+      "dts": true
+    },
+    {
+      "entries": [
+        "src/agg.ts"
+      ],
+      "dts": true
+    }
+  ],
+  "scripts": {
+    "pub": "pnpm publish --access public",
+    "test": "vitest",
+    "setup-skills": "node ./scripts/setup-skills.js"
+  }
+}

package/scripts/setup-skills.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/* prettier-ignore */
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+const SKILL_NAME = 'atscript-db-mongo'
+const SKILL_SRC = path.join(__dirname, '..', 'skills', SKILL_NAME)
+
+if (!fs.existsSync(SKILL_SRC)) {
+  console.error(`No skills found at ${SKILL_SRC}`)
+  console.error('Add your SKILL.md files to the skills/' + SKILL_NAME + '/ directory first.')
+  process.exit(1)
+}
+
+const AGENTS = {
+  'Claude Code': { dir: '.claude/skills',   global: path.join(os.homedir(), '.claude', 'skills') },
+  'Cursor':      { dir: '.cursor/skills',   global: path.join(os.homedir(), '.cursor', 'skills') },
+  'Windsurf':    { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
+  'Codex':       { dir: '.codex/skills',    global: path.join(os.homedir(), '.codex', 'skills') },
+  'OpenCode':    { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
+}
+
+const args = process.argv.slice(2)
+const isGlobal = args.includes('--global') || args.includes('-g')
+const isPostinstall = args.includes('--postinstall')
+let installed = 0, skipped = 0
+const installedDirs = []
+
+for (const [agentName, cfg] of Object.entries(AGENTS)) {
+  const targetBase = isGlobal ? cfg.global : path.join(process.cwd(), cfg.dir)
+  const agentRootDir = path.dirname(cfg.global) // Check if the agent has ever been installed globally
+
+  // In postinstall mode: silently skip agents that aren't set up globally
+  if (isPostinstall || isGlobal) {
+    if (!fs.existsSync(agentRootDir)) { skipped++; continue }
+  }
+
+  const dest = path.join(targetBase, SKILL_NAME)
+  try {
+    fs.mkdirSync(dest, { recursive: true })
+    fs.cpSync(SKILL_SRC, dest, { recursive: true })
+    console.log(`✅  ${agentName}: installed to ${dest}`)
+    installed++
+    if (!isGlobal) installedDirs.push(cfg.dir + '/' + SKILL_NAME)
+  } catch (err) {
+    console.warn(`⚠️   ${agentName}: failed — ${err.message}`)
+  }
+}
+
+// Add locally-installed skill dirs to .gitignore
+if (!isGlobal && installedDirs.length > 0) {
+  const gitignorePath = path.join(process.cwd(), '.gitignore')
+  let gitignoreContent = ''
+  try { gitignoreContent = fs.readFileSync(gitignorePath, 'utf8') } catch {}
+  const linesToAdd = installedDirs.filter(d => !gitignoreContent.includes(d))
+  if (linesToAdd.length > 0) {
+    const hasHeader = gitignoreContent.includes('# AI agent skills')
+    const block = (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '')
+      + (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n')
+      + linesToAdd.join('\n') + '\n'
+    fs.appendFileSync(gitignorePath, block)
+    console.log(`📝  Added ${linesToAdd.length} entries to .gitignore`)
+  }
+}
+
+if (installed === 0 && isPostinstall) {
+  // Silence is fine — no agents present, nothing to do
+} else if (installed === 0 && skipped === Object.keys(AGENTS).length) {
+  console.log('No agent directories detected. Try --global or run without it for project-local install.')
+} else if (installed === 0) {
+  console.log('Nothing installed. Run without --global to install project-locally.')
+} else {
+  console.log(`\n✨  Done! Restart your AI agent to pick up the "${SKILL_NAME}" skill.`)
+}

package/skills/atscript-db-mongo/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: atscript-db-mongo
+description: Use this skill when working with @atscript/db-mongo — to define MongoDB collections with @db.table and @db.mongo.collection, create indexes with @db.index.plain/@db.index.unique/@db.mongo.index.text, configure Atlas Search with @db.mongo.search.*, control patch strategies with @db.mongo.patch.strategy, use AsCollection for CRUD operations (insert/replace/update/syncIndexes), validate data with createValidator, or configure MongoPlugin in atscript.config.
+---
+
+# @atscript/db-mongo
+
+MongoDB metadata extension for Atscript. Defines annotations for collections, indexes, search, and patch strategies, plus runtime classes (`AsCollection`, `AsMongo`) with built-in validation, filtering, querying, and writing.
+
+## How to use this skill
+
+Read the domain file that matches the task. Do not load all files — only what you need.
+
+| Domain | File | Load when... |
+|--------|------|-------------|
+| Core setup & plugin config | [core.md](core.md) | Installing the plugin, configuring atscript.config, understanding the plugin architecture |
+| Annotations reference | [annotations.md](annotations.md) | Writing .as files with database and MongoDB annotations, understanding annotation arguments |
+| Collections & CRUD | [collections.md](collections.md) | Using AsCollection/AsMongo for insert, replace, update, query, or sync indexes |
+| Patch strategies | [patches.md](patches.md) | Working with @db.mongo.patch.strategy, array patch operations ($insert/$upsert/$update/$remove/$replace) |
+
+## Quick reference
+
+```atscript
+@db.table 'users'
+@db.mongo.collection
+export interface User {
+    @db.index.unique 'email_idx'
+    email: string.email
+
+    @db.mongo.index.text 5
+    name: string
+
+    @db.index.plain 'status_idx'
+    isActive: boolean
+}
+```
+
+```typescript
+import { AsMongo } from '@atscript/db-mongo'
+import { User } from './user.as'
+
+const asMongo = new AsMongo('mongodb://localhost:27017/mydb')
+const users = asMongo.getCollection(User)
+await users.insert({ email: 'a@b.com', name: 'Alice', isActive: true })
+```