npm - vibeops-tracker - Versions diffs - 0.1.0 - Mend

vibeops-tracker 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 (23) hide show

package/AUTHORS +10 -0
package/LICENSE +21 -0
package/README.md +209 -0
package/bin/cli.mjs +75 -0
package/lib/api.mjs +140 -0
package/lib/data-dir.mjs +46 -0
package/lib/prompt.mjs +96 -0
package/lib/store.mjs +569 -0
package/mcp-server.mjs +247 -0
package/package.json +62 -0
package/public/app.js +733 -0
package/public/apple-touch-icon.png +0 -0
package/public/favicon-32.png +0 -0
package/public/favicon.svg +56 -0
package/public/help.html +214 -0
package/public/icon-192.png +0 -0
package/public/icon-512.png +0 -0
package/public/icon.svg +56 -0
package/public/index.html +33 -0
package/public/manifest.webmanifest +12 -0
package/public/styles.css +420 -0
package/public/widget.js +554 -0
package/server.mjs +75 -0

package/public/apple-touch-icon.png ADDED Viewed

Binary file

package/public/favicon-32.png ADDED Viewed

Binary file

package/public/favicon.svg ADDED Viewed

@@ -0,0 +1,56 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024">
+  <!-- Tab favicon: same art as icon.svg, pre-rounded with transparent corners
+       (browsers don't mask favicons). Keep in sync with icon.svg. -->
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#222840"/>
+      <stop offset="0.55" stop-color="#12151f"/>
+      <stop offset="1" stop-color="#0b0d12"/>
+    </linearGradient>
+    <linearGradient id="wing" x1="0.18" y1="0" x2="0.82" y2="1">
+      <stop offset="0" stop-color="#a5acff"/>
+      <stop offset="0.5" stop-color="#6a6df5"/>
+      <stop offset="1" stop-color="#4d43d6"/>
+    </linearGradient>
+    <radialGradient id="sheen" cx="0.36" cy="0.28" r="0.8">
+      <stop offset="0" stop-color="#ffffff" stop-opacity="0.34"/>
+      <stop offset="0.45" stop-color="#ffffff" stop-opacity="0.08"/>
+      <stop offset="1" stop-color="#ffffff" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="glow" x="-50%" y="-50%" width="200%" height="200%">
+      <feGaussianBlur stdDeviation="85"/>
+    </filter>
+    <filter id="soft" x="-50%" y="-50%" width="200%" height="200%">
+      <feGaussianBlur stdDeviation="26"/>
+    </filter>
+    <clipPath id="rounded">
+      <rect width="1024" height="1024" rx="230"/>
+    </clipPath>
+  </defs>
+  <g clip-path="url(#rounded)">
+    <rect width="1024" height="1024" fill="url(#bg)"/>
+    <circle cx="512" cy="520" r="400" fill="#818cf8" opacity="0.26" filter="url(#glow)"/>
+    <g transform="translate(512 540) scale(1.07) translate(-512 -540)">
+      <ellipse cx="512" cy="874" rx="268" ry="44" fill="#000000" opacity="0.45" filter="url(#soft)"/>
+      <path d="M 466 246 Q 420 158 364 122" stroke="#4d5779" stroke-width="22" stroke-linecap="round" fill="none"/>
+      <path d="M 558 246 Q 604 158 660 122" stroke="#4d5779" stroke-width="22" stroke-linecap="round" fill="none"/>
+      <circle cx="364" cy="122" r="21" fill="#4d5779"/>
+      <circle cx="660" cy="122" r="21" fill="#4d5779"/>
+      <circle cx="512" cy="318" r="118" fill="#323a5e"/>
+      <circle cx="512" cy="565" r="285" fill="url(#wing)"/>
+      <circle cx="512" cy="565" r="285" fill="url(#sheen)"/>
+      <line x1="512" y1="280" x2="512" y2="850" stroke="#12151f" stroke-width="22"/>
+      <circle cx="398" cy="455" r="50" fill="#3b82f6"/>
+      <circle cx="372" cy="650" r="62" fill="#f97316"/>
+      <circle cx="633" cy="448" r="54" fill="#f59e0b"/>
+      <circle cx="650" cy="655" r="70" fill="#ef4444"/>
+    </g>
+  </g>
+</svg>

package/public/help.html ADDED Viewed

@@ -0,0 +1,214 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>VibeOps Tracker — Help</title>
+  <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+  <link rel="icon" href="/favicon-32.png" type="image/png" sizes="32x32" />
+  <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
+  <link rel="manifest" href="/manifest.webmanifest" />
+  <meta name="theme-color" content="#161a22" />
+  <link rel="stylesheet" href="/styles.css" />
+  <style>
+    #help { max-width: 880px; margin: 0 auto; padding: 24px 20px 80px; }
+    #help h2 { font-size: 20px; margin: 36px 0 10px; border-bottom: 1px solid var(--border); padding-bottom: 8px; }
+    #help h3 { font-size: 15px; margin: 22px 0 8px; color: var(--text); }
+    #help p, #help li { color: var(--text); line-height: 1.6; }
+    #help .note { color: var(--muted); font-size: 13px; }
+    #help pre {
+      background: #0b0d11; border: 1px solid var(--border); border-radius: 10px;
+      padding: 12px 14px; overflow-x: auto; font-size: 12.5px; line-height: 1.5; position: relative;
+    }
+    #help pre.prompt { border-left: 3px solid var(--accent); }
+    #help code { font-family: ui-monospace, SFMono-Regular, monospace; }
+    #help p > code, #help li > code { background: var(--panel-2); border: 1px solid var(--border); border-radius: 5px; padding: 1px 6px; font-size: 12.5px; }
+    .copy-btn {
+      position: absolute; top: 8px; right: 8px; background: var(--panel-2); color: var(--muted);
+      border: 1px solid var(--border); border-radius: 6px; padding: 3px 10px; font-size: 11px; cursor: pointer;
+    }
+    .copy-btn:hover { color: var(--text); border-color: var(--accent); }
+    .toc { background: var(--panel); border: 1px solid var(--border); border-radius: 10px; padding: 14px 18px; margin-top: 16px; }
+    .toc a { color: var(--accent); text-decoration: none; }
+    .toc li { margin: 4px 0; }
+  </style>
+</head>
+<body>
+  <header id="topbar">
+    <h1>VibeOps Tracker — Help</h1>
+    <a class="btn" href="/" style="margin-left:auto; text-decoration:none;">← Back to board</a>
+  </header>
+  <main id="help">
+    <p>VibeOps Tracker is a standalone app on <code>http://localhost:4400</code>. Issues live as one markdown
+    file each under <code>data/&lt;project&gt;/issues/</code> in the tracker repo — readable and greppable by
+    you and by agents. Projects' own repos contain <strong>one line</strong> of tracker-related code: the widget script tag.</p>
+    <div class="toc">
+      <ul>
+        <li><a href="#install">Install on a new project</a></li>
+        <li><a href="#disable">Disable / Enable / Remove</a></li>
+        <li><a href="#agents">Set up agent access (MCP)</a></li>
+        <li><a href="#usage">Ways to use it</a></li>
+        <li><a href="#prompts">Ready-made agent prompts</a></li>
+        <li><a href="#gotchas">Things to be aware of</a></li>
+      </ul>
+    </div>
+    <h2 id="install">Install on a new project</h2>
+    <p>1. Add one script tag to the project's frontend HTML (any framework, or none):</p>
+    <pre><code>&lt;script src="http://localhost:4400/widget.js" data-project="my-project" defer&gt;&lt;/script&gt;</code></pre>
+    <p>That's the whole install. A floating 🐞 button appears; submitting the dialog posts the issue
+    here with an automatic context snapshot: what you're looking at (URL, viewport, highlighted text)
+    is always attached, while the activity trail (last 10 clicks, last 10 fetches, recent JS errors
+    and failed requests) is a dialog checkbox — on by default for bugs, off for other types.
+    The project key auto-registers on first capture.</p>
+    <p>2. <em>Recommended:</em> tell the tracker where the project's repo lives, so generated prompts
+    point agents at the right working directory:</p>
+    <pre><code>curl -X POST http://localhost:4400/api/projects \
+  -H 'Content-Type: application/json' \
+  -d '{"key": "my-project", "name": "My Project", "repo_path": "/absolute/path/to/repo"}'</code></pre>
+    <p>3. <em>Optional:</em> enrich captures with app state and git info (great for worktree workflows —
+    captures then record which branch/worktree they came from):</p>
+    <pre><code>&lt;script&gt;
+  window.IssueTracker.configure({
+    context: () =&gt; ({
+      // anything useful: current tab, selected record, feature flags…
+      git: { branch: "...", commit: "...", worktree: "..." }  // if the host can know it
+    })
+  });
+&lt;/script&gt;</code></pre>
+    <h2 id="disable">Disable / Enable / Remove</h2>
+    <h3>Disable temporarily</h3>
+    <p>Comment out the script tag (the only integration point), or just stop the tracker server —
+    the widget fails safe and never breaks the host app:</p>
+    <pre><code>&lt;!-- &lt;script src="http://localhost:4400/widget.js" data-project="my-project" defer&gt;&lt;/script&gt; --&gt;</code></pre>
+    <h3>Enable / re-enable</h3>
+    <p>Uncomment (or re-add) the script tag, and make sure VibeOps Tracker is running: <code>cd /path/to/vibeops-tracker &amp;&amp; npm start</code> (or <code>npx vibeops-tracker</code>).</p>
+    <h3>Remove completely</h3>
+    <p>Delete the script tag and any <code>window.IssueTracker.configure</code> block from the project.
+    Nothing else lives in the project. The project's issues stay safely in the tracker's
+    <code>data/</code> dir; sweep or ignore them as you like.</p>
+    <h2 id="agents">Set up agent access (MCP)</h2>
+    <p>Register once (user scope = available in every project's Claude Code sessions):</p>
+    <pre><code>claude mcp add vibeops -- npx -y -p vibeops-tracker vibeops-mcp</code></pre>
+    <p>Tools: <code>get_tracker_instructions</code> (the workflow doctrine — agents should call it first),
+    <code>list_projects</code>, <code>list_issues</code>, <code>search_issues</code>, <code>get_issue</code>,
+    <code>create_issue</code>, <code>update_issue</code>, <code>add_comment</code>,
+    <code>resolve_issue</code>, <code>delete_issue</code> (permanent — requires <code>confirm: true</code>).
+    The MCP server reads the markdown files directly, so it works even when
+    the web server is down.</p>
+    <h2 id="usage">Ways to use it</h2>
+    <h3>Manual capture → paste into a session</h3>
+    <ol>
+      <li>Hit the 🐞 button in any app when something is off; describe seeing/expecting; submit.
+      <em>Tip:</em> highlight the exact text you're talking about <em>before</em> hitting 🐞 — it's
+      attached to the report (previewed in the dialog, removable) and quoted prominently in the
+      agent prompt. For non-bug reports the click/network/error trail is left off by default;
+      tick "Include activity trail" if it matters.</li>
+      <li>On the board, prioritize by dragging cards (order is saved into each issue's file).</li>
+      <li>Open a card → <strong>Copy Prompt</strong> → paste into a Claude Code session in that project.
+      The prompt carries the full issue, context summary, repo path, and the API workflow
+      (in-progress → resolve → in-review).</li>
+      <li>When the agent resolves, the card shows up in <strong>In Review</strong> with a PR-style
+      resolution and the list of files it touched. Verify, drag to Done, and occasionally
+      <strong>Sweep</strong> the Done column into the Archive.</li>
+    </ol>
+    <h3>Agent-driven (MCP)</h3>
+    <p>With the MCP server registered, you don't need to copy anything — just tell any session what
+    to do (see prompts below). Agents can also file issues themselves mid-task when they notice
+    something out of scope.</p>
+    <h3>Filing without a frontend</h3>
+    <p><strong>+ New issue</strong> on the board, or <code>create_issue</code> via MCP, or plain curl:</p>
+    <pre><code>curl -X POST http://localhost:4400/api/issues -H 'Content-Type: application/json' \
+  -d '{"project": "my-project", "title": "...", "type": "feature", "seeing": "...", "expecting": "..."}'</code></pre>
+    <h2 id="prompts">Ready-made agent prompts</h2>
+    <p class="note">Paste these into a Claude Code session running in the relevant project. Click a block to select it.</p>
+    <h3>Install the widget in this project</h3>
+    <pre class="prompt"><code>Install the issue-tracker capture widget into this project's frontend. Add
+&lt;script src="http://localhost:4400/widget.js" data-project="&lt;project-key&gt;" defer&gt;&lt;/script&gt;
+to the main HTML page(s), choosing a short kebab-case project key. Then register the repo path:
+curl -X POST http://localhost:4400/api/projects -H 'Content-Type: application/json' -d '{"key": "&lt;project-key&gt;", "name": "&lt;Readable Name&gt;", "repo_path": "&lt;absolute repo path&gt;"}'
+If the app knows its own state (current view, record ids, git branch), also add a
+window.IssueTracker.configure({ context: () =&gt; ({...}) }) block to enrich captures.
+Verify by loading the app and checking the 🐞 button appears bottom-right.</code></pre>
+    <h3>Disable or remove the widget from this project</h3>
+    <pre class="prompt"><code>Remove the issue-tracker widget from this project: find and delete the script tag that loads
+http://localhost:4400/widget.js (and any window.IssueTracker.configure block next to it).
+To disable temporarily instead of removing, comment the tag out. Make no other changes.</code></pre>
+    <h3>Pick up the next ticket and work it</h3>
+    <pre class="prompt"><code>You have access to my issue tracker via the issue-tracker MCP server. Call
+get_tracker_instructions first, then list_issues for project "&lt;project-key&gt;" with status
+"backlog" and pick the FIRST one (it's the highest priority). Read it fully with get_issue,
+reproduce from the captured context, mark it in-progress, fix it, and finish with
+resolve_issue (resolution summary + modified files). Then stop for my review — do not pick
+up another ticket unless I say so.</code></pre>
+    <h3>Triage what's on the board</h3>
+    <pre class="prompt"><code>Using the issue-tracker MCP server, list all issues for project "&lt;project-key&gt;" and give me
+a triage: which backlog items look quick vs. deep, anything that's probably a duplicate
+(use search_issues), anything in-review waiting on me, and what you'd tackle first and why.
+Don't change anything yet.</code></pre>
+    <h3>Migrate a roadmap / TODO file into the tracker</h3>
+    <pre class="prompt"><code>This project has roadmap/TODO files (ROADMAP.md, TODO.md, or similar — find them). Migrate
+their open items into my issue tracker via the issue-tracker MCP server (or curl to
+http://localhost:4400/api/issues if MCP is unavailable):
+1. Call get_tracker_instructions, then search_issues per item to skip anything already filed.
+2. For each open item, create_issue with project "&lt;project-key&gt;": title = the item;
+   seeing = current state/why it matters (quote the source file and line); expecting = done
+   criteria as concretely as the source allows; type = feature/improvement/bug as appropriate;
+   severity from any priority markers (default 3); tags = ["roadmap"] or ["todo"] plus topical tags.
+3. Keep one issue per actionable item — split grouped bullets, skip completed ones.
+4. When finished, report a table of created ids → titles, then UPDATE the source files: mark
+   migrated items with their new issue id (e.g. "→ tracked as &lt;id&gt;") instead of deleting them.
+Do not start working on any of the issues.</code></pre>
+    <h2 id="gotchas">Things to be aware of</h2>
+    <ul>
+      <li><strong>The tracker must be running</strong> for captures, the board, and Copy Prompt:
+        <code>npm start</code> in the tracker repo (the MCP tools work even without it).</li>
+      <li><strong>Capture-time context goes stale.</strong> Snapshots record the branch/worktree/port
+        at capture time; by pickup time the repo may have moved on. Prompts and instructions tell
+        agents to verify against current state.</li>
+      <li><strong>Issue files are the source of truth</strong>, stored under <code>data/</code> on your
+        machine. That directory is gitignored — it's real local tracker data, not versioned with the code,
+        so deletes are permanent (no git history to restore from). Don't hand-edit while the server is
+        mid-write; prefer the API/MCP (agents are told this).</li>
+      <li><strong>Deletion is manual and permanent.</strong> Open any issue and use <strong>Delete issue</strong>
+        in the drawer's Danger zone (two-step confirm) to remove stale, test, or junk issues for good —
+        this works on archived issues too. Agents can delete as well, via the MCP <code>delete_issue</code>
+        tool (guarded by a required <code>confirm: true</code> flag); the doctrine tells them to reserve it
+        for clearly stale/test/duplicate issues. For real issues you've resolved, prefer Done →
+        <strong>Sweep</strong> to the Archive over deleting; link duplicates with <code>related_to</code>.</li>
+      <li><strong>Statuses:</strong> backlog → in-progress → in-review → done. Agents never set
+        <em>done</em> — that's your verification step.</li>
+      <li><strong>localhost-only by design</strong> — the API has no auth and allows any origin; don't
+        expose port 4400 beyond your machine.</li>
+    </ul>
+  </main>
+  <script>
+    for (const pre of document.querySelectorAll('#help pre')) {
+      const btn = document.createElement('button');
+      btn.className = 'copy-btn';
+      btn.textContent = 'Copy';
+      btn.addEventListener('click', async () => {
+        await navigator.clipboard.writeText(pre.querySelector('code').innerText);
+        btn.textContent = 'Copied!';
+        setTimeout(() => (btn.textContent = 'Copy'), 1500);
+      });
+      pre.appendChild(btn);
+    }
+  </script>
+</body>
+</html>

package/public/icon-192.png ADDED Viewed

Binary file

package/public/icon-512.png ADDED Viewed

Binary file

package/public/icon.svg ADDED Viewed

@@ -0,0 +1,56 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024">
+  <!-- Issue Tracker app icon (master, full-bleed: macOS/iOS apply their own corner mask).
+       Geometric ladybug in the brand indigo; spots are the severity colors (sev2-5). -->
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#222840"/>
+      <stop offset="0.55" stop-color="#12151f"/>
+      <stop offset="1" stop-color="#0b0d12"/>
+    </linearGradient>
+    <linearGradient id="wing" x1="0.18" y1="0" x2="0.82" y2="1">
+      <stop offset="0" stop-color="#a5acff"/>
+      <stop offset="0.5" stop-color="#6a6df5"/>
+      <stop offset="1" stop-color="#4d43d6"/>
+    </linearGradient>
+    <radialGradient id="sheen" cx="0.36" cy="0.28" r="0.8">
+      <stop offset="0" stop-color="#ffffff" stop-opacity="0.34"/>
+      <stop offset="0.45" stop-color="#ffffff" stop-opacity="0.08"/>
+      <stop offset="1" stop-color="#ffffff" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="glow" x="-50%" y="-50%" width="200%" height="200%">
+      <feGaussianBlur stdDeviation="85"/>
+    </filter>
+    <filter id="soft" x="-50%" y="-50%" width="200%" height="200%">
+      <feGaussianBlur stdDeviation="26"/>
+    </filter>
+  </defs>
+  <rect width="1024" height="1024" fill="url(#bg)"/>
+  <circle cx="512" cy="520" r="400" fill="#818cf8" opacity="0.26" filter="url(#glow)"/>
+  <g id="bug" transform="translate(512 540) scale(1.07) translate(-512 -540)">
+    <ellipse cx="512" cy="874" rx="268" ry="44" fill="#000000" opacity="0.45" filter="url(#soft)"/>
+    <!-- antennae -->
+    <path d="M 466 246 Q 420 158 364 122" stroke="#4d5779" stroke-width="22" stroke-linecap="round" fill="none"/>
+    <path d="M 558 246 Q 604 158 660 122" stroke="#4d5779" stroke-width="22" stroke-linecap="round" fill="none"/>
+    <circle cx="364" cy="122" r="21" fill="#4d5779"/>
+    <circle cx="660" cy="122" r="21" fill="#4d5779"/>
+    <!-- head -->
+    <circle cx="512" cy="318" r="118" fill="#323a5e"/>
+    <!-- body -->
+    <circle cx="512" cy="565" r="285" fill="url(#wing)"/>
+    <circle cx="512" cy="565" r="285" fill="url(#sheen)"/>
+    <!-- wing split -->
+    <line x1="512" y1="280" x2="512" y2="850" stroke="#12151f" stroke-width="22"/>
+    <!-- spots: severity colors -->
+    <circle cx="398" cy="455" r="50" fill="#3b82f6"/>
+    <circle cx="372" cy="650" r="62" fill="#f97316"/>
+    <circle cx="633" cy="448" r="54" fill="#f59e0b"/>
+    <circle cx="650" cy="655" r="70" fill="#ef4444"/>
+  </g>
+</svg>

package/public/index.html ADDED Viewed

@@ -0,0 +1,33 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>VibeOps Tracker</title>
+  <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+  <link rel="icon" href="/favicon-32.png" type="image/png" sizes="32x32" />
+  <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
+  <link rel="manifest" href="/manifest.webmanifest" />
+  <meta name="theme-color" content="#161a22" />
+  <link rel="stylesheet" href="/styles.css" />
+</head>
+<body>
+  <header id="topbar">
+    <h1>VibeOps Tracker</h1>
+    <select id="project-select" aria-label="Project"></select>
+    <input id="search" type="search" placeholder="Search cards…" aria-label="Search issues" />
+    <span id="issue-count"></span>
+    <nav id="view-toggle">
+      <button id="view-board" class="toggle-btn on">Board</button>
+      <button id="view-archive" class="toggle-btn">Archive</button>
+    </nav>
+    <button id="new-issue" class="btn btn-primary">+ New issue</button>
+    <a id="help-link" class="btn" href="/help.html">Help</a>
+  </header>
+  <main id="board"></main>
+  <aside id="drawer" hidden></aside>
+  <div id="drawer-backdrop" hidden></div>
+  <div id="modal-root"></div>
+  <script src="/app.js"></script>
+</body>
+</html>

package/public/manifest.webmanifest ADDED Viewed

@@ -0,0 +1,12 @@
+{
+  "name": "VibeOps Tracker",
+  "short_name": "VibeOps",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#0f1115",
+  "theme_color": "#161a22",
+  "icons": [
+    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
+    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }
+  ]
+}