Fix npm publish failures from Deno/TypeScript import incompatibility

[Copilot]

Fix Publish to NPM errors and implement test to validate publish to NPM before release

Summary

This PR fixes TypeScript import errors preventing npm publishing and implements a comprehensive pre-publish validation system with robust error handling and cross-platform compatibility.

Problem

The npm publish workflow failed with:

TS2307 [ERROR]: Cannot find module 'file:///home/runner/work/pluresdb/pluresdb/legacy/util/debug'

Root cause: Conflict between TypeScript (Node.js) and Deno import conventions:

• TypeScript/Node.js: Doesn't allow .ts extensions in imports
• Deno: Requires explicit .ts extensions by default
• During npm publish, tests run with Deno and fail on missing extensions

Solution

1. Fixed Deno Type-Checking ✅

File: package.json

• Added --sloppy-imports flag to npm test command
• Allows Deno to resolve imports without explicit extensions
• Maintains backward compatibility with TypeScript compilation

2. Created Pre-Publish Validation Script ✅

File: scripts/validate-npm-publish.js

Features:

• Comprehensive pre-publish validation
• Cross-platform compatible (Windows, macOS, Linux)
• Clear, color-coded output
• Proper error tracking and reporting

Validations:

• ✅ package.json structure and required fields
• ✅ TypeScript compilation
• ✅ All required dist files exist (including vscode/extension and types/node-types)
• ✅ Deno type checking (with --sloppy-imports) on all tsconfig.json files
• ✅ All tests pass
• ✅ Package size check (configurable threshold)

Error Handling (based on code review):

• ✅ Checks if Deno is available before running tests
• ✅ Distinguishes between Deno unavailability and test failures
• ✅ Continues checking all files even if one fails
• ✅ Cross-platform PATH handling using path.delimiter
• ✅ Configurable package size threshold (MAX_PACKAGE_SIZE_MB)

Deno Type Checking Coverage:

• ✅ legacy/local-first/unified-api.ts
• ✅ legacy/node-index.ts
• ✅ legacy/better-sqlite3.ts
• ✅ legacy/cli.ts
• ✅ legacy/vscode/extension.ts

Usage: npm run validate-publish

3. Updated Release Workflow ✅

File: .github/workflows/release.yml

• Added "Validate package before publish" step
• Runs before build and publish
• Prevents broken packages from being published

4. Comprehensive Documentation ✅

File: docs/NPM_PUBLISH_VALIDATION.md

• Explains the dual-ecosystem challenge
• Documents the solution and implementation
• Provides usage examples
• Includes troubleshooting guide
• Lists import conventions for maintainability

Code Review Improvements

All feedback addressed:

1. ✅ Improved error handling - distinguishes Deno unavailability from failures
2. ✅ Complete file checking - reports all failures, not just the first
3. ✅ Configurable constants - MAX_PACKAGE_SIZE_MB defined at top
4. ✅ Cross-platform support - uses path.delimiter for PATH manipulation
5. ✅ Documentation accuracy - verified and updated reference URLs
6. ✅ Complete required files validation - includes all package.json exports
7. ✅ Complete Deno type checking - all tsconfig.json files checked

Testing

• ✅ TypeScript compilation works
• ✅ Validation script runs successfully
• ✅ All required dist files generated
• ✅ Deno type checking passes with --sloppy-imports
• ✅ Proper error handling and reporting
• ✅ Cross-platform compatibility

Files Changed

• package.json - Added --sloppy-imports and validate-publish script
• scripts/validate-npm-publish.js - New validation script
• .github/workflows/release.yml - Added validation step
• docs/NPM_PUBLISH_VALIDATION.md - New documentation

Impact

• Prevents future npm publish failures
• Provides early validation before release
• Improves developer experience with clear error messages
• Maintains dual-ecosystem compatibility (Node.js + Deno)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Fix Publish to NPM errors and implement test to validate publish to NPM before release</issue_title>
<issue_description>The job failed because of a TypeScript import error:

TS2307 [ERROR]: Cannot find module 'file:///home/runner/work/pluresdb/pluresdb/legacy/util/debug'. Maybe add a '.ts' extension or run with --sloppy-imports
at file:///home/runner/work/pluresdb/pluresdb/legacy/local-first/unified-api.ts:14:26

Solution:

1. Check the import statement in legacy/local-first/unified-api.ts at line 14. It likely looks like:
   import { ... } from '../util/debug';

2. If the file legacy/util/debug.ts exists, update the import to:
   import { ... } from '../util/debug.ts';

3. If the file does not exist:

   • Create legacy/util/debug.ts and add the required exports.
   • Or, correct the path if it's misspelled or misplaced.

4. If using a build tool that supports --sloppy-imports, you can add that flag, but the best practice is to always use explicit .ts extensions in Deno and strict TypeScript projects.

Example fix:
Change from:
import { myDebug } from '../util/debug';
To:
import { myDebug } from '../util/debug.ts';

Summary of actions:

• Update or correct the file path and add the .ts extension in your import statement(s).
• If the file is missing, add it or correct the path.

This should solve the immediate type-checking failure and allow the job to proceed.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Fix Publish to NPM errors and implement test to validate publish to NPM before release #63

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull request overview

This PR fixes npm publish failures caused by incompatibility between Deno's requirement for .ts extensions in imports and TypeScript's prohibition of them in compiled files. The solution uses Deno's --sloppy-imports flag to enable Node.js-style module resolution.

Changes:

• Added --sloppy-imports flag to the test command to allow Deno to resolve extensionless imports
• Created a comprehensive pre-publish validation script that checks TypeScript compilation, Deno type-checking, required files, tests, and package size
• Integrated validation into the CI/CD release workflow to prevent publish failures
• Added detailed documentation explaining the problem, solution, and troubleshooting steps

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
package.json	Added --sloppy-imports to test command and new validate-publish script
scripts/validate-npm-publish.js	New validation script with comprehensive pre-publish checks for npm packages
.github/workflows/release.yml	Added validation step before npm publish in release workflow
docs/NPM_PUBLISH_VALIDATION.md	Documentation explaining the dual-ecosystem import issue and validation system