CLI TypeScript migration (re) #2830

Harjun751 · 2026-02-07T03:46:34Z

What is the purpose of this pull request?

Overview of changes:

Resolves #2754

Migrate functional code in CLI package to typescript
- index.js and all util files converted to typescript
- live-server patch is still JavaScript - added type definitions for now.
- Test files migrated to typescript
- Add typescript configs in the cli package - generated files go to cli/dist/
Package changes
- Modified cli/package.json to properly prepare and publish the markbind-cli package.
- Modified root package.json to use the built CLI module in cli/dist/
- Updated selected packages to get built-in type definitions
- Installed some type definitions
Developer-facing changes
- Added a build/dev script in cli/package.json
- Updated root build/dev scripts to utilize Project References (running the build/dev scripts are functionally the same as a developer)
- Added tsx as a dev dependency - run TypeScript files directly using the bundled runner
- Update dev docs on modified setup instructions & on how to use tsx to directly run files

Anything you'd like to highlight/discuss:
The migrated code is TypeScript, but it's not good TypeScript. There's liberal use of any, so it could definitely be improved. I think we could do refactoring as a separate PR, as I didn't want to clutter this PR any further. LMK, though.

Suggested things to refactor:

Refactor core Site constructor. The CLI was using the constructor without properly specifying all the arguments - create an overloaded constructor for this?
TypeScript 4.4 set the error type of catch variable to unknown. This means that to extract the error message, type narrowing was required. This introduces an extra branch and decision - what to log when the type of error is unknown? Currently, it simply logs "unknown error". Suggest: extract a variable/function that can be re-used in these cases, instead of hard-coding a message.
Create an interface/type that can be used for the option parameter of the commander package callbacks
Generally improve logger re-use in the cmd/ files - a lot of code duplication.
Create an interface/type that can be used for the ServerConfig object in serve.ts
Decrease the high level of coupling between the CLI and Core package

I chose tsx over ts-node since tsx seems more actively-maintained (the last release for ts-node was 3 years ago). Furthermore, tsx seems generally faster, and I had a good experience using tsx with Webstorm with zero configuration or issues. If there's another option worth considering, feel free to raise it up.

In terms of documentation, I did not add an entry on how to configure VSCode with tsx to run TypeScript code directly with, as I don't use VSC. If you think it's valuable, please do add it in!

Testing instructions:

Above running normal tests, you can check if your IDE/setup can correctly run individual test cases/suites in the cli/test/unit directory, since they use TypeScript now.

Proposed commit message: (wrap lines at 72 characters)

Migrate functional code in CLI package to TypeScript

Checklist: ☑️

Updated the documentation for feature additions and enhancements
Added tests for bug fixes or features
Linked all related issues
No unrelated changes

Reviewer checklist:

Indicate the SEMVER impact of the PR:

Major (when you make incompatible API changes)
Minor (when you add functionality in a backward compatible manner)
Patch (when you make backward compatible bug fixes)

At the end of the review, please label the PR with the appropriate label: r.Major, r.Minor, r.Patch.

Breaking change release note preparation (if applicable):

To be included in the release note for any feature that is made obsolete/breaking

Give a brief explanation note about:

what was the old feature that was made obsolete

any replacement feature (if any), and

how the author should modify his website to migrate from the old feature to the replacement feature (if possible).

With migrated test files, eslint does not detect that functional test files are tests, resulting in raising "no-extraneous-dependencies" error. This error suggests that dependencies used in the actual application and not test harnesses/files should be in the main dependencies section. However, since these are test files, the dependencies should rightfully be in `devDependencies`. Hence, let's add an rule exclusion for import/no-extraneous-dependencies for the functional tests.

To facilitate TypeScript migration, update `diff` package to get in-built type declarations. No breaking changes related to current usage introduced.

istextorbinary developer dependency uses an old version without typescript type definitions. As part of migration of tests to typescript, the files requiring istextorbinary now need type definitions. Let's update istextorbinary to the latest version. No breaking changes were introduced that affected the usage of istextorbinary in the code.

To configure adapted tests and files to run properly, scripts need to be updated. Additionally, project references should be enabled to ensure that subpackages referring to each other are built in the correct order and correctly. Let's * Update root package.json to use `tsc --build` to build the backend * Update scripts that require CLI to use built output (.js files) * Update cli jest.config.ts to use ts-jest to be able to run test files with jest directly * Update root tsconfig to point to cli/ and core/ packages * Update core/ tsconfig to set `composite` to true to utilize incremental builds * Add cli/ tsconfig with references to core/ package, along with basic config * Update packages in package-lock

Due to update TypeScript configurations, update the developer docs to remain up-to-date on setting up the project and developing.

codecov · 2026-02-07T03:51:22Z

Codecov Report

❌ Patch coverage is 92.50000% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.20%. Comparing base (2f6cb37) to head (b7ed620).
⚠️ Report is 17 commits behind head on master.

Files with missing lines	Patch %	Lines
packages/cli/src/util/cliUtil.ts	91.66%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2830      +/-   ##
==========================================
- Coverage   72.20%   72.20%   -0.01%     
==========================================
  Files         134      134              
  Lines        7454     7461       +7     
  Branches     1528     1531       +3     
==========================================
+ Hits         5382     5387       +5     
- Misses       2026     2028       +2     
  Partials       46       46

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

tsconfig.json

tsconfig_base.json

packages/cli/test/functional/.eslintrc.js

gerteck

LGTM, good job on this

Note to self:

--build for tsc is for project references, which builds each package in dependency order.

Other stuff

CLI snapshot test fails on my local after checking out to this branch. (EDIT: Due to .DS_Store due to dev on MacOS, unrelated to this PR. Tests pass on CI.)
I got a permission denied as in, had to run chmod to add execute perms. i wonder if it is just a local dev env thing? Have not faced this before.
Generated js file does not have executable flag enabled.

Edit: The markbind CLI command fails with "permission denied" because the generated packages/cli/dist/index.js
file loses its executable flag during the build process. tsc does not preserve permissions from source files.

TypeScript compiler outputs all generated files with `644` permissions, meaning that by default generated files are not executable. Additionally, the compiler does not preserve permissions of source files when generating output, see: github.com/microsoft/TypeScript/issues/37583 This particularly causes a problem with `npm link`, since the entrypoint file does not have execute permissions after rebuilding, making the linked project unable to be ran. To workaround this, let's * Add a script to ensure that the entrypoint file is executable * Make the script run before `dev` and `build:backend` workflows * Add a disclaimer in documentation on what to do if the permission error occurs

gerteck · 2026-02-10T02:15:59Z

scripts/prepCliOutput.js

@@ -0,0 +1,43 @@
+/*


nice workaround for now

gerteck

LGTM, thanks for the great work on this @Harjun751

Merging this in, @MarkBind/active-3281-members do remember to update your forks and pull the latest after merging!

Harjun751 added 16 commits February 6, 2026 18:13

Add .gitignore and eslint exclusions for TS

aed3f8f

Rename cli/ files to TypeScript

507310d

Adapt cli/src/util to TypeScript

c3a1a39

Adapt cli/src/cmd to TypeScript

805b2de

Adapt cli/index to TypeScript

9740c8d

Adapt cli/test/unit to TypeScript

1fc374f

Adapt cli/test/functional/testUtil/ to TypeScript

cdcf3c3

Adapt cli/test/functional/ to TypeScript

9c036c0

Bump diff devdep from ^4.0.1 to ^8.0.3

30754f2

To facilitate TypeScript migration, update `diff` package to get in-built type declarations. No breaking changes related to current usage introduced.

Bump figlet from ^1.2.4 to ^1.9.4

a91f441

Add @types/lodash as dev dependency

966adbd

Add tsx as a dev dependency

75adf7a

Update developer documentation

df2ce3f

Due to update TypeScript configurations, update the developer docs to remain up-to-date on setting up the project and developing.

Harjun751 requested a review from a team February 7, 2026 03:51

gerteck reviewed Feb 7, 2026

View reviewed changes

tsconfig.json Show resolved Hide resolved

Harjun751 mentioned this pull request Feb 8, 2026

CLI TypeScript migration #2802

Closed

14 tasks

gerteck reviewed Feb 9, 2026

View reviewed changes

tsconfig_base.json Show resolved Hide resolved

gerteck reviewed Feb 9, 2026

View reviewed changes

packages/cli/test/functional/.eslintrc.js Show resolved Hide resolved

gerteck reviewed Feb 9, 2026

View reviewed changes

Harjun751 force-pushed the cli-typescript-migration-redux branch 2 times, most recently from 268221f to b7ed620 Compare February 10, 2026 01:36

gerteck reviewed Feb 10, 2026

View reviewed changes

scripts/prepCliOutput.js

@@ -0,0 +1,43 @@

/*

Copy link

Member

gerteck Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nice workaround for now

gerteck approved these changes Feb 10, 2026

View reviewed changes

gerteck merged commit fe1bcba into MarkBind:master Feb 10, 2026
16 of 21 checks passed

github-actions bot added the r.Minor Version resolver: increment by 0.1.0 label Feb 10, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CLI TypeScript migration (re) #2830

CLI TypeScript migration (re) #2830

Uh oh!

Harjun751 commented Feb 7, 2026 •

edited by gerteck

Loading

Uh oh!

codecov bot commented Feb 7, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gerteck left a comment •

edited

Loading

Uh oh!

gerteck Feb 10, 2026

Uh oh!

gerteck left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

CLI TypeScript migration (re) #2830

CLI TypeScript migration (re) #2830

Uh oh!

Conversation

Harjun751 commented Feb 7, 2026 • edited by gerteck Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Feb 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gerteck left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Other stuff

Uh oh!

gerteck Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

gerteck left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Harjun751 commented Feb 7, 2026 •

edited by gerteck

Loading

codecov bot commented Feb 7, 2026 •

edited

Loading

gerteck left a comment •

edited

Loading