guito 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to Guito are documented in this file. The project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html), and this changelog is structured around [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.5.1] - 2026-08-31
+
+### Added
+
+- Added a marketplace icon for the Visual Studio Code extension.
+
+## [0.5.0] - 2026-08-31
+
+### Added
+
+- Added a VS Code extension with a status-bar action, Command Palette command, repository picker, and reusable editor webviews.
+- Added support for local and remote VS Code workspaces, including Remote SSH, Dev Containers, and GitHub Codespaces.
+- Added authenticated per-repository server sessions for VS Code webviews.
+- Added server integration tests and release-version verification.
+- Added automated npm and Visual Studio Marketplace publishing for stable GitHub releases.
+- Added a project-wide contribution guide and changelog.
+
+### Changed
+
+- Split the reusable Fastify server from the CLI entry point so the browser client and VS Code extension share the same backend.
+- Added the VS Code extension as an npm workspace and integrated it into the project build.
+- Updated the Fastify server dependencies and Monaco editor.
+
+## [0.4.0] - 2026-08-20
+
+### Added
+
+- Added branch filtering, remote-branch visibility controls, and commit search.
+- Added a visual commit graph with branch and tag badges.
+- Added working-tree status to the history view.
+- Added commit and working-tree diff views with Monaco-powered inline and side-by-side layouts.
+- Added context menus for commit, branch, remote, archive, stash, reset, and cleanup actions.
+- Added toolbar actions for fetch, pull, pull with rebase, push, sync, and refresh.
+
+### Changed
+
+- Rebuilt the frontend with Angular.
+- Expanded the local Git API and refreshed the application layout and interactions.
+
+## [0.3.0] - 2026-01-05
+
+### Added
+
+- Added core Git workflows for commits, staging, branches, stashes, tags, merges, rebases, and remotes.
+- Added the first commit diff viewer with Monaco editor support.
+- Added the initial commit graph visualization.
+
+## [0.2.1] - 2025-05-23
+
+### Changed
+
+- Renamed the project and npm command from `easy-git-explorer` to `guito`.
+
+## [0.2.0] - 2024-06-26
+
+### Added
+
+- Added the first repository header and commit table.
+- Added initial npm usage documentation for the browser client.
+
+## [0.1.0] - 2024-06-20
+
+### Added
+
+- Added the first browser-based Git explorer MVP.

package/CONTRIBUTION.md

@@ -0,0 +1,138 @@
+# Contributing to Guito
+
+Thanks for helping improve Guito. Contributions to the Angular client, Fastify server, CLI, VS Code extension, tests, and documentation are welcome.
+
+## Before you start
+
+- Search the [existing issues](https://github.com/danisss9/Guito/issues) before starting work.
+- Discuss a large feature, behavior change, or architectural rewrite with the maintainer first. Use an issue when issue creation is available; otherwise, open a draft pull request with the proposal.
+- Keep pull requests focused. Unrelated fixes are easier to review as separate changes.
+- Never include repository credentials, tokens, personal paths, or sensitive Git data in code, tests, screenshots, or logs.
+
+## Prerequisites
+
+- Git
+- Node.js 24 and npm (Node.js 24 matches the release workflow)
+- Visual Studio Code 1.96 or newer when developing the extension
+
+The Angular toolchain also supports the Node.js versions declared by `@angular/build`, but using Node.js 24 gives contributors the closest match to CI.
+
+## Set up the project
+
+Fork and clone the repository, then install the locked dependencies from the project root:
+
+```sh
+git clone https://github.com/<your-user>/Guito.git
+cd Guito
+npm ci
+```
+
+Create a focused branch for your change:
+
+```sh
+git switch -c feature/short-description
+```
+
+## Run the browser client locally
+
+The API server and Angular development server run as separate processes. Start each command in its own terminal from the project root:
+
+```sh
+npm run dev:server
+```
+
+```sh
+npm run dev
+```
+
+Open `http://localhost:4200`. The Angular development server proxies `/api` requests to the API server on port `8080`.
+
+`npm run dev:server` compiles the server once before starting it. Restart that process after changing server code.
+
+To build and run the packaged application instead:
+
+```sh
+npm run build
+npm start
+```
+
+## Develop the VS Code extension
+
+Build the extension and its bundled UI:
+
+```sh
+npm run build:extension
+```
+
+Open the repository in Visual Studio Code and launch the **Run Guito Extension** debug configuration. Its pre-launch task rebuilds the extension. In the Extension Development Host, open a trusted Git workspace and run **Guito: Open Guito**.
+
+To create a local VSIX package:
+
+```sh
+npm run package:extension
+```
+
+The package is written to `vscode-extension/guito.vsix` and is ignored by Git.
+
+## Project structure
+
+| Path | Purpose |
+| --- | --- |
+| `src/` | Angular application, components, models, utilities, and API client. |
+| `server/` | Fastify API, Git integration, and CLI server entry point. |
+| `vscode-extension/` | VS Code extension manifest, source, build script, and extension-specific docs. |
+| `tests/` | Node integration tests for the local server. |
+| `scripts/` | Release verification utilities. |
+| `bin/` | Compiled server and UI assets shipped in the npm package. |
+| `.github/workflows/` | Release automation. |
+
+Treat `bin/`, `vscode-extension/dist/`, and packaged `.vsix` files as generated output. Make source changes under `src/`, `server/`, or `vscode-extension/src/`; do not edit generated bundles by hand. Regenerate build output with the npm scripts when it needs to be included or inspected.
+
+## Validate your change
+
+Run the same core checks used by the release workflow:
+
+```sh
+npm run check
+npm run build
+npm test
+```
+
+- Add or update tests when changing server routes, authentication, repository selection, or Git behavior.
+- Test UI changes against a disposable repository with branches, merges, remote references, working-tree changes, and untracked files where relevant.
+- Exercise destructive operations only in a disposable repository.
+- Verify extension changes in an Extension Development Host. If remote behavior changes, also test an appropriate remote workspace when possible.
+
+## Code and documentation guidelines
+
+- Follow the existing TypeScript and Angular patterns in the surrounding files.
+- Keep server operations scoped to the selected repository and validate any user-controlled paths or refs.
+- Return useful API errors without exposing secrets or unrelated filesystem data.
+- Preserve the confirmation flow for destructive Git operations.
+- Update `README.md` or extension documentation when user-facing behavior changes.
+- Add user-visible changes to the `Unreleased` section of `CHANGELOG.md`.
+
+## Submit a pull request
+
+Before submitting:
+
+1. Rebase or merge the latest `main` branch into your branch and resolve conflicts.
+2. Run the validation commands above.
+3. Review the diff for generated noise, secrets, debug logging, and unrelated edits.
+4. Explain what changed, why it changed, how it was tested, and any remaining limitations in the pull-request description.
+5. Link the relevant issue when one exists.
+
+Review feedback is part of the contribution process. Keep follow-up commits focused, and avoid force-pushing after review has started unless rebasing is necessary.
+
+## Releases
+
+Releases are maintained by the project owner. Pushing a stable `vX.Y.Z` Git tag triggers the release workflow, which verifies the root package and extension versions before building, testing, and publishing both packages. After both publishes succeed, the workflow creates the corresponding GitHub Release with generated release notes. npm uses trusted publishing, while the VS Code Marketplace publish reads the `VSCE_PAT` repository secret.
+
+Release preparation should update:
+
+- `package.json`
+- `package-lock.json`
+- `vscode-extension/package.json`
+- `CHANGELOG.md`
+
+Do not publish the npm package or VS Code extension from a contribution branch.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2023 danisss9
-
-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.
+MIT License
+
+Copyright (c) 2026 danisss9
+
+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,82 +1,82 @@
-# Guito
-
-**G**u**IT**o ([**GUI**to](https://dicionario.priberam.org/guito)) is a free and simple git client.
-
-## Table of Contents
-
-- [Guito](#guito)
-  - [Table of Contents](#table-of-contents)
-  - [Install](#install)
-  - [Use](#use)
-  - [Arguments](#arguments)
-  - [Changelog](#changelog)
-  - [FAQs](#faqs)
-
-## Install
-
-```cmd
-npm install -g guito
-```
-
-## Use
-
-Run the following command on the folder where you git repository is:
-
-```cmd
-npx guito
-```
-
-## Arguments
-
-| Argument          | Description                                |
-| ----------------- | ------------------------------------------ |
-| `--port <number>` | Port to serve the UI on (default: `8080`). |
-| `--no-open`       | Do not open the browser automatically.     |
-
-## Changelog
-
-**Version 0.4:**
-
-- rebuilt the UI with Angular
-- added commit graph visualization
-- added branch filtering and remote branch toggle
-- added commit search
-- added commit diff viewer
-
-**Version 0.3:**
-
-- added more git functionalities
-
-**Version 0.2:**
-
-- added header and table components
-
-**Version 0.1:**
-
-- published library
-
-## Development
-
-Install the dependencies and build everything:
-
-```cmd
-npm install
-npm run build
-npm start
-```
-
-To develop the UI with hot reload, run the API server and the Angular dev server in separate terminals:
-
-```cmd
-npm run dev:server
-```
-
-```cmd
-npm run dev
-```
-
-The UI dev server proxies `/api` requests to the API server.
-
-## FAQs
-
-No FAQs for now. (⌐■_■)
+# Guito
+
+Explore and manage Git repositories in a focused visual client. Guito runs locally in your browser or directly inside Visual Studio Code.
+
+The name combines **GUI** and **Git**: **G**u**IT**o. It is also a [Portuguese word for money](https://dicionario.priberam.org/guito).
+
+[npm package](https://www.npmjs.com/package/guito) · [VS Code extension](https://marketplace.visualstudio.com/items?itemName=danisss9.guito) · [Issue tracker](https://github.com/danisss9/Guito/issues)
+
+## Features
+
+- Visual commit graph with branch and tag references.
+- Commit search by subject, author, or hash.
+- Local and remote branch filtering.
+- Commit and working-tree diffs powered by the Monaco editor, with inline and side-by-side layouts.
+- Fetch, pull, pull with rebase, push, and sync actions.
+- Context actions for creating branches and tags, checking out commits, cherry-picking, reverting, merging, rebasing, resetting, and exporting archives.
+- Working-tree actions for stashing changes, resetting tracked changes, and cleaning untracked files.
+- Browser-based CLI and a VS Code extension with local, Remote SSH, Dev Container, and Codespaces support.
+
+> [!CAUTION]
+> Guito can run destructive Git operations, including hard resets, commit drops, forceful cleanup, and history changes. Review confirmation dialogs carefully and make sure important work is committed or backed up.
+
+## Quick start
+
+### Browser client
+
+You need Git, Node.js 20 or newer, and npm. From inside the repository you want to inspect, run:
+
+```sh
+npx guito
+```
+
+Guito starts a local server at `http://localhost:8080` and opens it in your default browser.
+
+To install the command globally instead:
+
+```sh
+npm install --global guito
+guito
+```
+
+### Visual Studio Code
+
+After installing the extension, open a trusted workspace containing a Git repository, then either:
+
+- select **Guito** in the status bar; or
+- run **Guito: Open Guito** from the Command Palette.
+
+In a multi-root workspace, Guito asks which repository to open. Git must be available on the local or remote VS Code extension host.
+
+## CLI options
+
+```text
+guito [--port <number>] [--no-open]
+```
+
+| Option            | Description                                                                                           |
+| ----------------- | ----------------------------------------------------------------------------------------------------- |
+| `--port <number>` | Port used by the local server. Defaults to `8080`; use `0` to select an available port automatically. |
+| `--no-open`       | Start the server without opening a browser.                                                           |
+
+Run the command from anywhere inside the Git worktree you want Guito to manage. Press `Ctrl+C` in the terminal to stop the server.
+
+## Using Guito
+
+- Select a commit to inspect its changed files, then select a file to open its diff.
+- Select **Uncommitted changes** to inspect the working tree.
+- Use the branch selector and remote-branch toggle to narrow the graph.
+- Right-click a commit, reference badge, or the working-tree row to open its available Git actions.
+- Use the toolbar for remote operations and manual refreshes.
+
+The standalone server can execute Git commands against the current repository. Keep it on a trusted machine and do not expose its port to untrusted networks.
+
+## Development and contributing
+
+See [CONTRIBUTION.md](CONTRIBUTION.md) for local setup, development commands, project structure, testing, and pull-request guidance.
+
+Release history is maintained in [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+Guito is available under the [MIT License](LICENSE).