Version 1.0 planning doc

[kenotron]

(note Nov. 2025: there are no active plans to work on a 1.0 release, but these are still good goals if we come back to it later)

Overview

workspace-tools had been used by some of the key monorepo scripts & tools that manage some of the large Microsoft JS projects. This library really came from merging tooling from these repos: backfill, beachball, just-scripts, and lage.

Problems of v0.x

The library has these characteristics & problems:

• the library is a LOOSELY defined set of functions surrounding getting workspace information and related git operations
• the additions to the library are mainly static functions, not classes
• some functions attempt to do caching but without standard ways to invalidate cache
• ALL functions are synchronous 👎🏼
• packageInfos and workspaces are loosely used between different functions as the "state" to be passed between functions - these are not used consistently

Proposal

Goals

1. API surface should be designed ahead of time before implementation
2. No external dependencies (lockfiles implementation, etc. should be implemented JUST enough to gather the information needed)
3. Prefer library calls over spawning processes
4. Asynchronous and Synchronous API surface
5. Leverage NAPI if it makes the operation fast
6. Split repo into monorepo to clearly delineate different aspects of workspace-tools - e.g. git, lockfile, filtering (Split workspace-tools package #229)