fix(moss-md-indexer): migrate off legacy `@inferedge-rest/moss` SDK

PR
2mo ago
+796-45

Description

This PR fixes two problems in packages/moss-md-indexer:

Problem 1: Legacy SDK dependency

The md-indexer depends on @inferedge-rest/moss (last published as 1.0.0-beta.3), a pre-release SDK that the rest of the repo has moved away from. Every other JS package uses @moss-dev/moss. The old package name also appears in vitepress-plugin-moss comments and README. The version range >=1.0.0-beta.3 is unbounded, meaning a future major release under that scope would install without anyone noticing.

Problem 2: Destructive upload behavior

Every time a VitePress build runs, the plugin calls uploadDocuments() which deletes the live index and then recreates it. Until createIndex finishes, search on the deployed site has no index to query. If createIndex fails (network error, quota, bad document), the site is left with no index at all. The deleteIndex call also swallows most errors and only logs a warning.

What changed

In packages/moss-md-indexer/src/uploader.ts:

  • Replaced MossRestClient import from @inferedge-rest/moss with MossClient from @moss-dev/moss
  • Changed deleteIndex parameter type from MossRestClient to MossClient
  • Replaced the delete-then-create flow in uploadDocuments() with non-destructive upsert:
    • Checks if the index exists via getIndex()
    • If missing, creates it with createIndex()
    • If exists, upserts new docs with addDocs(..., { upsert: true }) and removes stale IDs with deleteDocs()
  • Added UploadOptions interface with optional recreate flag to preserve the old behavior when needed
  • The createIndex() function signature and behavior remain unchanged

In packages/moss-md-indexer/package.json:

  • Replaced "@inferedge-rest/moss": ">=1.0.0-beta.3" with "@moss-dev/moss": "^1.0.0"
  • Added "vitest": "^4.1.8" to devDependencies
  • Added "test": "vitest run" script
  • Bumped version from 1.0.0-beta.3 to 1.0.0-beta.4

In packages/moss-md-indexer/tests/uploader.test.ts (new file):

  • 12 unit tests covering: index missing (creates new), index exists (upserts + deletes stale), no stale docs, all docs stale, empty document list (no-op), recreate mode (delete + create), error handling (no delete on failure)
  • Mocks MossClient using vi.hoisted and vi.mock

In packages/vitepress-plugin-moss/indexing.ts:

  • Updated comment from @inferedge-rest/moss MossRestClient to @moss-dev/moss MossClient

In packages/vitepress-plugin-moss/README.md:

  • Updated 3 references from @inferedge-rest/moss to @moss-dev/moss
  • Updated description from "deletes old index, then re-uploads chunks" to "upserts new docs, removes stale ones"

In packages/moss-md-indexer/CHANGELOG.md:

  • Added entry for 1.0.0-beta.4 documenting the migration and new behavior

Fixes #518

Type of Change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • This change requires a documentation update

Pull Request Checklist

  • I have read the CONTRIBUTING guide.
  • I have updated the documentation (if applicable).
  • My code follows the style guidelines of this project.
  • I have performed a self-review of my own code.
  • I have added tests that prove my fix is effective or that my feature works.
  • New and existing unit tests pass locally with my changes.

Summary by CodeRabbit

  • New Features

    • Document uploads now update existing indexes without taking them offline, adding new content and removing stale documents.
    • Failed uploads no longer leave the site without an index.
    • Added an optional recreate mode for full index replacement.
    • Exposed upload configuration options to package consumers.

  • Documentation

    • Updated indexing guidance for non-destructive uploads and current SDK integration.
    • Documented the Node.js 20.4 or later requirement.

  • Tests

    • Added coverage for index creation, updates, cleanup, failures, and recreate mode.

  • Chores

    • Updated the Moss SDK integration and package requirements.