workspaces.py

#!/usr/bin/env python3
"""
PURPOSE: Automate building, installing, and publishing our modules.
This is like a little clone of "lerna" for our purposes.

NOTE: I wrote this initially using npm and with the goal of publishing
to npmjs.com.   Now I don't care at all about publishing to npmjs.com,
and we're using pnpm.  So this is being turned into a package just
for cleaning/installing/building.

TEST:
 - This should always work:  "mypy workspaces.py"
"""

import argparse, json, os, platform, shlex, shutil, subprocess, sys, tempfile, time

from typing import Any, Optional, Callable, List

MAX_PACKAGE_LOCK_SIZE_MB = 5
RETIRED_WORKSPACES: set[str] = set()

TEST_ENV_SCRUB_KEYS = [
    # Live project-scoped auth / routing from interactive CoCalc shells can make
    # package tests accidentally talk to or mutate the current project.
    "COCALC_API_URL",
    "COCALC_BEARER_TOKEN",
    "COCALC_AGENT_TOKEN",
    "COCALC_PROJECT_ID",
    "COCALC_SECRET_TOKEN",
    "COCALC_CONTROL_DIR",
    "COCALC_TERMINAL_FILENAME",
    "COCALC_BROWSER_ID",
]


def scrub_live_cocalc_test_env() -> dict[str, str]:
    removed: dict[str, str] = {}
    for key in TEST_ENV_SCRUB_KEYS:
        value = os.environ.pop(key, None)
        if value is not None:
            removed[key] = value
    return removed


def restore_scrubbed_env(scrubbed: dict[str, str]) -> None:
    os.environ.update(scrubbed)


def set_package_test_tmpdir(path: str) -> tuple[str, dict[str, Optional[str]]]:
    safe_path = path.strip("/").replace("/", "-") or "workspace"
    tmpdir = tempfile.mkdtemp(prefix=f"cocalc-test-{safe_path}-")
    old = {key: os.environ.get(key) for key in ["TMPDIR", "TEMP", "TMP"]}
    os.environ.update({"TMPDIR": tmpdir, "TEMP": tmpdir, "TMP": tmpdir})
    return tmpdir, old


def restore_package_test_tmpdir(tmpdir: str,
                                old: dict[str, Optional[str]],
                                cleanup: bool = True) -> None:
    for key, value in old.items():
        if value is None:
            os.environ.pop(key, None)
        else:
            os.environ[key] = value
    if cleanup:
        shutil.rmtree(tmpdir, ignore_errors=True)


def is_jest_backed_package(package_json: dict[str, Any], path: str) -> bool:
    scripts = package_json.get("scripts", {})
    return path.endswith("packages/project-host") or any(
        "jest" in command for command in scripts.values())


def failed_jest_test_paths(report_path: str) -> List[str]:
    try:
        with open(report_path) as report_file:
            report = json.load(report_file)
    except (OSError, ValueError, TypeError):
        return []
    return [
        result["name"] for result in report.get("testResults", [])
        if result.get("status") == "failed" and result.get("name")
    ]


def newest_file(path: str) -> str:
    if platform.system() != 'Darwin':
        # See https://gist.github.com/brwyatt/c21a888d79927cb476a4 for this Linux
        # version:
        cmd = 'find . -type f -printf "%C@ %p\n" | sort -rn | head -n 1 | cut -d" " -f2'
    else:
        # but we had to rewrite this as suggested at
        # https://unix.stackexchange.com/questions/272491/bash-error-find-printf-unknown-primary-or-operator
        # etc to work on MacOS.
        cmd = 'find . -type f -print0 | xargs -0r stat -f "%Fc %N" | sort -rn | head -n 1 | cut -d" " -f2'
    return os.popen(f'cd "{path}" && {cmd}').read().strip()


SUCCESSFUL_BUILD = ".successful-build"


def needs_build(package: str) -> bool:
    # Code below was hopelessly naive, e.g, a failed build would not get retried.
    # We only need to do a build if the newest file in the tree is not
    # in the dist directory.
    path = os.path.join(os.path.dirname(__file__), package)
    if not os.path.exists(os.path.join(path, 'dist')):
        return True
    newest = newest_file(path)
    return not newest.startswith('./' + SUCCESSFUL_BUILD)


def handle_path(s: str,
                path: Optional[str] = None,
                verbose: bool = True) -> None:
    desc = s
    if path is not None:
        os.chdir(path)
        desc += " # in '%s'" % path
    if verbose:
        print(desc)


def cmd(s: str,
        path: Optional[str] = None,
        verbose: bool = True,
        noerr=False) -> None:
    home: str = os.path.abspath(os.curdir)
    try:
        handle_path(s, path, verbose)
        n = os.system(s)
        if n == 2:
            raise KeyboardInterrupt
        if n:
            msg = f"Error executing '{s}'"
            if noerr:
                print(msg)
            else:
                raise RuntimeError(msg)
    finally:
        os.chdir(home)


def run(s: str, path: Optional[str] = None, verbose: bool = True) -> str:
    home = os.path.abspath(os.curdir)
    try:
        handle_path(s, path, verbose)
        a = subprocess.run(s, shell=True, stdout=subprocess.PIPE)
        out = a.stdout.decode('utf8')
        if a.returncode:
            raise RuntimeError("Error executing '%s'" % s)
        return out
    finally:
        os.chdir(home)


def thread_map(callable: Callable,
               inputs: List[Any],
               nb_threads: int = 10) -> List:
    if len(inputs) == 0:
        return []
    if nb_threads == 1:
        return [callable(x) for x in inputs]
    from multiprocessing.pool import ThreadPool
    tp = ThreadPool(nb_threads)
    return tp.map(callable, inputs)


def all_packages() -> List[str]:
    # Compute all the packages.  Explicit order in some cases *does* matter as noted in comments,
    # but we use "tsc --build", which automatically builds deps if not built.
    v = [
        'packages/',  # top level workspace, e.g., typescript
        'packages/cdn',  # packages/hub assumes this is built
        'packages/docs',  # util depends on this for public docs metadata
        'packages/util',
        'packages/apps/document-build',  # conat and downstream apps import its dist
        'packages/sync',
        'packages/sync-client',
        'packages/conat',
        'packages/backend',
        'packages/api-client',
        'packages/apps/notebook',
        'packages/apps/tasks',
        'packages/jupyter',
        'packages/comm',
        'packages/project',
        'packages/assets',
        'packages/chat',
        'packages/chat-client',
        'packages/ai',
        'packages/frontend',  # static depends on frontend; frontend depends on assets
        # static imports compiled JS and copied CSS from essential-frontend.
        'packages/essential-frontend',
        'packages/static',  # packages/hub assumes this is built (for webpack dev server)
        'packages/http-api',  # depends on packages/frontend for i18n
        'packages/lite',
        'packages/project-runner',
        'packages/project-host',
        'packages/plus',
        'packages/export',
        'packages/cli',
        'packages/launchpad',
        'packages/cloud',
        'packages/server',
        'packages/database',
        'packages/project-proxy',
        'packages/file-server',
        'packages/hub',
        'packages/test'
    ]
    for root, dirs, files in os.walk('packages'):
        dirs[:] = [
            name for name in dirs
            if name not in {'build', 'dist', 'node_modules'}
        ]
        path = os.path.normpath(root)
        if path == 'packages' or 'package.json' not in files:
            continue
        if path in RETIRED_WORKSPACES:
            continue
        if path not in v:
            v.append(path)
    return v


def packages(args) -> List[str]:
    v = all_packages()
    # Filter to only the ones in packages (if given)
    if args.packages:
        packages = set(args.packages.split(','))
        v = [x for x in v if x.split('/')[-1] in packages]

    # Only take things not in exclude
    if args.exclude:
        exclude = set(args.exclude.split(','))
        v = [x for x in v if x.split('/')[-1] not in exclude]

    print("Packages: ", ', '.join(v))
    return v


def package_json(package: str) -> dict:
    return json.loads(open(f'{package}/package.json').read())


def write_package_json(package: str, x: dict) -> None:
    open(f'{package}/package.json', 'w').write(json.dumps(x, indent=2))


def dependent_packages(package: str) -> List[str]:
    # Get a list of the packages
    # it depends on by reading package.json
    x = package_json(package)
    if "workspaces" not in x:
        # no workspaces
        return []
    v: List[str] = []
    for path in x["workspaces"]:
        # path is a relative path
        npath = os.path.normpath(os.path.join(package, path))
        if npath != package:
            v.append(npath)
    return v


def get_package_version(package: str) -> str:
    return package_json(package)["version"]


def get_package_npm_name(package: str) -> str:
    return package_json(package)["name"]


def update_dependent_versions(package: str) -> None:
    """
    Update the versions of all of the workspaces that this
    package depends on.  The versions are set to whatever the
    current version is in the dependent packages package.json.

    There is a problem here, if you are publishing two
    packages A and B with versions vA and vB.  If you first publish
    A, then you set it as depending on B@vB.  However, when you then
    publish B you set its new version as vB+1, so A got published
    with the wrong version.  It's thus important to first
    update all the versions of the packages that will be published
    in a single phase, then update the dependent version numbers, and
    finally actually publish the packages to npm.  There will unavoidably
    be an interval of time when some of the packages are impossible to
    install (e.g., because A got published and depends on B@vB+1, but B
    isn't yet published).
    """
    x = package_json(package)
    changed = False
    for dependent in dependent_packages(package):
        print(f"Considering '{dependent}'")
        try:
            package_version = '^' + get_package_version(dependent)
        except:
            print(f"Skipping '{dependent}' since package not available")
            continue
        npm_name = get_package_npm_name(dependent)
        dev = npm_name in x.get("devDependencies", {})
        if dev:
            current_version = x.get("devDependencies", {}).get(npm_name, '')
        else:
            current_version = x.get("dependencies", {}).get(npm_name, '')
        # print(dependent, npm_name, current_version, package_version)
        if current_version != package_version:
            print(
                f"{package}: {dependent} changed from '{current_version}' to '{package_version}'"
            )
            x['devDependencies' if dev else 'dependencies'][
                npm_name] = package_version
            changed = True
    if changed:
        write_package_json(package, x)


def update_all_dependent_versions() -> None:
    for package in all_packages():
        update_dependent_versions(package)


def banner(s: str) -> None:
    print("\n" + "=" * 70)
    print("|| " + s)
    print("=" * 70 + "\n")


def install(args) -> None:
    v = packages(args)

    # The trick we use to build only a subset of the packages in a pnpm workspace
    # is to temporarily modify packages/pnpm-workspace.yaml to explicitly remove
    # the packages that we do NOT want to build.  This should be supported by
    # pnpm via the --filter option but I can't figure that out in a way that doesn't
    # break the global lockfile, so this is the hack we have for now.
    ws = "packages/pnpm-workspace.yaml"
    tmp = ws + ".tmp"
    allp = all_packages()
    try:
        if v != allp:
            shutil.copy(ws, tmp)
            s = open(ws, 'r').read() + '\n'
            for package in allp:
                if package not in v:
                    s += '  - "!%s"\n' % package.split('/')[-1]

            open(ws, 'w').write(s)

        print("install packages")
        # much faster special case
        # see https://github.com/pnpm/pnpm/issues/6778 for why we put that confirm option in
        # for the package-import-method, needed on zfs!, see https://github.com/pnpm/pnpm/issues/7024
        c = "cd packages && pnpm install --config.confirmModulesPurge=false --package-import-method=hardlink"
        if args.prod:
            args.dist_only = False
            args.node_modules_only = False
            args.parallel = True
            clean(args)
            c += " --prod"
        cmd(c)
    finally:
        if os.path.exists(tmp):
            shutil.move(tmp, ws)


def is_github_ci() -> bool:
    """Check if we're running in GitHub CI environment."""
    return 'GITHUB_STEP_SUMMARY' in os.environ


def write_github_summary(success: List[str], flaky: List[str],
                         fails: List[str], elapsed_minutes: float) -> None:
    """Write a markdown summary to GitHub Actions step summary."""
    if not is_github_ci():
        return

    summary_file = os.environ.get('GITHUB_STEP_SUMMARY')
    if not summary_file:
        return

    # Calculate totals
    total_packages = len(success) + len(flaky) + len(fails)
    success_count = len(success)
    flaky_count = len(flaky)
    fail_count = len(fails)

    # Guard against zero packages (e.g., --packages filter matched nothing)
    if total_packages == 0:
        return

    # Determine overall status
    if fail_count > 0:
        status_emoji = "❌"
        status_text = "Tests Failed"
        status_color = "🔴"
    elif flaky_count > 0:
        status_emoji = "⚠️"
        status_text = "Tests Passed (with retries)"
        status_color = "🟡"
    else:
        status_emoji = "✅"
        status_text = "All Tests Passed"
        status_color = "🟢"

    # Build markdown report
    md = []
    md.append(f"# {status_emoji} {status_text}\n")
    md.append(
        f"**{status_color} {success_count}/{total_packages} packages passed** • "
        f"⏱️ {elapsed_minutes:.1f} minutes\n")

    # Summary stats table
    md.append("## 📊 Test Summary\n")
    md.append("| Status | Count | Percentage |")
    md.append("|--------|-------|------------|")
    md.append(
        f"| ✅ Passed (first try) | {success_count} | {100*success_count/total_packages:.1f}% |"
    )
    md.append(
        f"| 🔄 Flaky (passed after retry) | {flaky_count} | {100*flaky_count/total_packages:.1f}% |"
    )
    md.append(
        f"| ❌ Failed | {fail_count} | {100*fail_count/total_packages:.1f}% |")
    md.append("")

    # Details for each category
    if success:
        md.append("## ✅ Passed on First Try\n")
        md.append("<details>")
        md.append(
            f"<summary>View {len(success)} successful packages</summary>\n")
        for pkg in sorted(success):
            pkg_name = pkg.split('/')[-1]
            md.append(f"- `{pkg_name}`")
        md.append("</details>\n")

    if flaky:
        md.append("## 🔄 Flaky Tests (Passed After Retry)\n")
        md.append(
            "> ⚠️ These tests failed initially but passed on retry. Consider investigating for stability.\n"
        )
        for pkg in sorted(flaky):
            pkg_name = pkg.split('/')[-1]
            md.append(f"- ⚠️ `{pkg_name}`")
        md.append("")

    if fails:
        md.append("## ❌ Failed Tests\n")
        md.append(
            "> 🚨 These tests failed all retry attempts. Action required!\n")
        for pkg in sorted(fails):
            pkg_name = pkg.split('/')[-1]
            md.append(f"- ❌ `{pkg_name}`")
        md.append("")

    # Write to file
    try:
        with open(summary_file, 'a') as f:
            f.write('\n'.join(md))
            f.write('\n')
    except Exception as e:
        print(f"Warning: Could not write GitHub summary: {e}")


def test(args) -> None:
    CUR = os.path.abspath('.')
    jest_cache_root = os.environ.get("COCALC_JEST_CACHE_DIR",
                                     os.path.join(CUR, ".cache", "jest"))
    flaky: List[str] = []
    fails: List[str] = []
    success: List[str] = []
    start = time.time()

    def status(package: Optional[str] = None):
        elapsed = (time.time() - start) / 60.0
        status_dict = {
            "fails": fails,
            "flaky": flaky,
            "success": success,
            "time": "%s minutes" % elapsed
        }

        if is_github_ci():
            # Format as GitHub Actions workflow command
            msg = (f"Test Status: "
                   f"{len(success)} passed, "
                   f"{len(flaky)} flaky, "
                   f"{len(fails)} failed "
                   f"({elapsed:.1f} minutes)")

            # Add package name if provided
            if package:
                pkg_name = package.split('/')[-1]
                msg += f" - testing `{pkg_name}`"

            if len(fails) > 0:
                # At least one failure - use error
                print(f"::error::❌ {msg}")
            elif len(flaky) > 0:
                # Flaky tests - use warning
                print(f"::warning::⚠️ {msg}")
            else:
                # All good - use notice
                print(f"::notice::✅ {msg}")
        else:
            # Normal console output
            print("Status: ", status_dict)

    v = packages(args)
    v.sort()
    n = 0
    for path in v:
        n += 1
        package_path = os.path.join(CUR, path)
        if package_path.endswith('packages/'):
            continue
        with open(os.path.join(package_path, 'package.json')) as package_file:
            package_data = json.load(package_file)
        package_scripts = package_data.get("scripts", {})
        jest_backed = is_jest_backed_package(package_data, path)
        jest_cache_path = os.path.join(
            jest_cache_root,
            path.strip("/").replace("/", "-"),
        )

        def f(attempt: int, retry_paths: List[str]):
            print("\n" * 3)
            print("*" * 40)
            print(f"TESTING {n}/{len(v)}: {path}")
            status(path)
            print("*" * 40)
            sys.stdout.flush(
            )  # Ensure output appears before subprocess starts
            if args.test_github_ci and 'test-github-ci' in package_scripts:
                test_cmd = "pnpm run test-github-ci"
            elif 'test:all' in package_scripts:
                test_cmd = "pnpm run --if-present test:all"
            else:
                test_cmd = "pnpm run --if-present test"
            if args.report:
                test_cmd += " --reporters=default --reporters=jest-junit"
            if args.max_workers:
                test_cmd += f' --maxWorkers={args.max_workers} '
            if retry_paths:
                quoted_paths = " ".join(shlex.quote(path)
                                        for path in retry_paths)
                test_cmd += f" --runTestsByPath {quoted_paths}"
            report_path = os.path.join(tmpdir,
                                       f"jest-results-{attempt}.json")
            if jest_backed:
                os.makedirs(jest_cache_path, exist_ok=True)
                test_cmd += (f" --cacheDirectory "
                             f"{shlex.quote(jest_cache_path)}"
                             f" --json --outputFile "
                             f"{shlex.quote(report_path)}")
            cmd(test_cmd, package_path)
            return report_path

        worked = False
        retry_paths: List[str] = []
        scrubbed = scrub_live_cocalc_test_env()
        tmpdir, old_tmp_env = set_package_test_tmpdir(path)
        try:
            for i in range(args.retries + 1):
                report_path = os.path.join(tmpdir,
                                           f"jest-results-{i}.json")
                try:
                    f(i, retry_paths)
                    worked = True
                    if i == 0:
                        success.append(path)
                    else:
                        flaky.append(path)
                    break
                except KeyboardInterrupt:
                    print("SIGINT -- ending test suite")
                    status()
                    return
                except Exception as err:
                    print(err)
                    retry_paths = (failed_jest_test_paths(report_path)
                                   if jest_backed else [])
                    print(f"ERROR testing {path}")
                    if retry_paths:
                        print("Retrying only failed Jest suites: " +
                              ", ".join(retry_paths))
                    if args.retries - i >= 1:
                        print(
                            f"Trying {path} again at most {args.retries - i} more times"
                        )
        finally:
            restore_package_test_tmpdir(tmpdir, old_tmp_env, cleanup=worked)
            restore_scrubbed_env(scrubbed)
        if not worked:
            print(f"Preserved failed test results in: {tmpdir}")
            fails.append(path)

    status()
    if len(flaky) > 0:
        print("Flaky test suites:", flaky)

    # Write GitHub Actions summary if in CI
    elapsed_minutes = (time.time() - start) / 60.0
    write_github_summary(success, flaky, fails, elapsed_minutes)

    if len(fails) == 0:
        print("ALL TESTS PASSED!")
    else:
        print("TESTS failed in the following packages -- ", fails)
        raise RuntimeError(f"Test Suite Failed {fails}")


# Build all the packages that need to be built.
def build(args) -> None:
    v = [package for package in packages(args) if needs_build(package)]
    CUR = os.path.abspath('.')

    def f(path: str) -> None:
        if not args.parallel and path != 'packages/static':
            # NOTE: in parallel mode we don't delete or there is no
            # hope of this working.
            dist = os.path.join(CUR, path, 'dist')
            if os.path.exists(dist):
                # clear dist/ dir
                shutil.rmtree(dist, ignore_errors=True)
        package_path = os.path.join(CUR, path)
        if not os.path.exists(package_path):
            # e.g., in some cases we delete packages entirely to speed
            # up the build
            return
        try:
            if args.dev and '"build:dev"' in open(
                    os.path.join(CUR, path, 'package.json')).read():
                cmd("pnpm run build:dev", package_path)
            else:
                cmd("pnpm run build", package_path)
        except Exception as err:
            if args.force:
                print(err)
            else:
                raise err
        # The build succeeded, so touch a file
        # to indicate this, so we won't build again
        # until something is newer than this file
        cmd("touch " + SUCCESSFUL_BUILD, package_path)

    if args.parallel:
        thread_map(f, v)
    else:
        thread_map(f, v, 1)


def tsc(args) -> None:
    v = packages(args)
    CUR = os.path.abspath('.')

    def has_missing_dist_with_incremental_cache(package_path: str) -> bool:
        """
        TypeScript project builds can report success from tsbuildinfo cache even if
        emitted output was deleted. Detect that state so we can force a rebuild.
        """
        return os.path.exists(
            os.path.join(package_path,
                         "tsconfig.tsbuildinfo")) and not os.path.exists(
                             os.path.join(package_path, "dist"))

    def f(path: str) -> None:
        package_path = os.path.join(CUR, path)
        if path.endswith('packages/'):
            return
        if not os.path.exists(os.path.join(package_path, 'tsconfig.json')):
            return
        cmd("pnpm exec tsc --build", package_path)
        if has_missing_dist_with_incremental_cache(package_path):
            print(
                f"{package_path}: dist missing after incremental build; forcing TypeScript rebuild"
            )
            cmd("pnpm exec tsc --build --force", package_path)

    if args.parallel:
        thread_map(f, v)
    else:
        thread_map(f, v, 1)


def clean(args) -> None:
    v = packages(args)

    if args.dist_only:
        folders = ['dist']
    elif args.node_modules_only:
        folders = ['node_modules']
    else:
        folders = ['node_modules', 'dist', SUCCESSFUL_BUILD]

    paths = []
    for path in v:
        for x in folders:
            y = os.path.abspath(os.path.join(path, x))
            if os.path.exists(y):
                paths.append(y)

    def f(path):
        print("rm -rf '%s'" % path)
        if not os.path.exists(path):
            return
        if os.path.isfile(path):
            os.unlink(path)
            return
        shutil.rmtree(path, ignore_errors=True)
        if os.path.exists(path):
            shutil.rmtree(path, ignore_errors=True)
        if os.path.exists(path):
            raise RuntimeError(f'failed to delete {path}')

    if (len(paths) == 0):
        banner("No node_modules or dist directories")
    else:
        banner("Deleting " + ', '.join(paths))
        thread_map(f, paths + ['packages/node_modules'], nb_threads=10)

    if not args.node_modules_only:
        # remove TypeScript incremental build metadata so future builds don't
        # assume outputs exist when we've just deleted them.
        banner("Removing tsconfig.tsbuildinfo files...")

        def remove_tsbuildinfo(package_path: str) -> None:
            tsinfo = os.path.join(package_path, "tsconfig.tsbuildinfo")
            if os.path.exists(tsinfo):
                print(f"rm -f '{tsinfo}'")
                try:
                    os.unlink(tsinfo)
                except FileNotFoundError:
                    pass

        for package in v:
            remove_tsbuildinfo(os.path.abspath(package))

        banner("Running 'pnpm run clean' if it exists...")

        def g(path):
            cmd("pnpm run --if-present clean", path)

        thread_map(g, [os.path.abspath(path) for path in v],
                   nb_threads=3 if args.parallel else 1)


def delete_package_lock(args) -> None:

    def f(path: str) -> None:
        p = os.path.join(path, 'package-lock.json')
        if os.path.exists(p):
            os.unlink(p)
        # See https://github.com/sagemathinc/cocalc/issues/6123
        # If we don't delete node_modules, then package-lock.json may blow up in size.
        node_modules = os.path.join(path, 'node_modules')
        if os.path.exists(node_modules):
            shutil.rmtree(node_modules, ignore_errors=True)

    thread_map(f, [os.path.abspath(path) for path in packages(args)],
               nb_threads=10)


def pnpm(args, noerr=False) -> None:
    v = packages(args)
    inputs: List[List[str]] = []
    for path in v:
        s = 'pnpm ' + ' '.join(['%s' % x for x in args.args])
        inputs.append([s, os.path.abspath(path)])

    def f(args) -> None:
        # kwds to make mypy happy
        kwds = {"noerr": noerr}
        cmd(*args, **kwds)

    if args.parallel:
        thread_map(f, inputs, 3)
    else:
        thread_map(f, inputs, 1)


def pnpm_noerror(args) -> None:
    pnpm(args, noerr=True)


def version_check(args):
    cmd("scripts/check_npm_packages.py")
    cmd("pnpm check-deps", './packages')


def node_version_check() -> None:
    version = int(os.popen('node --version').read().split('.')[0][1:])
    if version < 14:
        err = f"CoCalc requires node.js v14, but you're using node v{version}."
        if os.environ.get("COCALC_USERNAME",
                          '') == 'user' and 'COCALC_PROJECT_ID' in os.environ:
            err += '\nIf you are using https://cocalc.ai, put ". /cocalc/nvm/nvm.sh" in ~/.bashrc\nto get an appropriate version of node.'
        raise RuntimeError(err)


def pnpm_version_check() -> None:
    """
    Check if the pnpm utility is new enough
    """
    version = os.popen('pnpm --version').read()
    if int(version.split('.')[0]) < 7:
        raise RuntimeError(
            f"CoCalc requires pnpm version 7, but you're using pnpm v{version}."
        )


def main() -> None:
    node_version_check()
    pnpm_version_check()

    def packages_arg(parser):
        parser.add_argument(
            '--packages',
            type=str,
            default='',
            help=
            '(default: ""=everything) "foo,bar" means only the packages named foo and bar'
        )
        parser.add_argument(
            '--exclude',
            type=str,
            default='',
            help=
            '(default: ""=exclude nothing) "foo,bar" means exclude foo and bar'
        )
        parser.add_argument(
            '--parallel',
            action="store_const",
            const=True,
            help=
            'if given, do all in parallel; this will not work in some cases and may be ignored in others'
        )

    parser = argparse.ArgumentParser(prog='workspaces')
    subparsers = parser.add_subparsers(help='sub-command help')

    subparser = subparsers.add_parser(
        'install', help='install node_modules deps for all packages')
    subparser.add_argument('--prod',
                           action="store_const",
                           const=True,
                           help='only install prod deps (not dev ones)')
    packages_arg(subparser)
    subparser.set_defaults(func=install)

    subparser = subparsers.add_parser(
        'build', help='build all packages for which something has changed')
    subparser.add_argument(
        '--dev',
        action="store_const",
        const=True,
        help="only build enough for development (saves time and space)")
    subparser.add_argument('--force',
                           action="store_const",
                           const=True,
                           help="ignore build errors")
    packages_arg(subparser)
    subparser.set_defaults(func=build)

    subparser = subparsers.add_parser(
        'tsc', help='run typescript once on all packages')
    packages_arg(subparser)
    subparser.set_defaults(func=tsc)

    subparser = subparsers.add_parser(
        'clean', help='delete dist and node_modules folders')
    packages_arg(subparser)
    subparser.add_argument('--dist-only',
                           action="store_const",
                           const=True,
                           help="only delete dist directory")
    subparser.add_argument('--node-modules-only',
                           action="store_const",
                           const=True,
                           help="only delete node_modules directory")
    subparser.set_defaults(func=clean)

    subparser = subparsers.add_parser('pnpm',
                                      help='do "pnpm ..." in each package;')
    packages_arg(subparser)
    subparser.add_argument('args',
                           type=str,
                           nargs='*',
                           default='',
                           help='arguments to npm')
    subparser.set_defaults(func=pnpm)

    subparser = subparsers.add_parser(
        'pnpm-noerr',
        help=
        'like "pnpm" but suppresses errors; e.g., use for "pnpm-noerr audit fix"'
    )
    packages_arg(subparser)
    subparser.add_argument('args',
                           type=str,
                           nargs='*',
                           default='',
                           help='arguments to pnpm')
    subparser.set_defaults(func=pnpm_noerror)

    subparser = subparsers.add_parser(
        'version-check', help='version consistency checks across packages')
    subparser.set_defaults(func=version_check)

    subparser = subparsers.add_parser('test', help='test all packages')
    subparser.add_argument(
        "-r",
        "--retries",
        type=int,
        default=2,
        help=
        "how many times to retry a failed test suite before giving up; set to 0 to NOT retry"
    )
    subparser.add_argument(
        '--test-github-ci',
        const=True,
        action="store_const",
        help="run 'pnpm test-github-ci' if available instead of 'pnpm test'")
    subparser.add_argument('--report',
                           action="store_const",
                           const=True,
                           help='if given, generate test reports')
    subparser.add_argument(
        '--max-workers',
        type=str,
        default='',
        help=
        'optional maxWorkers argument to be passed to all all calls to pnpm test.  This can be helpful to prevent overly optimistic hyperthreading.'
    )
    packages_arg(subparser)
    subparser.set_defaults(func=test)

    args = parser.parse_args()
    if hasattr(args, 'func'):
        args.func(args)


if __name__ == '__main__':
    main()