rian-project-manager 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rian contributors
+
+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

@@ -0,0 +1,156 @@
+# Rian
+
+**Your local project desk.** A fast, keyboard-first terminal app for picking up work across development projects. Save a directory once; open your editor, coding tools, GitHub, shell, and project commands from one place.
+
+Built in Go with [Bubble Tea](https://github.com/charmbracelet/bubbletea), [Lip Gloss](https://github.com/charmbracelet/lipgloss), and [Bubbles](https://github.com/charmbracelet/bubbles). Local JSON storage. No accounts or background service.
+
+<!-- Screenshot placeholder: replace with a terminal capture of Rian in your own workspace. -->
+```text
+  RIAN / your project desk                              Ctrl+K actions
+
+  ╭─ Projects ─────────────────╮ ╭─ Cardly ──────────────────────────╮
+  │ › ★ Cardly        main ●   │ │ ~/dev/cardly                      │
+  │   Drift           main ○   │ │ Node.js · pnpm · Next.js           │
+  │   Rin              dev ●   │ │                                   │
+  │                            │ │ GitHub  FatalMistake02/Cardly      │
+  │                            │ │ Branch  main    Modified 3        │
+  │                            │ │ Ahead   1       Behind   0        │
+  │                            │ │                                   │
+  │                            │ │ v VS Code   o OpenCode            │
+  │                            │ │ K KiloCode  c ChatGPT             │
+  │                            │ │ t Terminal  g GitHub              │
+  ╰────────────────────────────╯ ╰───────────────────────────────────╯
+
+  ↑↓ / jk navigate   a add   / search   ? help   q quit
+```
+
+## Features
+
+- Resizable full-screen interface with a restrained `#fa11b0` accent, fuzzy project search, action palette, help, confirmations, and notifications.
+- Favorites first, followed by recently used projects. Opening an action or starting a command records use.
+- Project previews before saving, editable names/directories/URLs/GitHub overrides/tool settings, and custom commands.
+- VS Code, OpenCode, KiloCode (`kilo` or `kilocode`), ChatGPT, GitHub, and project URLs. Missing tools are explained in the palette.
+- Local Git status: branch, modified/untracked counts, ahead/behind, latest commit, and remote. The active project refreshes every 15 seconds and when the terminal regains focus. No automatic network calls.
+- Detected commands, custom overrides, and one active background command per project with recent output, PID, start time, stop, and rerun.
+- Git menu: fast-forward pull, push, fetch, staged commit, existing-branch switch, GitHub, and optional lazygit.
+
+## Install
+
+Requires **Node.js 22+**. Install the npm package to get the `rian` command:
+
+```sh
+npm install -g rian-project-manager
+rian add .
+rian
+```
+
+Or try it without a global install:
+
+```sh
+npx rian-project-manager
+```
+
+The package includes native executables for **macOS, Windows, and Linux**, on both **ARM64 and x64**. No Go installation, compiler, or separate binary download is needed. The small Node launcher passes terminal input and output directly to Rian. Its installation script only ensures the current platform's executable has permission to run.
+
+Git and coding tools are optional; install the tools you want and make their launchers available in `PATH`. On macOS, Rian also finds VS Code and ChatGPT in `/Applications` or `~/Applications`.
+
+### Build from source
+
+Requires **Go 1.26+** to build:
+
+```sh
+go build -trimpath -ldflags="-s -w" -o rian ./cmd/rian
+```
+
+On Windows, use `-o rian.exe`. Move the resulting executable to a directory in your `PATH`. That single executable is all Rian needs; no Go installation is needed to run it.
+
+```sh
+rian add .
+rian
+```
+
+The add command previews detection and asks for confirmation. Use `--yes` for scripts or automation after reviewing the directory. A modern UTF-8 terminal is recommended. The interface needs at least 52 columns × 16 rows; 100 × 30 gives the details more room.
+
+## CLI
+
+| Command | Behavior |
+| --- | --- |
+| `rian` | Open the interface |
+| `rian add <directory> [--yes]` | Inspect, preview, and save a project |
+| `rian list [--json]` | List saved projects |
+| `rian open <project>` / `rian vscode <project>` | Open VS Code |
+| `rian terminal <project>` | Start a shell in the project directory |
+| `rian opencode <project>` / `rian kilocode <project>` | Run the coding CLI interactively |
+| `rian chatgpt <project>` / `rian github <project>` | Open ChatGPT or the repository |
+| `rian run <project> <command>` | Run a detected/custom command in the foreground |
+| `rian remove <project> [--yes]` | Remove the Rian entry; keep all project files |
+| `rian config` | Print the config path |
+| `rian --help` / `rian --version` | Show help or version |
+
+Project lookup accepts an ID, an exact name, or an unambiguous fuzzy name. Quote names with spaces. Ambiguous matches print the matching names, IDs, and paths rather than selecting one.
+
+## Keyboard
+
+| Keys | Action |
+| --- | --- |
+| `↑` / `k`, `↓` / `j` | Previous / next project |
+| `Enter`, `Ctrl+K` | Project actions / command palette |
+| `/`, `Esc` | Search / leave search or close a modal |
+| `v`, `o`, `Shift+K` | VS Code, OpenCode, KiloCode |
+| `c`, `t`, `g` | ChatGPT, shell, GitHub |
+| `r`, `d`, `p` | Run command / active process, command menu, process output |
+| `Shift+G`, `Ctrl+R` | Git menu, rescan project files/tools/Git |
+| `f`, `a`, `e`, `Delete` | Favorite, add, edit, remove entry |
+| `?`, `q` / `Ctrl+C` | Help, quit |
+
+`k` always moves up; **Shift+K** launches KiloCode. Typing in inputs takes priority over project shortcuts.
+
+In **Edit Project**, use `Tab` or arrows to move fields, `Space` to toggle settings, and `Ctrl+S` to save. In the **command menu**, `Ctrl+N` adds a command, `Ctrl+E` edits it or creates an override, and `Ctrl+D` removes a custom command. Removing an override restores the detected command. In **process output**, `s` stops the process tree, `r` reruns a stopped command, `f` toggles output following, and arrows/Page Up/Page Down scroll. Leaving output keeps the command running; quitting asks to stop active commands.
+
+## Platforms and launchers
+
+- **Windows:** native executable, PowerShell (`pwsh` when available), batch-based tool launchers, and process-tree stopping.
+- **Linux:** native executable, the shell from `$SHELL` (fallback `/bin/sh`), `xdg-open` or `gio` for URLs, and process-group stopping.
+- **macOS:** native Apple Silicon and Intel executables, the shell from `$SHELL` (fallback `/bin/sh`), `open` for URLs/apps, and process-group stopping. VS Code and ChatGPT can be found in the system or user Applications folder. Mac builds are cross-compiled; testing on a physical Mac remains outstanding.
+
+The Terminal action opens an interactive shell in the current terminal and suspends Rian until `exit`. OpenCode, KiloCode, lazygit, and Git actions also suspend the interface and restore it on exit. This preserves interactive input and credential prompts without depending on one terminal emulator. ChatGPT uses a `chatgpt` launcher if found, then the macOS ChatGPT app when installed, otherwise the browser at `https://chatgpt.com`. It does not upload project files or attach project context automatically.
+
+## Configuration and detection
+
+Rian creates its config automatically:
+
+| Platform | Default path |
+| --- | --- |
+| Windows | `%AppData%\rian\config.json` |
+| Linux | `$XDG_CONFIG_HOME/rian/config.json`, or `~/.config/rian/config.json` |
+| macOS | `~/Library/Application Support/rian/config.json` |
+
+Set `RIAN_CONFIG_HOME` to use a different directory. Detailed UI errors go to `rian.log` alongside the config, with one rotated backup. Writes use a temporary file and a cross-process lock; invalid configs are preserved. If a crash leaves `config.json.lock`, remove that **empty lock directory** only after all Rian instances have exited.
+
+Detection checks files in the project root: `package.json`, package-manager declarations and npm/pnpm/yarn/Bun lockfiles, `go.mod`, `Cargo.toml`, Python manifests, and Flutter's `pubspec.yaml`. It recognizes Next.js, Vite, Expo, React Native, and React dependencies. Every portable package-script name becomes a runnable command. It also suggests Go, Cargo, Python/pytest, Django, and Flutter commands. Suggestions require the corresponding runtimes/dependencies; Rian never installs them. A declared package manager wins over lockfiles. Custom commands override detected commands by name. Use **Ctrl+R** after changing project files.
+
+GitHub remotes support HTTPS, SCP-style SSH, `ssh://`, and Git protocol URLs. Non-GitHub repositories still show local Git information. Commands execute only when selected, in the selected directory, using `cmd.exe` on Windows and the user's shell on Linux/macOS. Background commands capture output without an interactive stdin; run interactive programs through the shell action or `rian run`.
+
+## Development
+
+```sh
+gofmt -w cmd internal
+go test ./...
+go vet ./...
+go build ./cmd/rian
+```
+
+To build and check all six npm executables:
+
+```sh
+npm run build
+npm test
+npm run check:package
+npm pack
+```
+
+The build stamps the package version into each executable, records SHA-256 checksums and architecture information, and gathers dependency licenses. Package checks verify every binary and execute the host build. The npm package includes the Go source and third-party license notices. Generated artifacts live under `dist/binaries/`.
+
+Code lives in focused packages under `internal/`: `project`, `config`, `detect`, `git`, `tools`, `process`, `ui`, and `app`. Platform helpers have Windows/Unix implementations. The UI schedules disk scans and external work asynchronously. Tests cover storage and concurrency, remote parsing, real Git status, detection, fuzzy lookup, process cleanup, CLI flows, keyboard routing, and terminal-size bounds.
+
+Contributions should preserve the local-first model, keep tool execution out of rendering, and include focused tests for behavioral changes. Cloud accounts, sync, remote sessions, and a plugin system are outside this first version.