@atscript/db-mongo 0.1.54 → 0.1.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-mongo",
-  "version": "0.1.54",
+  "version": "0.1.55",
   "description": "Mongodb plugin for atscript.",
   "keywords": [
     "atscript",
@@ -18,13 +18,8 @@
     "url": "git+https://github.com/moostjs/atscript-db.git",
     "directory": "packages/db-mongo"
   },
-  "bin": {
-    "atscript-db-mongo-skill": "./scripts/setup-skills.js"
-  },
   "files": [
-    "dist",
-    "skills",
-    "scripts/setup-skills.js"
+    "dist"
   ],
   "type": "module",
   "main": "dist/index.mjs",
@@ -51,23 +46,22 @@
     "access": "public"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.48",
-    "@atscript/typescript": "^0.1.48",
+    "@atscript/core": "^0.1.50",
+    "@atscript/typescript": "^0.1.50",
     "mongodb": "^6.17.0",
-    "unplugin-atscript": "^0.1.48"
+    "unplugin-atscript": "^0.1.50"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.48",
-    "@atscript/typescript": "^0.1.48",
+    "@atscript/core": "^0.1.50",
+    "@atscript/typescript": "^0.1.50",
     "mongodb": "^6.17.0",
-    "@atscript/db": "^0.1.54"
+    "@atscript/db": "^0.1.55"
   },
   "scripts": {
     "postinstall": "asc -f dts",
     "build": "vp pack",
     "dev": "vp pack --watch",
     "test": "vp test",
-    "check": "vp check",
-    "setup-skills": "node ./scripts/setup-skills.js"
+    "check": "vp check"
   }
 }

package/scripts/setup-skills.js

@@ -1,88 +0,0 @@
-#!/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 = new Set(process.argv.slice(2));
-const isGlobal = args.has("--global") || args.has("-g");
-const isPostinstall = args.has("--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

@@ -1,45 +0,0 @@
----
-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 });
-```

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

@@ -1,168 +0,0 @@
-# Annotations Reference — @atscript/db-mongo
-
-> All database and MongoDB-specific annotations available when using the mongo plugin.
-
-## Annotation Namespaces
-
-Annotations are split between core `@db.*` (database-generic) and `@db.mongo.*` (MongoDB-specific).
-
-## Core `@db.*` Annotations
-
-These come from `@atscript/core` and are used by the mongo plugin at runtime.
-
-### `@db.table "name"` (interface-level)
-
-Names the collection. **Required** for `AsCollection` to work.
-
-```atscript
-@db.table 'users'
-export interface User {
-    name: string
-}
-```
-
-### `@db.index.plain "name?", "sort?"` (field-level, multiple)
-
-Standard index. Fields sharing the same name form a compound index.
-
-```atscript
-@db.table 'products'
-export interface Product {
-    @db.index.plain 'cat_status'
-    category: string
-
-    @db.index.plain 'cat_status'
-    status: string
-}
-```
-
-### `@db.index.unique "name?"` (field-level, multiple)
-
-Unique constraint index.
-
-```atscript
-@db.table 'users'
-export interface User {
-    @db.index.unique 'email_idx'
-    email: string.email
-}
-```
-
-### `@db.index.fulltext "name?"` (field-level, multiple)
-
-Generic fulltext index (always weight 1 in MongoDB).
-
-```atscript
-@db.table 'articles'
-export interface Article {
-    @db.index.fulltext
-    title: string
-}
-```
-
-## MongoDB-Specific `@db.mongo.*` Annotations
-
-### `@db.mongo.collection` (interface-level, no args)
-
-Optional convenience annotation. When present, auto-injects `_id: mongo.objectId` if the interface doesn't define one. Validates that `_id` (if present) is not optional and is of type string, number, or mongo.objectId.
-
-```atscript
-@db.table 'users'
-@db.mongo.collection
-export interface User {
-    // _id: mongo.objectId — auto-injected
-    name: string
-}
-```
-
-### `@db.mongo.autoIndexes true|false` (interface-level)
-
-Toggle automatic index creation when `syncIndexes()` is called. Default: true.
-
-### `@db.mongo.index.text weight?` (field-level)
-
-MongoDB-specific text index with optional weight (number). Extends `@db.index.fulltext` with weight support.
-
-```atscript
-@db.table 'articles'
-export interface Article {
-    @db.mongo.index.text 10
-    title: string
-
-    @db.mongo.index.text 1
-    body: string
-}
-```
-
-### `@db.mongo.search.dynamic "analyzer?", fuzzy?` (interface-level)
-
-Dynamic Atlas Search index.
-
-### `@db.mongo.search.static "analyzer?", fuzzy?, "indexName?"` (interface-level, multiple)
-
-Named static Atlas Search index.
-
-### `@db.mongo.search.text "analyzer?", "indexName?"` (field-level, multiple)
-
-Atlas Search text field mapping.
-
-### `@db.mongo.search.vector dimensions, "similarity?", "indexName?"` (field-level)
-
-Vector search index. Similarity: `"cosine"`, `"euclidean"`, or `"dotProduct"`.
-
-```atscript
-@db.table 'documents'
-export interface Document {
-    @db.mongo.search.vector 1536, "cosine", "vector_idx"
-    embedding: mongo.vector
-}
-```
-
-### `@db.mongo.search.filter "indexName"` (field-level, multiple)
-
-Pre-filter field for vector search.
-
-### `@db.mongo.patch.strategy "replace"|"merge"` (field-level)
-
-Controls how nested objects and arrays are updated during patch operations. See [patches.md](patches.md) for details.
-
-### `@db.mongo.array.uniqueItems` (field-level)
-
-Enforces set-semantics on array `$insert` operations — duplicates are silently dropped.
-
-```atscript
-@db.table 'tags'
-export interface TaggedItem {
-    @db.mongo.array.uniqueItems
-    tags: string[]
-}
-```
-
-## Common Patterns
-
-### Full collection definition
-
-```atscript
-@db.table 'users'
-@db.mongo.collection
-export interface User {
-    @db.index.unique 'email_idx'
-    email: string.email
-
-    @db.mongo.index.text 5
-    @expect.minLength 2
-    name: string
-
-    @db.index.plain 'status_idx'
-    isActive: boolean
-
-    @db.mongo.patch.strategy 'merge'
-    profile: {
-        bio?: string
-        avatar?: string
-    }
-
-    @db.mongo.array.uniqueItems
-    tags?: string[]
-}
-```

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

@@ -1,142 +0,0 @@
-# Collections & CRUD — @atscript/db-mongo
-
-> Using AsMongo and AsCollection for database operations.
-
-## AsMongo
-
-Entry point for MongoDB operations. Wraps a `MongoClient` and provides a collection registry.
-
-```typescript
-import { AsMongo } from "@atscript/db-mongo";
-
-// From connection string
-const asMongo = new AsMongo("mongodb://localhost:27017/mydb");
-
-// From existing MongoClient
-const asMongo = new AsMongo(existingClient);
-
-// With logger
-const asMongo = new AsMongo(connectionString, myLogger);
-```
-
-### `getCollection<T>(type, logger?)`
-
-Returns an `AsCollection<T>` for the given Atscript annotated type. Collections are cached per type.
-
-```typescript
-import { User } from "./user.as";
-
-const users = asMongo.getCollection(User);
-```
-
-## AsCollection
-
-Core collection abstraction providing validation, CRUD operations, and index management.
-
-### Properties
-
-- **`name`** — Collection name (from `@db.table`)
-- **`collection`** — Raw MongoDB `Collection` instance
-- **`flatMap`** — `Map<string, TAtscriptAnnotatedType>` of all fields in dot-notation
-
-### Insert
-
-```typescript
-// Insert one
-const result = await users.insert({
-  email: "alice@example.com",
-  name: "Alice",
-  isActive: true,
-});
-
-// Insert many
-const result = await users.insert([
-  { email: "alice@example.com", name: "Alice", isActive: true },
-  { email: "bob@example.com", name: "Bob", isActive: false },
-]);
-```
-
-Validates the payload before inserting. Auto-generates `ObjectId` for `_id` if type is `mongo.objectId`.
-
-### Replace
-
-```typescript
-await users.replace({
-  _id: "507f1f77bcf86cd799439011",
-  email: "alice@new.com",
-  name: "Alice Updated",
-  isActive: true,
-});
-```
-
-Validates the full document and replaces by `_id`.
-
-### Update (Patch)
-
-```typescript
-await users.update({
-  _id: "507f1f77bcf86cd799439011",
-  name: "New Name",
-  // Only updates specified fields
-});
-```
-
-Uses `CollectionPatcher` internally to build MongoDB aggregation pipelines. See [patches.md](patches.md) for array patch operations.
-
-### Validation
-
-```typescript
-// Get a validator for different contexts
-const insertValidator = users.getValidator("insert");
-const updateValidator = users.getValidator("update");
-const patchValidator = users.getValidator("patch");
-
-// Create a custom validator
-const validator = users.createValidator({
-  partial: true,
-  plugins: [myPlugin],
-  skipList: new Set(["internalField"]),
-});
-```
-
-### Index Management
-
-```typescript
-// Sync indexes — creates/drops to match .as definitions
-await users.syncIndexes();
-```
-
-Only manages indexes prefixed with `atscript__`. User-created indexes are not touched.
-
-Reads index definitions from:
-
-- `@db.index.plain` → standard indexes
-- `@db.index.unique` → unique indexes
-- `@db.index.fulltext` → text indexes (weight 1)
-- `@db.mongo.index.text` → text indexes (custom weight)
-- `@db.mongo.search.*` → Atlas Search indexes
-
-### Querying
-
-```typescript
-// Find documents
-const cursor = users.collection.find({ isActive: true });
-
-// Use the raw MongoDB collection for queries
-const doc = await users.collection.findOne({ _id: users.prepareId(id) });
-```
-
-### `prepareId(id)`
-
-Converts a string ID to `ObjectId` if the collection uses `mongo.objectId` type for `_id`.
-
-```typescript
-const objectId = users.prepareId("507f1f77bcf86cd799439011");
-```
-
-## Best Practices
-
-- Use `getValidator()` for context-specific validation before custom operations
-- Call `syncIndexes()` on application startup to ensure indexes match definitions
-- Use `prepareId()` when working with raw MongoDB queries to handle ObjectId conversion
-- The `flatMap` property is lazily built — first access triggers computation

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

@@ -1,84 +0,0 @@
-# Core Setup — @atscript/db-mongo
-
-> Plugin installation, configuration, and architecture overview.
-
-## Installation
-
-```bash
-npm install @atscript/db-mongo
-# peer dependencies:
-npm install @atscript/core @atscript/typescript mongodb
-```
-
-## Plugin Configuration
-
-Add `MongoPlugin()` to your `atscript.config.ts`:
-
-```typescript
-import { defineConfig } from "@atscript/core";
-import { ts } from "@atscript/typescript";
-import MongoPlugin from "@atscript/db-mongo/plugin";
-
-export default defineConfig({
-  rootDir: "src",
-  plugins: [ts(), MongoPlugin()],
-});
-```
-
-The plugin registers:
-
-- **Primitives**: `mongo.objectId` (24-char hex string), `mongo.vector` (number array)
-- **Annotations**: All `@db.mongo.*` annotations (collection, indexes, search, patch, array)
-
-## Architecture
-
-```
-@atscript/db-mongo
-├── plugin/
-│   ├── index.ts          — MongoPlugin factory
-│   ├── annotations.ts    — All db.mongo.* annotation specs
-│   └── primitives.ts     — mongo.objectId, mongo.vector
-└── lib/
-    ├── as-mongo.ts        — AsMongo: MongoDB client wrapper
-    ├── as-collection.ts   — AsCollection: collection abstraction (validation, indexes, CRUD)
-    ├── collection-patcher.ts — Converts patch payloads to MongoDB aggregation pipelines
-    └── validate-plugins.ts   — Validator plugins for ObjectId and unique arrays
-```
-
-## Primitives
-
-### `mongo.objectId`
-
-A string type constrained to `/^[a-fA-F0-9]{24}$/`. Used for MongoDB `_id` fields.
-
-```atscript
-export interface User {
-    _id: mongo.objectId
-    name: string
-}
-```
-
-### `mongo.vector`
-
-An alias for `number[]`. Used for vector search fields.
-
-```atscript
-export interface Document {
-    embedding: mongo.vector
-}
-```
-
-## Regenerating atscript.d.ts
-
-After annotation changes, regenerate the type declarations:
-
-```bash
-cd packages/db-mongo && node ../typescript/dist/cli.cjs -f dts
-```
-
-## Best Practices
-
-- Always use `@db.table` to name your collections — it's required by `AsCollection`
-- `@db.mongo.collection` is optional — it only auto-injects `_id: mongo.objectId` if missing
-- Use `mongo.objectId` type for `_id` fields when you want ObjectId-based IDs
-- Use `string` type for `_id` when you want string-based IDs

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

@@ -1,206 +0,0 @@
-# Patch Strategies — @atscript/db-mongo
-
-> How `@db.mongo.patch.strategy` and array patch operations work.
-
-## Overview
-
-When updating documents via `AsCollection.update()`, the `CollectionPatcher` converts your patch payload into MongoDB aggregation pipeline stages. The behavior depends on two things:
-
-1. **`@db.mongo.patch.strategy`** on objects — controls whether nested objects are replaced or merged
-2. **Array key fields** (`@expect.array.key`) and patch operations — controls how array elements are matched and modified
-
-## Object Patch Strategies
-
-### Default (no annotation) — Replace
-
-Without `@db.mongo.patch.strategy`, nested objects are fully replaced:
-
-```atscript
-@db.table 'users'
-export interface User {
-    address: {
-        line1: string
-        city: string
-        zip: string
-    }
-}
-```
-
-```typescript
-// This replaces the entire address object
-await users.update({
-  _id: id,
-  address: { line1: "123 Main St", city: "NYC", zip: "10001" },
-});
-```
-
-### `@db.mongo.patch.strategy 'replace'`
-
-Explicit replacement — same as default. The entire nested object is overwritten.
-
-### `@db.mongo.patch.strategy 'merge'`
-
-Individual fields within the nested object are updated without affecting unspecified fields:
-
-```atscript
-@db.table 'users'
-export interface User {
-    @db.mongo.patch.strategy 'merge'
-    contacts: {
-        email: string
-        phone: string
-    }
-}
-```
-
-```typescript
-// Only updates phone, email is preserved
-await users.update({
-  _id: id,
-  contacts: { phone: "+1-555-0100" },
-});
-```
-
-### Nested strategies
-
-Strategies can be applied at any nesting level:
-
-```atscript
-@db.table 'config'
-export interface Config {
-    @db.mongo.patch.strategy 'merge'
-    settings: {
-        @db.mongo.patch.strategy 'replace'
-        theme: { primary: string, secondary: string }
-
-        @db.mongo.patch.strategy 'merge'
-        notifications: { email: boolean, push: boolean }
-    }
-}
-```
-
-## Array Patch Operations
-
-Top-level arrays in a patch payload use a structured format with operation keys.
-
-### `$replace`
-
-Replaces the entire array:
-
-```typescript
-await collection.update({
-  _id: id,
-  tags: { $replace: ["new", "tags", "only"] },
-});
-```
-
-### `$insert`
-
-Appends items to the array:
-
-```typescript
-await collection.update({
-  _id: id,
-  tags: { $insert: ["newTag1", "newTag2"] },
-});
-```
-
-If `@db.mongo.array.uniqueItems` is set, duplicates are silently dropped (uses `$setUnion`).
-
-### `$upsert`
-
-Insert-or-update by key. For keyed arrays (`@expect.array.key`), removes existing elements matching the key(s) and appends the new ones:
-
-```atscript
-@db.table 'products'
-export interface Product {
-    items: {
-        @expect.array.key
-        sku: string
-        quantity: number
-        price: number
-    }[]
-}
-```
-
-```typescript
-await products.update({
-  _id: id,
-  items: {
-    $upsert: [
-      { sku: "ABC", quantity: 10, price: 9.99 }, // replaces existing ABC or inserts
-    ],
-  },
-});
-```
-
-For non-keyed arrays, behaves like `$addToSet` (deep equality).
-
-### `$update`
-
-Updates existing array elements matched by key:
-
-```typescript
-await products.update({
-  _id: id,
-  items: {
-    $update: [
-      { sku: "ABC", quantity: 20 }, // updates only quantity for sku=ABC
-    ],
-  },
-});
-```
-
-With `@db.mongo.patch.strategy 'merge'` on the array field, uses `$mergeObjects` to merge into the matched element. Without it, replaces the matched element entirely.
-
-### `$remove`
-
-Removes array elements:
-
-```typescript
-// Keyed — removes by key match
-await products.update({
-  _id: id,
-  items: {
-    $remove: [{ sku: "ABC" }],
-  },
-});
-
-// Non-keyed — removes by deep equality
-await collection.update({
-  _id: id,
-  tags: {
-    $remove: ["obsoleteTag"],
-  },
-});
-```
-
-## Array Keys
-
-Use `@expect.array.key` to mark fields that uniquely identify array elements:
-
-```atscript
-export interface Translations {
-    entries: {
-        @expect.array.key
-        lang: string
-        @expect.array.key
-        key: string
-        value: string
-    }[]
-}
-```
-
-Multiple key fields form a composite key — elements are matched when ALL key fields match.
-
-## Implementation Details
-
-The `CollectionPatcher` converts patch payloads into MongoDB aggregation pipeline stages using:
-
-- `$reduce` + `$filter` + `$concatArrays` for keyed upsert/remove
-- `$map` + `$cond` + `$mergeObjects` for keyed update with merge
-- `$setUnion` for unique/non-keyed insert
-- `$setDifference` for non-keyed remove
-- `$concatArrays` for plain append
-
-All operations are performed atomically in a single `updateOne()` call using an aggregation pipeline.