From 4c6dfa78b397a462807269c86acb8073c53d63c8 Mon Sep 17 00:00:00 2001 From: rochala Date: Tue, 24 Mar 2026 10:30:56 +0100 Subject: [PATCH 1/2] Improove docs --- README.md | 215 ++++++++++++++++++++++++++++++++++++++++++++---------- SKILL.md | 76 +++++++++++++++++++ 2 files changed, 252 insertions(+), 39 deletions(-) create mode 100644 SKILL.md diff --git a/README.md b/README.md index a219aa2..1a1578f 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@

Cellar

- Look up the public API of any Maven-published JVM dependency from the terminal. + Look up the public API of any JVM dependency from the terminal.

--- @@ -18,58 +18,94 @@ Cellar gives agents — and humans — a single shell command that returns exact | Format | Support | |---|---| -| Scala 3 (TASTy) | Full — signatures, flags, companions, sealed hierarchies, givens, extensions, docstrings, source | +| Scala 3 (TASTy) | Full — signatures, flags, companions, sealed hierarchies, givens, extensions, docstrings | | Scala 2 (pickles) | Best-effort — type information may be incomplete | -| Java (.class) | Good — signatures, members, source | +| Java (.class) | Good — signatures, members | -## Usage +## Installation -### `cellar get ` +Download the native binary for your platform from the [latest release](https://github.com/simple-scala-tooling/cellar/releases): -Look up a single symbol — type signature, flags, members, companion, known subtypes, docstring. +| Platform | Archive | +|---|---| +| Linux x86_64 | `cellar--linux-x86_64.tar.gz` | +| Linux aarch64 | `cellar--linux-aarch64.tar.gz` | +| macOS arm64 | `cellar--macos-arm64.tar.gz` | -``` -cellar get org.typelevel:cats-core_3:2.10.0 cats.Monad -cellar get org.apache.commons:commons-lang3:3.14.0 org.apache.commons.lang3.StringUtils +```sh +# Example: Linux x86_64 +curl -fSL https://github.com/simple-scala-tooling/cellar/releases/latest/download/cellar-0.1.0-M1-linux-x86_64.tar.gz | tar xz +sudo mv cellar /usr/local/bin/ ``` -### `cellar get-source ` +To verify checksums and signatures, see [RELEASING.md](RELEASING.md). -Fetch the source code from the published `-sources.jar`. +## Quick start -``` -cellar get-source org.typelevel:cats-core_3:2.10.0 cats.Monad -``` +```sh +# Look up a trait from cats +cellar get-external org.typelevel:cats-core_3:2.10.0 cats.Monad -### `cellar list ` +# List top-level symbols in a package +cellar list-external org.typelevel:cats-core_3:2.10.0 cats -List all public symbols in a package or class. Supports `--limit N` (default: 50). +# Search for a method name +cellar search-external org.typelevel:cats-core_3:2.10.0 flatMap -``` -cellar list org.typelevel:cats-core_3:2.10.0 cats -cellar list org.typelevel:cats-core_3:2.10.0 cats.Monad +# View source code +cellar get-source org.typelevel:cats-core_3:2.10.0 cats.Monad + +# Dependency tree +cellar deps org.typelevel:cats-effect_3:3.5.4 ``` -### `cellar search ` +## Commands -Case-insensitive substring search across all symbol names. Supports `--limit N` (default: 50). +Cellar has two modes: **project-aware** commands that work against your current project's classpath, and **external** commands that query arbitrary Maven coordinates. -``` -cellar search org.typelevel:cats-core_3:2.10.0 flatMap -cellar search io.circe:circe-core_3:0.14.6 decode +### Project-aware commands + +Run from your project root. Cellar auto-detects the build tool (Mill, sbt, or scala-cli), extracts the classpath, and queries your project's code and all its dependencies. + +```sh +cellar get [--module ] +cellar list [--module ] +cellar search [--module ] ``` -### `cellar deps ` +- **Mill / sbt**: `--module` is required (e.g. `--module lib`, `--module core`) +- **scala-cli**: `--module` is not supported — omit it -Print the full transitive dependency tree. +The classpath is cached after the first run. Use `--no-cache` to force re-extraction. +### External commands + +Query any published Maven artifact by explicit coordinate: + +```sh +cellar get-external +cellar list-external +cellar search-external +cellar get-source +cellar deps ``` -cellar deps org.typelevel:cats-effect_3:3.5.4 -``` -### Coordinates +### Command reference + +| Command | Description | +|---|---| +| `get` | Symbol info from the current project (signature, flags, members, docs) | +| `get-external` | Symbol info from a Maven coordinate | +| `get-source` | Source code from a published `-sources.jar` | +| `list` | List public symbols in a package/class from the current project | +| `list-external` | List public symbols from a Maven coordinate | +| `search` | Case-insensitive substring search in the current project | +| `search-external` | Case-insensitive substring search from a Maven coordinate | +| `deps` | Print the transitive dependency tree | + +### Maven coordinates -Maven coordinates must be explicit — `group:artifact:version`. The `::` shorthand is not supported. +Coordinates use the format `group:artifact:version`. The `::` shorthand is **not** supported — use the full artifact name. ``` org.typelevel:cats-core_3:2.10.0 # Scala 3 @@ -77,13 +113,21 @@ org.typelevel:cats-core_2.13:2.10.0 # Scala 2 org.apache.commons:commons-lang3:3.14.0 # Java ``` +Use `latest` as the version to automatically resolve the most recent release: + +```sh +cellar get-external org.typelevel:cats-core_3:latest cats.Monad +``` + ### Options -| Flag | Description | -|---|---| -| `--java-home ` | Use a specific JDK for JRE classpath | -| `-r`, `--repository ` | Extra Maven repository URL (repeatable) | -| `-l`, `--limit ` | Max results (`list` and `search` only) | +| Flag | Applies to | Description | +|---|---|---| +| `--module `, `-m` | project commands | Build module name (required for Mill/sbt) | +| `--no-cache` | project commands | Skip classpath cache, re-extract from build tool | +| `--java-home ` | all | Use a specific JDK for JRE classpath | +| `-r`, `--repository ` | external commands | Extra Maven repository URL (repeatable) | +| `-l`, `--limit ` | `list`, `search` | Max results (default: 50) | ## Output conventions @@ -92,20 +136,109 @@ org.apache.commons:commons-lang3:3.14.0 # Java - **Exit 0** — success - **Exit 1** — error -## Building +## Example output + +
+cellar get-external org.typelevel:cats-core_3:2.10.0 cats.Monad + + ## cats.Monad + ```scala + trait Monad[F] extends FlatMap[F] with Applicative[F] + ``` + Monad. + Allows composition of dependent effectful functions. + + **Flags:** abstract + **Origin:** cats.Monad + **Members:** + ```scala + def flatMap[A, B](fa: F[A])(f: Function1[A, F[B]]): F[B] + def pure[A](x: A): F[A] + def flatten[A](ffa: F[F[A]]): F[A] + def iterateWhile[A](f: F[A])(p: Function1[A, Boolean]): F[A] + ... + ``` + +
+ +
+cellar list-external org.typelevel:cats-core_3:2.10.0 cats --limit 5 + + object Eval$ + trait ComposedContravariantCovariant[F, G] extends Contravariant[TypeLambda] + object Later$ + object Show$ + trait EvalSemigroup[A] extends Semigroup[Eval[A]] + Note: results truncated at 5. Use --limit to increase. + +
+ +
+cellar search-external org.typelevel:cats-core_3:2.10.0 flatMap --limit 3 + + cats.FlatMap — object FlatMap$ + cats.FlatMap — trait FlatMap[F] extends Apply[F] with FlatMapArityFunctions[F] + cats.FlatMap$ — object FlatMap$ + Note: results truncated at 3. Use --limit to increase. + +
+ +## Using cellar with Claude Code + +Add the following to your project's `CLAUDE.md` to teach Claude Code how to use cellar: + +````markdown +## Cellar + +When you need the API of a JVM dependency, use cellar. Always prefer cellar over hallucinating API signatures. + +### Project-aware commands (run from project root) + +For querying the current project's code and dependencies (auto-detects build tool): + + cellar get [--module ] # single symbol + cellar list [--module ] # explore a package + cellar search [--module ] # find by name + +- Mill/sbt projects: `--module` is required (e.g. `--module lib`, `--module core`) +- scala-cli projects: `--module` is not supported (omit it) +- `--no-cache`: skip classpath cache, re-extract from build tool +- `--java-home`: override JRE classpath + +### External commands (query arbitrary Maven coordinates) + +For querying any published artifact by explicit coordinate: + + cellar get-external # single symbol + cellar list-external # explore a package + cellar search-external # find by name + cellar get-source # source code + cellar deps # dependency tree + +Coordinates must be explicit: `group:artifact_3:version` (use `latest` for newest version). + +### Workflow + +1. **Don't know the package?** → `cellar search ` or `cellar search-external ` +2. **Know the package, not the type?** → `cellar list ` or `cellar list-external ` +3. **Know the type?** → `cellar get ` or `cellar get-external ` +4. **Need the source?** → `cellar get-source ` +```` + +## Building from source Requires JDK 17+ and [Mill](https://mill-build.org/). ```sh # Fat JAR ./mill cli.assembly -java -jar out/cli/assembly.dest/out.jar get org.typelevel:cats-core_3:2.10.0 cats.Monad +java -jar out/cli/assembly.dest/out.jar get-external org.typelevel:cats-core_3:2.10.0 cats.Monad # Native image (GraalVM) ./mill cli.nativeImage -# Wrapper script -./scripts/cellar get org.typelevel:cats-core_3:2.10.0 cats.Monad +# Wrapper script (for development) +./scripts/cellar get-external org.typelevel:cats-core_3:2.10.0 cats.Monad ``` ### Running tests @@ -121,3 +254,7 @@ java -jar out/cli/assembly.dest/out.jar get org.typelevel:cats-core_3:2.10.0 cat ## Tech stack Scala 3, Cats Effect, fs2, [tasty-query](https://github.com/scalacenter/tasty-query), [Coursier](https://get-coursier.io/), [decline](https://ben.kirw.in/decline/), Mill. + +## License + +[MPL-2.0](LICENSE) diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..0b3d29e --- /dev/null +++ b/SKILL.md @@ -0,0 +1,76 @@ +--- +name: cellar +description: Look up the public API of any JVM dependency (Scala 3, Scala 2, Java) from the terminal. Returns type signatures, members, docstrings, and source code as Markdown. +--- + +# Cellar + +Use cellar to look up the API of JVM dependencies instead of guessing or hallucinating signatures. + +## Project-aware commands (run from project root) + +Query the current project's code and all its dependencies. Cellar auto-detects the build tool (Mill, sbt, scala-cli). + + cellar get [--module ] # single symbol (signature, members, docs) + cellar list [--module ] # list symbols in a package or class + cellar search [--module ] # case-insensitive substring search + +- Mill/sbt projects: `--module` is required (e.g. `--module lib`, `--module core`) +- scala-cli projects: omit `--module` +- `--no-cache`: skip classpath cache, re-extract from build tool +- `--java-home `: override JRE classpath +- `-l`, `--limit `: max results for `list`/`search` (default: 50) + +## External commands (query arbitrary Maven coordinates) + +Query any published artifact by explicit coordinate (`group:artifact:version`): + + cellar get-external # single symbol + cellar list-external # list symbols + cellar search-external # search by name + cellar get-source # fetch source code + cellar deps # dependency tree + +- Coordinates must be explicit: `group:artifact_3:version` (no `::` shorthand) +- Use `latest` as the version to resolve the most recent release +- `-r`, `--repository `: extra Maven repository (repeatable) + +## Workflow + +1. **Don't know the package?** → `cellar search` / `cellar search-external` +2. **Know the package, not the type?** → `cellar list` / `cellar list-external` +3. **Know the type?** → `cellar get` / `cellar get-external` +4. **Need the implementation?** → `cellar get-source` + +## Examples + +```sh +# Look up a Scala 3 trait +cellar get-external org.typelevel:cats-core_3:2.10.0 cats.Monad + +# Look up a Java class +cellar get-external org.apache.commons:commons-lang3:3.14.0 org.apache.commons.lang3.StringUtils + +# List a package +cellar list-external io.circe:circe-core_3:0.14.6 io.circe + +# Search for a method +cellar search-external org.typelevel:cats-core_3:2.10.0 flatMap + +# Get source code +cellar get-source org.typelevel:cats-core_3:2.10.0 cats.Monad + +# Dependency tree +cellar deps org.typelevel:cats-effect_3:3.5.4 + +# Project-aware (from a Mill project root) +cellar get --module lib cats.Monad +cellar list --module core cats +cellar search --module lib flatMap +``` + +## Output + +- **stdout**: Markdown — ready to consume directly +- **stderr**: diagnostics (warnings, truncation notices) +- **Exit 0**: success, **Exit 1**: error From 665f659bbba29b529f20981c803d4f30a4c75cfe Mon Sep 17 00:00:00 2001 From: rochala Date: Tue, 24 Mar 2026 11:16:35 +0100 Subject: [PATCH 2/2] Improve download --- README.md | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 1a1578f..1fb3b73 100644 --- a/README.md +++ b/README.md @@ -24,17 +24,10 @@ Cellar gives agents — and humans — a single shell command that returns exact ## Installation -Download the native binary for your platform from the [latest release](https://github.com/simple-scala-tooling/cellar/releases): - -| Platform | Archive | -|---|---| -| Linux x86_64 | `cellar--linux-x86_64.tar.gz` | -| Linux aarch64 | `cellar--linux-aarch64.tar.gz` | -| macOS arm64 | `cellar--macos-arm64.tar.gz` | +Download the native binary for your platform from https://github.com/simple-scala-tooling/cellar/releases/latest, then extract and install: ```sh -# Example: Linux x86_64 -curl -fSL https://github.com/simple-scala-tooling/cellar/releases/latest/download/cellar-0.1.0-M1-linux-x86_64.tar.gz | tar xz +tar xz -f cellar-*.tar.gz sudo mv cellar /usr/local/bin/ ```