@r0cksolid/emerald-cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 R0ck Solid Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# @r0cksolid/emerald-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `emerald` command answers how to get a Hypixel SkyBlock item from a terminal: it finds items, lists every way to get one, and plans the steps, materials and totals to make it. It reads the item snapshot that ships with `@r0cksolid/emerald-core` and needs no network access.
+
+## Install
+
+```sh
+npm install --global @r0cksolid/emerald-cli
+emerald --help
+```
+
+The package installs one command, `emerald`, and depends on `@r0cksolid/emerald-core` at the same version for its snapshot.
+
+## Commands
+
+```sh
+emerald search refined diamond
+emerald ways REFINED_DIAMOND
+emerald plan REFINED_DIAMOND --count 2
+emerald config levels number
+```
+
+- `emerald search <query>...` finds items by name or id, typos included, and prints each row's id, shown name and category. A pet, minion or enchanted book family prints one line per member, and a variant word such as `leg` in `emerald search leg bee` marks the member it names with `>`. `--limit <n>` (default 25) and `--offset <n>` (default 0) page through the rows.
+- `emerald ways <item-id>` prints every way to get an item, grouped as Obtain (activities, buying, opening containers) and Make (crafting, forging, Kat, shard fusion, the Enchantment Table), each with its costs, notes and tags, such as `[upgrade]` or the event that gates it.
+- `emerald plan <item-id>` prints the steps that make an item, inputs first, then the materials those steps stop at, each with its ways, then the total coins, currencies and station time. `--count <n>` (default 1) plans for that many.
+- `emerald config levels [roman|number]` prints or saves how runes, enchanted books and minions write their level: `Acacia Minion XII` or `Acacia Minion 12`.
+
+Every id the commands print can be passed straight to `emerald ways` or `emerald plan`. `emerald <command> --help` lists a command's options. Each command except `config` also takes `--snapshot <dir>`, which loads another snapshot directory instead of the packaged one, and `--levels <roman|number>`, which overrides the saved level style for one run.
+
+`emerald plan REFINED_DIAMOND --count 2` prints:
+
+```text
+2 × REFINED_DIAMOND  Refined Diamond
+
+Steps
+  1. 640 × ENCHANTED_DIAMOND · Crafting, 640 runs
+     102,400 × DIAMOND
+     Requires: Diamond IV
+  2. 4 × ENCHANTED_DIAMOND_BLOCK · Crafting, 4 runs
+     640 × ENCHANTED_DIAMOND
+     Requires: Diamond VIII
+  3. 2 × REFINED_DIAMOND · Forging, 2 runs
+     4 × ENCHANTED_DIAMOND_BLOCK · 16h
+     Requires: HotM 2
+
+Materials
+  102,400 × DIAMOND
+    Activities › Gathering
+      Mining collection
+    Make › Crafting
+      1 × DIAMOND_BLOCK · makes 9
+
+Totals, at base values
+  Station time: 16h
+```
+
+Bare `emerald` in a terminal opens an interactive mode: type an item's name and it opens as a checklist of its plan, which you tick off as you go. A mob opens a page of its drops, and an NPC a page of what it sells. Without a terminal on both stdin and stdout, bare `emerald` prints usage and exits 2.
+
+## Scripts and agents
+
+The commands never prompt, and apart from colour their output does not change when a terminal is attached.
+
+- stdout carries only the result, or the help that `--help` asks for. Usage errors and other errors go to stderr, one line per error.
+- `--json` prints one JSON document, exactly the answer of the `@r0cksolid/emerald-core` query behind the command: `ItemCatalog.search`, `itemWays` or `itemPlan`.
+- Text is coloured when stdout is a terminal that supports colour. `NO_COLOR` turns colour off. `FORCE_COLOR` forces it on, even when stdout is piped, and takes precedence over `NO_COLOR`. `--json` is never coloured.
+- The exit code is 0 on success, 1 when the request can't be answered, such as an unknown id or an unreadable snapshot, and 2 on a usage error. A search that matches nothing prints nothing and exits 0.
+- Output follows the saved level style, so pass `--levels` to pin a script's output.
+
+## Settings
+
+`emerald config` saves its settings in `emerald/settings.json` under `$XDG_CONFIG_HOME` when that is an absolute path, otherwise under `%APPDATA%` on Windows, otherwise under `~/.config`. `emerald config --help` prints the path. A missing file means the defaults.
+
+## Requirements
+
+Node 26 or later (`"engines": { "node": ">=26" }`).
+
+## Licence
+
+The code is MIT, copyright R0ck Solid Software (`LICENSE`). The command bundles its JavaScript dependencies, whose licences are in `dist/THIRD-PARTY-NOTICES.txt`. The item data comes from `@r0cksolid/emerald-core`'s snapshot, which stays under its sources' terms; that package's README credits each source.
+
+This package is not affiliated with or endorsed by Hypixel or Mojang. It is not an official Minecraft product.

package/dist/THIRD-PARTY-NOTICES.txt

@@ -0,0 +1,141 @@
+@earendil-works/pi-tui@1.5.0 (MIT)
+
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+------------------------------------------------------------------------
+
+get-east-asian-width@1.6.0 (MIT)
+
+MIT License
+
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+------------------------------------------------------------------------
+
+marked-cjk-friendly@0.1.2 (MIT)
+
+Copyright (c) 2024 Tatsunori Uchino, and authors and contributors of original packages
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+------------------------------------------------------------------------
+
+marked@18.0.11 (MIT)
+
+# License information
+
+## Contribution License Agreement
+
+If you contribute code to this project, you are implicitly allowing your code
+to be distributed under the MIT license. You are also implicitly verifying that
+all code is your original work. `</legalese>`
+
+## Marked
+
+Copyright (c) 2018+, MarkedJS (https://github.com/markedjs/)
+Copyright (c) 2011-2018, Christopher Jeffrey (https://github.com/chjj/)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+## Markdown
+
+Copyright © 2004, John Gruber
+http://daringfireball.net/
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+* Neither the name “Markdown” nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+This software is provided by the copyright holders and contributors “as is” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.
+
+------------------------------------------------------------------------
+
+typebox@1.4.3 (MIT)
+
+TypeBox
+
+The MIT License (MIT)
+
+Copyright (c) 2017-2026 Haydn Paterson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.