From 80d35fef4ed00d9974373e650e672344bb45723b Mon Sep 17 00:00:00 2001 From: harshitha-cstk Date: Wed, 1 Apr 2026 16:07:32 +0530 Subject: [PATCH 1/6] Add version bump check workflow and remove old release workflow --- .github/workflows/check-version-bump.yml | 79 ++++++++++++++++++++++++ .github/workflows/release.yml | 77 ----------------------- .husky/post-checkout | 40 ++++++++++++ 3 files changed, 119 insertions(+), 77 deletions(-) create mode 100644 .github/workflows/check-version-bump.yml delete mode 100644 .github/workflows/release.yml create mode 100755 .husky/post-checkout diff --git a/.github/workflows/check-version-bump.yml b/.github/workflows/check-version-bump.yml new file mode 100644 index 0000000..31bdf66 --- /dev/null +++ b/.github/workflows/check-version-bump.yml @@ -0,0 +1,79 @@ +# Catches when developers forget to bump package.json for release-affecting changes. +# App code changes (app.js, bin/, config/, routes/, views/, etc.) require a version bump vs latest tag. +# Skips for: test-only, docs, .github (workflows/config), dependency-only bumps without app edits. +name: Check Version Bump + +on: + pull_request: + +jobs: + version-bump: + name: Version bump + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Detect changed files and version bump + id: detect + run: | + if git rev-parse HEAD^2 >/dev/null 2>&1; then + FILES=$(git diff --name-only HEAD^1 HEAD^2) + else + FILES=$(git diff --name-only HEAD~1 HEAD) + fi + VERSION_FILES_CHANGED=false + echo "$FILES" | grep -qx 'package.json' && VERSION_FILES_CHANGED=true + echo "version_files_changed=$VERSION_FILES_CHANGED" >> $GITHUB_OUTPUT + # App source paths for this boilerplate (no lib/webpack/dist); .github/ and test/ do not count + CODE_CHANGED=false + echo "$FILES" | grep -qE '^app\.js$|^bin/|^config/|^middlewares/|^models/|^public/|^routes/|^views/|^schemaNentries/' && CODE_CHANGED=true + echo "$FILES" | grep -qx 'package.json' && CODE_CHANGED=true + echo "code_changed=$CODE_CHANGED" >> $GITHUB_OUTPUT + + - name: Skip when only test/docs/.github changed + if: steps.detect.outputs.code_changed != 'true' + run: | + echo "No release-affecting files changed (e.g. only test/docs/.github). Skipping version-bump check." + exit 0 + + - name: Fail when version bump was missed + if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed != 'true' + run: | + echo "::error::This PR has code changes but no version bump. Please bump the version in package.json." + exit 1 + + - name: Setup Node + if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed == 'true' + uses: actions/setup-node@v4 + with: + node-version: '22.x' + + - name: Check version bump + if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed == 'true' + run: | + set -e + PKG_VERSION=$(node -p "require('./package.json').version.replace(/^v/, '')") + if [ -z "$PKG_VERSION" ]; then + echo "::error::Could not read version from package.json" + exit 1 + fi + git fetch --tags --force 2>/dev/null || true + LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || true) + if [ -z "$LATEST_TAG" ]; then + echo "No existing tags found. Skipping version-bump check (first release)." + exit 0 + fi + LATEST_VERSION="${LATEST_TAG#v}" + LATEST_VERSION="${LATEST_VERSION%%-*}" + if [ "$(printf '%s\n' "$LATEST_VERSION" "$PKG_VERSION" | sort -V | tail -1)" != "$PKG_VERSION" ]; then + echo "::error::Version bump required: package.json version ($PKG_VERSION) is not greater than latest tag ($LATEST_TAG). Please bump the version in package.json." + exit 1 + fi + if [ "$PKG_VERSION" = "$LATEST_VERSION" ]; then + echo "::error::Version bump required: package.json version ($PKG_VERSION) equals latest tag ($LATEST_TAG). Please bump the version in package.json." + exit 1 + fi + echo "Version bump check passed: package.json is at $PKG_VERSION (latest tag: $LATEST_TAG)." diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml deleted file mode 100644 index 964fa22..0000000 --- a/.github/workflows/release.yml +++ /dev/null @@ -1,77 +0,0 @@ -name: Release - -on: - push: - branches: [master] - -jobs: - build: - runs-on: ubuntu-latest - steps: - # Checkout the repository - - name: Checkout repository - uses: actions/checkout@v4 - - # Setup Node.js environment - - name: Setup Node.js - uses: actions/setup-node@v4 - with: - node-version: "22.x" - - # Install dependencies - - name: Install dependencies - run: npm install - - # Fetch package details (name and version) - - name: Get package details - id: package - uses: codex-team/action-nodejs-package-info@v1.1 - - # Install npm-pack-all to create a package archive - - name: Install npm pack - run: npm install npm-pack - - # Pack the package into a .tgz archive - - name: Pack the npm package - run: npm pack - - # Publish the package to npm - - name: Publish to npm - id: publish_npm - uses: JS-DevTools/npm-publish@v3 - with: - token: ${{ secrets.NPM_TOKEN }} - # access: public # Uncomment this line if you want to publish the package as public for first time - - # Auto-tag the new version if a change is detected - - name: Auto-tag new version - id: update_tag - uses: Klemensas/action-autotag@stable - with: - GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}" - tag_prefix: "v" - - # Create a new GitHub Release - - name: Create GitHub Release - if: steps.update_tag.outputs.tagname != '' - uses: actions/create-release@v1 - id: create_release - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - with: - tag_name: ${{ steps.update_tag.outputs.tagname }} - release_name: Release ${{ steps.update_tag.outputs.tagname }} - draft: false - prerelease: false - - # Upload the packaged .tgz file as a release asset - - name: Upload Release Asset - if: steps.update_tag.outputs.tagname != '' - uses: actions/upload-release-asset@v1 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - with: - upload_url: ${{ steps.create_release.outputs.upload_url }} - asset_path: "./contentstack-datasync-mongodb-sdk-${{ steps.package.outputs.version }}.tgz" - asset_name: "contentstack-datasync-mongodb-sdk-${{ steps.package.outputs.version }}.tgz" - asset_content_type: application/tgz diff --git a/.husky/post-checkout b/.husky/post-checkout new file mode 100755 index 0000000..302fdc6 --- /dev/null +++ b/.husky/post-checkout @@ -0,0 +1,40 @@ +#!/usr/bin/env sh +# When switching to a branch that doesn't exist on remote (e.g. newly created), +# pull and merge origin/main or origin/master into current branch. Does not push. + +# Only run on branch checkout (not file checkout) +if [ "$3" != "1" ]; then + exit 0 +fi + +# Skip if we don't have a remote +if ! git rev-parse --verify origin 2>/dev/null; then + exit 0 +fi + +CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD) + +# Skip main/master - no need to merge base into these +case "$CURRENT_BRANCH" in + main|master) exit 0 ;; +esac + +# Only run when current branch does not exist on origin (treat as new local branch) +if git ls-remote --heads origin "$CURRENT_BRANCH" 2>/dev/null | grep -q .; then + echo "post-checkout: $CURRENT_BRANCH exists on origin, skipping merge." + exit 0 +fi + +# Prefer main, fallback to master +if git rev-parse --verify origin/main 2>/dev/null; then + BASE=origin/main +elif git rev-parse --verify origin/master 2>/dev/null; then + BASE=origin/master +else + exit 0 +fi + +echo "New branch detected: merging latest $BASE into $CURRENT_BRANCH (local only, not pushing)..." +git fetch origin +git merge "$BASE" --no-edit --no-ff +echo "Done. Merge is local only; push when ready." From 20204161f5eead031e96562f77881f1d76fadac7 Mon Sep 17 00:00:00 2001 From: harshitha-cstk Date: Wed, 1 Apr 2026 16:18:37 +0530 Subject: [PATCH 2/6] add cursor rules and skills --- .cursor/rules/README.md | 24 +++++++++ .cursor/rules/code-review.mdc | 41 +++++++++++++++ .cursor/rules/datasync-mongodb.mdc | 32 ++++++++++++ .cursor/rules/dev-workflow.md | 29 +++++++++++ .cursor/rules/testing.mdc | 35 +++++++++++++ .cursor/rules/typescript.mdc | 28 ++++++++++ AGENTS.md | 49 +++++++++++++++++ skills/README.md | 14 +++++ skills/code-review/SKILL.md | 52 +++++++++++++++++++ .../SKILL.md | 45 ++++++++++++++++ skills/testing/SKILL.md | 41 +++++++++++++++ 11 files changed, 390 insertions(+) create mode 100644 .cursor/rules/README.md create mode 100644 .cursor/rules/code-review.mdc create mode 100644 .cursor/rules/datasync-mongodb.mdc create mode 100644 .cursor/rules/dev-workflow.md create mode 100644 .cursor/rules/testing.mdc create mode 100644 .cursor/rules/typescript.mdc create mode 100644 AGENTS.md create mode 100644 skills/README.md create mode 100644 skills/code-review/SKILL.md create mode 100644 skills/contentstack-typescript-datasync-mongodb/SKILL.md create mode 100644 skills/testing/SKILL.md diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md new file mode 100644 index 0000000..f8c956c --- /dev/null +++ b/.cursor/rules/README.md @@ -0,0 +1,24 @@ +# Cursor rules — `@contentstack/datasync-mongodb-sdk` + +This directory contains project-specific rules for AI assistants and developers. Rules use YAML frontmatter with `description`, and optionally `globs` and/or `alwaysApply`. + +## How to use + +- Rules with **`alwaysApply: true`** are intended to be loaded in relevant sessions automatically (depending on your Cursor settings). +- Rules with **globs** apply when editing matching files. +- For rules without `alwaysApply`, reference them explicitly when needed, e.g. **`@dev-workflow`**, **`@typescript`**, **`@datasync-mongodb`**, **`@testing`**, **`@code-review`** (use the file base name as shown in your Cursor UI). + +## Rule index + +| File | alwaysApply | Globs | When it applies | +|------|-------------|-------|-----------------| +| [dev-workflow.md](./dev-workflow.md) | No | *(none)* | Branching, scripts, PR/release expectations, security hooks | +| [typescript.mdc](./typescript.mdc) | No | `src/**/*.ts`, `typings/**/*.ts` | TypeScript style, layout, TSLint alignment | +| [datasync-mongodb.mdc](./datasync-mongodb.mdc) | No | `src/**/*.ts` | DataSync MongoDB SDK patterns (Stack, config, MongoDB — not CDA/CMA) | +| [testing.mdc](./testing.mdc) | No | `test/**/*.ts`, `jest.config.js` | Jest tests, MongoDB integration tests, fixtures | +| [code-review.mdc](./code-review.mdc) | **Yes** | *(global)* | PR checklist, terminology (DataSync vs CDA/CMA) | + +## Related + +- Root agent entry point: [../../AGENTS.md](../../AGENTS.md) (repository root) +- Skills index: [../../skills/README.md](../../skills/README.md) diff --git a/.cursor/rules/code-review.mdc b/.cursor/rules/code-review.mdc new file mode 100644 index 0000000..9d6a64d --- /dev/null +++ b/.cursor/rules/code-review.mdc @@ -0,0 +1,41 @@ +--- +description: PR review checklist for DataSync MongoDB SDK — API docs, compatibility, errors, tests, dependencies. +alwaysApply: true +--- + +# Code review checklist + +## Product terminology + +- This repo is the **DataSync MongoDB SDK** (local MongoDB over synced content). Do **not** describe changes as **CDA** (Delivery API) or **CMA** (Management API) unless the PR explicitly integrates separate HTTP clients — that is not the core of this package. + +## Public API and docs + +- New or changed **public** methods on `Contentstack` / `Stack` should have accurate **JSDoc** consistent with existing files. +- README / example snippets should stay aligned with **`Stack.connect()`** and config shape in `src/config.ts`. + +## Backward compatibility + +- Avoid breaking changes to method names, config keys, and default behaviors without a semver-major plan. +- Consider existing synced MongoDB document shapes and locale/collection naming. + +## Errors and behavior + +- Prefer consistent error messages via **`src/messages.ts`** where applicable. +- Preserve null/undefined handling consistent with MongoDB driver and existing query chains. + +## Dependencies and security + +- New dependencies need justification (bundle size, maintenance, overlap with `lodash` / `mongodb` / `sift`). +- Be mindful of **SCA** / supply-chain expectations (Snyk runs in husky pre-commit for many devs). + +## Tests + +- Meaningful **Jest** coverage for new branches; run **`npm test`** with MongoDB available. +- Update or add fixtures under **`test/data/`** when adding query scenarios. + +## Severity (optional) + +- **Blocker:** Crashes, data corruption risk, security issues, broken public API contract. +- **Major:** Incorrect results, missing tests for critical paths, breaking changes without version strategy. +- **Minor:** Style, small refactors, doc typos. diff --git a/.cursor/rules/datasync-mongodb.mdc b/.cursor/rules/datasync-mongodb.mdc new file mode 100644 index 0000000..0858a60 --- /dev/null +++ b/.cursor/rules/datasync-mongodb.mdc @@ -0,0 +1,32 @@ +--- +description: DataSync MongoDB SDK — Stack API, MongoDB connection, config, and query patterns (not CDA/CMA HTTP APIs). +globs: + - src/**/*.ts +alwaysApply: false +--- + +# DataSync MongoDB SDK core + +This package **queries MongoDB** that holds Contentstack **DataSync**-synced content. It does **not** call Contentstack **Delivery** or **Management** REST APIs. + +## Mental model + +- **`Contentstack.Stack(config, existingDb?)`** (`src/index.ts`) returns **`Stack`** (`src/stack.ts`). +- Call **`Stack.connect()`** before queries (see README). +- Config merges with defaults in **`src/config.ts`**: `contentStore.url`, `dbName`, collection names (`collection.asset` / `entry` / `schema`), `locale`, `limit`, `skip`, `referenceDepth`, `projections`, `options` (MongoClient options), indexes, etc. +- Optional second constructor argument: an **existing MongoDB connection** for advanced hosting scenarios. + +## Patterns in code + +- Uses **`mongodb`** driver (`MongoClient`, `Db`, collections). +- Uses **`sift`** for filter matching where applicable. +- **Locales** and **content type** UIDs drive collection naming and queries; respect `validateConfig` / URI validation in **`src/util.ts`**. +- Errors and user-facing strings live in **`src/messages.ts`**. + +## Documentation alignment + +- Product docs: [Contentstack DataSync](https://www.contentstack.com/docs/guide/synchronization/contentstack-datasync) and related DataSync / content-store-mongodb material — **not** CDA/CMA API reference docs for HTTP JSON payloads. + +## Out of scope for this SDK + +- Do not model this package as an HTTP SDK or assume `fetch`/axios patterns for Contentstack cloud APIs here. diff --git a/.cursor/rules/dev-workflow.md b/.cursor/rules/dev-workflow.md new file mode 100644 index 0000000..c27ccfe --- /dev/null +++ b/.cursor/rules/dev-workflow.md @@ -0,0 +1,29 @@ +--- +description: Branch workflow, npm scripts, PR expectations, version bumps, and local security hooks for this repo. +--- + +# Development workflow + +## Branches + +Use your team’s Git conventions (feature branches off the main integration branch, PR-based merge). No branch naming scheme is enforced in this repository’s config files. + +## Lint and tests + +- **Compile:** `npm run compile` or `npm run build-ts` (clean + build). +- **Tests:** `npm test` (Jest). Requires a **running MongoDB** reachable at the URL in stack config (defaults to `mongodb://localhost:27017`). +- **Lint:** `npm run tslint` (TSLint on `src/**/*.ts`). + +## Pre-commit (local) + +`.husky/pre-commit` runs **Snyk** (`snyk test --all-projects`) and **Talisman** secret scanning. Both tools must be installed on the developer machine unless commits are skipped with `SKIP_HOOK=1` (documented in the hook). This is separate from `npm test` / `tslint`. + +## Pull requests + +- Prefer green **Jest** runs for changes that touch query or connection behavior. +- Repository automation may include **SCA**, **policy**, and **CodeQL** workflows under `.github/workflows/` — follow failing checks before merge. +- **Version bump:** `.github/workflows/check-version-bump.yml` enforces `package.json` version bumps for certain change sets. *Note:* That workflow’s path filters appear tailored to a different layout in places; if your PR changes `src/` or `test/` and CI expects a version bump, confirm behavior against the latest workflow definition. + +## Releases + +Package version is **`package.json` → `version`**. Publishing uses `publishConfig.access: public`. Bump the version when releasing; align with maintainers on semver for breaking Stack API or config shape changes. diff --git a/.cursor/rules/testing.mdc b/.cursor/rules/testing.mdc new file mode 100644 index 0000000..836b8d8 --- /dev/null +++ b/.cursor/rules/testing.mdc @@ -0,0 +1,35 @@ +--- +description: Jest tests, MongoDB integration requirements, and test data layout for datasync-mongodb-sdk. +globs: + - test/**/*.ts + - jest.config.js +alwaysApply: false +--- + +# Testing + +## Runner and config + +- **Jest** with **`ts-jest`** preset (`jest.config.js`). +- **Environment:** `node`. +- **Match:** `**/test/**/*.ts` (and `.js` if present). +- **Coverage:** collected to `coverage/` (JSON + HTML reporters). `test/data/*` paths are ignored per `testPathIgnorePatterns`. + +## Integration vs unit + +- Tests are largely **integration**: they connect to a **real MongoDB** via `Stack.connect()`, insert fixtures, assert query results, then tear down collections / close the client. +- There is no separate `test/integration` folder; behavior is split by topic files (e.g. `core.ts`, `queries.ts`, `references.ts`). + +## Fixtures + +- Shared sample documents: `test/data/*.ts` (e.g. `blog.ts`, `author.ts`, `content_types.ts`). +- Stack config for tests: **`test/config.ts`** (e.g. `dbName: 'sync-test'`). + +## Environment + +- Default Mongo URL comes from merged **`src/config.ts`** (`contentStore.url`) unless tests override `contentStore` in the config object passed to `Contentstack.Stack(...)`. +- No standard **`env` file** is defined in-repo for tests; use local MongoDB or explicitly pass `contentStore.url` in test configs. + +## Naming + +- Test files use descriptive topic names (`comparison-operators.ts`, `skip-limit.ts`, etc.), not `*.test.ts` — Jest picks them up via `testMatch`. diff --git a/.cursor/rules/typescript.mdc b/.cursor/rules/typescript.mdc new file mode 100644 index 0000000..3b21eb9 --- /dev/null +++ b/.cursor/rules/typescript.mdc @@ -0,0 +1,28 @@ +--- +description: TypeScript conventions for this repo — compiler settings, TSLint, and src/ layout. +globs: + - src/**/*.ts + - typings/**/*.ts +alwaysApply: false +--- + +# TypeScript — datasync-mongodb-sdk + +## Toolchain + +- **TypeScript** ~4.9 (`package.json` / `tsconfig.json`). +- **Module:** CommonJS, `target` ES6, `moduleResolution` node. Declarations emit to `typings/`, JS to `dist/`. +- **Strictness:** `alwaysStrict`, `noImplicitReturns`, `noUnusedLocals`, `noUnusedParameters`, `noFallthroughCasesInSwitch`. + +## Style (TSLint) + +Align with `tslint.json`: **2-space** indent, **single quotes**, **no semicolons** (`semicolon: never`), **max line length 120**, `only-arrow-functions`, `ordered-imports`, `interface-name` with `I` prefix where used, `no-default-export` (prefer named exports from modules — entry re-exports via `src/index.ts`). + +## Layout + +- Keep new logic in `src/`; avoid expanding `example/` for core behavior. +- Match existing patterns: JSDoc blocks on public classes/methods where the file already uses them. + +## Logging + +- Avoid adding `console.log` / noisy logging in library paths; TSLint warns on several `console` methods. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..aac1724 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,49 @@ +# Agent guidance — `@contentstack/datasync-mongodb-sdk` + +## What this package is + +**Contentstack DataSync MongoDB SDK** — a TypeScript/JavaScript library that **queries content already synced into MongoDB** (via Contentstack DataSync and stores such as `@contentstack/content-store-mongodb`). It is **not** a Content Delivery API (CDA) or Content Management API (CMA) HTTP client; it wraps the **MongoDB Node.js driver**, uses **sift** for predicate matching, and exposes a **Stack**-style query API over local collections. + +## Repository + +- **GitHub:** https://github.com/contentstack/datasync-mongodb-sdk + +## Tech stack + +| Area | Details | +|------|---------| +| Language | TypeScript **4.9.x** (compiles to `dist/`, declarations in `typings/`) | +| Runtime | Node.js **≥ 8** (`package.json` engines); README suggests Node **20+** for local dev | +| Build | `tsc` — `npm run compile` / `npm run build-ts` (with clean) | +| Tests | **Jest 29** + **ts-jest**, Node test environment | +| Data access | **mongodb** ^6.x, **lodash**, **sift** | +| Lint | **TSLint** (`npm run tslint`) — repo does not use ESLint | +| Docs | JSDoc → `npm run build-doc` (outputs under `docs/`) | + +## Main entry points and layout + +- **Published entry:** `main` → `dist/index.js` (build from `src/index.ts`). +- **Public API:** `Contentstack.Stack(config, db?)` → `Stack` instance (`src/index.ts`, `src/stack.ts`). +- **Config defaults:** `src/config.ts`; messages: `src/messages.ts`; helpers: `src/util.ts`. +- **Type declarations:** `typings/*.d.ts` (generated/committed alongside build). +- **Example:** `example/index.js` (not part of the core SDK package surface for agent edits). + +## Common commands + +| Command | Purpose | +|---------|---------| +| `npm run compile` | TypeScript compile to `dist/` | +| `npm run build-ts` | `clean` + full `tsc` | +| `npm run clean` | Remove `dist/`, `typings/`, `coverage/` | +| `npm test` | Run Jest (see `jest.config.js`) | +| `npm run tslint` | Lint `src/**/*.ts` | +| `npm run build-doc` | Build TS then JSDoc site | + +## Tests and credentials + +Tests under `test/` are **integration-style**: they call `Stack.connect()` and use a real MongoDB instance (default **`mongodb://localhost:27017`** from `src/config.ts` unless overridden in config). There is **no** separate `.env` contract in this repo for tests; ensure MongoDB is running locally (database name in tests is typically `sync-test` per `test/config.ts`). Fixture data lives under `test/data/` (ignored as tests by Jest patterns where configured). + +## Further reading for agents + +- **Cursor rules (when to apply, globs, @-references):** [.cursor/rules/README.md](.cursor/rules/README.md) +- **Skills (expanded checklists and workflows):** [skills/README.md](skills/README.md) diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..1b29778 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,14 @@ +# Agent skills — `@contentstack/datasync-mongodb-sdk` + +Short index of per-topic folders containing **SKILL.md** files. Use them for deeper context than the Cursor rules alone. + +| Skill folder | When to use it | +|--------------|----------------| +| [code-review](./code-review/SKILL.md) | PR preparation, review criteria, severity labels, terminology (DataSync vs CDA/CMA). | +| [testing](./testing/SKILL.md) | Running Jest, MongoDB prerequisites, fixtures, test naming. | +| [contentstack-typescript-datasync-mongodb](./contentstack-typescript-datasync-mongodb/SKILL.md) | SDK mental model (`Stack`, config, MongoDB), where to change query or connection behavior. | + +## Related + +- [AGENTS.md](../AGENTS.md) — single entry point for tools, paths, and commands. +- [.cursor/rules/README.md](../.cursor/rules/README.md) — rule index and globs. diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 0000000..5ec1dcc --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,52 @@ +--- +name: code-review +description: PR review checklist for the Contentstack DataSync MongoDB SDK — JSDoc, compatibility, errors, tests, dependencies, and DataSync-vs-CDA/CMA terminology. +--- + +# Skill: Code review (datasync-mongodb-sdk) + +Use this skill when preparing or reviewing pull requests for **@contentstack/datasync-mongodb-sdk**. + +## Scope reminder + +This package implements **DataSync** queries against **MongoDB** (synced content). It is **not** the Contentstack **Delivery API (CDA)** or **Management API (CMA)** HTTP SDK. Reviews should use **DataSync** / **MongoDB Stack** terminology unless the change explicitly touches another system. + +## Checklist + +### Public API and documentation + +- New or changed public surface on `Contentstack` / `Stack` has accurate **JSDoc** and matches behavior in `src/stack.ts`. +- README or `example/` updates reflect required **`Stack.connect()`** usage and realistic `contentStore` config. + +### Backward compatibility + +- Avoid breaking changes to exported names, config keys, default limits/skip/locale behavior, or query result shapes without a major version plan. +- Call out any change that affects **collection naming**, **locale** handling, or **reference depth** behavior for consumers. + +### Errors and robustness + +- Errors should flow through established patterns; prefer centralized copy in **`src/messages.ts`** where the codebase already does. +- Avoid leaking internal MongoDB details in thrown messages unless intentional. + +### Dependencies and security + +- Justify new packages; prefer existing **lodash**, **mongodb**, **sift** usage patterns. +- Consider **Snyk**/SCA impact and supply-chain expectations. + +### Tests + +- Add or update **Jest** tests with **MongoDB** running locally (default URL from config). +- Use **`test/data/`** fixtures for new document shapes; keep `test/config.ts` consistent with inserted collections. + +### Optional severity + +| Level | Examples | +|-------|----------| +| Blocker | Data loss, security issue, broken connect/query for supported config | +| Major | Wrong query results, missing tests for new feature, accidental breaking change | +| Minor | Typos, non-functional cleanup, comment-only | + +## Related + +- Cursor rule: [`.cursor/rules/code-review.mdc`](../../.cursor/rules/code-review.mdc) +- Entry point: [`AGENTS.md`](../../AGENTS.md) diff --git a/skills/contentstack-typescript-datasync-mongodb/SKILL.md b/skills/contentstack-typescript-datasync-mongodb/SKILL.md new file mode 100644 index 0000000..b58b95f --- /dev/null +++ b/skills/contentstack-typescript-datasync-mongodb/SKILL.md @@ -0,0 +1,45 @@ +--- +name: contentstack-typescript-datasync-mongodb +description: Mental model and file map for the TypeScript DataSync MongoDB SDK — Stack, config, MongoDB driver usage (not CDA/CMA). +--- + +# Skill: Contentstack TypeScript — DataSync MongoDB SDK + +Use this skill when changing **query behavior**, **connection lifecycle**, or **configuration defaults** for **`@contentstack/datasync-mongodb-sdk`**. + +## What this SDK is + +- **DataSync MongoDB SDK:** queries **local/synced** MongoDB collections populated by Contentstack **DataSync** (e.g. via content-store-mongodb). **Not** a REST client for **Delivery** or **Management** APIs. + +## Entry and flow + +1. **`Contentstack.Stack(config, existingDb?)`** — `src/index.ts` → constructs **`Stack`**. +2. **`Stack.connect()`** — establishes MongoDB client / DB (see `src/stack.ts`). +3. Fluent API — **`contentType()`**, **`entries()`**, **`assets()`**, filters, **`language()`**, **`includeReferences()`**, etc., ending in **`find()`** / similar per implementation. + +## Where to change things + +| Concern | Primary location | +|---------|------------------| +| Defaults and mergeable config | `src/config.ts` | +| Connection, queries, cursor logic | `src/stack.ts` | +| Validation helpers (URI, config) | `src/util.ts` | +| User-facing error/warning strings | `src/messages.ts` | +| Package export surface | `src/index.ts` | + +## Dependencies (facts from package.json) + +- **`mongodb`** — database access. +- **`lodash`** — merging and data manipulation. +- **`sift`** — matching filters. + +## Config concepts + +- **`contentStore`:** `url`, `dbName`, **`collection`** (asset/entry/schema names), `locale`, `limit`, `skip`, `projections`, `options` (MongoClient), `referenceDepth`, `indexes`, internal type keys, etc. +- **Locales** can influence collection naming in advanced setups (see tests that prefix collection names with locale segments). + +## Related + +- Cursor rule: [`.cursor/rules/datasync-mongodb.mdc`](../../.cursor/rules/datasync-mongodb.mdc) +- Cursor rule: [`.cursor/rules/typescript.mdc`](../../.cursor/rules/typescript.mdc) +- Entry point: [`AGENTS.md`](../../AGENTS.md) diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md new file mode 100644 index 0000000..a01f1e4 --- /dev/null +++ b/skills/testing/SKILL.md @@ -0,0 +1,41 @@ +--- +name: testing +description: How to run and extend Jest tests for the DataSync MongoDB SDK — MongoDB, fixtures, and jest.config.js behavior. +--- + +# Skill: Testing (datasync-mongodb-sdk) + +## Commands + +```bash +npm test +``` + +Uses **Jest** with **`ts-jest`** (`jest.config.js`). There is no separate `test:unit` vs `test:integration` script in `package.json` — all tests live under **`test/`** and typically require a real database. + +## Prerequisites + +- **MongoDB** running and reachable at the URL used by tests (defaults to **`mongodb://localhost:27017`** via merged `src/config.ts`, unless your test overrides `contentStore.url`). +- Test database name is commonly **`sync-test`** per **`test/config.ts`**. + +## Layout + +| Path | Role | +|------|------| +| `test/*.ts` | Topic suites (e.g. `core.ts`, `queries.ts`) | +| `test/data/*.ts` | Fixture documents imported into collections in `beforeAll` | +| `jest.config.js` | `testMatch`, coverage, `testPathIgnorePatterns` (e.g. `test/data`) | + +## Patterns + +- Tests obtain **`db`** from **`Stack.connect()`**, insert fixtures with the MongoDB driver, run Stack queries, assert, then **`Stack.close()`** in `afterAll` where used. +- File names are **topic-based**, not `*.spec.ts` — Jest discovers them via glob. + +## Environment + +- No committed `.env` contract for this repo; pass **`contentStore`** (including `url`) in the config object when you need non-default hosts or auth. + +## Related + +- Cursor rule: [`.cursor/rules/testing.mdc`](../../.cursor/rules/testing.mdc) +- Entry point: [`AGENTS.md`](../../AGENTS.md) From f910fb22b84ae50e874e84f18bc7ec475ebcea62 Mon Sep 17 00:00:00 2001 From: harshitha-cstk Date: Thu, 2 Apr 2026 13:14:22 +0530 Subject: [PATCH 3/6] upgrade lodash --- package-lock.json | 429 +++++++++++++++++++++++----------------------- package.json | 4 +- 2 files changed, 218 insertions(+), 215 deletions(-) diff --git a/package-lock.json b/package-lock.json index b8fceaa..6fceccb 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,15 +1,15 @@ { "name": "@contentstack/datasync-mongodb-sdk", - "version": "1.0.14", + "version": "1.0.15", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@contentstack/datasync-mongodb-sdk", - "version": "1.0.14", + "version": "1.0.15", "license": "MIT", "dependencies": { - "lodash": "^4.17.23", + "lodash": "^4.18.1", "mongodb": "^6.21.0", "sift": "^17.1.3" }, @@ -33,13 +33,13 @@ } }, "node_modules/@babel/code-frame": { - "version": "7.27.1", - "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.27.1.tgz", - "integrity": "sha512-cjQ7ZlQ0Mv3b47hABuTevyTuYN4i+loJKGeV9flcCgIK37cCXRh+L1bd3iBHlynerhQ7BhCkn2BPbQUL+rGqFg==", + "version": "7.29.0", + "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.0.tgz", + "integrity": "sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw==", "dev": true, "license": "MIT", "dependencies": { - "@babel/helper-validator-identifier": "^7.27.1", + "@babel/helper-validator-identifier": "^7.28.5", "js-tokens": "^4.0.0", "picocolors": "^1.1.1" }, @@ -48,9 +48,9 @@ } }, "node_modules/@babel/compat-data": { - "version": "7.28.5", - "resolved": "https://registry.npmjs.org/@babel/compat-data/-/compat-data-7.28.5.tgz", - "integrity": "sha512-6uFXyCayocRbqhZOB+6XcuZbkMNimwfVGFji8CTZnCzOHVGvDqzvitu1re2AU5LROliz7eQPhB8CpAMvnx9EjA==", + "version": "7.29.0", + "resolved": "https://registry.npmjs.org/@babel/compat-data/-/compat-data-7.29.0.tgz", + "integrity": "sha512-T1NCJqT/j9+cn8fvkt7jtwbLBfLC/1y1c7NtCeXFRgzGTsafi68MRv8yzkYSapBnFA6L3U2VSc02ciDzoAJhJg==", "dev": true, "license": "MIT", "engines": { @@ -58,21 +58,21 @@ } }, "node_modules/@babel/core": { - "version": "7.28.5", - "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.28.5.tgz", - "integrity": "sha512-e7jT4DxYvIDLk1ZHmU/m/mB19rex9sv0c2ftBtjSBv+kVM/902eh0fINUzD7UwLLNR+jU585GxUJ8/EBfAM5fw==", + "version": "7.29.0", + "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.29.0.tgz", + "integrity": "sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==", "dev": true, "license": "MIT", "dependencies": { - "@babel/code-frame": "^7.27.1", - "@babel/generator": "^7.28.5", - "@babel/helper-compilation-targets": "^7.27.2", - "@babel/helper-module-transforms": "^7.28.3", - "@babel/helpers": "^7.28.4", - "@babel/parser": "^7.28.5", - "@babel/template": "^7.27.2", - "@babel/traverse": "^7.28.5", - "@babel/types": "^7.28.5", + "@babel/code-frame": "^7.29.0", + "@babel/generator": "^7.29.0", + "@babel/helper-compilation-targets": "^7.28.6", + "@babel/helper-module-transforms": "^7.28.6", + "@babel/helpers": "^7.28.6", + "@babel/parser": "^7.29.0", + "@babel/template": "^7.28.6", + "@babel/traverse": "^7.29.0", + "@babel/types": "^7.29.0", "@jridgewell/remapping": "^2.3.5", "convert-source-map": "^2.0.0", "debug": "^4.1.0", @@ -89,14 +89,14 @@ } }, "node_modules/@babel/generator": { - "version": "7.28.5", - "resolved": "https://registry.npmjs.org/@babel/generator/-/generator-7.28.5.tgz", - "integrity": "sha512-3EwLFhZ38J4VyIP6WNtt2kUdW9dokXA9Cr4IVIFHuCpZ3H8/YFOl5JjZHisrn1fATPBmKKqXzDFvh9fUwHz6CQ==", + "version": "7.29.1", + "resolved": "https://registry.npmjs.org/@babel/generator/-/generator-7.29.1.tgz", + "integrity": "sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw==", "dev": true, "license": "MIT", "dependencies": { - "@babel/parser": "^7.28.5", - "@babel/types": "^7.28.5", + "@babel/parser": "^7.29.0", + "@babel/types": "^7.29.0", "@jridgewell/gen-mapping": "^0.3.12", "@jridgewell/trace-mapping": "^0.3.28", "jsesc": "^3.0.2" @@ -106,13 +106,13 @@ } }, "node_modules/@babel/helper-compilation-targets": { - "version": "7.27.2", - "resolved": "https://registry.npmjs.org/@babel/helper-compilation-targets/-/helper-compilation-targets-7.27.2.tgz", - "integrity": "sha512-2+1thGUUWWjLTYTHZWK1n8Yga0ijBz1XAhUXcKy81rd5g6yh7hGqMp45v7cadSbEHc9G3OTv45SyneRN3ps4DQ==", + "version": "7.28.6", + "resolved": "https://registry.npmjs.org/@babel/helper-compilation-targets/-/helper-compilation-targets-7.28.6.tgz", + "integrity": "sha512-JYtls3hqi15fcx5GaSNL7SCTJ2MNmjrkHXg4FSpOA/grxK8KwyZ5bubHsCq8FXCkua6xhuaaBit+3b7+VZRfcA==", "dev": true, "license": "MIT", "dependencies": { - "@babel/compat-data": "^7.27.2", + "@babel/compat-data": "^7.28.6", "@babel/helper-validator-option": "^7.27.1", "browserslist": "^4.24.0", "lru-cache": "^5.1.1", @@ -133,29 +133,29 @@ } }, "node_modules/@babel/helper-module-imports": { - "version": "7.27.1", - "resolved": "https://registry.npmjs.org/@babel/helper-module-imports/-/helper-module-imports-7.27.1.tgz", - "integrity": "sha512-0gSFWUPNXNopqtIPQvlD5WgXYI5GY2kP2cCvoT8kczjbfcfuIljTbcWrulD1CIPIX2gt1wghbDy08yE1p+/r3w==", + "version": "7.28.6", + "resolved": "https://registry.npmjs.org/@babel/helper-module-imports/-/helper-module-imports-7.28.6.tgz", + "integrity": "sha512-l5XkZK7r7wa9LucGw9LwZyyCUscb4x37JWTPz7swwFE/0FMQAGpiWUZn8u9DzkSBWEcK25jmvubfpw2dnAMdbw==", "dev": true, "license": "MIT", "dependencies": { - "@babel/traverse": "^7.27.1", - "@babel/types": "^7.27.1" + "@babel/traverse": "^7.28.6", + "@babel/types": "^7.28.6" }, "engines": { "node": ">=6.9.0" } }, "node_modules/@babel/helper-module-transforms": { - "version": "7.28.3", - "resolved": "https://registry.npmjs.org/@babel/helper-module-transforms/-/helper-module-transforms-7.28.3.tgz", - "integrity": "sha512-gytXUbs8k2sXS9PnQptz5o0QnpLL51SwASIORY6XaBKF88nsOT0Zw9szLqlSGQDP/4TljBAD5y98p2U1fqkdsw==", + "version": "7.28.6", + "resolved": "https://registry.npmjs.org/@babel/helper-module-transforms/-/helper-module-transforms-7.28.6.tgz", + "integrity": "sha512-67oXFAYr2cDLDVGLXTEABjdBJZ6drElUSI7WKp70NrpyISso3plG9SAGEF6y7zbha/wOzUByWWTJvEDVNIUGcA==", "dev": true, "license": "MIT", "dependencies": { - "@babel/helper-module-imports": "^7.27.1", - "@babel/helper-validator-identifier": "^7.27.1", - "@babel/traverse": "^7.28.3" + "@babel/helper-module-imports": "^7.28.6", + "@babel/helper-validator-identifier": "^7.28.5", + "@babel/traverse": "^7.28.6" }, "engines": { "node": ">=6.9.0" @@ -165,9 +165,9 @@ } }, "node_modules/@babel/helper-plugin-utils": { - "version": "7.27.1", - "resolved": "https://registry.npmjs.org/@babel/helper-plugin-utils/-/helper-plugin-utils-7.27.1.tgz", - "integrity": "sha512-1gn1Up5YXka3YYAHGKpbideQ5Yjf1tDa9qYcgysz+cNCXukyLl6DjPXhD3VRwSb8c0J9tA4b2+rHEZtc6R0tlw==", + "version": "7.28.6", + "resolved": "https://registry.npmjs.org/@babel/helper-plugin-utils/-/helper-plugin-utils-7.28.6.tgz", + "integrity": "sha512-S9gzZ/bz83GRysI7gAD4wPT/AI3uCnY+9xn+Mx/KPs2JwHJIz1W8PZkg2cqyt3RNOBM8ejcXhV6y8Og7ly/Dug==", "dev": true, "license": "MIT", "engines": { @@ -205,27 +205,27 @@ } }, "node_modules/@babel/helpers": { - "version": "7.28.4", - "resolved": "https://registry.npmjs.org/@babel/helpers/-/helpers-7.28.4.tgz", - "integrity": "sha512-HFN59MmQXGHVyYadKLVumYsA9dBFun/ldYxipEjzA4196jpLZd8UjEEBLkbEkvfYreDqJhZxYAWFPtrfhNpj4w==", + "version": "7.29.2", + "resolved": "https://registry.npmjs.org/@babel/helpers/-/helpers-7.29.2.tgz", + "integrity": "sha512-HoGuUs4sCZNezVEKdVcwqmZN8GoHirLUcLaYVNBK2J0DadGtdcqgr3BCbvH8+XUo4NGjNl3VOtSjEKNzqfFgKw==", "dev": true, "license": "MIT", "dependencies": { - "@babel/template": "^7.27.2", - "@babel/types": "^7.28.4" + "@babel/template": "^7.28.6", + "@babel/types": "^7.29.0" }, "engines": { "node": ">=6.9.0" } }, "node_modules/@babel/parser": { - "version": "7.28.5", - "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.28.5.tgz", - "integrity": "sha512-KKBU1VGYR7ORr3At5HAtUQ+TV3SzRCXmA/8OdDZiLDBIZxVyzXuztPjfLd3BV1PRAQGCMWWSHYhL0F8d5uHBDQ==", + "version": "7.29.2", + "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.2.tgz", + "integrity": "sha512-4GgRzy/+fsBa72/RZVJmGKPmZu9Byn8o4MoLpmNe1m8ZfYnz5emHLQz3U4gLud6Zwl0RZIcgiLD7Uq7ySFuDLA==", "dev": true, "license": "MIT", "dependencies": { - "@babel/types": "^7.28.5" + "@babel/types": "^7.29.0" }, "bin": { "parser": "bin/babel-parser.js" @@ -290,13 +290,13 @@ } }, "node_modules/@babel/plugin-syntax-import-attributes": { - "version": "7.27.1", - "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-import-attributes/-/plugin-syntax-import-attributes-7.27.1.tgz", - "integrity": "sha512-oFT0FrKHgF53f4vOsZGi2Hh3I35PfSmVs4IBFLFj4dnafP+hIWDLg3VyKmUHfLoLHlyxY4C7DGtmHuJgn+IGww==", + "version": "7.28.6", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-import-attributes/-/plugin-syntax-import-attributes-7.28.6.tgz", + "integrity": "sha512-jiLC0ma9XkQT3TKJ9uYvlakm66Pamywo+qwL+oL8HJOvc6TWdZXVfhqJr8CCzbSGUAbDOzlGHJC1U+vRfLQDvw==", "dev": true, "license": "MIT", "dependencies": { - "@babel/helper-plugin-utils": "^7.27.1" + "@babel/helper-plugin-utils": "^7.28.6" }, "engines": { "node": ">=6.9.0" @@ -332,13 +332,13 @@ } }, "node_modules/@babel/plugin-syntax-jsx": { - "version": "7.27.1", - "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-jsx/-/plugin-syntax-jsx-7.27.1.tgz", - "integrity": "sha512-y8YTNIeKoyhGd9O0Jiyzyyqk8gdjnumGTQPsz0xOZOQ2RmkVJeZ1vmmfIvFEKqucBG6axJGBZDE/7iI5suUI/w==", + "version": "7.28.6", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-jsx/-/plugin-syntax-jsx-7.28.6.tgz", + "integrity": "sha512-wgEmr06G6sIpqr8YDwA2dSRTE3bJ+V0IfpzfSY3Lfgd7YWOaAdlykvJi13ZKBt8cZHfgH1IXN+CL656W3uUa4w==", "dev": true, "license": "MIT", "dependencies": { - "@babel/helper-plugin-utils": "^7.27.1" + "@babel/helper-plugin-utils": "^7.28.6" }, "engines": { "node": ">=6.9.0" @@ -458,13 +458,13 @@ } }, "node_modules/@babel/plugin-syntax-typescript": { - "version": "7.27.1", - "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-typescript/-/plugin-syntax-typescript-7.27.1.tgz", - "integrity": "sha512-xfYCBMxveHrRMnAWl1ZlPXOZjzkN82THFvLhQhFXFt81Z5HnN+EtUkZhv/zcKpmT3fzmWZB0ywiBrbC3vogbwQ==", + "version": "7.28.6", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-typescript/-/plugin-syntax-typescript-7.28.6.tgz", + "integrity": "sha512-+nDNmQye7nlnuuHDboPbGm00Vqg3oO8niRRL27/4LYHUsHYh0zJ1xWOz0uRwNFmM1Avzk8wZbc6rdiYhomzv/A==", "dev": true, "license": "MIT", "dependencies": { - "@babel/helper-plugin-utils": "^7.27.1" + "@babel/helper-plugin-utils": "^7.28.6" }, "engines": { "node": ">=6.9.0" @@ -474,33 +474,33 @@ } }, "node_modules/@babel/template": { - "version": "7.27.2", - "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.27.2.tgz", - "integrity": "sha512-LPDZ85aEJyYSd18/DkjNh4/y1ntkE5KwUHWTiqgRxruuZL2F1yuHligVHLvcHY2vMHXttKFpJn6LwfI7cw7ODw==", + "version": "7.28.6", + "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.28.6.tgz", + "integrity": "sha512-YA6Ma2KsCdGb+WC6UpBVFJGXL58MDA6oyONbjyF/+5sBgxY/dwkhLogbMT2GXXyU84/IhRw/2D1Os1B/giz+BQ==", "dev": true, "license": "MIT", "dependencies": { - "@babel/code-frame": "^7.27.1", - "@babel/parser": "^7.27.2", - "@babel/types": "^7.27.1" + "@babel/code-frame": "^7.28.6", + "@babel/parser": "^7.28.6", + "@babel/types": "^7.28.6" }, "engines": { "node": ">=6.9.0" } }, "node_modules/@babel/traverse": { - "version": "7.28.5", - "resolved": "https://registry.npmjs.org/@babel/traverse/-/traverse-7.28.5.tgz", - "integrity": "sha512-TCCj4t55U90khlYkVV/0TfkJkAkUg3jZFA3Neb7unZT8CPok7iiRfaX0F+WnqWqt7OxhOn0uBKXCw4lbL8W0aQ==", + "version": "7.29.0", + "resolved": "https://registry.npmjs.org/@babel/traverse/-/traverse-7.29.0.tgz", + "integrity": "sha512-4HPiQr0X7+waHfyXPZpWPfWL/J7dcN1mx9gL6WdQVMbPnF3+ZhSMs8tCxN7oHddJE9fhNE7+lxdnlyemKfJRuA==", "dev": true, "license": "MIT", "dependencies": { - "@babel/code-frame": "^7.27.1", - "@babel/generator": "^7.28.5", + "@babel/code-frame": "^7.29.0", + "@babel/generator": "^7.29.0", "@babel/helper-globals": "^7.28.0", - "@babel/parser": "^7.28.5", - "@babel/template": "^7.27.2", - "@babel/types": "^7.28.5", + "@babel/parser": "^7.29.0", + "@babel/template": "^7.28.6", + "@babel/types": "^7.29.0", "debug": "^4.3.1" }, "engines": { @@ -508,9 +508,9 @@ } }, "node_modules/@babel/types": { - "version": "7.28.5", - "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.28.5.tgz", - "integrity": "sha512-qQ5m48eI/MFLQ5PxQj4PFaprjyCTLI37ElWMmNs0K8Lk3dVeOdNpB3ks8jc7yM5CDmVC73eMVk/trk3fgmrUpA==", + "version": "7.29.0", + "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.0.tgz", + "integrity": "sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==", "dev": true, "license": "MIT", "dependencies": { @@ -528,29 +528,6 @@ "dev": true, "license": "MIT" }, - "node_modules/@isaacs/balanced-match": { - "version": "4.0.1", - "resolved": "https://registry.npmjs.org/@isaacs/balanced-match/-/balanced-match-4.0.1.tgz", - "integrity": "sha512-yzMTt9lEb8Gv7zRioUilSglI0c0smZ9k5D65677DLWLtWJaXIS3CqcGyUFByYKlnUj6TkjLVs54fBl6+TiGQDQ==", - "dev": true, - "license": "MIT", - "engines": { - "node": "20 || >=22" - } - }, - "node_modules/@isaacs/brace-expansion": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/@isaacs/brace-expansion/-/brace-expansion-5.0.0.tgz", - "integrity": "sha512-ZT55BDLV0yv0RBm2czMiZ+SqCGO7AvmOM3G/w2xhVPH+te0aKgFjmBvGlL1dH+ql2tgGO3MVrbb3jCKyvpgnxA==", - "dev": true, - "license": "MIT", - "dependencies": { - "@isaacs/balanced-match": "^4.0.1" - }, - "engines": { - "node": "20 || >=22" - } - }, "node_modules/@istanbuljs/load-nyc-config": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/@istanbuljs/load-nyc-config/-/load-nyc-config-1.1.0.tgz", @@ -921,31 +898,31 @@ } }, "node_modules/@jsdoc/salty": { - "version": "0.2.9", - "resolved": "https://registry.npmjs.org/@jsdoc/salty/-/salty-0.2.9.tgz", - "integrity": "sha512-yYxMVH7Dqw6nO0d5NIV8OQWnitU8k6vXH8NtgqAfIa/IUqRMxRv/NUJJ08VEKbAakwxlgBl5PJdrU0dMPStsnw==", + "version": "0.2.11", + "resolved": "https://registry.npmjs.org/@jsdoc/salty/-/salty-0.2.11.tgz", + "integrity": "sha512-luR/TZqgru6gNjBQnRIbzNPOmDG62VIFQO7QyEjc1/zk3VP3yoGfuecwP2uOlAmKz+t6aq9bwsBV3FgiyHTT7Q==", "dev": true, "license": "Apache-2.0", "dependencies": { - "lodash": "^4.17.21" + "lodash": "^4.17.23" }, "engines": { "node": ">=v12.0.0" } }, "node_modules/@mongodb-js/saslprep": { - "version": "1.4.4", - "resolved": "https://registry.npmjs.org/@mongodb-js/saslprep/-/saslprep-1.4.4.tgz", - "integrity": "sha512-p7X/ytJDIdwUfFL/CLOhKgdfJe1Fa8uw9seJYvdOmnP9JBWGWHW69HkOixXS6Wy9yvGf1MbhcS6lVmrhy4jm2g==", + "version": "1.4.6", + "resolved": "https://registry.npmjs.org/@mongodb-js/saslprep/-/saslprep-1.4.6.tgz", + "integrity": "sha512-y+x3H1xBZd38n10NZF/rEBlvDOOMQ6LKUTHqr8R9VkJ+mmQOYtJFxIlkkK8fZrtOiL6VixbOBWMbZGBdal3Z1g==", "license": "MIT", "dependencies": { "sparse-bitfield": "^3.0.3" } }, "node_modules/@sinclair/typebox": { - "version": "0.27.8", - "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.27.8.tgz", - "integrity": "sha512-+Fj43pSMwJs4KRrH/938Uf+uAELIgVBmQzg/q1YG10djyfA3TnrU8N8XzqCh/okZdszqBQTZf96idMfE5lnwTA==", + "version": "0.27.10", + "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.27.10.tgz", + "integrity": "sha512-MTBk/3jGLNB2tVxv6uLlFh1iu64iYOQ2PbdOSK3NW8JZsmlaOh2q6sdtKowBhfw8QFLmYNzTW4/oK4uATIi6ZA==", "dev": true, "license": "MIT" }, @@ -1341,13 +1318,16 @@ "license": "MIT" }, "node_modules/baseline-browser-mapping": { - "version": "2.9.11", - "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.9.11.tgz", - "integrity": "sha512-Sg0xJUNDU1sJNGdfGWhVHX0kkZ+HWcvmVymJbj6NSgZZmW/8S9Y2HQ5euytnIgakgxN6papOAWiwDo1ctFDcoQ==", + "version": "2.10.13", + "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.13.tgz", + "integrity": "sha512-BL2sTuHOdy0YT1lYieUxTw/QMtPBC3pmlJC6xk8BBYVv6vcw3SGdKemQ+Xsx9ik2F/lYDO9tqsFQH1r9PFuHKw==", "dev": true, "license": "Apache-2.0", "bin": { - "baseline-browser-mapping": "dist/cli.js" + "baseline-browser-mapping": "dist/cli.cjs" + }, + "engines": { + "node": ">=6.0.0" } }, "node_modules/bluebird": { @@ -1358,9 +1338,9 @@ "license": "MIT" }, "node_modules/brace-expansion": { - "version": "1.1.12", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz", - "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==", + "version": "1.1.13", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.13.tgz", + "integrity": "sha512-9ZLprWS6EENmhEOpjCYW2c8VkmOvckIJZfkr7rBW6dObmfgJ/L1GpSYW5Hpo9lDz4D1+n0Ckz8rU7FwHDQiG/w==", "dev": true, "license": "MIT", "dependencies": { @@ -1382,9 +1362,9 @@ } }, "node_modules/browserslist": { - "version": "4.28.1", - "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.1.tgz", - "integrity": "sha512-ZC5Bd0LgJXgwGqUknZY/vkUQ04r8NXnJZ3yYi4vDmSiZmC/pdSN0NbNRPxZpbtO4uAfDUAFffO8IZoM3Gj8IkA==", + "version": "4.28.2", + "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.2.tgz", + "integrity": "sha512-48xSriZYYg+8qXna9kwqjIVzuQxi+KYWp2+5nCYnYKPTr0LvD89Jqk2Or5ogxz0NUMfIjhh2lIUX/LyX9B4oIg==", "dev": true, "funding": [ { @@ -1402,11 +1382,11 @@ ], "license": "MIT", "dependencies": { - "baseline-browser-mapping": "^2.9.0", - "caniuse-lite": "^1.0.30001759", - "electron-to-chromium": "^1.5.263", - "node-releases": "^2.0.27", - "update-browserslist-db": "^1.2.0" + "baseline-browser-mapping": "^2.10.12", + "caniuse-lite": "^1.0.30001782", + "electron-to-chromium": "^1.5.328", + "node-releases": "^2.0.36", + "update-browserslist-db": "^1.2.3" }, "bin": { "browserslist": "cli.js" @@ -1485,9 +1465,9 @@ } }, "node_modules/caniuse-lite": { - "version": "1.0.30001762", - "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001762.tgz", - "integrity": "sha512-PxZwGNvH7Ak8WX5iXzoK1KPZttBXNPuaOvI2ZYU7NrlM+d9Ov+TUvlLOBNGzVXAntMSMMlJPd+jY6ovrVjSmUw==", + "version": "1.0.30001784", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001784.tgz", + "integrity": "sha512-WU346nBTklUV9YfUl60fqRbU5ZqyXlqvo1SgigE1OAXK5bFL8LL9q1K7aap3N739l4BvNqnkm3YrGHiY9sfUQw==", "dev": true, "funding": [ { @@ -1698,9 +1678,9 @@ } }, "node_modules/dedent": { - "version": "1.7.1", - "resolved": "https://registry.npmjs.org/dedent/-/dedent-1.7.1.tgz", - "integrity": "sha512-9JmrhGZpOlEgOLdQgSm0zxFaYoQon408V1v49aqTWuXENVlnCuY9JBZcXZiCsZQWDjTm5Qf/nIvAy77mXDAjEg==", + "version": "1.7.2", + "resolved": "https://registry.npmjs.org/dedent/-/dedent-1.7.2.tgz", + "integrity": "sha512-WzMx3mW98SN+zn3hgemf4OzdmyNhhhKz5Ay0pUfQiMQ3e1g+xmTJWp/pKdwKVXhdSkAEGIIzqeuWrL3mV/AXbA==", "dev": true, "license": "MIT", "peerDependencies": { @@ -1733,9 +1713,9 @@ } }, "node_modules/diff": { - "version": "4.0.2", - "resolved": "https://registry.npmjs.org/diff/-/diff-4.0.2.tgz", - "integrity": "sha512-58lmxKSA4BNyLz+HHMUzlOEpg09FV+ev6ZMe3vJihgdxzgcwZ8VoEEPmALCZG9LmqfVoNMMKpttIYTVG6uDY7A==", + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/diff/-/diff-4.0.4.tgz", + "integrity": "sha512-X07nttJQkwkfKfvTPG/KSnE2OMdcUCao6+eXF3wmnIQRn2aPAHH3VxDbDOdegkd6JbPsXqShpvEOHfAT+nCNwQ==", "dev": true, "license": "BSD-3-Clause", "engines": { @@ -1753,9 +1733,9 @@ } }, "node_modules/electron-to-chromium": { - "version": "1.5.267", - "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.267.tgz", - "integrity": "sha512-0Drusm6MVRXSOJpGbaSVgcQsuB4hEkMpHXaVstcPmhu5LIedxs1xNK/nIxmQIU/RPC0+1/o0AVZfBTkTNJOdUw==", + "version": "1.5.331", + "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.331.tgz", + "integrity": "sha512-IbxXrsTlD3hRodkLnbxAPP4OuJYdWCeM3IOdT+CpcMoIwIoDfCmRpEtSPfwBXxVkg9xmBeY7Lz2Eo2TDn/HC3Q==", "dev": true, "license": "ISC" }, @@ -2009,7 +1989,7 @@ "version": "7.2.3", "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz", "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==", - "deprecated": "Glob versions prior to v9 are no longer supported", + "deprecated": "Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me", "dev": true, "license": "ISC", "dependencies": { @@ -2042,9 +2022,9 @@ "license": "MIT" }, "node_modules/handlebars": { - "version": "4.7.8", - "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.8.tgz", - "integrity": "sha512-vafaFqs8MZkRrSX7sFVUdo3ap/eNiLnb4IakshzvP56X5Nr1iGKAIqdX6tMlm6HcNRIkr6AxO5jFEoJzzpT8aQ==", + "version": "4.7.9", + "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.9.tgz", + "integrity": "sha512-4E71E0rpOaQuJR2A3xDZ+GM1HyWYv1clR58tC8emQNeQe3RH7MAzSbat+V0wG78LQBo6m6bzSG/L4pBuCsgnUQ==", "dev": true, "license": "MIT", "dependencies": { @@ -2298,9 +2278,9 @@ } }, "node_modules/istanbul-lib-instrument/node_modules/semver": { - "version": "7.7.3", - "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz", - "integrity": "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==", + "version": "7.7.4", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz", + "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==", "dev": true, "license": "ISC", "bin": { @@ -2837,9 +2817,9 @@ } }, "node_modules/jest-snapshot/node_modules/semver": { - "version": "7.7.3", - "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz", - "integrity": "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==", + "version": "7.7.4", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz", + "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==", "dev": true, "license": "ISC", "bin": { @@ -3105,9 +3085,9 @@ } }, "node_modules/lodash": { - "version": "4.17.23", - "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.23.tgz", - "integrity": "sha512-LgVTMpQtIopCi79SJeDiP0TfWi5CNEc/L/aRdTh3yIvmZXTnheWpKjSZhnvMl8iXbC1tFg9gdHHDMLoV7CnG+w==", + "version": "4.18.1", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz", + "integrity": "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==", "license": "MIT" }, "node_modules/lodash.memoize": { @@ -3144,9 +3124,9 @@ } }, "node_modules/make-dir/node_modules/semver": { - "version": "7.7.3", - "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz", - "integrity": "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==", + "version": "7.7.4", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz", + "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==", "dev": true, "license": "ISC", "bin": { @@ -3174,9 +3154,9 @@ } }, "node_modules/markdown-it": { - "version": "14.1.0", - "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.0.tgz", - "integrity": "sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==", + "version": "14.1.1", + "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.1.tgz", + "integrity": "sha512-BuU2qnTti9YKgK5N+IeMubp14ZUKUUw7yeJbkjtosvHiP0AZ5c8IAgEMk79D0eC8F23r4Ac/q8cAIFdm2FtyoA==", "dev": true, "license": "MIT", "dependencies": { @@ -3267,9 +3247,9 @@ } }, "node_modules/minimatch": { - "version": "3.1.2", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz", - "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==", + "version": "3.1.5", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz", + "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==", "dev": true, "license": "ISC", "dependencies": { @@ -3290,11 +3270,11 @@ } }, "node_modules/minipass": { - "version": "7.1.2", - "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.2.tgz", - "integrity": "sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw==", + "version": "7.1.3", + "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz", + "integrity": "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==", "dev": true, - "license": "ISC", + "license": "BlueOak-1.0.0", "engines": { "node": ">=16 || 14 >=14.17" } @@ -3412,9 +3392,9 @@ } }, "node_modules/node-notifier/node_modules/semver": { - "version": "7.7.3", - "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz", - "integrity": "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==", + "version": "7.7.4", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz", + "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==", "dev": true, "license": "ISC", "bin": { @@ -3425,9 +3405,9 @@ } }, "node_modules/node-releases": { - "version": "2.0.27", - "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.27.tgz", - "integrity": "sha512-nmh3lCkYZ3grZvqcCH+fjmQ7X+H0OeZgP40OierEaAptX4XofMh5kwNbWh7lBduUzCcV/8kZ+NDLCwm2iorIlA==", + "version": "2.0.37", + "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.37.tgz", + "integrity": "sha512-1h5gKZCF+pO/o3Iqt5Jp7wc9rH3eJJ0+nh/CIoiRwjRxde/hAHyLPXYN4V3CqKAbiZPSeJFSWHmJsbkicta0Eg==", "dev": true, "license": "MIT" }, @@ -3599,9 +3579,9 @@ "license": "MIT" }, "node_modules/path-scurry": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.1.tgz", - "integrity": "sha512-oWyT4gICAu+kaA7QWk/jvCHWarMKNs6pXOGWKDTr7cw4IGcUbW+PeTfbaQiLGheFRpjo6O9J0PmyMfQPjH71oA==", + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.2.tgz", + "integrity": "sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==", "dev": true, "license": "BlueOak-1.0.0", "dependencies": { @@ -3609,16 +3589,16 @@ "minipass": "^7.1.2" }, "engines": { - "node": "20 || >=22" + "node": "18 || 20 || >=22" }, "funding": { "url": "https://github.com/sponsors/isaacs" } }, "node_modules/path-scurry/node_modules/lru-cache": { - "version": "11.2.4", - "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.2.4.tgz", - "integrity": "sha512-B5Y16Jr9LB9dHVkh6ZevG+vAbOsNOYCX+sXvFWFu7B3Iz5mijW3zdbMyhsh8ANd2mSWBYdJgnqi+mL7/LrOPYg==", + "version": "11.2.7", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.2.7.tgz", + "integrity": "sha512-aY/R+aEsRelme17KGQa/1ZSIpLpNYYrhcrepKTZgE+W3WM16YMCaPwOHLHsmopZHELU0Ojin1lPVxKR0MihncA==", "dev": true, "license": "BlueOak-1.0.0", "engines": { @@ -3633,9 +3613,9 @@ "license": "ISC" }, "node_modules/picomatch": { - "version": "2.3.1", - "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", - "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==", + "version": "2.3.2", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz", + "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==", "dev": true, "license": "MIT", "engines": { @@ -3828,13 +3808,13 @@ } }, "node_modules/rimraf": { - "version": "6.1.2", - "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-6.1.2.tgz", - "integrity": "sha512-cFCkPslJv7BAXJsYlK1dZsbP8/ZNLkCAQ0bi1hf5EKX2QHegmDFEFA6QhuYJlk7UDdc+02JjO80YSOrWPpw06g==", + "version": "6.1.3", + "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-6.1.3.tgz", + "integrity": "sha512-LKg+Cr2ZF61fkcaK1UdkH2yEBBKnYjTyWzTJT6KNPcSPaiT7HSdhtMXQuN5wkTX0Xu72KQ1l8S42rlmexS2hSA==", "dev": true, "license": "BlueOak-1.0.0", "dependencies": { - "glob": "^13.0.0", + "glob": "^13.0.3", "package-json-from-dist": "^1.0.1" }, "bin": { @@ -3847,35 +3827,58 @@ "url": "https://github.com/sponsors/isaacs" } }, + "node_modules/rimraf/node_modules/balanced-match": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz", + "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==", + "dev": true, + "license": "MIT", + "engines": { + "node": "18 || 20 || >=22" + } + }, + "node_modules/rimraf/node_modules/brace-expansion": { + "version": "5.0.5", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.5.tgz", + "integrity": "sha512-VZznLgtwhn+Mact9tfiwx64fA9erHH/MCXEUfB/0bX/6Fz6ny5EGTXYltMocqg4xFAQZtnO3DHWWXi8RiuN7cQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "balanced-match": "^4.0.2" + }, + "engines": { + "node": "18 || 20 || >=22" + } + }, "node_modules/rimraf/node_modules/glob": { - "version": "13.0.0", - "resolved": "https://registry.npmjs.org/glob/-/glob-13.0.0.tgz", - "integrity": "sha512-tvZgpqk6fz4BaNZ66ZsRaZnbHvP/jG3uKJvAZOwEVUL4RTA5nJeeLYfyN9/VA8NX/V3IBG+hkeuGpKjvELkVhA==", + "version": "13.0.6", + "resolved": "https://registry.npmjs.org/glob/-/glob-13.0.6.tgz", + "integrity": "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==", "dev": true, "license": "BlueOak-1.0.0", "dependencies": { - "minimatch": "^10.1.1", - "minipass": "^7.1.2", - "path-scurry": "^2.0.0" + "minimatch": "^10.2.2", + "minipass": "^7.1.3", + "path-scurry": "^2.0.2" }, "engines": { - "node": "20 || >=22" + "node": "18 || 20 || >=22" }, "funding": { "url": "https://github.com/sponsors/isaacs" } }, "node_modules/rimraf/node_modules/minimatch": { - "version": "10.1.1", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.1.1.tgz", - "integrity": "sha512-enIvLvRAFZYXJzkCYG5RKmPfrFArdLv+R+lbQ53BmIMLIry74bjKzX6iHAm8WYamJkhSSEabrWN5D97XnKObjQ==", + "version": "10.2.5", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.5.tgz", + "integrity": "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==", "dev": true, "license": "BlueOak-1.0.0", "dependencies": { - "@isaacs/brace-expansion": "^5.0.0" + "brace-expansion": "^5.0.5" }, "engines": { - "node": "20 || >=22" + "node": "18 || 20 || >=22" }, "funding": { "url": "https://github.com/sponsors/isaacs" @@ -4150,19 +4153,19 @@ } }, "node_modules/ts-jest": { - "version": "29.4.6", - "resolved": "https://registry.npmjs.org/ts-jest/-/ts-jest-29.4.6.tgz", - "integrity": "sha512-fSpWtOO/1AjSNQguk43hb/JCo16oJDnMJf3CdEGNkqsEX3t0KX96xvyX1D7PfLCpVoKu4MfVrqUkFyblYoY4lA==", + "version": "29.4.9", + "resolved": "https://registry.npmjs.org/ts-jest/-/ts-jest-29.4.9.tgz", + "integrity": "sha512-LTb9496gYPMCqjeDLdPrKuXtncudeV1yRZnF4Wo5l3SFi0RYEnYRNgMrFIdg+FHvfzjCyQk1cLncWVqiSX+EvQ==", "dev": true, "license": "MIT", "dependencies": { "bs-logger": "^0.2.6", "fast-json-stable-stringify": "^2.1.0", - "handlebars": "^4.7.8", + "handlebars": "^4.7.9", "json5": "^2.2.3", "lodash.memoize": "^4.1.2", "make-error": "^1.3.6", - "semver": "^7.7.3", + "semver": "^7.7.4", "type-fest": "^4.41.0", "yargs-parser": "^21.1.1" }, @@ -4179,7 +4182,7 @@ "babel-jest": "^29.0.0 || ^30.0.0", "jest": "^29.0.0 || ^30.0.0", "jest-util": "^29.0.0 || ^30.0.0", - "typescript": ">=4.3 <6" + "typescript": ">=4.3 <7" }, "peerDependenciesMeta": { "@babel/core": { @@ -4203,9 +4206,9 @@ } }, "node_modules/ts-jest/node_modules/semver": { - "version": "7.7.3", - "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz", - "integrity": "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==", + "version": "7.7.4", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz", + "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==", "dev": true, "license": "ISC", "bin": { @@ -4439,9 +4442,9 @@ } }, "node_modules/underscore": { - "version": "1.13.7", - "resolved": "https://registry.npmjs.org/underscore/-/underscore-1.13.7.tgz", - "integrity": "sha512-GMXzWtsc57XAtguZgaQViUOzs0KTkk8ojr3/xAxXLITqf/3EMwxC0inyETfDFjH/Krbhuep0HNbbjI9i/q3F3g==", + "version": "1.13.8", + "resolved": "https://registry.npmjs.org/underscore/-/underscore-1.13.8.tgz", + "integrity": "sha512-DXtD3ZtEQzc7M8m4cXotyHR+FAS18C64asBYY5vqZexfYryNNnDc02W4hKg3rdQuqOYas1jkseX0+nZXjTXnvQ==", "dev": true, "license": "MIT" }, diff --git a/package.json b/package.json index c03d4d9..b92483e 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "author": "Contentstack Ecosystem ", "name": "@contentstack/datasync-mongodb-sdk", - "version": "1.0.14", + "version": "1.0.15", "description": "Mongodb query wrapper around contents synced via @contentstack/content-store-mongodb", "main": "dist/index.js", "scripts": { @@ -18,7 +18,7 @@ }, "license": "MIT", "dependencies": { - "lodash": "^4.17.23", + "lodash": "^4.18.1", "mongodb": "^6.21.0", "sift": "^17.1.3" }, From a487c7996c28e1c16454fff79b34b51ec607bfd2 Mon Sep 17 00:00:00 2001 From: harshitha-cstk Date: Thu, 2 Apr 2026 15:16:50 +0530 Subject: [PATCH 4/6] Enhance AGENTS.md with comprehensive project guidance, including a single source of truth, detailed tech stack, source layout, and contributor workflow. Update commands and clarify testing model for better contributor experience. --- AGENTS.md | 106 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 79 insertions(+), 27 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index aac1724..1a3d18b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,49 +1,101 @@ # Agent guidance — `@contentstack/datasync-mongodb-sdk` +## Single source of truth + +Use this file and **`skills/`** as the **canonical** place for project context, workflows, and review standards so contributors get consistent guidance in any IDE or agent (Cursor, Copilot, CLI, others). + +| Layer | Role | +|-------|------| +| **`AGENTS.md`** (this file) | Entry point: package identity, repo links, tech stack, source layout, commands, and skills index | +| **`skills//SKILL.md`** | Full detail: SDK mental model, testing, and code review checklists | +| **`.cursor/rules/`** | Cursor-only scoped pointers (`description` / `globs` / `alwaysApply`) that reference this file and `skills/` | + +**Flow:** Cursor rules → **`AGENTS.md`** → **`skills/*.md`** + ## What this package is -**Contentstack DataSync MongoDB SDK** — a TypeScript/JavaScript library that **queries content already synced into MongoDB** (via Contentstack DataSync and stores such as `@contentstack/content-store-mongodb`). It is **not** a Content Delivery API (CDA) or Content Management API (CMA) HTTP client; it wraps the **MongoDB Node.js driver**, uses **sift** for predicate matching, and exposes a **Stack**-style query API over local collections. +**Contentstack DataSync MongoDB SDK** is a **Node.js/TypeScript** library that **queries MongoDB** holding content synced from Contentstack DataSync (per `package.json`, contents synced via **`@contentstack/content-store-mongodb`**). It uses the **MongoDB Node.js driver**, **lodash**, and **sift** over **local collections**. + +It is **not** the Contentstack **Delivery** (CDA) SDK or **Management** (CMA) SDK, and it does **not** call Contentstack REST APIs for core behavior. ## Repository -- **GitHub:** https://github.com/contentstack/datasync-mongodb-sdk +- **Git:** [https://github.com/contentstack/datasync-mongodb-sdk](https://github.com/contentstack/datasync-mongodb-sdk) +- **Product docs:** [https://www.contentstack.com/docs/guide/synchronization/contentstack-datasync](https://www.contentstack.com/docs/guide/synchronization/contentstack-datasync) ## Tech stack | Area | Details | |------|---------| -| Language | TypeScript **4.9.x** (compiles to `dist/`, declarations in `typings/`) | -| Runtime | Node.js **≥ 8** (`package.json` engines); README suggests Node **20+** for local dev | -| Build | `tsc` — `npm run compile` / `npm run build-ts` (with clean) | -| Tests | **Jest 29** + **ts-jest**, Node test environment | -| Data access | **mongodb** ^6.x, **lodash**, **sift** | -| Lint | **TSLint** (`npm run tslint`) — repo does not use ESLint | -| Docs | JSDoc → `npm run build-doc` (outputs under `docs/`) | - -## Main entry points and layout - -- **Published entry:** `main` → `dist/index.js` (build from `src/index.ts`). -- **Public API:** `Contentstack.Stack(config, db?)` → `Stack` instance (`src/index.ts`, `src/stack.ts`). -- **Config defaults:** `src/config.ts`; messages: `src/messages.ts`; helpers: `src/util.ts`. -- **Type declarations:** `typings/*.d.ts` (generated/committed alongside build). -- **Example:** `example/index.js` (not part of the core SDK package surface for agent edits). +| Language/runtime | TypeScript (`typescript` `^4.9.5` in `package.json`); Node.js `>=8` (`engines`); README may recommend a newer Node for local dev | +| Compilation/build | `tsc` (`npm run compile`); clean + `tsc` via `npm run build-ts`; output to `dist/` and `typings/` | +| Test framework | Jest + ts-jest (`jest.config.js`, Node test environment, coverage enabled). `npm test` runs Jest only (no `pretest` script in `package.json`) | +| Lint/tooling | `npm run tslint` runs TSLint via `tslint.json` on `src/**/*.ts` — this repo does **not** define `npm run lint` or ESLint | +| Core query/data libs | `lodash`, `sift`, `mongodb` (runtime `dependencies`) | +| Docs generation | JSDoc via `npm run build-doc` (builds TS then runs JSDoc into `docs/`) | + +## Source layout and public entry points + +| Role | Path | +|------|------| +| Package runtime entry | `dist/index.js` (`main` in `package.json`) | +| TS public facade | `src/index.ts` (`Contentstack`, `Contentstack.Stack`) | +| User-visible messages | `src/messages.ts` | +| Query builder / core behavior | `src/stack.ts` | +| Defaults + validation helpers | `src/config.ts`, `src/util.ts` | +| Tests and fixtures | `test/` with fixtures in `test/data/` | +| Generated declarations | `typings/*.d.ts` | +| Example (non-published root) | `example/index.js` | ## Common commands | Command | Purpose | |---------|---------| -| `npm run compile` | TypeScript compile to `dist/` | -| `npm run build-ts` | `clean` + full `tsc` | +| `npm run build-ts` | Clean `dist`, `typings`, `coverage`, then compile TypeScript | +| `npm run compile` | Compile TypeScript only | +| `npm test` | Jest with coverage (`jest.config.js`) | +| `npm run tslint` | TSLint on `src/**/*.ts` (`tslint.json`) | | `npm run clean` | Remove `dist/`, `typings/`, `coverage/` | -| `npm test` | Run Jest (see `jest.config.js`) | -| `npm run tslint` | Lint `src/**/*.ts` | -| `npm run build-doc` | Build TS then JSDoc site | +| `npm run build-doc` | Build TS then generate JSDoc under `docs/` | + +## Test model and env/credentials + +- Tests are **integration-style** against a **real MongoDB** (e.g. `Stack.connect()`); they are **not** live Contentstack HTTP API calls. +- Test suites live in `test/`; `jest.config.js` controls matches/ignores. Fixture data: `test/data/`. +- Default connection comes from merged config in **`src/config.ts`** (e.g. **`mongodb://localhost:27017`** unless tests override `contentStore.url`). Typical test DB name: **`sync-test`** (`test/config.ts`). +- No Delivery/Management API credentials are required for core tests. There is **no** committed `.env` contract; pass **`contentStore`** (including `url`) in config when you need non-default hosts or auth. + +## Skills index + +- Skills index: [`skills/README.md`](skills/README.md) +- Key skills: + - [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) + - [`skills/testing/SKILL.md`](skills/testing/SKILL.md) + - [`skills/contentstack-typescript-datasync-mongodb/SKILL.md`](skills/contentstack-typescript-datasync-mongodb/SKILL.md) + +## Cursor rules + +- Cursor rules overview: [`.cursor/rules/README.md`](.cursor/rules/README.md) +- Treat `.cursor/rules/` as scoped pointers; do not treat them as a second source of truth. +- Update policy and standards primarily in `AGENTS.md` and `skills/`, then keep rule pointers aligned. + +## Contributor workflow (concise) + +- **`.husky/pre-commit`** runs **Snyk** and **Talisman** when installed; bypass only as documented locally (e.g. `SKIP_HOOK`). +- **Releases:** version in **`package.json`**. CI may enforce version bumps (see `.github/workflows/check-version-bump.yml`). + +## Cursor-specific quick references -## Tests and credentials +For Cursor workflows, reference these scoped rules: -Tests under `test/` are **integration-style**: they call `Stack.connect()` and use a real MongoDB instance (default **`mongodb://localhost:27017`** from `src/config.ts` unless overridden in config). There is **no** separate `.env` contract in this repo for tests; ensure MongoDB is running locally (database name in tests is typically `sync-test` per `test/config.ts`). Fixture data lives under `test/data/` (ignored as tests by Jest patterns where configured). +- `@typescript` → [`.cursor/rules/typescript.mdc`](.cursor/rules/typescript.mdc) +- `@testing` → [`.cursor/rules/testing.mdc`](.cursor/rules/testing.mdc) +- `@datasync-mongodb` → [`.cursor/rules/datasync-mongodb.mdc`](.cursor/rules/datasync-mongodb.mdc) +- `@code-review` → [`.cursor/rules/code-review.mdc`](.cursor/rules/code-review.mdc) +- `@dev-workflow` → [`.cursor/rules/dev-workflow.md`](.cursor/rules/dev-workflow.md) -## Further reading for agents +Related skills: -- **Cursor rules (when to apply, globs, @-references):** [.cursor/rules/README.md](.cursor/rules/README.md) -- **Skills (expanded checklists and workflows):** [skills/README.md](skills/README.md) +- [`skills/contentstack-typescript-datasync-mongodb/SKILL.md`](skills/contentstack-typescript-datasync-mongodb/SKILL.md) +- [`skills/testing/SKILL.md`](skills/testing/SKILL.md) +- [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) From c75364e10a2176417910d9236e2c7ad4e2dca68a Mon Sep 17 00:00:00 2001 From: harshitha-cstk Date: Mon, 6 Apr 2026 15:37:00 +0530 Subject: [PATCH 5/6] Refactor documentation structure by consolidating and updating agent skills and rules. Remove outdated cursor rules and enhance clarity in AGENTS.md, skills, and testing documentation for improved developer onboarding and contribution processes. --- .cursor/rules/README.md | 25 +--- .cursor/rules/code-review.mdc | 41 ------ .cursor/rules/datasync-mongodb.mdc | 32 ----- .cursor/rules/dev-workflow.md | 29 ----- .cursor/rules/testing.mdc | 35 ----- .cursor/rules/typescript.mdc | 28 ---- AGENTS.md | 123 ++++++++---------- skills/README.md | 24 ++-- skills/code-review/SKILL.md | 55 ++++---- .../SKILL.md | 45 ------- skills/datasync-mongodb/SKILL.md | 68 ++++++++++ skills/dev-workflow/SKILL.md | 60 +++++++++ skills/testing/SKILL.md | 56 ++++---- skills/typescript/SKILL.md | 46 +++++++ 14 files changed, 313 insertions(+), 354 deletions(-) delete mode 100644 .cursor/rules/code-review.mdc delete mode 100644 .cursor/rules/datasync-mongodb.mdc delete mode 100644 .cursor/rules/dev-workflow.md delete mode 100644 .cursor/rules/testing.mdc delete mode 100644 .cursor/rules/typescript.mdc delete mode 100644 skills/contentstack-typescript-datasync-mongodb/SKILL.md create mode 100644 skills/datasync-mongodb/SKILL.md create mode 100644 skills/dev-workflow/SKILL.md create mode 100644 skills/typescript/SKILL.md diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md index f8c956c..e60fad1 100644 --- a/.cursor/rules/README.md +++ b/.cursor/rules/README.md @@ -1,24 +1,5 @@ -# Cursor rules — `@contentstack/datasync-mongodb-sdk` +# Cursor (optional) -This directory contains project-specific rules for AI assistants and developers. Rules use YAML frontmatter with `description`, and optionally `globs` and/or `alwaysApply`. +**Cursor** users: start at the repo root **[`AGENTS.md`](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`** (universal for any editor or tool). -## How to use - -- Rules with **`alwaysApply: true`** are intended to be loaded in relevant sessions automatically (depending on your Cursor settings). -- Rules with **globs** apply when editing matching files. -- For rules without `alwaysApply`, reference them explicitly when needed, e.g. **`@dev-workflow`**, **`@typescript`**, **`@datasync-mongodb`**, **`@testing`**, **`@code-review`** (use the file base name as shown in your Cursor UI). - -## Rule index - -| File | alwaysApply | Globs | When it applies | -|------|-------------|-------|-----------------| -| [dev-workflow.md](./dev-workflow.md) | No | *(none)* | Branching, scripts, PR/release expectations, security hooks | -| [typescript.mdc](./typescript.mdc) | No | `src/**/*.ts`, `typings/**/*.ts` | TypeScript style, layout, TSLint alignment | -| [datasync-mongodb.mdc](./datasync-mongodb.mdc) | No | `src/**/*.ts` | DataSync MongoDB SDK patterns (Stack, config, MongoDB — not CDA/CMA) | -| [testing.mdc](./testing.mdc) | No | `test/**/*.ts`, `jest.config.js` | Jest tests, MongoDB integration tests, fixtures | -| [code-review.mdc](./code-review.mdc) | **Yes** | *(global)* | PR checklist, terminology (DataSync vs CDA/CMA) | - -## Related - -- Root agent entry point: [../../AGENTS.md](../../AGENTS.md) (repository root) -- Skills index: [../../skills/README.md](../../skills/README.md) +This folder **only** contains this **README** — no `.mdc` or other rule files — so nothing editor-specific duplicates the canonical docs. diff --git a/.cursor/rules/code-review.mdc b/.cursor/rules/code-review.mdc deleted file mode 100644 index 9d6a64d..0000000 --- a/.cursor/rules/code-review.mdc +++ /dev/null @@ -1,41 +0,0 @@ ---- -description: PR review checklist for DataSync MongoDB SDK — API docs, compatibility, errors, tests, dependencies. -alwaysApply: true ---- - -# Code review checklist - -## Product terminology - -- This repo is the **DataSync MongoDB SDK** (local MongoDB over synced content). Do **not** describe changes as **CDA** (Delivery API) or **CMA** (Management API) unless the PR explicitly integrates separate HTTP clients — that is not the core of this package. - -## Public API and docs - -- New or changed **public** methods on `Contentstack` / `Stack` should have accurate **JSDoc** consistent with existing files. -- README / example snippets should stay aligned with **`Stack.connect()`** and config shape in `src/config.ts`. - -## Backward compatibility - -- Avoid breaking changes to method names, config keys, and default behaviors without a semver-major plan. -- Consider existing synced MongoDB document shapes and locale/collection naming. - -## Errors and behavior - -- Prefer consistent error messages via **`src/messages.ts`** where applicable. -- Preserve null/undefined handling consistent with MongoDB driver and existing query chains. - -## Dependencies and security - -- New dependencies need justification (bundle size, maintenance, overlap with `lodash` / `mongodb` / `sift`). -- Be mindful of **SCA** / supply-chain expectations (Snyk runs in husky pre-commit for many devs). - -## Tests - -- Meaningful **Jest** coverage for new branches; run **`npm test`** with MongoDB available. -- Update or add fixtures under **`test/data/`** when adding query scenarios. - -## Severity (optional) - -- **Blocker:** Crashes, data corruption risk, security issues, broken public API contract. -- **Major:** Incorrect results, missing tests for critical paths, breaking changes without version strategy. -- **Minor:** Style, small refactors, doc typos. diff --git a/.cursor/rules/datasync-mongodb.mdc b/.cursor/rules/datasync-mongodb.mdc deleted file mode 100644 index 0858a60..0000000 --- a/.cursor/rules/datasync-mongodb.mdc +++ /dev/null @@ -1,32 +0,0 @@ ---- -description: DataSync MongoDB SDK — Stack API, MongoDB connection, config, and query patterns (not CDA/CMA HTTP APIs). -globs: - - src/**/*.ts -alwaysApply: false ---- - -# DataSync MongoDB SDK core - -This package **queries MongoDB** that holds Contentstack **DataSync**-synced content. It does **not** call Contentstack **Delivery** or **Management** REST APIs. - -## Mental model - -- **`Contentstack.Stack(config, existingDb?)`** (`src/index.ts`) returns **`Stack`** (`src/stack.ts`). -- Call **`Stack.connect()`** before queries (see README). -- Config merges with defaults in **`src/config.ts`**: `contentStore.url`, `dbName`, collection names (`collection.asset` / `entry` / `schema`), `locale`, `limit`, `skip`, `referenceDepth`, `projections`, `options` (MongoClient options), indexes, etc. -- Optional second constructor argument: an **existing MongoDB connection** for advanced hosting scenarios. - -## Patterns in code - -- Uses **`mongodb`** driver (`MongoClient`, `Db`, collections). -- Uses **`sift`** for filter matching where applicable. -- **Locales** and **content type** UIDs drive collection naming and queries; respect `validateConfig` / URI validation in **`src/util.ts`**. -- Errors and user-facing strings live in **`src/messages.ts`**. - -## Documentation alignment - -- Product docs: [Contentstack DataSync](https://www.contentstack.com/docs/guide/synchronization/contentstack-datasync) and related DataSync / content-store-mongodb material — **not** CDA/CMA API reference docs for HTTP JSON payloads. - -## Out of scope for this SDK - -- Do not model this package as an HTTP SDK or assume `fetch`/axios patterns for Contentstack cloud APIs here. diff --git a/.cursor/rules/dev-workflow.md b/.cursor/rules/dev-workflow.md deleted file mode 100644 index c27ccfe..0000000 --- a/.cursor/rules/dev-workflow.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -description: Branch workflow, npm scripts, PR expectations, version bumps, and local security hooks for this repo. ---- - -# Development workflow - -## Branches - -Use your team’s Git conventions (feature branches off the main integration branch, PR-based merge). No branch naming scheme is enforced in this repository’s config files. - -## Lint and tests - -- **Compile:** `npm run compile` or `npm run build-ts` (clean + build). -- **Tests:** `npm test` (Jest). Requires a **running MongoDB** reachable at the URL in stack config (defaults to `mongodb://localhost:27017`). -- **Lint:** `npm run tslint` (TSLint on `src/**/*.ts`). - -## Pre-commit (local) - -`.husky/pre-commit` runs **Snyk** (`snyk test --all-projects`) and **Talisman** secret scanning. Both tools must be installed on the developer machine unless commits are skipped with `SKIP_HOOK=1` (documented in the hook). This is separate from `npm test` / `tslint`. - -## Pull requests - -- Prefer green **Jest** runs for changes that touch query or connection behavior. -- Repository automation may include **SCA**, **policy**, and **CodeQL** workflows under `.github/workflows/` — follow failing checks before merge. -- **Version bump:** `.github/workflows/check-version-bump.yml` enforces `package.json` version bumps for certain change sets. *Note:* That workflow’s path filters appear tailored to a different layout in places; if your PR changes `src/` or `test/` and CI expects a version bump, confirm behavior against the latest workflow definition. - -## Releases - -Package version is **`package.json` → `version`**. Publishing uses `publishConfig.access: public`. Bump the version when releasing; align with maintainers on semver for breaking Stack API or config shape changes. diff --git a/.cursor/rules/testing.mdc b/.cursor/rules/testing.mdc deleted file mode 100644 index 836b8d8..0000000 --- a/.cursor/rules/testing.mdc +++ /dev/null @@ -1,35 +0,0 @@ ---- -description: Jest tests, MongoDB integration requirements, and test data layout for datasync-mongodb-sdk. -globs: - - test/**/*.ts - - jest.config.js -alwaysApply: false ---- - -# Testing - -## Runner and config - -- **Jest** with **`ts-jest`** preset (`jest.config.js`). -- **Environment:** `node`. -- **Match:** `**/test/**/*.ts` (and `.js` if present). -- **Coverage:** collected to `coverage/` (JSON + HTML reporters). `test/data/*` paths are ignored per `testPathIgnorePatterns`. - -## Integration vs unit - -- Tests are largely **integration**: they connect to a **real MongoDB** via `Stack.connect()`, insert fixtures, assert query results, then tear down collections / close the client. -- There is no separate `test/integration` folder; behavior is split by topic files (e.g. `core.ts`, `queries.ts`, `references.ts`). - -## Fixtures - -- Shared sample documents: `test/data/*.ts` (e.g. `blog.ts`, `author.ts`, `content_types.ts`). -- Stack config for tests: **`test/config.ts`** (e.g. `dbName: 'sync-test'`). - -## Environment - -- Default Mongo URL comes from merged **`src/config.ts`** (`contentStore.url`) unless tests override `contentStore` in the config object passed to `Contentstack.Stack(...)`. -- No standard **`env` file** is defined in-repo for tests; use local MongoDB or explicitly pass `contentStore.url` in test configs. - -## Naming - -- Test files use descriptive topic names (`comparison-operators.ts`, `skip-limit.ts`, etc.), not `*.test.ts` — Jest picks them up via `testMatch`. diff --git a/.cursor/rules/typescript.mdc b/.cursor/rules/typescript.mdc deleted file mode 100644 index 3b21eb9..0000000 --- a/.cursor/rules/typescript.mdc +++ /dev/null @@ -1,28 +0,0 @@ ---- -description: TypeScript conventions for this repo — compiler settings, TSLint, and src/ layout. -globs: - - src/**/*.ts - - typings/**/*.ts -alwaysApply: false ---- - -# TypeScript — datasync-mongodb-sdk - -## Toolchain - -- **TypeScript** ~4.9 (`package.json` / `tsconfig.json`). -- **Module:** CommonJS, `target` ES6, `moduleResolution` node. Declarations emit to `typings/`, JS to `dist/`. -- **Strictness:** `alwaysStrict`, `noImplicitReturns`, `noUnusedLocals`, `noUnusedParameters`, `noFallthroughCasesInSwitch`. - -## Style (TSLint) - -Align with `tslint.json`: **2-space** indent, **single quotes**, **no semicolons** (`semicolon: never`), **max line length 120**, `only-arrow-functions`, `ordered-imports`, `interface-name` with `I` prefix where used, `no-default-export` (prefer named exports from modules — entry re-exports via `src/index.ts`). - -## Layout - -- Keep new logic in `src/`; avoid expanding `example/` for core behavior. -- Match existing patterns: JSDoc blocks on public classes/methods where the file already uses them. - -## Logging - -- Avoid adding `console.log` / noisy logging in library paths; TSLint warns on several `console` methods. diff --git a/AGENTS.md b/AGENTS.md index 1a3d18b..60fb7b1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,101 +1,92 @@ -# Agent guidance — `@contentstack/datasync-mongodb-sdk` +# AI agent docs — `@contentstack/datasync-mongodb-sdk` -## Single source of truth +You are working on the **Contentstack DataSync MongoDB SDK** — a library that queries **MongoDB** (or a Mongo-compatible store) holding content synced via **Contentstack DataSync**, **not** the Content **Delivery** (CDA) or **Management** (CMA) HTTP SDKs. Core behavior uses the **MongoDB driver** and queries against **persisted sync data**, not live stack REST calls for normal reads. -Use this file and **`skills/`** as the **canonical** place for project context, workflows, and review standards so contributors get consistent guidance in any IDE or agent (Cursor, Copilot, CLI, others). +## Single source of truth | Layer | Role | |-------|------| -| **`AGENTS.md`** (this file) | Entry point: package identity, repo links, tech stack, source layout, commands, and skills index | -| **`skills//SKILL.md`** | Full detail: SDK mental model, testing, and code review checklists | -| **`.cursor/rules/`** | Cursor-only scoped pointers (`description` / `globs` / `alwaysApply`) that reference this file and `skills/` | - -**Flow:** Cursor rules → **`AGENTS.md`** → **`skills/*.md`** +| **[`.cursor/rules/README.md`](.cursor/rules/README.md)** | Optional Cursor pointer (the **only** file under `.cursor/rules/`); links to **`AGENTS.md`** and **`skills/`** | +| **`AGENTS.md`** (this file) | Universal entry: identity, out-of-scope, links, tech stack, commands, skills index | +| **`skills//SKILL.md`** | Full conventions and checklists (source of truth for depth) | -## What this package is +**Flow:** [`.cursor/rules/README.md`](.cursor/rules/README.md) → **`AGENTS.md`** → **`skills//SKILL.md`** -**Contentstack DataSync MongoDB SDK** is a **Node.js/TypeScript** library that **queries MongoDB** holding content synced from Contentstack DataSync (per `package.json`, contents synced via **`@contentstack/content-store-mongodb`**). It uses the **MongoDB Node.js driver**, **lodash**, and **sift** over **local collections**. +## Out of scope (unless comparing or documenting migration) -It is **not** the Contentstack **Delivery** (CDA) SDK or **Management** (CMA) SDK, and it does **not** call Contentstack REST APIs for core behavior. +- **Not** the CDA or CMA **HTTP** client SDKs. +- **Not** live Contentstack **REST** reads for normal query paths — this SDK targets **synced data in MongoDB**. ## Repository -- **Git:** [https://github.com/contentstack/datasync-mongodb-sdk](https://github.com/contentstack/datasync-mongodb-sdk) -- **Product docs:** [https://www.contentstack.com/docs/guide/synchronization/contentstack-datasync](https://www.contentstack.com/docs/guide/synchronization/contentstack-datasync) +| | | +|--|--| +| **npm** | `@contentstack/datasync-mongodb-sdk` | +| **Git** | [https://github.com/contentstack/datasync-mongodb-sdk](https://github.com/contentstack/datasync-mongodb-sdk) | +| **Product docs** | [Contentstack DataSync](https://www.contentstack.com/docs/guide/synchronization/contentstack-datasync) | ## Tech stack | Area | Details | |------|---------| -| Language/runtime | TypeScript (`typescript` `^4.9.5` in `package.json`); Node.js `>=8` (`engines`); README may recommend a newer Node for local dev | -| Compilation/build | `tsc` (`npm run compile`); clean + `tsc` via `npm run build-ts`; output to `dist/` and `typings/` | -| Test framework | Jest + ts-jest (`jest.config.js`, Node test environment, coverage enabled). `npm test` runs Jest only (no `pretest` script in `package.json`) | -| Lint/tooling | `npm run tslint` runs TSLint via `tslint.json` on `src/**/*.ts` — this repo does **not** define `npm run lint` or ESLint | -| Core query/data libs | `lodash`, `sift`, `mongodb` (runtime `dependencies`) | -| Docs generation | JSDoc via `npm run build-doc` (builds TS then runs JSDoc into `docs/`) | +| Language | TypeScript `^4.9.5` (`package.json`); `tsc` → `dist/`, declarations `typings/` (`tsconfig.json`) | +| Runtime | Node `>=8` (`engines`); README may suggest a newer Node for local dev | +| Build | `npm run compile` (`tsc`); `npm run build-ts` (`clean` + `tsc`) | +| Test | Jest `^29` + ts-jest, Node env, coverage on (`jest.config.js`). **`npm test` is `jest` only** — no `pretest` in `package.json` | +| Lint | **TSLint** — `npm run tslint` + `tslint.json` on `src/**/*.ts`. **No ESLint** / no `npm run lint` in this repo | +| Runtime deps | `mongodb`, `lodash`, `sift` | +| Docs | `npm run build-doc` (builds then JSDoc → `docs/`) | ## Source layout and public entry points | Role | Path | |------|------| -| Package runtime entry | `dist/index.js` (`main` in `package.json`) | -| TS public facade | `src/index.ts` (`Contentstack`, `Contentstack.Stack`) | -| User-visible messages | `src/messages.ts` | -| Query builder / core behavior | `src/stack.ts` | -| Defaults + validation helpers | `src/config.ts`, `src/util.ts` | -| Tests and fixtures | `test/` with fixtures in `test/data/` | -| Generated declarations | `typings/*.d.ts` | -| Example (non-published root) | `example/index.js` | +| Package entry | `dist/index.js` (`main`) | +| Public API | `src/index.ts` — `Contentstack`, `Contentstack.Stack(config, db?)` | +| Query / connection | `src/stack.ts` | +| Defaults + validation | `src/config.ts`, `src/util.ts` | +| Messages | `src/messages.ts` | +| Tests + fixtures | `test/`, `test/data/` | +| Declarations | `typings/*.d.ts` | +| Example | `example/index.js` | -## Common commands +## Commands | Command | Purpose | |---------|---------| -| `npm run build-ts` | Clean `dist`, `typings`, `coverage`, then compile TypeScript | -| `npm run compile` | Compile TypeScript only | -| `npm test` | Jest with coverage (`jest.config.js`) | -| `npm run tslint` | TSLint on `src/**/*.ts` (`tslint.json`) | -| `npm run clean` | Remove `dist/`, `typings/`, `coverage/` | -| `npm run build-doc` | Build TS then generate JSDoc under `docs/` | +| `npm run build-ts` | Clean `dist/`, `typings/`, `coverage/`, then `tsc` | +| `npm run compile` | `tsc` only | +| `npm test` | Jest (coverage per `jest.config.js`) | +| `npm run tslint` | TSLint `src/**/*.ts` | +| `npm run clean` | Rimraf `dist`, `typings`, `coverage` | +| `npm run build-doc` | Full build + JSDoc to `docs/` | -## Test model and env/credentials +## Test model and credentials -- Tests are **integration-style** against a **real MongoDB** (e.g. `Stack.connect()`); they are **not** live Contentstack HTTP API calls. -- Test suites live in `test/`; `jest.config.js` controls matches/ignores. Fixture data: `test/data/`. -- Default connection comes from merged config in **`src/config.ts`** (e.g. **`mongodb://localhost:27017`** unless tests override `contentStore.url`). Typical test DB name: **`sync-test`** (`test/config.ts`). -- No Delivery/Management API credentials are required for core tests. There is **no** committed `.env` contract; pass **`contentStore`** (including `url`) in config when you need non-default hosts or auth. +- **Integration-style** tests against a **real MongoDB** (`Stack.connect()`, inserts, queries, teardown). **Not** live Contentstack HTTP API calls. +- Default URI from merged **`src/config.ts`** (e.g. `mongodb://localhost:27017`); tests often use **`test/config.ts`** (`dbName` e.g. `sync-test`). +- **No** committed `.env` for tests; override via **`contentStore`** (including `url`) in code. **Do not** commit production Mongo URIs or secrets. +- **No** Testcontainers or CI Mongo service defined in-repo — local MongoDB is the documented path for developers running tests. ## Skills index -- Skills index: [`skills/README.md`](skills/README.md) -- Key skills: - - [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) - - [`skills/testing/SKILL.md`](skills/testing/SKILL.md) - - [`skills/contentstack-typescript-datasync-mongodb/SKILL.md`](skills/contentstack-typescript-datasync-mongodb/SKILL.md) +Canonical detail lives under **`skills//SKILL.md`**. See **[`skills/README.md`](skills/README.md)**. -## Cursor rules +| Skill | `SKILL.md` | +|-------|------------| +| Dev workflow, hooks, CI | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | +| TypeScript / TSLint / `src/` layout | [`skills/typescript/SKILL.md`](skills/typescript/SKILL.md) | +| DataSync MongoDB SDK behavior | [`skills/datasync-mongodb/SKILL.md`](skills/datasync-mongodb/SKILL.md) | +| Testing | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | +| Code review | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | -- Cursor rules overview: [`.cursor/rules/README.md`](.cursor/rules/README.md) -- Treat `.cursor/rules/` as scoped pointers; do not treat them as a second source of truth. -- Update policy and standards primarily in `AGENTS.md` and `skills/`, then keep rule pointers aligned. - -## Contributor workflow (concise) +## Using Cursor -- **`.husky/pre-commit`** runs **Snyk** and **Talisman** when installed; bypass only as documented locally (e.g. `SKIP_HOOK`). -- **Releases:** version in **`package.json`**. CI may enforce version bumps (see `.github/workflows/check-version-bump.yml`). +- Open **[`.cursor/rules/README.md`](.cursor/rules/README.md)** — the sole file in **`.cursor/rules/`** — for pointers to **`AGENTS.md`** and **`skills/`**. +- Full guidance: **`skills//SKILL.md`** (attach or `@`-reference those paths in chat per your Cursor setup); there are **no** `.cursor/rules/*.mdc` files in this repo. -## Cursor-specific quick references - -For Cursor workflows, reference these scoped rules: - -- `@typescript` → [`.cursor/rules/typescript.mdc`](.cursor/rules/typescript.mdc) -- `@testing` → [`.cursor/rules/testing.mdc`](.cursor/rules/testing.mdc) -- `@datasync-mongodb` → [`.cursor/rules/datasync-mongodb.mdc`](.cursor/rules/datasync-mongodb.mdc) -- `@code-review` → [`.cursor/rules/code-review.mdc`](.cursor/rules/code-review.mdc) -- `@dev-workflow` → [`.cursor/rules/dev-workflow.md`](.cursor/rules/dev-workflow.md) - -Related skills: +## Contributor workflow (concise) -- [`skills/contentstack-typescript-datasync-mongodb/SKILL.md`](skills/contentstack-typescript-datasync-mongodb/SKILL.md) -- [`skills/testing/SKILL.md`](skills/testing/SKILL.md) -- [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) +- **`.husky/pre-commit`:** **Snyk** + **Talisman** when installed; `SKIP_HOOK=1` only if your team allows. +- **CI:** `.github/workflows/` includes CodeQL, SCA, policy scans, **check-version-bump** — see each file for triggers. +- **Version bump workflow** path filters may **not** list `src/`; maintainers may need to align the workflow with this layout (see [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md)). diff --git a/skills/README.md b/skills/README.md index 1b29778..8295049 100644 --- a/skills/README.md +++ b/skills/README.md @@ -1,14 +1,18 @@ -# Agent skills — `@contentstack/datasync-mongodb-sdk` +# Skills — `@contentstack/datasync-mongodb-sdk` -Short index of per-topic folders containing **SKILL.md** files. Use them for deeper context than the Cursor rules alone. +**This directory is the source of truth** for detailed conventions (workflow, TypeScript/TSLint, DataSync MongoDB SDK behavior, tests, code review). Read **[`AGENTS.md`](../AGENTS.md)** at the repo root for the index, identity, and command tables; each skill is a folder with **`SKILL.md`** (YAML frontmatter: `name`, `description`). -| Skill folder | When to use it | -|--------------|----------------| -| [code-review](./code-review/SKILL.md) | PR preparation, review criteria, severity labels, terminology (DataSync vs CDA/CMA). | -| [testing](./testing/SKILL.md) | Running Jest, MongoDB prerequisites, fixtures, test naming. | -| [contentstack-typescript-datasync-mongodb](./contentstack-typescript-datasync-mongodb/SKILL.md) | SDK mental model (`Stack`, config, MongoDB), where to change query or connection behavior. | +## When to use which skill -## Related +| Skill folder | Use when | +|--------------|----------| +| [`dev-workflow/`](dev-workflow/SKILL.md) | Branches, `npm` scripts, Husky, CI, version bumps | +| [`typescript/`](typescript/SKILL.md) | `tsconfig`, TSLint, `src/` layout, JSDoc | +| [`datasync-mongodb/`](datasync-mongodb/SKILL.md) | `Stack`, MongoDB config, queries — DataSync vs CDA/CMA | +| [`testing/`](testing/SKILL.md) | Jest, MongoDB test setup, fixtures, `jest.config.js` | +| [`code-review/`](code-review/SKILL.md) | PR checklist, semver, terminology | -- [AGENTS.md](../AGENTS.md) — single entry point for tools, paths, and commands. -- [.cursor/rules/README.md](../.cursor/rules/README.md) — rule index and globs. +## How to use these docs + +- **Humans / any tool:** Start at **`AGENTS.md`**, then open the relevant **`skills//SKILL.md`**. +- **Cursor users:** **[`.cursor/rules/README.md`](../.cursor/rules/README.md)** (the only file under **`.cursor/rules/`**) points at **`AGENTS.md`** and **`skills/`**. diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 5ec1dcc..c7731b4 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -1,52 +1,59 @@ --- name: code-review -description: PR review checklist for the Contentstack DataSync MongoDB SDK — JSDoc, compatibility, errors, tests, dependencies, and DataSync-vs-CDA/CMA terminology. +description: PR review for DataSync MongoDB SDK — JSDoc, compatibility, errors, tests, deps/SCA; terminology DataSync MongoDB SDK not CDA/CMA HTTP --- -# Skill: Code review (datasync-mongodb-sdk) +# Code review — `@contentstack/datasync-mongodb-sdk` -Use this skill when preparing or reviewing pull requests for **@contentstack/datasync-mongodb-sdk**. +## When to use -## Scope reminder +- Reviewing a PR that touches `src/`, `test/`, or public docs +- Self-checking before request for review +- Judging semver impact for Stack / config / query behavior -This package implements **DataSync** queries against **MongoDB** (synced content). It is **not** the Contentstack **Delivery API (CDA)** or **Management API (CMA)** HTTP SDK. Reviews should use **DataSync** / **MongoDB Stack** terminology unless the change explicitly touches another system. +## Instructions -## Checklist +### Scope and terminology -### Public API and documentation +- This package is the **DataSync MongoDB SDK** (MongoDB over **synced** content). Do **not** call it the **CDA** or **CMA** **HTTP** SDK unless the change explicitly compares or documents migration. +- Behavior should be validated with **MongoDB + Jest** tests, not live stack REST calls, unless the PR is explicitly about integration docs. -- New or changed public surface on `Contentstack` / `Stack` has accurate **JSDoc** and matches behavior in `src/stack.ts`. -- README or `example/` updates reflect required **`Stack.connect()`** usage and realistic `contentStore` config. +### Public API and docs + +- **`Contentstack` / `Stack`** public surface should have accurate **JSDoc** consistent with `src/stack.ts`. +- **README** / **`example/`** must match **`Stack.connect()`** and **`contentStore`** keys from **`src/config.ts`** and real usage. ### Backward compatibility -- Avoid breaking changes to exported names, config keys, default limits/skip/locale behavior, or query result shapes without a major version plan. -- Call out any change that affects **collection naming**, **locale** handling, or **reference depth** behavior for consumers. +- Avoid breaking query result shape, **config** schema, or public method signatures without a **semver-major** plan. +- Watch **locale**, **collection naming**, **reference depth**, **limit/skip** defaults. + +### Errors and messages + +- Prefer centralized strings in **`src/messages.ts`** where the codebase already does. -### Errors and robustness +### Correctness and null safety -- Errors should flow through established patterns; prefer centralized copy in **`src/messages.ts`** where the codebase already does. -- Avoid leaking internal MongoDB details in thrown messages unless intentional. +- Align with MongoDB driver and existing null checks in query chains. ### Dependencies and security -- Justify new packages; prefer existing **lodash**, **mongodb**, **sift** usage patterns. -- Consider **Snyk**/SCA impact and supply-chain expectations. +- New dependencies need justification; align with **`lodash` / `mongodb` / `sift`** patterns and **Snyk**/SCA expectations. ### Tests -- Add or update **Jest** tests with **MongoDB** running locally (default URL from config). -- Use **`test/data/`** fixtures for new document shapes; keep `test/config.ts` consistent with inserted collections. +- Behavioral changes in **`src/`** need matching **`test/`** updates and **`test/data/`** fixtures when document shapes change. ### Optional severity | Level | Examples | |-------|----------| -| Blocker | Data loss, security issue, broken connect/query for supported config | -| Major | Wrong query results, missing tests for new feature, accidental breaking change | -| Minor | Typos, non-functional cleanup, comment-only | +| Blocker | Wrong query results, data corruption risk, security issue, broken public API contract | +| Major | Missing tests for core behavior, breaking change without version/docs strategy | +| Minor | Style, non-user-facing refactors, doc nits | -## Related +## References -- Cursor rule: [`.cursor/rules/code-review.mdc`](../../.cursor/rules/code-review.mdc) -- Entry point: [`AGENTS.md`](../../AGENTS.md) +- [`../testing/SKILL.md`](../testing/SKILL.md) +- [`../datasync-mongodb/SKILL.md`](../datasync-mongodb/SKILL.md) +- [`../../AGENTS.md`](../../AGENTS.md) diff --git a/skills/contentstack-typescript-datasync-mongodb/SKILL.md b/skills/contentstack-typescript-datasync-mongodb/SKILL.md deleted file mode 100644 index b58b95f..0000000 --- a/skills/contentstack-typescript-datasync-mongodb/SKILL.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -name: contentstack-typescript-datasync-mongodb -description: Mental model and file map for the TypeScript DataSync MongoDB SDK — Stack, config, MongoDB driver usage (not CDA/CMA). ---- - -# Skill: Contentstack TypeScript — DataSync MongoDB SDK - -Use this skill when changing **query behavior**, **connection lifecycle**, or **configuration defaults** for **`@contentstack/datasync-mongodb-sdk`**. - -## What this SDK is - -- **DataSync MongoDB SDK:** queries **local/synced** MongoDB collections populated by Contentstack **DataSync** (e.g. via content-store-mongodb). **Not** a REST client for **Delivery** or **Management** APIs. - -## Entry and flow - -1. **`Contentstack.Stack(config, existingDb?)`** — `src/index.ts` → constructs **`Stack`**. -2. **`Stack.connect()`** — establishes MongoDB client / DB (see `src/stack.ts`). -3. Fluent API — **`contentType()`**, **`entries()`**, **`assets()`**, filters, **`language()`**, **`includeReferences()`**, etc., ending in **`find()`** / similar per implementation. - -## Where to change things - -| Concern | Primary location | -|---------|------------------| -| Defaults and mergeable config | `src/config.ts` | -| Connection, queries, cursor logic | `src/stack.ts` | -| Validation helpers (URI, config) | `src/util.ts` | -| User-facing error/warning strings | `src/messages.ts` | -| Package export surface | `src/index.ts` | - -## Dependencies (facts from package.json) - -- **`mongodb`** — database access. -- **`lodash`** — merging and data manipulation. -- **`sift`** — matching filters. - -## Config concepts - -- **`contentStore`:** `url`, `dbName`, **`collection`** (asset/entry/schema names), `locale`, `limit`, `skip`, `projections`, `options` (MongoClient), `referenceDepth`, `indexes`, internal type keys, etc. -- **Locales** can influence collection naming in advanced setups (see tests that prefix collection names with locale segments). - -## Related - -- Cursor rule: [`.cursor/rules/datasync-mongodb.mdc`](../../.cursor/rules/datasync-mongodb.mdc) -- Cursor rule: [`.cursor/rules/typescript.mdc`](../../.cursor/rules/typescript.mdc) -- Entry point: [`AGENTS.md`](../../AGENTS.md) diff --git a/skills/datasync-mongodb/SKILL.md b/skills/datasync-mongodb/SKILL.md new file mode 100644 index 0000000..4386c15 --- /dev/null +++ b/skills/datasync-mongodb/SKILL.md @@ -0,0 +1,68 @@ +--- +name: datasync-mongodb +description: DataSync MongoDB SDK — Stack, MongoDB connection, contentStore config, queries; not CDA/CMA HTTP +--- + +# SDK core and queries — `@contentstack/datasync-mongodb-sdk` + +## When to use + +- Implementing or changing query behavior, filters, or references in `src/stack.ts` +- Adjusting defaults, URI validation, or locale/collection behavior (`src/config.ts`, `src/util.ts`) +- Adding exports or user-facing errors (`src/index.ts`, `src/messages.ts`) + +## Instructions + +### Product model + +- **`@contentstack/datasync-mongodb-sdk`** queries **MongoDB** filled by Contentstack **DataSync** and stores such as **`@contentstack/content-store-mongodb`** (`package.json` description). It does **not** call Contentstack **Delivery** or **Management** REST APIs for normal reads. +- **Stack** here is the query facade over **persisted sync data**, not an HTTP API stack or region endpoint. + +### Entry flow + +1. **`Contentstack.Stack(config, existingDb?)`** (`src/index.ts`) constructs **`Stack`** (`src/stack.ts`). +2. **`Stack.connect()`** establishes the MongoDB client / database — call before queries (see README). +3. Fluent API: **`contentType(uid)`**, **`entries()`**, **`assets()`**, filters, **`language()`**, **`includeReferences()`**, pagination, projections — see **`src/stack.ts`**. + +### Configuration + +- Config merges with **`src/config.ts`** defaults: e.g. **`contentStore.url`**, **`dbName`**, **`collection`** (asset / entry / schema names), **`locale`**, **`limit`**, **`skip`**, **`projections`**, **`options`** (MongoClient options), **`referenceDepth`**, **`indexes`**, internal type keys. +- Optional second argument to **`Stack`**: an **existing** MongoDB connection for advanced scenarios. +- **Indexes:** README recommends indexes on keys such as `_content_type_uid`, `uid`, `locale`, `updated_at` — align with ops for performance. + +### Query execution + +- **Driver:** **`mongodb`** (`MongoClient`, `Db`, collections). +- **Filtering:** **`sift`** where used; **merge/sort:** **`lodash`** patterns in `stack.ts`. +- **Validation:** **`validateConfig`**, **`validateURI`**, **`getCollectionName`** in **`src/util.ts`**. +- **Errors:** prefer **`src/messages.ts`** for user-facing strings. + +### Async patterns + +- **`connect()`** / query methods follow existing **Promise** / `.then()` patterns in the codebase; match surrounding style when extending. + +### Retries + +- Document **MongoClient** / driver options under **`contentStore.options`** in config; **no** separate retry framework is defined in-repo — only what **`mongodb`** and merged config provide. + +### Scope + +- **`src/`** is the SDK core; **`example/`** is illustrative. + +### Where to change code + +| Concern | Start here | +|---------|------------| +| New operator or query path | `src/stack.ts` | +| Defaults, merge behavior | `src/config.ts` | +| URI / config validation | `src/util.ts` | +| User-visible messages | `src/messages.ts` | +| Public exports | `src/index.ts` | + +## References + +- [DataSync guide](https://www.contentstack.com/docs/guide/synchronization/contentstack-datasync) +- [SDK docs](https://contentstack.github.io/datasync-mongodb-sdk/) (when linked from repo README) +- [`../typescript/SKILL.md`](../typescript/SKILL.md) +- [`../testing/SKILL.md`](../testing/SKILL.md) +- [`../../AGENTS.md`](../../AGENTS.md) diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md new file mode 100644 index 0000000..efbb892 --- /dev/null +++ b/skills/dev-workflow/SKILL.md @@ -0,0 +1,60 @@ +--- +name: dev-workflow +description: Branches, npm scripts, Husky, CI, and version-bump expectations for @contentstack/datasync-mongodb-sdk +--- + +# Dev workflow — Contentstack DataSync MongoDB SDK + +## When to use + +- Onboarding or setting up locally +- Before opening or updating a PR +- Planning a release or editing `package.json` version + +## Instructions + +### Branches + +- No `development` / `master` policy is **encoded in this repo** — use your team’s Git flow (feature branches, PR merge targets). + +### Install and build + +```bash +npm install +npm run build-ts +``` + +`npm run build-ts` runs `clean` (rimraf `dist`, `typings`, `coverage`) then `tsc` (`package.json`). + +### Quality gates + +```bash +npm run tslint # TSLint — src/**/*.ts, tslint.json +npm test # Jest — no pretest script; ensure MongoDB available for integration tests +``` + +- **`npm run compile`** — `tsc` without clean (faster incremental builds). + +### PR expectations + +- Run **build** (`build-ts` or `compile` as appropriate), **tslint**, and **tests** when touching `src/` or query behavior. +- **`.husky/pre-commit`** runs **Snyk** and **Talisman** when installed; use **`SKIP_HOOK=1`** only when your team allows bypassing checks. + +### Version bumps and CI + +- Version lives in **`package.json`**. Coordinate semver with maintainers for breaking **Stack** API or **contentStore** config shape changes. +- **`.github/workflows/check-version-bump.yml`** flags missing `package.json` bumps for some “code changed” paths — its **`grep` patterns currently reference paths like `app.js`, `bin/`, `routes/`, not `src/`**. **Placeholder for maintainers:** align this workflow with **`src/`** / **`test/`** or confirm it is intentionally narrow. + +### Other workflows + +- **`.github/workflows/`** also includes **CodeQL**, **SCA**, **policy** scans — read each YAML for triggers. + +### Docs + +- **`npm run build-doc`** — requires successful TS output then JSDoc into **`docs/`**. + +## References + +- [`../testing/SKILL.md`](../testing/SKILL.md) +- [`../typescript/SKILL.md`](../typescript/SKILL.md) +- [`../../AGENTS.md`](../../AGENTS.md) diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md index a01f1e4..8b542ea 100644 --- a/skills/testing/SKILL.md +++ b/skills/testing/SKILL.md @@ -1,41 +1,53 @@ --- name: testing -description: How to run and extend Jest tests for the DataSync MongoDB SDK — MongoDB, fixtures, and jest.config.js behavior. +description: Jest + ts-jest for DataSync MongoDB SDK — real MongoDB integration tests, fixtures, jest.config.js, no live Contentstack HTTP --- -# Skill: Testing (datasync-mongodb-sdk) +# Testing — `@contentstack/datasync-mongodb-sdk` -## Commands +## When to use -```bash -npm test -``` +- Adding or changing tests under `test/` +- Debugging failures after `src/` changes +- Understanding Jest ignores, coverage, or fixture layout -Uses **Jest** with **`ts-jest`** (`jest.config.js`). There is no separate `test:unit` vs `test:integration` script in `package.json` — all tests live under **`test/`** and typically require a real database. +## Instructions -## Prerequisites +### Commands -- **MongoDB** running and reachable at the URL used by tests (defaults to **`mongodb://localhost:27017`** via merged `src/config.ts`, unless your test overrides `contentStore.url`). -- Test database name is commonly **`sync-test`** per **`test/config.ts`**. +- **`npm test`** — runs **`jest`** only (`package.json`). **No `pretest`** — run **`npm run build-ts`** or **`npm run compile`** first if `dist/` / imports require it. +- **`npm run build-ts`** — use when you need a clean compile before debugging. -## Layout +### Runner and config + +- **Jest** + **ts-jest**, **Node** environment (`jest.config.js`). +- **`collectCoverage: true`** — reports under **`coverage/`** (JSON + HTML). +- **`testMatch`:** `**/test/**/*.ts` (and `.js`). +- **`testPathIgnorePatterns`:** `/test/data/*`, `/test/.*config.ts` — fixture/config paths are not treated as test files. +- **`notify: true`** — may use `node-notifier` locally; optional in headless CI. + +### Layout | Path | Role | |------|------| -| `test/*.ts` | Topic suites (e.g. `core.ts`, `queries.ts`) | -| `test/data/*.ts` | Fixture documents imported into collections in `beforeAll` | -| `jest.config.js` | `testMatch`, coverage, `testPathIgnorePatterns` (e.g. `test/data`) | +| `test/**/*.ts` | Topic suites (`core.ts`, `queries.ts`, …) | +| `test/data/*.ts` | Fixture documents imported into collections | +| `test/config.ts` | Shared stack test config (e.g. `dbName`) | +| `jest.config.js` | Match, ignore, coverage, transform | -## Patterns +### Patterns -- Tests obtain **`db`** from **`Stack.connect()`**, insert fixtures with the MongoDB driver, run Stack queries, assert, then **`Stack.close()`** in `afterAll` where used. -- File names are **topic-based**, not `*.spec.ts` — Jest discovers them via glob. +- Tests typically **`Stack.connect()`**, insert fixtures via MongoDB driver, run Stack queries, assert, drop collections / **`Stack.close()`** in `afterAll` where used. +- File names are **topic-based** (not required `*.test.ts`). -## Environment +### Environment and credentials -- No committed `.env` contract for this repo; pass **`contentStore`** (including `url`) in the config object when you need non-default hosts or auth. +- **Real MongoDB** at URL from merged config — default **`mongodb://localhost:27017`** in **`src/config.ts`** unless tests override **`contentStore.url`**. +- **No** Delivery/Management API keys for core tests. +- **No** `.env` contract in-repo; pass **`contentStore`** in code. **Do not** put production URIs in tests or CI secrets in the repo. +- **No** Testcontainers / dockerized Mongo in this repo’s scripts — document **local MongoDB** for developers unless CI is extended. -## Related +## References -- Cursor rule: [`.cursor/rules/testing.mdc`](../../.cursor/rules/testing.mdc) -- Entry point: [`AGENTS.md`](../../AGENTS.md) +- [`../datasync-mongodb/SKILL.md`](../datasync-mongodb/SKILL.md) +- [`../../AGENTS.md`](../../AGENTS.md) diff --git a/skills/typescript/SKILL.md b/skills/typescript/SKILL.md new file mode 100644 index 0000000..41ebeea --- /dev/null +++ b/skills/typescript/SKILL.md @@ -0,0 +1,46 @@ +--- +name: typescript +description: TypeScript and TSLint for src/ — tsconfig, tslint.json, layout, JSDoc; no ESLint in this repo +--- + +# TypeScript (`src/`) — `@contentstack/datasync-mongodb-sdk` + +## When to use + +- Editing or adding files under `src/` or generated `typings/` +- Aligning with compiler and TSLint settings +- Choosing where new code belongs (`index.ts`, `stack.ts`, `config.ts`, `util.ts`, `messages.ts`) + +## Instructions + +### Tooling + +- **Compiler:** `tsconfig.json` — CommonJS, ES6 target, `noImplicitReturns`, `noUnusedLocals` / `noUnusedParameters`, declarations to **`typings/`**, output **`dist/`**. +- **Lint:** **`npm run tslint`** with **`tslint.json`** on **`src/**/*.ts`**. This repo has **no ESLint** and **no `npm run lint`** script. + +### Style (TSLint) + +- Match `tslint.json`: e.g. 2-space indent, single quotes, no semicolons (`semicolon: never`), max line length 120, `ordered-imports`, `no-default-export` (entry composes via `src/index.ts`), `interface-name` with `I` prefix where used. + +### Layout + +- Public exports: **`src/index.ts`** (`Contentstack`, `Contentstack.Stack`). +- Core query/connection logic: **`src/stack.ts`**. +- Defaults: **`src/config.ts`**; validation/helpers: **`src/util.ts`**; copy: **`src/messages.ts`**. + +### JSDoc + +- Follow existing **`@public` / `@description`** patterns for symbols documented for **`npm run build-doc`**. + +### Logging + +- TSLint warns on several **`console`** methods in library code — avoid noisy logging in `src/`. + +### Dependencies + +- Do not assume HTTP/REST clients for core behavior — this SDK uses **MongoDB** + **lodash** + **sift** per **`package.json`**. + +## References + +- [`../datasync-mongodb/SKILL.md`](../datasync-mongodb/SKILL.md) +- [`../../AGENTS.md`](../../AGENTS.md) From e1345fcc2ad5fa0d25f253e858f81c4cd79985eb Mon Sep 17 00:00:00 2001 From: harshitha-cstk Date: Mon, 6 Apr 2026 15:43:57 +0530 Subject: [PATCH 6/6] Add GitHub Actions workflow for automated npm package release on new version creation --- .github/workflows/release.yml | 55 +++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 .github/workflows/release.yml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..115b812 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,55 @@ +name: Release + +on: + release: + types: [created] + +jobs: + build: + runs-on: ubuntu-latest + steps: + # Checkout the repository + - name: Checkout repository + uses: actions/checkout@v4 + + # Setup Node.js environment + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: "22.x" + + # Install dependencies + - name: Install dependencies + run: npm install + + # Fetch package details (name and version) + - name: Get package details + id: package + uses: codex-team/action-nodejs-package-info@v1.1 + + # Install npm-pack-all to create a package archive + - name: Install npm pack + run: npm install npm-pack + + # Pack the package into a .tgz archive + - name: Pack the npm package + run: npm pack + + # Publish the package to npm + - name: Publish to npm + id: publish_npm + uses: JS-DevTools/npm-publish@v3 + with: + token: ${{ secrets.NPM_TOKEN }} + # access: public # Uncomment this line if you want to publish the package as public for first time + + # Upload the packaged .tgz to the release that triggered this workflow + - name: Upload Release Asset + uses: actions/upload-release-asset@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ github.event.release.upload_url }} + asset_path: "./contentstack-datasync-mongodb-sdk-${{ steps.package.outputs.version }}.tgz" + asset_name: "contentstack-datasync-mongodb-sdk-${{ steps.package.outputs.version }}.tgz" + asset_content_type: application/tgz