getgloss 0.2.0 → 0.3.0

package/README.md

@@ -6,11 +6,18 @@
 
 Gloss is a local browser review loop for coding agents. It captures your current
 git diff, opens a localhost review UI, lets you attach comments to changed
-lines or ranges, and writes structured feedback back into the repo for an
-agent to re-ingest.
+lines or ranges, and writes structured feedback under `~/.gloss` for an agent
+to re-ingest.
 
 ## Install
 
+```bash
+brew install iamrajjoshi/tap/gloss
+gloss open --json
+```
+
+With npm:
+
 ```bash
 npm install -g getgloss
 gloss open --json
@@ -25,13 +32,13 @@ npx getgloss open --json
 For a new agent chat, use:
 
 ```text
-Install Gloss with npm. Then read https://getgloss.dev/setup.md.
+Install Gloss with Homebrew or npm. Then read https://getgloss.dev/setup.md.
 ```
 
 ### Claude Code Skill
 
-Gloss ships a Claude Code skill at `skill/SKILL.md`. Install it with the
-[`skills` CLI](https://github.com/vercel-labs/agent-skills):
+Gloss ships a packaged Claude Code skill at `skill/SKILL.md`. Install it with
+the [`skills` CLI](https://github.com/vercel-labs/agent-skills):
 
 ```bash
 # Global (available across all projects)
@@ -42,9 +49,12 @@ npx skills add iamrajjoshi/gloss --skill gloss -a claude-code
 ```
 
 `-g` installs to `~/.claude/skills/`, `-a claude-code` targets Claude Code, and
-`--skill gloss` installs only the Gloss skill from the repo.
+`--skill gloss` installs only the Gloss skill folder from the repo. The skill
+teaches agents to run `gloss open --json`, wait for browser submission, read
+`feedbackPath`, apply comments, validate, and mark the review resolved when MCP
+tools are available.
 
-The hosted install script is npm-only:
+The hosted install script remains npm-only:
 
 ```bash
 curl -fsSL https://getgloss.dev/install.sh | sh
@@ -78,16 +88,17 @@ keeps the old behavior and does not fall back to a branch diff.
 Completed reviews are written to:
 
 ```text
-<repo>/.gloss/reviews/<reviewId>/
+~/.gloss/reviews/<reviewId>/
   meta.json
   diff.json
   feedback.json
   feedback.md
-  original/
+  resolved.json
 ```
 
 `feedback.json` is the machine-readable payload. `feedback.md` is a readable
-summary ordered by file and line.
+summary ordered by file and line. Set `GLOSS_STATE_DIR` to use an isolated
+state root for tests or development.
 
 ## MCP
 
@@ -122,10 +133,12 @@ Releases follow Willow's tag-driven shape:
 2. GitHub Actions runs checks, tests, and the production build.
 3. The package is published to npm as `getgloss`.
 4. A GitHub release is created with `npm pack` output and checksums.
+5. The Homebrew formula is updated in `iamrajjoshi/homebrew-tap`.
 
 Required repository secrets:
 
 - `NPM_TOKEN`
+- `HOMEBREW_TAP_GITHUB_TOKEN`
 
 ## Attribution
 

package/dist/cli/index.js

@@ -24,7 +24,7 @@ import path from "path";
 // package.json
 var package_default = {
   name: "getgloss",
-  version: "0.2.0",
+  version: "0.3.0",
   description: "Local browser-based diff review for coding-agent loops.",
   type: "module",
   packageManager: "pnpm@10.33.2",
@@ -127,6 +127,27 @@ function globalLogDir() {
 function globalServerLogFile() {
   return path.join(globalLogDir(), "server.log");
 }
+function globalReviewsDir() {
+  return path.join(globalStateDir(), "reviews");
+}
+function globalReviewDir(reviewId) {
+  return path.join(globalReviewsDir(), reviewId);
+}
+function globalReviewMetaFile(reviewId) {
+  return path.join(globalReviewDir(reviewId), "meta.json");
+}
+function globalReviewDiffFile(reviewId) {
+  return path.join(globalReviewDir(reviewId), "diff.json");
+}
+function globalReviewFeedbackFile(reviewId) {
+  return path.join(globalReviewDir(reviewId), "feedback.json");
+}
+function globalReviewMarkdownFile(reviewId) {
+  return path.join(globalReviewDir(reviewId), "feedback.md");
+}
+function globalReviewResolvedFile(reviewId) {
+  return path.join(globalReviewDir(reviewId), "resolved.json");
+}
 async function ensureDir(dir) {
   await mkdir(dir, { recursive: true });
 }
@@ -717,6 +738,275 @@ async function assertGitAvailable() {
   await execa("git", ["--version"]);
 }
 
+// src/server/store.ts
+import { readdir, readFile as readFile2, rm as rm2, writeFile as writeFile2 } from "fs/promises";
+import { ulid } from "ulid";
+
+// src/shared/markdown.ts
+function formatLineRange(comment) {
+  const prefix = comment.side;
+  if (comment.startLine === comment.endLine) {
+    return `${prefix}${comment.startLine}`;
+  }
+  return `${prefix}${comment.startLine}-${prefix}${comment.endLine}`;
+}
+function fenceFor(snippet) {
+  let fence = "```";
+  while (snippet.includes(fence)) {
+    fence += "`";
+  }
+  return fence;
+}
+function languageForPath2(filePath) {
+  const ext = filePath.split(".").pop()?.toLowerCase();
+  const map = {
+    cjs: "js",
+    css: "css",
+    go: "go",
+    html: "html",
+    js: "js",
+    json: "json",
+    jsx: "jsx",
+    md: "markdown",
+    mjs: "js",
+    py: "python",
+    rb: "ruby",
+    rs: "rust",
+    sh: "bash",
+    swift: "swift",
+    ts: "ts",
+    tsx: "tsx",
+    yaml: "yaml",
+    yml: "yaml"
+  };
+  return ext ? map[ext] ?? ext : "";
+}
+function languageForSnippet(filePath, snippet) {
+  const lines = snippet.split("\n").filter((line) => line.length > 0);
+  const looksLikeUnifiedDiff = lines.length > 0 && lines.some((line) => line.startsWith("+") || line.startsWith("-")) && lines.every((line) => line.startsWith("+") || line.startsWith("-") || line.startsWith(" "));
+  return looksLikeUnifiedDiff ? "diff" : languageForPath2(filePath);
+}
+function byFileThenLine(a, b) {
+  return a.filePath.localeCompare(b.filePath) || a.startLine - b.startLine || a.endLine - b.endLine || a.side.localeCompare(b.side);
+}
+function serializeFeedbackMarkdown(bundle) {
+  const comments = [...bundle.comments].sort(byFileThenLine);
+  const files = [...new Set(comments.map((comment) => comment.filePath))];
+  const lines = [
+    `# Gloss feedback - ${bundle.timestamp}`,
+    `Review: ${bundle.reviewId}`,
+    `Base: ${bundle.base.ref} (${bundle.base.sha.slice(0, 7)})  Branch: ${bundle.branch ?? "(detached)"}`,
+    `Files: ${files.length}   Comments: ${comments.length}`,
+    ""
+  ];
+  for (const filePath of files) {
+    lines.push(`## ${filePath}`, "");
+    for (const comment of comments.filter((item) => item.filePath === filePath)) {
+      const snippet = comment.originalSnippet.trimEnd();
+      const firstSnippetLine = snippet.split("\n").find((line) => line.trim().length > 0);
+      const heading = comment.startLine === comment.endLine && firstSnippetLine ? `### ${formatLineRange(comment)} - \`${firstSnippetLine.trim().slice(0, 80)}\`` : `### ${formatLineRange(comment)}`;
+      lines.push(heading, comment.body.trim(), "");
+      if (snippet) {
+        const fence = fenceFor(snippet);
+        lines.push(`${fence}${languageForSnippet(comment.filePath, snippet)}`, snippet, fence, "");
+      }
+    }
+  }
+  return `${lines.join("\n").trimEnd()}
+`;
+}
+
+// src/server/store.ts
+var ReviewStore = class {
+  reviews = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Map();
+  async create(diff) {
+    const id = ulid();
+    const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+    const meta = {
+      id,
+      cwd: diff.cwd,
+      base: diff.base,
+      branch: diff.branch,
+      status: "pending",
+      createdAt,
+      artifactDir: globalReviewDir(id)
+    };
+    const record = { meta, diff };
+    this.reviews.set(id, record);
+    await this.persistInitial(record);
+    this.emit({ type: "review.opened", reviewId: id });
+    return record;
+  }
+  async list() {
+    await this.loadAllReviews();
+    return [...this.reviews.values()].map((record) => record.meta).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+  }
+  async get(id) {
+    return this.reviews.get(id) ?? await this.loadKnownReview(id);
+  }
+  async submit(id, comments) {
+    const record = await this.get(id);
+    if (!record) {
+      throw new Error(`Review ${id} not found`);
+    }
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    const feedback = {
+      version: 1,
+      reviewId: id,
+      timestamp,
+      base: record.diff.base,
+      branch: record.diff.branch,
+      comments: [...comments].sort(
+        (a, b) => a.filePath.localeCompare(b.filePath) || a.startLine - b.startLine || a.endLine - b.endLine || a.side.localeCompare(b.side)
+      )
+    };
+    record.feedback = feedback;
+    record.meta = { ...record.meta, status: "completed", completedAt: timestamp };
+    this.reviews.set(id, record);
+    const artifactDir = globalReviewDir(id);
+    const feedbackPath = globalReviewFeedbackFile(id);
+    const markdownPath = globalReviewMarkdownFile(id);
+    record.meta = {
+      ...record.meta,
+      artifactDir,
+      feedbackPath,
+      markdownPath
+    };
+    await ensureDir(artifactDir);
+    await Promise.all([
+      writeFile2(globalReviewMetaFile(id), `${JSON.stringify(record.meta, null, 2)}
+`),
+      writeFile2(feedbackPath, `${JSON.stringify(feedback, null, 2)}
+`),
+      writeFile2(markdownPath, serializeFeedbackMarkdown(feedback))
+    ]);
+    this.emit({
+      type: "review.completed",
+      reviewId: id,
+      counts: {
+        files: new Set(feedback.comments.map((comment) => comment.filePath)).size,
+        comments: feedback.comments.length
+      }
+    });
+    return { record, feedbackPath, markdownPath };
+  }
+  async feedback(id) {
+    const record = await this.get(id);
+    return record?.feedback ?? null;
+  }
+  async markResolved(id, summary) {
+    const record = await this.get(id);
+    if (!record) {
+      throw new Error(`Review ${id} not found`);
+    }
+    const resolvedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const resolvedPath = globalReviewResolvedFile(id);
+    record.meta = { ...record.meta, status: "resolved", resolvedAt };
+    this.reviews.set(id, record);
+    await ensureDir(globalReviewDir(id));
+    await writeFile2(
+      resolvedPath,
+      `${JSON.stringify({ reviewId: id, summary: summary ?? null, resolvedAt }, null, 2)}
+`
+    );
+    await writeFile2(globalReviewMetaFile(id), `${JSON.stringify(record.meta, null, 2)}
+`);
+    return resolvedPath;
+  }
+  subscribe(reviewId, listener) {
+    const listeners = this.listeners.get(reviewId) ?? /* @__PURE__ */ new Set();
+    listeners.add(listener);
+    this.listeners.set(reviewId, listeners);
+    return () => {
+      listeners.delete(listener);
+      if (listeners.size === 0) {
+        this.listeners.delete(reviewId);
+      }
+    };
+  }
+  emit(event) {
+    for (const listener of this.listeners.get(event.reviewId) ?? []) {
+      listener(event);
+    }
+  }
+  async persistInitial(record) {
+    const dir = globalReviewDir(record.meta.id);
+    await ensureDir(dir);
+    await Promise.all([
+      writeFile2(globalReviewMetaFile(record.meta.id), `${JSON.stringify(record.meta, null, 2)}
+`),
+      writeFile2(globalReviewDiffFile(record.meta.id), `${JSON.stringify(record.diff, null, 2)}
+`)
+    ]);
+  }
+  async loadKnownReview(id) {
+    const existing = this.reviews.get(id);
+    if (existing) {
+      return existing;
+    }
+    return this.loadReview(id);
+  }
+  async loadAllReviews() {
+    let entries;
+    try {
+      entries = await readdir(globalReviewsDir(), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    await Promise.all(
+      entries.filter((entry) => entry.isDirectory()).map((entry) => this.loadReview(entry.name))
+    );
+  }
+  async loadReview(id) {
+    try {
+      const [metaRaw, diffRaw] = await Promise.all([
+        readFile2(globalReviewMetaFile(id), "utf8"),
+        readFile2(globalReviewDiffFile(id), "utf8")
+      ]);
+      const meta = JSON.parse(metaRaw);
+      const diff = JSON.parse(diffRaw);
+      let feedback;
+      try {
+        feedback = JSON.parse(
+          await readFile2(globalReviewFeedbackFile(id), "utf8")
+        );
+      } catch {
+        feedback = void 0;
+      }
+      const record = {
+        meta: {
+          ...meta,
+          artifactDir: meta.artifactDir ?? globalReviewDir(id),
+          feedbackPath: meta.feedbackPath ?? (feedback ? globalReviewFeedbackFile(id) : void 0),
+          markdownPath: meta.markdownPath ?? (feedback ? globalReviewMarkdownFile(id) : void 0)
+        },
+        diff,
+        feedback
+      };
+      this.reviews.set(id, record);
+      return record;
+    } catch {
+      return null;
+    }
+  }
+};
+var reviewStore = new ReviewStore();
+
+// src/cli/status.ts
+async function listReviewsForStatus({
+  responsive,
+  server
+}) {
+  if (server && responsive) {
+    try {
+      return (await new ServerClient(serverUrl(server)).listReviews()).reviews;
+    } catch {
+    }
+  }
+  return new ReviewStore().list();
+}
+
 // src/cli/index.ts
 function printJson(value) {
   process.stdout.write(`${JSON.stringify(value, null, 2)}
@@ -742,7 +1032,13 @@ program.command("open").description("Capture local changes and open them for rev
       await openBrowser(url);
     }
     if (options.watch === false) {
-      const result2 = { reviewId: meta.id, url, files: diff.files.length, scope: diff.scope.mode };
+      const result2 = {
+        reviewId: meta.id,
+        url,
+        files: diff.files.length,
+        scope: diff.scope.mode,
+        artifactDir: meta.artifactDir
+      };
       globals.json ? printJson(result2) : printPlain(`Review ${meta.id}: ${url}`);
       return;
     }
@@ -761,8 +1057,9 @@ program.command("open").description("Capture local changes and open them for rev
       url,
       files: event.counts.files,
       comments: event.counts.comments,
-      feedbackPath: `${diff.cwd}/.gloss/reviews/${meta.id}/feedback.json`,
-      markdownPath: `${diff.cwd}/.gloss/reviews/${meta.id}/feedback.md`,
+      feedbackPath: globalReviewFeedbackFile(meta.id),
+      markdownPath: globalReviewMarkdownFile(meta.id),
+      artifactDir: globalReviewDir(meta.id),
       feedback
     };
     globals.json ? printJson(result) : printPlain(`Review ${meta.id} completed with ${event.counts.comments} comments`);
@@ -784,10 +1081,7 @@ program.command("status").description("Show server and active reviews").action(a
   const globals = program.opts();
   const info = await readServerInfo();
   const responsive = info ? await isServerResponsive(info) : false;
-  let reviews = [];
-  if (info && responsive) {
-    reviews = (await new ServerClient(serverUrl(info)).listReviews()).reviews;
-  }
+  const reviews = await listReviewsForStatus({ responsive, server: info });
   const status = { running: responsive, server: info, reviews };
   globals.json ? printJson(status) : printPlain(
     responsive && info ? `Gloss server running at ${serverUrl(info)} with ${reviews.length} active review(s)` : "Gloss server is not running"