getgloss 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. package/LICENSE +22 -0
  2. package/README.md +109 -0
  3. package/dist/cli/index.js +638 -0
  4. package/dist/cli/index.js.map +1 -0
  5. package/dist/mcp/index.js +293 -0
  6. package/dist/mcp/index.js.map +1 -0
  7. package/dist/server/daemon.js +427 -0
  8. package/dist/server/daemon.js.map +1 -0
  9. package/dist/web/assets/index-BiGi3rBS.css +1 -0
  10. package/dist/web/assets/index-GpOF1p41.js +149 -0
  11. package/dist/web/index.html +14 -0
  12. package/dist/web/prompt.md +58 -0
  13. package/dist/web/setup.md +133 -0
  14. package/package.json +80 -0
  15. package/skill/SKILL.md +23 -0
package/dist/web/index.html ADDED
@@ -0,0 +1,14 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
+ <title>Gloss</title>
7
+ <script type="module" crossorigin src="/assets/index-GpOF1p41.js"></script>
8
+ <link rel="stylesheet" crossorigin href="/assets/index-BiGi3rBS.css">
9
+ </head>
10
+ <body>
11
+ <div id="root"></div>
12
+ </body>
13
+ </html>
14
+
package/dist/web/prompt.md ADDED
@@ -0,0 +1,58 @@
1
+ ## Gloss
2
+
3
+ Use Gloss when the user wants to review local code changes, inspect a multi-file
4
+ diff in a browser, or leave comments for an agent before a PR.
5
+
6
+ The user may say "gloss this", "open Gloss", "review my changes", "local diff
7
+ review", or "let me comment on the diff". Treat those as requests to use Gloss
8
+ when the current working tree has code changes.
9
+
10
+ From the repo root, open a blocking review with:
11
+
12
+ ```bash
13
+ gloss open --json --base HEAD
14
+ ```
15
+
16
+ Use `--base <ref>` when the user specifies a comparison base such as
17
+ `origin/main` or `origin/master`.
18
+
19
+ Leave the command running. Do not interrupt, kill, background, detach, or treat
20
+ the waiting process as cleanup. The wait is intentional: Gloss exits after the
21
+ user clicks Submit in the browser, and that exit is your signal to resume.
22
+
23
+ When `gloss open --json` exits, parse the JSON output. Prefer reading
24
+ `feedbackPath` from disk when present, because it contains the durable structured
25
+ feedback bundle. Address every comment in file/line order, then run the
26
+ narrowest relevant validation.
27
+
28
+ If the user only wants a review URL and does not want you to wait, run:
29
+
30
+ ```bash
31
+ gloss open --json --no-watch
32
+ ```
33
+
34
+ Gloss feedback is stored under:
35
+
36
+ ```text
37
+ <repo>/.gloss/reviews/<reviewId>/feedback.json
38
+ <repo>/.gloss/reviews/<reviewId>/feedback.md
39
+ ```
40
+
41
+ Use `feedback.json` for structured agent work. Use `feedback.md` when a human
42
+ readable summary is useful.
43
+
44
+ Gloss is for code diffs. Do not use it for Markdown plan annotation; use
45
+ Roughdraft for Markdown review if the user has Roughdraft installed.
46
+
47
+ Useful commands:
48
+
49
+ ```bash
50
+ gloss status --json
51
+ gloss watch <reviewId> --json
52
+ gloss doctor
53
+ gloss mcp
54
+ ```
55
+
56
+ The MCP server exposes tools to list pending reviews, fetch review details,
57
+ watch for completion, read feedback, and mark a review resolved.
58
+
package/dist/web/setup.md ADDED
@@ -0,0 +1,133 @@
1
+ # Gloss Agent Setup
2
+
3
+ You are setting yourself up to use Gloss, a local code-diff review tool for
4
+ coding-agent loops.
5
+
6
+ Gloss captures the current git diff, opens a localhost browser review UI, lets
7
+ the user attach comments to changed lines and ranges, then writes structured
8
+ feedback to `.gloss/reviews/<reviewId>/feedback.json` and `feedback.md`.
9
+
10
+ ## Check Installation
11
+
12
+ Check whether Gloss is available:
13
+
14
+ ```bash
15
+ gloss help
16
+ ```
17
+
18
+ If Gloss is missing and the user has asked you to install it, install it with:
19
+
20
+ ```bash
21
+ npm i -g getgloss
22
+ ```
23
+
24
+ If the user did not explicitly ask you to install software, ask before
25
+ installing a global npm package.
26
+
27
+ ## Update Your Persistent Instructions
28
+
29
+ Add Gloss guidance to the persistent instruction file this agent will actually
30
+ load. Prefer global or user-level instructions, because Gloss is a cross-project
31
+ workflow.
32
+
33
+ First inspect the user's existing setup. Do not create a new instruction file
34
+ when an appropriate one already exists.
35
+
36
+ Common current locations:
37
+
38
+ ```text
39
+ OpenAI Codex: ${CODEX_HOME:-$HOME/.codex}/AGENTS.md
40
+ Claude Code: $HOME/.claude/CLAUDE.md
41
+ Gemini CLI: $HOME/.gemini/GEMINI.md
42
+ opencode: ${XDG_CONFIG_HOME:-$HOME/.config}/opencode/AGENTS.md
43
+ Cursor: Cursor Settings > Rules for global user rules; project AGENTS.md or .cursor/rules/*
44
+ VS Code Copilot: GitHub/VS Code settings for personal instructions; project .github/copilot-instructions.md, .github/instructions/*.instructions.md, or AGENTS.md
45
+ ```
46
+
47
+ Check for existing files before editing:
48
+
49
+ ```bash
50
+ find \
51
+ "${CODEX_HOME:-$HOME/.codex}" \
52
+ "$HOME/.claude" \
53
+ "$HOME/.gemini" \
54
+ "${XDG_CONFIG_HOME:-$HOME/.config}/opencode" \
55
+ "$PWD" \
56
+ -maxdepth 3 \
57
+ \( -name "AGENTS.md" -o -name "CLAUDE.md" -o -name "GEMINI.md" -o -name "copilot-instructions.md" -o -name "*.instructions.md" \) \
58
+ 2>/dev/null
59
+ ```
60
+
61
+ If one or more files exist, choose the one for the current agent and merge in
62
+ any missing Gloss guidance. If the current agent cannot determine which file it
63
+ loads, use its built-in memory or settings command when available.
64
+
65
+ If no persistent instruction file exists and the user has not specified a tool,
66
+ create a portable canonical file at
67
+ `${XDG_CONFIG_HOME:-$HOME/.config}/agents/AGENTS.md`, then connect
68
+ vendor-specific global files to it. Do not overwrite existing files.
69
+
70
+ ```bash
71
+ canonical_agents_file="${XDG_CONFIG_HOME:-$HOME/.config}/agents/AGENTS.md"
72
+ mkdir -p "$(dirname "$canonical_agents_file")"
73
+ touch "$canonical_agents_file"
74
+
75
+ mkdir -p "${CODEX_HOME:-$HOME/.codex}"
76
+ [ -e "${CODEX_HOME:-$HOME/.codex}/AGENTS.md" ] || [ -L "${CODEX_HOME:-$HOME/.codex}/AGENTS.md" ] || ln -s "$canonical_agents_file" "${CODEX_HOME:-$HOME/.codex}/AGENTS.md"
77
+
78
+ mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/opencode"
79
+ [ -e "${XDG_CONFIG_HOME:-$HOME/.config}/opencode/AGENTS.md" ] || [ -L "${XDG_CONFIG_HOME:-$HOME/.config}/opencode/AGENTS.md" ] || ln -s "$canonical_agents_file" "${XDG_CONFIG_HOME:-$HOME/.config}/opencode/AGENTS.md"
80
+
81
+ mkdir -p "$HOME/.gemini"
82
+ [ -e "$HOME/.gemini/GEMINI.md" ] || [ -L "$HOME/.gemini/GEMINI.md" ] || ln -s "$canonical_agents_file" "$HOME/.gemini/GEMINI.md"
83
+
84
+ mkdir -p "$HOME/.claude"
85
+ [ -e "$HOME/.claude/CLAUDE.md" ] || [ -L "$HOME/.claude/CLAUDE.md" ] || printf "@%s\n" "$canonical_agents_file" > "$HOME/.claude/CLAUDE.md"
86
+ ```
87
+
88
+ Use imports or symlinks only when the target agent supports normal Markdown
89
+ files at that path. For UI-only settings such as Cursor User Rules or GitHub
90
+ Copilot personal instructions, tell the user what text to add rather than
91
+ editing an unknown file.
92
+
93
+ The canonical Gloss instruction block is hosted at
94
+ https://getgloss.dev/prompt.md. After you identify or create the right
95
+ instruction file, prefer appending or merging that exact block:
96
+
97
+ ```bash
98
+ agent_instructions_file="/absolute/path/to/AGENTS.md"
99
+ printf "\n\n" >> "$agent_instructions_file"
100
+ curl -fsSL https://getgloss.dev/prompt.md >> "$agent_instructions_file"
101
+ ```
102
+
103
+ If the instruction file already has Gloss guidance, merge in any missing
104
+ guidance from https://getgloss.dev/prompt.md instead of duplicating the section.
105
+
106
+ After updating your instructions, briefly tell the user which file you changed.
107
+
108
+ ## Local Usage Reference
109
+
110
+ Open a review and wait until the user submits feedback:
111
+
112
+ ```bash
113
+ gloss open --json --base HEAD
114
+ ```
115
+
116
+ Open a review and return immediately:
117
+
118
+ ```bash
119
+ gloss open --json --no-watch
120
+ ```
121
+
122
+ Read pending/completed reviews through MCP:
123
+
124
+ ```bash
125
+ gloss mcp
126
+ ```
127
+
128
+ Diagnose setup:
129
+
130
+ ```bash
131
+ gloss doctor
132
+ ```
133
+
package/package.json ADDED
@@ -0,0 +1,80 @@
1
+ {
2
+ "name": "getgloss",
3
+ "version": "0.1.0",
4
+ "description": "Local browser-based diff review for coding-agent loops.",
5
+ "type": "module",
6
+ "packageManager": "pnpm@10.33.2",
7
+ "bin": {
8
+ "gloss": "./dist/cli/index.js"
9
+ },
10
+ "files": [
11
+ "dist",
12
+ "skill",
13
+ "README.md",
14
+ "LICENSE"
15
+ ],
16
+ "scripts": {
17
+ "build": "pnpm build:web && pnpm build:node",
18
+ "build:web": "vite build",
19
+ "build:node": "tsup",
20
+ "check": "biome check .",
21
+ "format": "biome format --write .",
22
+ "prepack": "pnpm build",
23
+ "dev:web": "vite --host 127.0.0.1",
24
+ "setup": "tsx scripts/dev-cli.ts",
25
+ "test": "vitest run",
26
+ "test:watch": "vitest"
27
+ },
28
+ "engines": {
29
+ "node": ">=20"
30
+ },
31
+ "dependencies": {
32
+ "@hono/node-server": "^1.14.4",
33
+ "@modelcontextprotocol/sdk": "^1.29.0",
34
+ "@pierre/diffs": "^1.2.1",
35
+ "@tailwindcss/vite": "^4.1.7",
36
+ "commander": "^14.0.0",
37
+ "execa": "^9.5.3",
38
+ "get-port": "^7.1.0",
39
+ "hono": "^4.7.10",
40
+ "lucide-react": "^1.16.0",
41
+ "open": "^10.1.2",
42
+ "react": "^19.1.0",
43
+ "react-dom": "^19.1.0",
44
+ "ulid": "^3.0.0",
45
+ "zod": "^4.4.3",
46
+ "zustand": "^5.0.5"
47
+ },
48
+ "devDependencies": {
49
+ "@biomejs/biome": "^2.0.6",
50
+ "@types/node": "^24.0.1",
51
+ "@types/react": "^19.1.6",
52
+ "@types/react-dom": "^19.1.5",
53
+ "@vitejs/plugin-react": "^4.5.2",
54
+ "playwright": "^1.52.0",
55
+ "tsup": "^8.5.0",
56
+ "tsx": "^4.20.3",
57
+ "typescript": "^5.8.3",
58
+ "vite": "^6.3.5",
59
+ "vitest": "^3.2.3"
60
+ },
61
+ "keywords": [
62
+ "diff",
63
+ "review",
64
+ "coding-agents",
65
+ "mcp"
66
+ ],
67
+ "author": "Raj Joshi",
68
+ "license": "MIT",
69
+ "homepage": "https://getgloss.dev",
70
+ "repository": {
71
+ "type": "git",
72
+ "url": "git+https://github.com/iamrajjoshi/gloss.git"
73
+ },
74
+ "bugs": {
75
+ "url": "https://github.com/iamrajjoshi/gloss/issues"
76
+ },
77
+ "publishConfig": {
78
+ "access": "public"
79
+ }
80
+ }
package/skill/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: gloss
3
+ description: Open local code changes in Gloss for browser review, wait for feedback, and address the returned comments.
4
+ ---
5
+
6
+ # Gloss
7
+
8
+ Use this skill when the user asks to review local code changes with Gloss, says
9
+ "gloss this", "open gloss", "review my changes", or wants a browser-based local
10
+ diff review before a PR.
11
+
12
+ ## Workflow
13
+
14
+ 1. Run `gloss open --json --base ${base:-HEAD}` from the repo root.
15
+ 2. Wait for the command to exit. It blocks until the browser review is submitted.
16
+ 3. Parse the JSON output and read `feedbackPath` if present.
17
+ 4. Address each comment in order by file and line.
18
+ 5. Validate the fix with the narrowest relevant tests or build.
19
+ 6. Summarize the comments addressed and the validation performed.
20
+
21
+ If the user asks only to open the review and not wait, run
22
+ `gloss open --json --no-watch`.
23
+