@rbxts/centurion-ui 1.0.8 → 2.0.0-rc.1

package/README.md

@@ -1,29 +1,74 @@
 <div align="center">
   <a href="https://centurion.paradoxum.dev/" target="_blank">
-    <img src="https://raw.githubusercontent.com/paradoxuum/centurion/main/docs/src/assets/logo.webp" width="150" />
+    <img src="https://raw.githubusercontent.com/paradoxuum/centurion/main/docs/public/logo.svg" width="150" />
   </a>
 
-  <h1>Centurion - UI</h1>
+  <h1>Centurion</h1>
 
-  <p>
-    <strong>A flexible and extensible command framework for roblox-ts</strong>
-  </p>
-
-  This package contains Centurion's user interface. To use it, you must
-  also install [@rbxts/centurion](https://www.npmjs.com/package/@rbxts/centurion).
+  <p><strong>A flexible and extensible command framework for Roblox</strong></p>
 
   [![CI status][ci-badge]][ci-url]
   [![npm latest version][npm-latest-badge]][npm-latest-url]
-  [![npm dev version][npm-next-badge]][npm-next-url]
+  [![MIT License][license-badge]][license-url]
 
-  [npm-latest-badge]: https://img.shields.io/npm/v/%40rbxts%2Fcenturion?logo=npm&label=latest&color=green
+  [npm-latest-badge]: https://img.shields.io/npm/v/@rbxts/centurion.svg?style=for-the-badge&logo=npm
   [npm-latest-url]: https://www.npmjs.com/package/@rbxts/centurion/v/latest
-  [npm-next-badge]: https://img.shields.io/npm/v/%40rbxts%2Fcenturion%2Fnext?logo=npm&label=next
-  [npm-next-url]: https://www.npmjs.com/package/@rbxts/centurion/v/next
-  [ci-badge]: https://github.com/paradoxuum/centurion/actions/workflows/ci.yml/badge.svg?branch=main
+  [ci-badge]: https://img.shields.io/github/actions/workflow/status/paradoxuum/centurion/ci.yml?style=for-the-badge&branch=main&logo=github
   [ci-url]: https://github.com/paradoxuum/centurion/actions/workflows/ci.yml
+  [license-badge]: https://img.shields.io/github/license/paradoxuum/centurion?style=for-the-badge
+  [license-url]: https://github.com/paradoxuum/centurion/blob/main/LICENSE.md
+
+  <img src="https://raw.githubusercontent.com/paradoxuum/centurion/main/docs/public/example.webp" alt="Example" style="border-radius: 4px;" />
 
-  <a href="https://centurion.paradoxum.dev/">📖 Documentation</a>
+  [📖 **Documentation →**](https://centurion.paradoxum.dev/)
 </div>
 
-<img src="https://raw.githubusercontent.com/paradoxuum/centurion/main/public/banner.png" />
+## ✨ Features
+
+- 🌙 **Luau and roblox-ts.** Written in Luau with full TypeScript typings, and available on both Wally and npm.
+
+- ✏️ **Simple to define.** Register commands with a plain table, or use decorators and classes in roblox-ts.
+
+- 🧩 **Typed arguments.** Built-in types for players, teams, numbers, colors, durations, vectors and more, with optional, multi-value and rest arguments. Register your own types with custom suggestions.
+
+- 🔐 **Guards and permissions.** Guard commands with reusable checks, and control access with prioritised, inheritable roles.
+
+- 🔄 **Client-server sync.** Players only receive the commands they're allowed to run, and stay up to date as commands or roles change.
+
+- 💻 **Optional terminal UI.** A clean console with suggestions, fuzzy matching, tab completion, syntax highlighting and history. Use it as-is, theme it, or build your own.
+
+## 📦 Installation
+
+```toml
+# wally.toml
+[dependencies]
+centurion = "paradoxuum/centurion@2.0.0"
+centurion-ui = "paradoxuum/centurion-ui@2.0.0"
+```
+
+```bash
+# roblox-ts
+npm install @rbxts/centurion @rbxts/centurion-ui
+```
+
+See the [documentation](https://centurion.paradoxum.dev/) to get started.
+
+## 💖 Attributions
+
+- [🍀 Charm](https://github.com/littensy/charm): Inspiration for command syncing
+
+- [💻 Conch](https://github.com/alicesaidhi/conch): UI utility components and text box state handling
+
+- [🌿 Vide](https://github.com/centau/vide): Reactive UI library powering the terminal UI
+
+---
+
+<p align="center">
+This project is released under the <a href="https://github.com/paradoxuum/centurion/blob/main/LICENSE.md">MIT License</a>.
+</p>
+
+<div align="center">
+
+[![MIT License](https://img.shields.io/github/license/paradoxuum/centurion?style=for-the-badge)](https://github.com/paradoxuum/centurion/blob/main/LICENSE.md)
+
+</div>

package/centurion.luau

@@ -0,0 +1,10 @@
+local centurion = require(script.Parent.Parent.centurion.src)
+
+export type Argument = centurion.Argument
+export type ArgumentRange = centurion.ArgumentRange
+export type Command<T...> = centurion.Command<T...>
+export type Response = centurion.Response
+export type Result<T = unknown> = centurion.Result<T>
+export type Token = centurion.Token
+
+return centurion

package/package.json

@@ -1,14 +1,20 @@
 {
   "name": "@rbxts/centurion-ui",
   "description": "Terminal UI for the Centurion command framework",
-  "version": "1.0.8",
+  "version": "2.0.0-rc.1",
   "author": "paradoxuum",
   "license": "MIT",
-  "main": "out/init.lua",
-  "types": "out/index.d.ts",
+  "main": "src/ts/init.luau",
+  "types": "src/ts/index.d.ts",
   "files": [
-    "out",
-    "!**/*.tsbuildinfo",
+    "src",
+    "vide/src",
+    "vide/init.luau",
+    "*.luau",
+    "!src/stories",
+    "!wally.toml",
+    "!wally.lock",
+    "!default.project.json",
     "!**/__tests__"
   ],
   "keywords": [
@@ -26,24 +32,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "devDependencies": {
-    "@rbxts/compiler-types": "3.0.0-types.0",
-    "@rbxts/types": "^1.0.813",
-    "roblox-ts": "3.0.0",
-    "shx": "^0.3.4",
-    "typescript": "5.5.3",
-    "@rbxts/centurion": "^1.0.1"
-  },
   "dependencies": {
-    "@rbxts/services": "^1.5.5",
-    "@rbxts/set-timeout": "^1.1.2",
-    "@rbxts/vide": "^0.5.3"
-  },
-  "peerDependencies": {
-    "@rbxts/centurion": "^1.0.1"
+    "@rbxts/centurion": "^2.0.0-rc.1"
   },
-  "scripts": {
-    "build": "shx rm -rf out && rbxtsc --verbose",
-    "dev": "shx rm -rf out && rbxtsc -w"
-  }
+  "scripts": {}
 }

package/src/analyse/cursor.luau

@@ -0,0 +1,25 @@
+--!strict
+
+type Token = {
+	read span: vector,
+}
+
+-- finds the token the cursor is on
+local function locate(tokens: { read [number]: Token }, cursor_pos: number): (number, boolean)
+	local before = 0
+	for i, token in tokens do
+		if cursor_pos >= token.span.x and cursor_pos <= token.span.y + 1 then
+			return i, false
+		end
+
+		if token.span.y + 1 < cursor_pos then
+			before = i
+		end
+	end
+
+	return before + 1, true
+end
+
+return {
+	locate = locate,
+}

package/src/analyse/highlight.luau

@@ -0,0 +1,91 @@
+--!strict
+local Players = game:GetService("Players")
+
+local centurion = require("../../centurion")
+local rich = require("../rich")
+local types = require("../types")
+
+type Kind = "command" | "argument" | "string" | "invalid"
+
+local function is_valid(raw: string, arg: centurion.Argument): boolean
+	local ok, result = pcall(centurion.transform_arg, Players.LocalPlayer, arg, raw)
+	return ok and result.success
+end
+
+local function classify(text: string): { { span: vector, kind: Kind } }
+	local resolution = centurion.resolve_command(text)
+	local tokens = resolution.tokens
+	local cmds = centurion.registry.commands
+
+	local highlights = {}
+	local function add(token: centurion.Token, kind: Kind)
+		table.insert(highlights, { span = token.span, kind = kind })
+	end
+
+	local cmd_name = resolution.name
+	local cmd_index = resolution.name_end
+
+	if not cmd_name then
+		for _, token in tokens do
+			add(token, "invalid")
+		end
+		return highlights
+	end
+
+	for i = 1, cmd_index do
+		add(tokens[i], "command")
+	end
+
+	local cmd = cmds[cmd_name]
+	local args: { centurion.Argument } = if cmd.arguments then { cmd.arguments() } :: { centurion.Argument } else {}
+
+	local ranges, next_index = centurion.assign_args(args, #tokens - cmd_index)
+	for i, arg in args do
+		for j = ranges[i].first, ranges[i].last do
+			local token = tokens[cmd_index + j]
+			local raw = text:sub(token.span.x, token.span.y)
+
+			if not is_valid(raw, arg) then
+				add(token, "invalid")
+			elseif raw:match("^[\"']") then
+				add(token, "string")
+			else
+				add(token, "argument")
+			end
+		end
+	end
+
+	-- input past the last argument is rejected, including by commands that
+	-- take no arguments at all
+	for j = cmd_index + next_index, #tokens do
+		add(tokens[j], "invalid")
+	end
+
+	if resolution.unclosed_quote and #highlights > 0 then
+		highlights[#highlights].kind = "invalid"
+	end
+
+	return highlights
+end
+
+local function highlight(text: string, theme: types.Theme): string
+	local colors: { [Kind]: Color3 } = {
+		command = theme.highlight,
+		argument = theme.text,
+		string = theme.success,
+		invalid = theme.error,
+	}
+
+	local out = {}
+	local pos = 1
+	for _, item in classify(text) do
+		table.insert(out, rich.escape(text:sub(pos, item.span.x - 1)))
+		table.insert(out, rich.color(rich.escape(text:sub(item.span.x, item.span.y)), colors[item.kind]))
+		pos = item.span.y + 1
+	end
+	table.insert(out, rich.escape(text:sub(pos)))
+
+	return table.concat(out)
+end
+
+return highlight

package/src/analyse/init.luau

@@ -0,0 +1,318 @@
+--!strict
+local Players = game:GetService("Players")
+
+local centurion = require("../centurion")
+local cursor = require("@self/cursor")
+local match = require("@self/match")
+local suggest = require("@self/suggest")
+local types = require("./types")
+
+local function analyse(text: string, cursor_pos: number, max_suggestions: number?): types.AnalysisResult
+	local resolution = centurion.resolve_command(text)
+	local tokens = resolution.tokens
+
+	if #tokens == 0 then
+		return {
+			result = {
+				success = true,
+				value = nil :: any,
+			},
+			suggestions = {},
+		}
+	end
+
+	local cmds = centurion.registry.commands
+
+	local cmd_name: string? = resolution.name
+	local cmd_index: number? = cmd_name and resolution.name_end or nil
+
+	local arg_tokens: { centurion.Token } = cmd_index and { select(2, unpack(tokens, cmd_index)) } or {}
+
+	local at_arg = false
+	if cmd_index and cursor_pos - 1 > tokens[cmd_index].span.y then
+		at_arg = true
+	end
+
+	local slot, inserting = cursor.locate(arg_tokens, cursor_pos)
+
+	local function process_arg(): types.AnalysisResult?
+		if not cmd_name then
+			return nil
+		end
+
+		if not cmd_index then
+			return nil
+		end
+
+		local cmd = cmds[cmd_name]
+		if not cmd then
+			return nil
+		end
+
+		local cmd_args: { centurion.Argument } = if cmd.arguments
+			then { cmd.arguments() } :: { centurion.Argument }
+			else {}
+		local arg_text = resolution.args
+
+		-- commands taking no arguments have nothing to suggest, but still
+		-- reject extra input
+		if #cmd_args == 0 then
+			if #arg_tokens == 0 then
+				return nil
+			end
+
+			return {
+				result = centurion.transform_args(Players.LocalPlayer, arg_text, cmd_args),
+				suggestions = {},
+			}
+		end
+
+		local transform_result = centurion.transform_args(Players.LocalPlayer, arg_text, cmd_args)
+
+		if not at_arg then
+			return {
+				result = transform_result,
+				suggestions = {},
+			}
+		end
+
+		-- assign tokens to arguments the same way execution does, counting the
+		-- token about to be typed if the cursor isn't on an existing one
+		local count = if inserting then #arg_tokens + 1 else #arg_tokens
+		local ranges = centurion.assign_args(cmd_args, count)
+
+		local arg_index: number? = nil
+		for i, range in ranges do
+			if slot >= range.first and slot <= range.last then
+				arg_index = i
+				break
+			end
+		end
+
+		-- past the last argument, which execution rejects
+		if not arg_index then
+			return {
+				result = transform_result,
+				suggestions = {},
+			}
+		end
+
+		local arg = cmd_args[arg_index]
+		local arg_type = centurion.registry.types[arg.type]
+		assert(arg_type, "Unknown argument type: " .. tostring(arg.type))
+
+		local input_token: centurion.Token
+		if inserting then
+			-- an empty span at the cursor, so a suggestion is inserted there
+			input_token = {
+				span = vector.create(cursor_pos, cursor_pos - 1, 0),
+				text = "",
+				quoted = false,
+			}
+		else
+			input_token = arg_tokens[slot]
+		end
+
+		if arg_type.kind == "list" then
+			local parsed_token = centurion.parse_text(text:sub(input_token.span.x, input_token.span.y), ",")
+
+			local at_list_token = false
+			for _, t in parsed_token.tokens do
+				if t.span.y + input_token.span.x - 1 >= cursor_pos - 1 then
+					at_list_token = true
+					input_token = {
+						span = vector.create(t.span.x + input_token.span.x - 1, t.span.y + input_token.span.x - 1, 0),
+						text = t.text,
+						quoted = t.quoted,
+					}
+					break
+				end
+			end
+
+			if not at_list_token and #parsed_token.tokens > 0 then
+				local last_token = parsed_token.tokens[#parsed_token.tokens]
+				input_token = {
+					span = vector.create(
+						last_token.span.y + input_token.span.x + 1,
+						last_token.span.y + input_token.span.x + 1,
+						0
+					),
+					text = "",
+					quoted = false,
+				}
+			end
+		end
+
+		local arg_suggestions: { string } = {}
+		if arg_type.suggestions then
+			arg_suggestions = table.clone(arg_type.suggestions(input_token.text, Players.LocalPlayer))
+		end
+
+		if arg.suggestions then
+			for _, suggestion in arg.suggestions do
+				table.insert(arg_suggestions, suggestion)
+			end
+		end
+
+		-- check for duplicates
+		local seen = {}
+		for i = #arg_suggestions, 1, -1 do
+			local suggestion = arg_suggestions[i]
+			if seen[suggestion] then
+				table.remove(arg_suggestions, i)
+			else
+				seen[suggestion] = true
+			end
+		end
+
+		local suggestions = {}
+		if #arg_suggestions > 0 then
+			local matches = suggest(input_token.text, arg_suggestions, max_suggestions)
+
+			for _, suggestion_text in matches do
+				local replacement = ""
+				local replacement_text = {}
+				for _, replacement_token in centurion.parse_text(suggestion_text, " ").tokens do
+					table.insert(replacement_text, replacement_token.text)
+				end
+
+				if #replacement_text == 1 then
+					replacement = replacement_text[1]
+				else
+					replacement = '"' .. table.concat(replacement_text, " ") .. '"'
+				end
+
+				local suggestion = {
+					kind = "argument",
+					name = suggestion_text,
+					matches = match(input_token.text, suggestion_text),
+
+					span = input_token.span,
+					replace = replacement,
+				} :: types.AnalysisSuggestion
+				table.insert(suggestions, suggestion)
+			end
+		end
+
+		return {
+			result = transform_result,
+			argument = {
+				index = arg_index,
+				type = arg.type,
+				kind = arg_type.kind,
+			},
+			suggestions = suggestions,
+		} :: types.AnalysisResult
+	end
+
+	local function process_command(): types.AnalysisResult
+		local to_match = {}
+		for k, _ in cmds do
+			if k == cmd_name then
+				continue
+			end
+			table.insert(to_match, k)
+		end
+
+		local token_text = {}
+		for _, token in tokens do
+			table.insert(token_text, token.text)
+		end
+
+		local query = table.concat(token_text, " ")
+		local matches = suggest(query, to_match, max_suggestions)
+		if cmd_name then
+			table.insert(matches, 1, cmd_name)
+		end
+
+		local result: centurion.Result<unknown>
+		if cmd_name then
+			result = {
+				success = true,
+				value = nil :: any,
+			}
+		else
+			result = {
+				success = false :: false,
+				error = "Unknown command",
+			}
+		end
+
+		local suggestions = {}
+		for _, cmd_match in matches do
+			local suggestion = {
+				kind = "command",
+				name = cmd_match,
+				description = cmds[cmd_match].description,
+				matches = match(query, cmd_match),
+
+				span = vector.create(1, tokens[#tokens].span.y, 0),
+				replace = cmd_match,
+			} :: types.AnalysisSuggestion
+			table.insert(suggestions, suggestion)
+		end
+
+		return {
+			result = result,
+			suggestions = suggestions,
+		} :: types.AnalysisResult
+	end
+
+	local analysis_result: centurion.Result<unknown>
+
+	local arg_result = process_arg()
+	local cmd_result = process_command()
+	if resolution.unclosed_quote then
+		analysis_result = {
+			success = false,
+			error = "Unclosed quote at position " .. tokens[#tokens].span.x,
+		}
+	else
+		if arg_result then
+			analysis_result = arg_result.result
+		else
+			analysis_result = cmd_result.result
+		end
+	end
+
+	local final_suggestions = cmd_result.suggestions
+	if at_arg and arg_result then
+		final_suggestions = arg_result.suggestions
+
+		-- a subcommand shares the position of its parent's first argument, so
+		-- both sets are offered there instead of the argument replacing them
+		if cmd_name and slot == 1 then
+			local prefix = cmd_name .. " "
+			local merged: { types.AnalysisSuggestion } = {}
+
+			for _, suggestion in cmd_result.suggestions do
+				if suggestion.name ~= cmd_name and suggestion.name:sub(1, #prefix) == prefix then
+					table.insert(merged, suggestion)
+				end
+			end
+
+			if #merged > 0 then
+				for _, suggestion in final_suggestions do
+					table.insert(merged, suggestion)
+				end
+
+				if max_suggestions then
+					for i = #merged, max_suggestions + 1, -1 do
+						merged[i] = nil
+					end
+				end
+
+				final_suggestions = merged
+			end
+		end
+	end
+
+	return {
+		result = analysis_result,
+		command = cmd_name,
+		argument = arg_result and arg_result.argument or nil,
+		suggestions = final_suggestions,
+	}
+end
+
+return analyse