feat(ls): support output format

[tknickman]

Description

Support output format for ls

Testing Instructions

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
examples-nonmonorepo	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Aug 19, 2024 8:34pm

8 Skipped Deployments

Name	Status	Preview	Comments	Updated (UTC)
examples-basic-web	⬜️ Ignored (Inspect)	Visit Preview		Aug 19, 2024 8:34pm
examples-designsystem-docs	⬜️ Ignored (Inspect)	Visit Preview		Aug 19, 2024 8:34pm
examples-gatsby-web	⬜️ Ignored (Inspect)	Visit Preview		Aug 19, 2024 8:34pm
examples-kitchensink-blog	⬜️ Ignored (Inspect)	Visit Preview		Aug 19, 2024 8:34pm
examples-native-web	⬜️ Ignored (Inspect)	Visit Preview		Aug 19, 2024 8:34pm
examples-svelte-web	⬜️ Ignored (Inspect)	Visit Preview		Aug 19, 2024 8:34pm
examples-tailwind-web	⬜️ Ignored (Inspect)	Visit Preview		Aug 19, 2024 8:34pm
examples-vite-web	⬜️ Ignored (Inspect)	Visit Preview		Aug 19, 2024 8:34pm

[dimitropoulos]

Here's what I tested:

`--output=json`

$ t ls --output=json
turbo 2.0.14

 WARNING  ls command is experimental and may change in the future
{
  "package_manager": "pnpm",
  "packages": [
    {
      "name": "@turbo-internal/top-issues-gh-action",
      "path": "packages/top-issues"
    },
    {
      "name": "@turbo/benchmark",
      "path": "packages/turbo-benchmark"
    },
    {
      "name": "@turbo/codemod",
      "path": "packages/turbo-codemod"
    },
    {
      "name": "@turbo/eslint-config",
      "path": "packages/eslint-config"
    },
    {
      "name": "@turbo/exe-stub",
      "path": "packages/turbo-exe-stub"
    },
    {
      "name": "@turbo/gen",
      "path": "packages/turbo-gen"
    },
    {
      "name": "@turbo/telemetry",
      "path": "packages/turbo-telemetry"
    },
    {
      "name": "@turbo/test-utils",
      "path": "packages/turbo-test-utils"
    },
    {
      "name": "@turbo/tsconfig",
      "path": "packages/tsconfig"
    },
    {
      "name": "@turbo/types",
      "path": "packages/turbo-types"
    },
    {
      "name": "@turbo/utils",
      "path": "packages/turbo-utils"
    },
    {
      "name": "@turbo/workspaces",
      "path": "packages/turbo-workspaces"
    },
    {
      "name": "@turborepo-examples-tests/basic",
      "path": "turborepo-tests/example-basic"
    },
    {
      "name": "@turborepo-examples-tests/design-system",
      "path": "turborepo-tests/example-design-system"
    },
    {
      "name": "@turborepo-examples-tests/kitchen-sink",
      "path": "turborepo-tests/example-kitchen-sink"
    },
    {
      "name": "@turborepo-examples-tests/non-monorepo",
      "path": "turborepo-tests/example-non-monorepo"
    },
    {
      "name": "@turborepo-examples-tests/with-berry",
      "path": "turborepo-tests/example-with-berry"
    },
    {
      "name": "@turborepo-examples-tests/with-changesets",
      "path": "turborepo-tests/example-with-changesets"
    },
    {
      "name": "@turborepo-examples-tests/with-npm",
      "path": "turborepo-tests/example-with-npm"
    },
    {
      "name": "@turborepo-examples-tests/with-react-native-web",
      "path": "turborepo-tests/example-with-react-native-web"
    },
    {
      "name": "@turborepo-examples-tests/with-rollup",
      "path": "turborepo-tests/example-with-rollup"
    },
    {
      "name": "@turborepo-examples-tests/with-svelte",
      "path": "turborepo-tests/example-with-svelte"
    },
    {
      "name": "@turborepo-examples-tests/with-tailwind",
      "path": "turborepo-tests/example-with-tailwind"
    },
    {
      "name": "@turborepo-examples-tests/with-vite",
      "path": "turborepo-tests/example-with-vite"
    },
    {
      "name": "@turborepo-examples-tests/with-yarn",
      "path": "turborepo-tests/example-with-yarn"
    },
    {
      "name": "cargo-sweep-action",
      "path": ".github/actions/cargo-sweep"
    },
    {
      "name": "cli",
      "path": "cli"
    },
    {
      "name": "create-turbo",
      "path": "packages/create-turbo"
    },
    {
      "name": "eslint-config-turbo",
      "path": "packages/eslint-config-turbo"
    },
    {
      "name": "eslint-plugin-turbo",
      "path": "packages/eslint-plugin-turbo"
    },
    {
      "name": "prysk",
      "path": "packages/prysk"
    },
    {
      "name": "turbo-ignore",
      "path": "packages/turbo-ignore"
    },
    {
      "name": "turbo-vsc",
      "path": "packages/turbo-vsc"
    },
    {
      "name": "turborepo-examples",
      "path": "examples"
    },
    {
      "name": "turborepo-repository",
      "path": "packages/turbo-repository"
    },
    {
      "name": "turborepo-tests-helpers",
      "path": "turborepo-tests/helpers"
    },
    {
      "name": "turborepo-tests-integration",
      "path": "turborepo-tests/integration"
    }
  ]
}

`--output=pretty`

$ t ls --output=pretty
turbo 2.0.14

 WARNING  ls command is experimental and may change in the future
37 packages

  @turbo-internal/top-issues-gh-action packages/top-issues
  @turbo/benchmark packages/turbo-benchmark
  @turbo/codemod packages/turbo-codemod
  @turbo/eslint-config packages/eslint-config
  @turbo/exe-stub packages/turbo-exe-stub
  @turbo/gen packages/turbo-gen
  @turbo/telemetry packages/turbo-telemetry
  @turbo/test-utils packages/turbo-test-utils
  @turbo/tsconfig packages/tsconfig
  @turbo/types packages/turbo-types
  @turbo/utils packages/turbo-utils
  @turbo/workspaces packages/turbo-workspaces
  @turborepo-examples-tests/basic turborepo-tests/example-basic
  @turborepo-examples-tests/design-system turborepo-tests/example-design-system
  @turborepo-examples-tests/kitchen-sink turborepo-tests/example-kitchen-sink
  @turborepo-examples-tests/non-monorepo turborepo-tests/example-non-monorepo
  @turborepo-examples-tests/with-berry turborepo-tests/example-with-berry
  @turborepo-examples-tests/with-changesets turborepo-tests/example-with-changesets
  @turborepo-examples-tests/with-npm turborepo-tests/example-with-npm
  @turborepo-examples-tests/with-react-native-web turborepo-tests/example-with-react-native-web
  @turborepo-examples-tests/with-rollup turborepo-tests/example-with-rollup
  @turborepo-examples-tests/with-svelte turborepo-tests/example-with-svelte
  @turborepo-examples-tests/with-tailwind turborepo-tests/example-with-tailwind
  @turborepo-examples-tests/with-vite turborepo-tests/example-with-vite
  @turborepo-examples-tests/with-yarn turborepo-tests/example-with-yarn
  cargo-sweep-action .github/actions/cargo-sweep
  cli cli
  create-turbo packages/create-turbo
  eslint-config-turbo packages/eslint-config-turbo
  eslint-plugin-turbo packages/eslint-plugin-turbo
  prysk packages/prysk
  turbo-ignore packages/turbo-ignore
  turbo-vsc packages/turbo-vsc
  turborepo-examples examples
  turborepo-repository packages/turbo-repository
  turborepo-tests-helpers turborepo-tests/helpers
  turborepo-tests-integration turborepo-tests/integration

with no `--output` flag

$ t ls
turbo 2.0.14

 WARNING  ls command is experimental and may change in the future
37 packages

  @turbo-internal/top-issues-gh-action packages/top-issues
  @turbo/benchmark packages/turbo-benchmark
  @turbo/codemod packages/turbo-codemod
  @turbo/eslint-config packages/eslint-config
  @turbo/exe-stub packages/turbo-exe-stub
  @turbo/gen packages/turbo-gen
  @turbo/telemetry packages/turbo-telemetry
  @turbo/test-utils packages/turbo-test-utils
  @turbo/tsconfig packages/tsconfig
  @turbo/types packages/turbo-types
  @turbo/utils packages/turbo-utils
  @turbo/workspaces packages/turbo-workspaces
  @turborepo-examples-tests/basic turborepo-tests/example-basic
  @turborepo-examples-tests/design-system turborepo-tests/example-design-system
  @turborepo-examples-tests/kitchen-sink turborepo-tests/example-kitchen-sink
  @turborepo-examples-tests/non-monorepo turborepo-tests/example-non-monorepo
  @turborepo-examples-tests/with-berry turborepo-tests/example-with-berry
  @turborepo-examples-tests/with-changesets turborepo-tests/example-with-changesets
  @turborepo-examples-tests/with-npm turborepo-tests/example-with-npm
  @turborepo-examples-tests/with-react-native-web turborepo-tests/example-with-react-native-web
  @turborepo-examples-tests/with-rollup turborepo-tests/example-with-rollup
  @turborepo-examples-tests/with-svelte turborepo-tests/example-with-svelte
  @turborepo-examples-tests/with-tailwind turborepo-tests/example-with-tailwind
  @turborepo-examples-tests/with-vite turborepo-tests/example-with-vite
  @turborepo-examples-tests/with-yarn turborepo-tests/example-with-yarn
  cargo-sweep-action .github/actions/cargo-sweep
  cli cli
  create-turbo packages/create-turbo
  eslint-config-turbo packages/eslint-config-turbo
  eslint-plugin-turbo packages/eslint-plugin-turbo
  prysk packages/prysk
  turbo-ignore packages/turbo-ignore
  turbo-vsc packages/turbo-vsc
  turborepo-examples examples
  turborepo-repository packages/turbo-repository
  turborepo-tests-helpers turborepo-tests/helpers
  turborepo-tests-integration turborepo-tests/integration

`--help` contains the field

$ t ls --help
EXPERIMENTAL: List packages in your monorepo

Usage: turbo ls [OPTIONS] [PACKAGES]...

Arguments:
  [PACKAGES]...
          Get insight into a specific package, such as its dependencies and tasks

Options:
      --affected
          Show only packages that are affected by changes between the current branch and `main`

      --version
          

  -F, --filter <FILTER>
          Use the given selector to specify package(s) to act as entry points. The syntax mirrors pnpm's syntax, and additional documentation and examples can be found in turbo's documentation https://turbo.build/repo/docs/reference/command-line-reference/run#--filter

      --skip-infer
          Skip any attempts to infer which version of Turbo the project is configured to use

      --no-update-notifier
          Disable the turbo update notification

      --output <OUTPUT>
          Output format

          Possible values:
          - pretty: Output in a human-readable format
          - json:   Output in JSON format for direct parsing

      --api <API>
          Override the endpoint for API calls

      --color
          Force color usage in the terminal

      --cwd <CWD>
          The directory in which to run turbo

      --heap <HEAP>
          Specify a file to save a pprof heap profile

      --ui <UI>
          Specify whether to use the streaming UI or TUI

          Possible values:
          - tui:    Use the terminal user interface
          - stream: Use the standard output stream

      --login <LOGIN>
          Override the login endpoint

      --no-color
          Suppress color usage in the terminal

      --preflight
          When enabled, turbo will precede HTTP requests with an OPTIONS request for authorization

      --remote-cache-timeout <TIMEOUT>
          Set a timeout for all HTTP requests

      --team <TEAM>
          Set the team slug for API calls

      --token <TOKEN>
          Set the auth token for API calls

      --trace <TRACE>
          Specify a file to save a pprof trace

      --verbosity <COUNT>
          Verbosity level

      --dangerously-disable-package-manager-check
          Allow for missing `packageManager` in `package.json`.
          
          `turbo` will use hints from codebase to guess which package manager should be used.

  -h, --help
          Print help (see a summary with '-h')

`--output=asdf` returns a useful error

$ t ls --output=asdf
 ERROR  invalid value 'asdf' for '--output <OUTPUT>'
  [possible values: pretty, json]

For more information, try '--help'.

all looks great!

All changes addressed

[chris-olszewski]

This doesn't produce valid JSON for a consumer if there is more than one package provided as it'll produce one object per package

[tknickman]

Ah good call - I didn't realize we supported that - will fix.

[chris-olszewski]

I would recommend against pushing an error into the JSON and instead throw the error. As of #8969 we now print errors to stderr so the error wouldn't get piped to jq.

Putting the error into JSON leads to a confusing jq error:

$ echo '{"error": "bad JSON"}' | jq '.packages | map(.path)'
jq: error (at <stdin>:1): Cannot iterate over null (null)

[NicholasLYang]

yeah that makes sense. Previously you'd get a panic error, but with stderr printing I guess that's avoided