chore: Add comprehensive GitHub Copilot instructions with validated commands and timing expectations (#830)

This PR adds a comprehensive `.github/copilot-instructions.md` file that
provides GitHub Copilot coding agents with detailed, validated
instructions for working effectively in the cnpmcore codebase.

## What's Included

The instructions cover all essential aspects of development workflow:

- **Environment Setup**: Complete bootstrap process with Node.js,
MySQL/PostgreSQL, and Redis
- **Build & Development**: All npm scripts with measured timing
expectations
- **Testing Strategy**: Both individual test execution and full suite
with proper timeout warnings
- **Database Management**: Setup instructions for both MySQL and
PostgreSQL environments
- **Validation Scenarios**: Step-by-step manual testing procedures for
API endpoints and functionality
- **Architecture Guide**: Project structure navigation and key service
locations
- **Troubleshooting**: Common issues and resolution steps

## Key Features

**Validated Commands**: Every single command has been tested and
measured:
- npm install: ~2 minutes
- TypeScript compilation: ~6 seconds
- Database initialization: <2 seconds  
- Development server startup: ~20 seconds
- Individual tests: ~12 seconds
- **Full test suite: 4+ minutes with "NEVER CANCEL" warnings**

**Critical Timeout Guidance**: The instructions include explicit
warnings about long-running operations with specific timeout
recommendations to prevent premature cancellation of builds and tests.

**Dual Database Support**: Complete workflows for both MySQL and
PostgreSQL development environments with Docker compose setup.

**Manual Validation**: Specific scenarios for testing API endpoints,
authentication, and core registry functionality to ensure changes work
correctly.

The instructions follow the imperative tone requirement ("Run this
command", "Do not do this") and provide the firm directive to always
reference these instructions first before falling back to additional
search or context gathering.

Fixes #829.

> [!WARNING]
>
> <details>
> <summary>Firewall rules blocked me from connecting to one or more
addresses (expand for details)</summary>
>
> #### I tried to connect to the following addresses, but was blocked by
firewall rules:
>
> - `custom.npmjs.com`
> - Triggering command: `/usr/local/bin/node
--unhandled-rejections=strict
/home/REDACTED/work/cnpmcore/cnpmcore/node_modules/mocha/bin/_mocha
--exit --timeout=60000
--reporter=/home/REDACTED/work/cnpmcore/cnpmcore/node_modules/mochawesome-with-mocha/src/mochawesome.js
--reporter-options=reportDir=node_modules/.mochawesome-reports
--require=/home/REDACTED/work/cnpmcore/cnpmcore/node_modules/@eggjs/mock/dist/esm/register.js
/home/REDACTED/work/cnpmcore/cnpmcore/test/.setup.ts
test/cli/npm/access.test.ts test/cli/npm/install.test.ts
test/common/CryptoUtil.test.ts test/common/FileUtil.test.ts
test/common/PackageUtil.test.ts test/common/UserUtil.test.ts
test/common/adapter/BugVersionStore.test.ts
test/common/adapter/CacheAdapter.test.ts
test/common/adapter/NpmRegistry.test.ts
test/common/adapter/binary/ApiBinary.test.ts
test/common/adapter/binary/BucketBinary.test.ts
test/common/adapter/binary/ChromeForTestingBinary.test.ts
test/common/adapter/binary/CypressBinary.test.ts
test/common/adapter/binary/EdgedriverBinary.test.ts
test/common/adapter/binary/ElectronBinary.test.ts
test/common/adapter/binary/GithubBinary.test.ts
test/common/adapter/binary/ImageminBinary.test.ts
test/common/adapter/binary/NodeBinary.test.ts
test/common/adapter/binary/NodePreGypBinary.test.ts
test/common/adapter/binary/NwjsBinary.test.ts
test/common/adapter/binary/PlaywrightBinary.test.ts
test/common/adapter/binary/PrismaBinary.test.ts
test/common/adapter/binary/PuppeteerBinary.test.ts
test/common/adapter/binary/SqlcipherBinary.test.ts
test/common/adapter/changesStream/CnpmcoreChangesStream.test.ts
test/common/adapter/changesStream/CnpmjsorgChangesStream.test.ts
test/common/adapter/changesStream/NpmChangesStream.test.ts
test/core/entity/BugVersion.test.ts
test/core/entity/PaddingSemver.test.ts test/core/entity/SqlRange.test.ts
test/core/entity/Task.test.ts
test/core/event/BugVersionFixHandler.test.ts
test/core/event/ChangesStream.test.ts
test/core/event/StoreManifest.test.ts
test/core/service/BinarySyncerService/createTask.test.ts
test/core/service/BinarySyncerService/executeTask.test.ts
test/core/service/BugVersionService/cleanBugVersionPackageCache.test.ts
test/core/service/BugVersionService/fixPackageBugVersion.test.ts
test/core/service/BugVersionService/fixPackageBugVersions.test.ts
test/core/service/ChangesStreamService.test.ts
test/core/service/CreateHookTriggerService.test.ts
test/core/service/HookManageService/createHook.test.ts
test/core/service/HookManageService/deleteHook.test.ts
test/core/service/HookManageService/getHookByOwnerId.test.ts
test/core/service/HookManageService/updateHook.test.ts
test/core/service/HookTriggerService.test.ts
test/core/service/PackageManagerService/block.test.ts
test/core/service/PackageManagerService/publish.test.ts
test/core/service/PackageSyncerService/createTask.test.ts
test/core/service/PackageSyncerService/executeTask.test.ts
test/core/service/PackageSyncerService/findExecuteTask.test.ts
test/core/service/PackageSyncerService/getTaskRegistry.test.ts
test/core/service/PackageVersionService.test.ts
test/core/service/ProxyCacheService.test.ts
test/core/service/RegistryManagerService/index.test.ts
test/core/service/ScopeManagerService/index.test.ts
test/core/service/TaskService/findExecuteTask.test.ts
test/core/util/EntityUtil.test.ts test/infra/QueueAdapter.test.ts
test/port/controller/AccessController/listCollaborators.test.ts
test/port/controller/AccessController/listPackagesByUser.test.ts
test/port/controller/BinarySyncController/showBinary.test.ts
test/port/controller/ChangesStreamController/listChanges.test.ts
test/port/controller/DownloadController/showPackageDownloads.test.ts
test/port/controller/HomeController/cors.test.ts
test/port/controller/HomeController/misc.test.ts
test/port/controller/HomeController/ping.test.ts
test/port/controller/HomeController/showTotal.test.ts
test/port/controller/PackageBlockController/blockPackage.test.ts
test/port/controller/PackageBlockController/unblockPackage.test.ts
test/port/controller/PackageSyncController/createSyncTask.test.ts
test/port/controller/PackageSyncController/showSyncTask.test.ts
test/port/controller/PackageSyncController/showSyncTaskLog.test.ts
test/port/controller/PackageTagController/removeTag.test.ts
test/port/controller/PackageTagController/saveTag.test.ts
test/port/controller/PackageTagController/showTags.test.ts
test/port/controller/PackageVersionFileController/listFiles.test.ts
test/port/controller/PackageVersionFileController/raw.test.ts
test/port/controller/PackageVersionFileController/sync.test.ts
test/port/controller/ProxyCacheController/index.test.ts
test/port/controller/RegistryController/index.test.ts
test/port/controller/ScopeController/index.test.ts
test/port/controller/TokenController/createToken.test.ts
test/port/controller/TokenController/listTokens.test.ts
test/port/controller/TokenController/removeToken.test.ts
test/port/controller/UserController/loginOrCreateUser.test.ts
test/port/controller/UserController/logout.test.ts
test/port/controller/UserController/saveProfile.test.ts
test/port/controller/UserController/showProfile.test.ts
test/port/controller/UserController/showUser.test.ts
test/port/controller/UserController/starredByUser.test.ts
test/port/controller/UserController/whoami.test.ts
test/port/controller/hook/HookController.test.ts
test/port/controller/package/DownloadPackageVersionTarController.test.ts
test/port/controller/package/RemovePackageVersionController.test.ts
test/port/controller/package/SavePackageVersionController.test.ts
test/port/controller/package/SearchPackageController.test.ts
test/port/controller/package/ShowPackageController.test.ts
test/port/controller/package/ShowPackageVersionController.test.ts
test/port/controller/package/UpdatePackageController.test.ts
test/port/middleware/AlwaysAuth.test.ts
test/port/middleware/Tracing.test.ts
test/port/webauth/webauthController.test.ts
test/repository/ChangeRepository.test.ts
test/repository/PackageRepository.test.ts
test/repository/ProxyCachePepository.test.ts
test/repository/RegistryRepository.test.ts
test/repository/ScopeRepository.test.ts
test/repository/SearchRepository.test.ts
test/repository/TaskRepository.test.ts
test/repository/TotalRepository.test.ts
test/schedule/ChangesStreamWorker.test.ts
test/schedule/CheckProxyCacheUpdateWorker.test.ts
test/schedule/CheckRecentlyUpdatedPackages.test.ts
test/schedule/CleanTempDir.test.ts
test/schedule/SyncBinaryWorker.test.ts
test/schedule/SyncPackageWorker.test.ts
test/schedule/SyncProxyCacheWorker.test.ts
test/schedule/TaskTimeoutHandler.test.ts` (dns block)
> - `msedgewebdriverstorage.blob.core.windows.net`
> - Triggering command: `/usr/local/bin/node
--unhandled-rejections=strict
/home/REDACTED/work/cnpmcore/cnpmcore/node_modules/mocha/bin/_mocha
--exit --timeout=60000
--reporter=/home/REDACTED/work/cnpmcore/cnpmcore/node_modules/mochawesome-with-mocha/src/mochawesome.js
--reporter-options=reportDir=node_modules/.mochawesome-reports
--require=/home/REDACTED/work/cnpmcore/cnpmcore/node_modules/@eggjs/mock/dist/esm/register.js
/home/REDACTED/work/cnpmcore/cnpmcore/test/.setup.ts
test/cli/npm/access.test.ts test/cli/npm/install.test.ts
test/common/CryptoUtil.test.ts test/common/FileUtil.test.ts
test/common/PackageUtil.test.ts test/common/UserUtil.test.ts
test/common/adapter/BugVersionStore.test.ts
test/common/adapter/CacheAdapter.test.ts
test/common/adapter/NpmRegistry.test.ts
test/common/adapter/binary/ApiBinary.test.ts
test/common/adapter/binary/BucketBinary.test.ts
test/common/adapter/binary/ChromeForTestingBinary.test.ts
test/common/adapter/binary/CypressBinary.test.ts
test/common/adapter/binary/EdgedriverBinary.test.ts
test/common/adapter/binary/ElectronBinary.test.ts
test/common/adapter/binary/GithubBinary.test.ts
test/common/adapter/binary/ImageminBinary.test.ts
test/common/adapter/binary/NodeBinary.test.ts
test/common/adapter/binary/NodePreGypBinary.test.ts
test/common/adapter/binary/NwjsBinary.test.ts
test/common/adapter/binary/PlaywrightBinary.test.ts
test/common/adapter/binary/PrismaBinary.test.ts
test/common/adapter/binary/PuppeteerBinary.test.ts
test/common/adapter/binary/SqlcipherBinary.test.ts
test/common/adapter/changesStream/CnpmcoreChangesStream.test.ts
test/common/adapter/changesStream/CnpmjsorgChangesStream.test.ts
test/common/adapter/changesStream/NpmChangesStream.test.ts
test/core/entity/BugVersion.test.ts
test/core/entity/PaddingSemver.test.ts test/core/entity/SqlRange.test.ts
test/core/entity/Task.test.ts
test/core/event/BugVersionFixHandler.test.ts
test/core/event/ChangesStream.test.ts
test/core/event/StoreManifest.test.ts
test/core/service/BinarySyncerService/createTask.test.ts
test/core/service/BinarySyncerService/executeTask.test.ts
test/core/service/BugVersionService/cleanBugVersionPackageCache.test.ts
test/core/service/BugVersionService/fixPackageBugVersion.test.ts
test/core/service/BugVersionService/fixPackageBugVersions.test.ts
test/core/service/ChangesStreamService.test.ts
test/core/service/CreateHookTriggerService.test.ts
test/core/service/HookManageService/createHook.test.ts
test/core/service/HookManageService/deleteHook.test.ts
test/core/service/HookManageService/getHookByOwnerId.test.ts
test/core/service/HookManageService/updateHook.test.ts
test/core/service/HookTriggerService.test.ts
test/core/service/PackageManagerService/block.test.ts
test/core/service/PackageManagerService/publish.test.ts
test/core/service/PackageSyncerService/createTask.test.ts
test/core/service/PackageSyncerService/executeTask.test.ts
test/core/service/PackageSyncerService/findExecuteTask.test.ts
test/core/service/PackageSyncerService/getTaskRegistry.test.ts
test/core/service/PackageVersionService.test.ts
test/core/service/ProxyCacheService.test.ts
test/core/service/RegistryManagerService/index.test.ts
test/core/service/ScopeManagerService/index.test.ts
test/core/service/TaskService/findExecuteTask.test.ts
test/core/util/EntityUtil.test.ts test/infra/QueueAdapter.test.ts
test/port/controller/AccessController/listCollaborators.test.ts
test/port/controller/AccessController/listPackagesByUser.test.ts
test/port/controller/BinarySyncController/showBinary.test.ts
test/port/controller/ChangesStreamController/listChanges.test.ts
test/port/controller/DownloadController/showPackageDownloads.test.ts
test/port/controller/HomeController/cors.test.ts
test/port/controller/HomeController/misc.test.ts
test/port/controller/HomeController/ping.test.ts
test/port/controller/HomeController/showTotal.test.ts
test/port/controller/PackageBlockController/blockPackage.test.ts
test/port/controller/PackageBlockController/unblockPackage.test.ts
test/port/controller/PackageSyncController/createSyncTask.test.ts
test/port/controller/PackageSyncController/showSyncTask.test.ts
test/port/controller/PackageSyncController/showSyncTaskLog.test.ts
test/port/controller/PackageTagController/removeTag.test.ts
test/port/controller/PackageTagController/saveTag.test.ts
test/port/controller/PackageTagController/showTags.test.ts
test/port/controller/PackageVersionFileController/listFiles.test.ts
test/port/controller/PackageVersionFileController/raw.test.ts
test/port/controller/PackageVersionFileController/sync.test.ts
test/port/controller/ProxyCacheController/index.test.ts
test/port/controller/RegistryController/index.test.ts
test/port/controller/ScopeController/index.test.ts
test/port/controller/TokenController/createToken.test.ts
test/port/controller/TokenController/listTokens.test.ts
test/port/controller/TokenController/removeToken.test.ts
test/port/controller/UserController/loginOrCreateUser.test.ts
test/port/controller/UserController/logout.test.ts
test/port/controller/UserController/saveProfile.test.ts
test/port/controller/UserController/showProfile.test.ts
test/port/controller/UserController/showUser.test.ts
test/port/controller/UserController/starredByUser.test.ts
test/port/controller/UserController/whoami.test.ts
test/port/controller/hook/HookController.test.ts
test/port/controller/package/DownloadPackageVersionTarController.test.ts
test/port/controller/package/RemovePackageVersionController.test.ts
test/port/controller/package/SavePackageVersionController.test.ts
test/port/controller/package/SearchPackageController.test.ts
test/port/controller/package/ShowPackageController.test.ts
test/port/controller/package/ShowPackageVersionController.test.ts
test/port/controller/package/UpdatePackageController.test.ts
test/port/middleware/AlwaysAuth.test.ts
test/port/middleware/Tracing.test.ts
test/port/webauth/webauthController.test.ts
test/repository/ChangeRepository.test.ts
test/repository/PackageRepository.test.ts
test/repository/ProxyCachePepository.test.ts
test/repository/RegistryRepository.test.ts
test/repository/ScopeRepository.test.ts
test/repository/SearchRepository.test.ts
test/repository/TaskRepository.test.ts
test/repository/TotalRepository.test.ts
test/schedule/ChangesStreamWorker.test.ts
test/schedule/CheckProxyCacheUpdateWorker.test.ts
test/schedule/CheckRecentlyUpdatedPackages.test.ts
test/schedule/CleanTempDir.test.ts
test/schedule/SyncBinaryWorker.test.ts
test/schedule/SyncPackageWorker.test.ts
test/schedule/SyncProxyCacheWorker.test.ts
test/schedule/TaskTimeoutHandler.test.ts` (dns block)
> - `r.cnpmjs.org`
> - Triggering command: `/usr/local/bin/node
--unhandled-rejections=strict
/home/REDACTED/work/cnpmcore/cnpmcore/node_modules/mocha/bin/_mocha
--exit --timeout=60000
--reporter=/home/REDACTED/work/cnpmcore/cnpmcore/node_modules/mochawesome-with-mocha/src/mochawesome.js
--reporter-options=reportDir=node_modules/.mochawesome-reports
--require=/home/REDACTED/work/cnpmcore/cnpmcore/node_modules/@eggjs/mock/dist/esm/register.js
/home/REDACTED/work/cnpmcore/cnpmcore/test/.setup.ts
test/cli/npm/access.test.ts test/cli/npm/install.test.ts
test/common/CryptoUtil.test.ts test/common/FileUtil.test.ts
test/common/PackageUtil.test.ts test/common/UserUtil.test.ts
test/common/adapter/BugVersionStore.test.ts
test/common/adapter/CacheAdapter.test.ts
test/common/adapter/NpmRegistry.test.ts
test/common/adapter/binary/ApiBinary.test.ts
test/common/adapter/binary/BucketBinary.test.ts
test/common/adapter/binary/ChromeForTestingBinary.test.ts
test/common/adapter/binary/CypressBinary.test.ts
test/common/adapter/binary/EdgedriverBinary.test.ts
test/common/adapter/binary/ElectronBinary.test.ts
test/common/adapter/binary/GithubBinary.test.ts
test/common/adapter/binary/ImageminBinary.test.ts
test/common/adapter/binary/NodeBinary.test.ts
test/common/adapter/binary/NodePreGypBinary.test.ts
test/common/adapter/binary/NwjsBinary.test.ts
test/common/adapter/binary/PlaywrightBinary.test.ts
test/common/adapter/binary/PrismaBinary.test.ts
test/common/adapter/binary/PuppeteerBinary.test.ts
test/common/adapter/binary/SqlcipherBinary.test.ts
test/common/adapter/changesStream/CnpmcoreChangesStream.test.ts
test/common/adapter/changesStream/CnpmjsorgChangesStream.test.ts
test/common/adapter/changesStream/NpmChangesStream.test.ts
test/core/entity/BugVersion.test.ts
test/core/entity/PaddingSemver.test.ts test/core/entity/SqlRange.test.ts
test/core/entity/Task.test.ts
test/core/event/BugVersionFixHandler.test.ts
test/core/event/ChangesStream.test.ts
test/core/event/StoreManifest.test.ts
test/core/service/BinarySyncerService/createTask.test.ts
test/core/service/BinarySyncerService/executeTask.test.ts
test/core/service/BugVersionService/cleanBugVersionPackageCache.test.ts
test/core/service/BugVersionService/fixPackageBugVersion.test.ts
test/core/service/BugVersionService/fixPackageBugVersions.test.ts
test/core/service/ChangesStreamService.test.ts
test/core/service/CreateHookTriggerService.test.ts
test/core/service/HookManageService/createHook.test.ts
test/core/service/HookManageService/deleteHook.test.ts
test/core/service/HookManageService/getHookByOwnerId.test.ts
test/core/service/HookManageService/updateHook.test.ts
test/core/service/HookTriggerService.test.ts
test/core/service/PackageManagerService/block.test.ts
test/core/service/PackageManagerService/publish.test.ts
test/core/service/PackageSyncerService/createTask.test.ts
test/core/service/PackageSyncerService/executeTask.test.ts
test/core/service/PackageSyncerService/findExecuteTask.test.ts
test/core/service/PackageSyncerService/getTaskRegistry.test.ts
test/core/service/PackageVersionService.test.ts
test/core/service/ProxyCacheService.test.ts
test/core/service/RegistryManagerService/index.test.ts
test/core/service/ScopeManagerService/index.test.ts
test/core/service/TaskService/findExecuteTask.test.ts
test/core/util/EntityUtil.test.ts test/infra/QueueAdapter.test.ts
test/port/controller/AccessController/listCollaborators.test.ts
test/port/controller/AccessController/listPackagesByUser.test.ts
test/port/controller/BinarySyncController/showBinary.test.ts
test/port/controller/ChangesStreamController/listChanges.test.ts
test/port/controller/DownloadController/showPackageDownloads.test.ts
test/port/controller/HomeController/cors.test.ts
test/port/controller/HomeController/misc.test.ts
test/port/controller/HomeController/ping.test.ts
test/port/controller/HomeController/showTotal.test.ts
test/port/controller/PackageBlockController/blockPackage.test.ts
test/port/controller/PackageBlockController/unblockPackage.test.ts
test/port/controller/PackageSyncController/createSyncTask.test.ts
test/port/controller/PackageSyncController/showSyncTask.test.ts
test/port/controller/PackageSyncController/showSyncTaskLog.test.ts
test/port/controller/PackageTagController/removeTag.test.ts
test/port/controller/PackageTagController/saveTag.test.ts
test/port/controller/PackageTagController/showTags.test.ts
test/port/controller/PackageVersionFileController/listFiles.test.ts
test/port/controller/PackageVersionFileController/raw.test.ts
test/port/controller/PackageVersionFileController/sync.test.ts
test/port/controller/ProxyCacheController/index.test.ts
test/port/controller/RegistryController/index.test.ts
test/port/controller/ScopeController/index.test.ts
test/port/controller/TokenController/createToken.test.ts
test/port/controller/TokenController/listTokens.test.ts
test/port/controller/TokenController/removeToken.test.ts
test/port/controller/UserController/loginOrCreateUser.test.ts
test/port/controller/UserController/logout.test.ts
test/port/controller/UserController/saveProfile.test.ts
test/port/controller/UserController/showProfile.test.ts
test/port/controller/UserController/showUser.test.ts
test/port/controller/UserController/starredByUser.test.ts
test/port/controller/UserController/whoami.test.ts
test/port/controller/hook/HookController.test.ts
test/port/controller/package/DownloadPackageVersionTarController.test.ts
test/port/controller/package/RemovePackageVersionController.test.ts
test/port/controller/package/SavePackageVersionController.test.ts
test/port/controller/package/SearchPackageController.test.ts
test/port/controller/package/ShowPackageController.test.ts
test/port/controller/package/ShowPackageVersionController.test.ts
test/port/controller/package/UpdatePackageController.test.ts
test/port/middleware/AlwaysAuth.test.ts
test/port/middleware/Tracing.test.ts
test/port/webauth/webauthController.test.ts
test/repository/ChangeRepository.test.ts
test/repository/PackageRepository.test.ts
test/repository/ProxyCachePepository.test.ts
test/repository/RegistryRepository.test.ts
test/repository/ScopeRepository.test.ts
test/repository/SearchRepository.test.ts
test/repository/TaskRepository.test.ts
test/repository/TotalRepository.test.ts
test/schedule/ChangesStreamWorker.test.ts
test/schedule/CheckProxyCacheUpdateWorker.test.ts
test/schedule/CheckRecentlyUpdatedPackages.test.ts
test/schedule/CleanTempDir.test.ts
test/schedule/SyncBinaryWorker.test.ts
test/schedule/SyncPackageWorker.test.ts
test/schedule/SyncProxyCacheWorker.test.ts
test/schedule/TaskTimeoutHandler.test.ts` (dns block)
> - `replicate.npmjs.com`
> - Triggering command: `/usr/local/bin/node
--unhandled-rejections=strict
/home/REDACTED/work/cnpmcore/cnpmcore/node_modules/mocha/bin/_mocha
--exit --timeout=60000
--reporter=/home/REDACTED/work/cnpmcore/cnpmcore/node_modules/mochawesome-with-mocha/src/mochawesome.js
--reporter-options=reportDir=node_modules/.mochawesome-reports
--require=/home/REDACTED/work/cnpmcore/cnpmcore/node_modules/@eggjs/mock/dist/esm/register.js
/home/REDACTED/work/cnpmcore/cnpmcore/test/.setup.ts
test/cli/npm/access.test.ts test/cli/npm/install.test.ts
test/common/CryptoUtil.test.ts test/common/FileUtil.test.ts
test/common/PackageUtil.test.ts test/common/UserUtil.test.ts
test/common/adapter/BugVersionStore.test.ts
test/common/adapter/CacheAdapter.test.ts
test/common/adapter/NpmRegistry.test.ts
test/common/adapter/binary/ApiBinary.test.ts
test/common/adapter/binary/BucketBinary.test.ts
test/common/adapter/binary/ChromeForTestingBinary.test.ts
test/common/adapter/binary/CypressBinary.test.ts
test/common/adapter/binary/EdgedriverBinary.test.ts
test/common/adapter/binary/ElectronBinary.test.ts
test/common/adapter/binary/GithubBinary.test.ts
test/common/adapter/binary/ImageminBinary.test.ts
test/common/adapter/binary/NodeBinary.test.ts
test/common/adapter/binary/NodePreGypBinary.test.ts
test/common/adapter/binary/NwjsBinary.test.ts
test/common/adapter/binary/PlaywrightBinary.test.ts
test/common/adapter/binary/PrismaBinary.test.ts
test/common/adapter/binary/PuppeteerBinary.test.ts
test/common/adapter/binary/SqlcipherBinary.test.ts
test/common/adapter/changesStream/CnpmcoreChangesStream.test.ts
test/common/adapter/changesStream/CnpmjsorgChangesStream.test.ts
test/common/adapter/changesStream/NpmChangesStream.test.ts
test/core/entity/BugVersion.test.ts
test/core/entity/PaddingSemver.test.ts test/core/entity/SqlRange.test.ts
test/core/entity/Task.test.ts
test/core/event/BugVersionFixHandler.test.ts
test/core/event/ChangesStream.test.ts
test/core/event/StoreManifest.test.ts
test/core/service/BinarySyncerService/createTask.test.ts
test/core/service/BinarySyncerService/executeTask.test.ts
test/core/service/BugVersionService/cleanBugVersionPackageCache.test.ts
test/core/service/BugVersionService/fixPackageBugVersion.test.ts
test/core/service/BugVersionService/fixPackageBugVersions.test.ts
test/core/service/ChangesStreamService.test.ts
test/core/service/CreateHookTriggerService.test.ts
test/core/service/HookManageService/createHook.test.ts
test/core/service/HookManageService/deleteHook.test.ts
test/core/service/HookManageService/getHookByOwnerId.test.ts
test/core/service/HookManageService/updateHook.test.ts
test/core/service/HookTriggerService.test.ts
test/core/service/PackageManagerService/block.test.ts
test/core/service/PackageManagerService/publish.test.ts
test/core/service/PackageSyncerService/createTask.test.ts
test/core/service/PackageSyncerService/executeTask.test.ts
test/core/service/PackageSyncerService/findExecuteTask.test.ts
test/core/service/PackageSyncerService/getTaskRegistry.test.ts
test/core/service/PackageVersionService.test.ts
test/core/service/ProxyCacheService.test.ts
test/core/service/RegistryManagerService/index.test.ts
test/core/service/ScopeManagerService/index.test.ts
test/core/service/TaskService/findExecuteTask.test.ts
test/core/util/EntityUtil.test.ts test/infra/QueueAdapter.test.ts
test/port/controller/AccessController/listCollaborators.test.ts
test/port/controller/AccessController/listPackagesByUser.test.ts
test/port/controller/BinarySyncController/showBinary.test.ts
test/port/controller/ChangesStreamController/listChanges.test.ts
test/port/controller/DownloadController/showPackageDownloads.test.ts
test/port/controller/HomeController/cors.test.ts
test/port/controller/HomeController/misc.test.ts
test/port/controller/HomeController/ping.test.ts
test/port/controller/HomeController/showTotal.test.ts
test/port/controller/PackageBlockController/blockPackage.test.ts
test/port/controller/PackageBlockController/unblockPackage.test.ts
test/port/controller/PackageSyncController/createSyncTask.test.ts
test/port/controller/PackageSyncController/showSyncTask.test.ts
test/port/controller/PackageSyncController/showSyncTaskLog.test.ts
test/port/controller/PackageTagController/removeTag.test.ts
test/port/controller/PackageTagController/saveTag.test.ts
test/port/controller/PackageTagController/showTags.test.ts
test/port/controller/PackageVersionFileController/listFiles.test.ts
test/port/controller/PackageVersionFileController/raw.test.ts
test/port/controller/PackageVersionFileController/sync.test.ts
test/port/controller/ProxyCacheController/index.test.ts
test/port/controller/RegistryController/index.test.ts
test/port/controller/ScopeController/index.test.ts
test/port/controller/TokenController/createToken.test.ts
test/port/controller/TokenController/listTokens.test.ts
test/port/controller/TokenController/removeToken.test.ts
test/port/controller/UserController/loginOrCreateUser.test.ts
test/port/controller/UserController/logout.test.ts
test/port/controller/UserController/saveProfile.test.ts
test/port/controller/UserController/showProfile.test.ts
test/port/controller/UserController/showUser.test.ts
test/port/controller/UserController/starredByUser.test.ts
test/port/controller/UserController/whoami.test.ts
test/port/controller/hook/HookController.test.ts
test/port/controller/package/DownloadPackageVersionTarController.test.ts
test/port/controller/package/RemovePackageVersionController.test.ts
test/port/controller/package/SavePackageVersionController.test.ts
test/port/controller/package/SearchPackageController.test.ts
test/port/controller/package/ShowPackageController.test.ts
test/port/controller/package/ShowPackageVersionController.test.ts
test/port/controller/package/UpdatePackageController.test.ts
test/port/middleware/AlwaysAuth.test.ts
test/port/middleware/Tracing.test.ts
test/port/webauth/webauthController.test.ts
test/repository/ChangeRepository.test.ts
test/repository/PackageRepository.test.ts
test/repository/ProxyCachePepository.test.ts
test/repository/RegistryRepository.test.ts
test/repository/ScopeRepository.test.ts
test/repository/SearchRepository.test.ts
test/repository/TaskRepository.test.ts
test/repository/TotalRepository.test.ts
test/schedule/ChangesStreamWorker.test.ts
test/schedule/CheckProxyCacheUpdateWorker.test.ts
test/schedule/CheckRecentlyUpdatedPackages.test.ts
test/schedule/CleanTempDir.test.ts
test/schedule/SyncBinaryWorker.test.ts
test/schedule/SyncPackageWorker.test.ts
test/schedule/SyncProxyCacheWorker.test.ts
test/schedule/TaskTimeoutHandler.test.ts` (dns block)
>
> If you need me to access, download, or install something from one of
these locations, you can either:
>
> - Configure [Actions setup
steps](https://gh.io/copilot/actions-setup-steps) to set up my
environment, which run before the firewall is enabled
> - Add the appropriate URLs or hosts to the custom allowlist in this
repository's [Copilot coding agent
settings](https://github.com/cnpm/cnpmcore/settings/copilot/coding_agent)
(admins only)
>
> </details>



<!-- START COPILOT CODING AGENT TIPS -->
---

💡 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](https://gh.io/copilot-coding-agent-tips) in the docs.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: fengmk2 <156269+fengmk2@users.noreply.github.com>

.github/copilot-instructions.md

@@ -0,0 +1,282 @@
+# cnpmcore - Private NPM Registry for Enterprise
+
+cnpmcore is a TypeScript-based private NPM registry implementation built with Egg.js framework. It provides enterprise-grade package management with support for MySQL/PostgreSQL databases, Redis caching, and optional Elasticsearch.
+
+**ALWAYS reference these instructions first** and fallback to search or bash commands only when you encounter unexpected information that does not match the information here.
+
+## Prerequisites and Environment Setup
+
+- **Node.js**: Version 20.18.0 or higher (required by engines field in package.json)
+- **Database**: MySQL 5.7+ or PostgreSQL 17+
+- **Cache**: Redis 6+
+- **Optional**: Elasticsearch 8.x for enhanced search capabilities
+
+## Working Effectively
+
+### Bootstrap and Build
+```bash
+# Install dependencies (takes ~2 minutes)
+npm install
+
+# Copy environment configuration
+cp .env.example .env
+
+# Lint code (very fast, <1 second)
+npm run lint
+
+# Fix linting issues
+npm run lint:fix
+
+# Build TypeScript (takes ~6 seconds)
+npm run tsc
+
+# Production build (takes ~6 seconds)
+npm run tsc:prod
+```
+
+### Database Setup - MySQL (Recommended for Development)
+```bash
+# Start MySQL + Redis services via Docker (takes ~1 minute to pull images initially)
+docker compose -f docker-compose.yml up -d
+
+# Verify services are running
+docker compose ps
+
+# Initialize database (takes <2 seconds)
+CNPMCORE_DATABASE_NAME=cnpmcore bash ./prepare-database-mysql.sh
+
+# For tests, create test database
+mysql -h 127.0.0.1 -P 3306 -u root -e "CREATE DATABASE cnpmcore_unittest;"
+```
+
+### Database Setup - PostgreSQL (Alternative)
+```bash
+# Start PostgreSQL + Redis services via Docker
+docker compose -f docker-compose-postgres.yml up -d
+
+# Initialize database (takes <1 second)
+CNPMCORE_DATABASE_NAME=cnpmcore bash ./prepare-database-postgresql.sh
+```
+
+### Development Server
+```bash
+# MySQL development server (starts in ~20 seconds)
+npm run dev
+# Server runs on http://127.0.0.1:7001
+
+# PostgreSQL development server
+npm run dev:postgresql
+# Server runs on http://127.0.0.1:7001
+```
+
+### Testing
+```bash
+# Run full test suite with MySQL - NEVER CANCEL: Takes 4+ minutes. Set timeout to 10+ minutes.
+npm run test
+
+# Run full test suite with PostgreSQL - NEVER CANCEL: Takes 4+ minutes. Set timeout to 10+ minutes.
+npm run test:postgresql
+
+# Run single test file (for faster iteration, takes ~12 seconds)
+npm run test:local test/common/CryptoUtil.test.ts
+
+# Test coverage with MySQL - NEVER CANCEL: Takes 5+ minutes. Set timeout to 15+ minutes.
+npm run cov
+
+# Test coverage with PostgreSQL - NEVER CANCEL: Takes 5+ minutes. Set timeout to 15+ minutes.
+npm run cov:postgresql
+```
+
+**CRITICAL TESTING NOTES:**
+- **NEVER CANCEL** build or test commands - they may take 4-15 minutes to complete
+- Individual test files run much faster (~12 seconds) for development iteration
+- Full test suite processes 100+ test files and requires database initialization
+- Test failures may occur in CI environment; use individual test files for validation
+
+### Production Commands
+```bash
+# CI pipeline commands - NEVER CANCEL: Takes 5+ minutes. Set timeout to 15+ minutes.
+npm run ci          # MySQL CI (includes lint, test, coverage, build)
+npm run ci:postgresql  # PostgreSQL CI
+
+# Production start/stop
+npm run start       # Start as daemon
+npm run stop        # Stop daemon
+npm run start:foreground  # Start in foreground for debugging
+```
+
+## Validation Scenarios
+
+**ALWAYS manually validate changes** by running through these scenarios:
+
+### Basic API Validation
+```bash
+# Start development server
+npm run dev
+
+# Test registry root endpoint
+curl http://127.0.0.1:7001
+# Should return JSON with app metadata and stats
+
+# Test authentication endpoint
+curl http://127.0.0.1:7001/-/whoami
+# Should return authentication error (expected when not logged in)
+
+# Test package listing (initially empty)
+curl http://127.0.0.1:7001/-/all
+```
+
+### Admin User Setup and Package Publishing
+```bash
+# Register admin user (cnpmcore_admin) - requires allowPublicRegistration=true in config
+npm login --registry=http://127.0.0.1:7001
+
+# Verify login
+npm whoami --registry=http://127.0.0.1:7001
+
+# Test package publishing
+npm publish --registry=http://127.0.0.1:7001
+```
+
+## Architecture and Navigation
+
+### Project Structure
+```
+app/
+├── common/          # Global utilities and adapters
+│   ├── adapter/     # External service adapters (NpmRegistry, Binary, etc.)
+│   └── enum/        # Shared enumerations
+├── core/            # Business logic layer
+│   ├── entity/      # Core domain models
+│   ├── event/       # Event handlers and async processing
+│   ├── service/     # Core business services
+│   └── util/        # Internal utilities
+├── port/            # Interface layer
+│   ├── controller/  # HTTP controllers
+│   ├── middleware/  # Express middleware
+│   ├── schedule/    # Background job schedulers
+│   └── webauth/     # WebAuth integration
+├── repository/      # Data access layer
+│   ├── model/       # ORM models
+│   └── util/        # Repository utilities
+└── infra/           # Infrastructure adapters
+```
+
+### Key Services and Controllers
+- **PackageController**: Main package CRUD operations
+- **PackageManagerService**: Core package management business logic
+- **BinarySyncerService**: Binary package synchronization
+- **ChangesStreamService**: NPM registry change stream processing
+- **UserController**: User authentication and profile management
+
+### Configuration Files
+- `config/config.default.ts`: Main application configuration
+- `config/database.ts`: Database connection settings
+- `.env`: Environment-specific variables
+- `tsconfig.json`: TypeScript compilation settings
+
+## Common Development Tasks
+
+### Adding New Features
+1. **ALWAYS run** `npm run lint:fix` before making changes
+2. Add entity classes in `app/core/entity/` for new domain models
+3. Add services in `app/core/service/` for business logic
+4. Add controllers in `app/port/controller/` for HTTP endpoints
+5. Add repositories in `app/repository/` for data access
+6. **ALWAYS run** tests and linting before committing
+
+### Database Migrations
+- SQL files are in `sql/mysql/` and `sql/postgresql/`
+- Migration scripts automatically run during database preparation
+- **NEVER** modify existing migration files - only add new ones
+
+### Background Jobs
+- Schedulers are in `app/port/schedule/`
+- Include sync workers, cleanup tasks, and stream processors
+- Jobs run automatically when development server starts
+
+## Troubleshooting
+
+### Database Connection Issues
+```bash
+# Check if services are running
+docker compose ps
+
+# Reset MySQL environment
+docker compose -f docker-compose.yml down
+docker compose -f docker-compose.yml up -d
+CNPMCORE_DATABASE_NAME=cnpmcore bash ./prepare-database-mysql.sh
+
+# Reset PostgreSQL environment
+docker compose -f docker-compose-postgres.yml down
+docker compose -f docker-compose-postgres.yml up -d
+CNPMCORE_DATABASE_NAME=cnpmcore bash ./prepare-database-postgresql.sh
+```
+
+### Build Issues
+```bash
+# Clean and rebuild
+npm run clean
+npm run tsc
+
+# Check TypeScript configuration
+npx tsc --noEmit
+```
+
+### Test Issues
+```bash
+# Create missing test database
+mysql -h 127.0.0.1 -P 3306 -u root -e "CREATE DATABASE cnpmcore_unittest;"
+
+# Run single test for debugging
+npm run test:local test/common/CryptoUtil.test.ts
+```
+
+## CI/CD Integration
+
+The project uses GitHub Actions with workflows in `.github/workflows/`:
+- `nodejs.yml`: Main CI pipeline with MySQL, PostgreSQL, and Elasticsearch testing
+- Multiple Node.js versions tested: 20, 22, 24
+- **CRITICAL**: CI jobs include long-running tests that can take 15+ minutes per database type
+
+### Pre-commit Validation
+**ALWAYS run before committing:**
+```bash
+npm run lint:fix    # Fix linting issues
+npm run tsc        # Verify TypeScript compilation
+npm run test:local test/path/to/relevant.test.ts  # Run relevant tests
+```
+
+## Docker Support
+
+### Development Environments
+- `docker-compose.yml`: MySQL + Redis + phpMyAdmin
+- `docker-compose-postgres.yml`: PostgreSQL + Redis + pgAdmin  
+- `docker-compose-es.yml`: Elasticsearch integration
+
+### Production Images
+```bash
+# Build Alpine image
+npm run images:alpine
+
+# Build Debian image  
+npm run images:debian
+```
+
+## External Dependencies
+
+- **Database**: MySQL 9.x or PostgreSQL 17+
+- **Cache**: Redis 6+ 
+- **Search**: Elasticsearch 8.x (optional)
+- **Storage**: Local filesystem or S3-compatible storage
+- **Framework**: Egg.js with extensive TypeScript integration
+
+## Performance Notes
+
+- **Startup Time**: ~20 seconds for development server
+- **Build Time**: ~6 seconds for TypeScript compilation  
+- **Test Time**: 4-15 minutes for full suite (database dependent)
+- **Package Installation**: ~2 minutes for npm install
+- **Database Init**: <2 seconds for either MySQL or PostgreSQL
+
+Always account for these timings when setting timeouts for automated processes.