gitmark 0.0.78 → 0.0.79

package/README.md

@@ -68,8 +68,17 @@ The chain of addresses on Bitcoin mirrors the chain of commits in git. Anyone ca
 | `git mark info` | Show trail state, balance, addresses |
 | `git mark verify` | Verify all marks against Bitcoin |
 | `git mark update` | Update blocktrails.json from git notes |
+| `git mark badge` | Print README badge markdown. Option: `--branch` |
 | `git mark --version` | Show version |
 
+## Badge
+
+`git mark badge` prints markdown for a README badge, built from the `origin` remote, the current branch (or `--branch`) and `blocktrails.json`. For example, this is the badge for [melvincarvalho/delivery-day](https://github.com/melvincarvalho/delivery-day), whose trail is on txbt4:
+
+[![gitmarks](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmelvincarvalho%2Fdelivery-day%2Fgh-pages%2Fblocktrails.json&query=%24.states.length&label=gitmarks&suffix=%20%C2%B7%20txbt4&color=f7931a)](https://mempool.guide/testnet4/tx/8129190799de150153bdae7d1092c4cd505874e842cfbf429ac452956025fa51)
+
+It's a shields.io [dynamic JSON badge](https://shields.io/badges/dynamic-json-badge) that counts `states` in the pushed trail file, and links to the latest mark on the chain's explorer. The count updates whenever `blocktrails.json` is pushed, so it shows what the repo records. `git mark verify` checks it against the chain. For remotes not on GitHub, it prints `RAW_TRAIL_URL` and `TRAIL_LINK` placeholders to fill in.
+
 ## Trail File
 
 `blocktrails.json` in your repo root — committed, visible, verifiable:

package/bin/git-mark.js

@@ -9,6 +9,7 @@
  *   git mark info
  *   git mark verify
  *   git mark update
+ *   git mark badge [--branch name]
  */
 
 import { secp256k1, schnorr } from '@noble/curves/secp256k1';
@@ -565,6 +566,48 @@ async function cmdVerify() {
   process.exit(ok ? 0 : 1);
 }
 
+// --- Badge ---
+// owner/repo from a GitHub remote URL (https, ssh or scp form), or null
+function parseGithubRemote(url) {
+  const m = String(url || '').trim().match(/^(?:https?:\/\/|ssh:\/\/git@|git@)github\.com[:/]([^/]+)\/(.+?)(?:\.git)?\/?$/);
+  return m ? { owner: m[1], repo: m[2] } : null;
+}
+
+// the explorer's web page for a transaction: its API base without /api
+function explorerTxUrl(chain, txid) {
+  const api = CHAINS[chain]?.explorer;
+  return api ? `${api.replace(/\/api$/, '')}/tx/${txid}` : null;
+}
+
+// Markdown for a shields.io dynamic JSON badge counting the marks in the pushed trail file.
+// trailUrl: where the raw blocktrails.json is served; link: where the badge points.
+function badgeMarkdown({ trailUrl, chain, link }) {
+  const q = new URLSearchParams({ url: trailUrl, query: '$.states.length', label: 'gitmarks', suffix: ` · ${chain}`, color: 'f7931a' });
+  const img = `https://img.shields.io/badge/dynamic/json?${q.toString().replace(/\+/g, '%20')}`;
+  return `[![gitmarks](${img})](${link})`;
+}
+
+function cmdBadge(args) {
+  const trail = loadFullTrail();
+  if (!trail) { console.error(`No ${TRAIL_FILE} found. Run: git mark init`); process.exit(1); }
+  const branchIdx = args.indexOf('--branch');
+  const quiet = (cmd) => { try { return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return ''; } };
+  const branch = (branchIdx !== -1 ? args[branchIdx + 1] : null) || quiet('git symbolic-ref --short HEAD') || 'main';
+  const remote = quiet('git remote get-url origin');
+  const gh = parseGithubRemote(remote);
+
+  // the latest mark; before the first one, the badge links to the trail file instead
+  const lastTxid = trail.txo.length ? parseTxoUri(trail.txo[trail.txo.length - 1]).txid : null;
+  const trailUrl = gh
+    ? `https://raw.githubusercontent.com/${gh.owner}/${gh.repo}/${branch}/${TRAIL_FILE}`
+    : 'RAW_TRAIL_URL';
+  const link = (lastTxid && explorerTxUrl(trail.chain, lastTxid))
+    || (gh ? `https://github.com/${gh.owner}/${gh.repo}/blob/${branch}/${TRAIL_FILE}` : 'TRAIL_LINK');
+
+  console.log(badgeMarkdown({ trailUrl, chain: trail.chain, link }));
+  if (!gh) console.error(`\nOrigin is not on GitHub: replace RAW_TRAIL_URL with the URL-encoded address the pushed ${TRAIL_FILE} is served from, and TRAIL_LINK with where the badge should point.`);
+}
+
 function cmdUpdate() {
   const trail = loadTrailFromNotes();
   if (!trail) { console.error(`No ${TRAIL_FILE} found. Run: git mark init`); process.exit(1); }
@@ -577,7 +620,8 @@ export {
   taggedHash, btScalar, deriveChainedPrivkey, deriveChainedPubkey,
   pubkeyToAddress, parseTxoUri, p2trScript, buildTransaction,
   TRAIL_FILE, PRIVATE_FILE, CHAINS, isDirty, loadTrailFromNotes, loadFullTrail,
-  resolveVoucher, consumeVoucher
+  resolveVoucher, consumeVoucher,
+  parseGithubRemote, explorerTxUrl, badgeMarkdown
 };
 
 // --- CLI ---
@@ -596,6 +640,8 @@ if (isMain) {
     cmdVerify();
   } else if (cmd === 'update') {
     cmdUpdate();
+  } else if (cmd === 'badge') {
+    cmdBadge(args.slice(1));
   } else if (cmd === 'mark' || !cmd || (cmd && !cmd.startsWith('-'))) {
     if (!existsSync(TRAIL_FILE) && cmd !== 'mark') {
       console.log('Usage:');
@@ -604,6 +650,7 @@ if (isMain) {
       console.log('  git mark info             # show trail state');
       console.log('  git mark verify           # verify trail against Bitcoin');
       console.log('  git mark update           # update blocktrails.json from git notes');
+      console.log('  git mark badge            # print README badge markdown');
     } else {
       cmdMark(args.slice(cmd === 'mark' ? 1 : 0));
     }
@@ -613,5 +660,6 @@ if (isMain) {
     console.log('  git mark                  # anchor HEAD to Bitcoin');
     console.log('  git mark info             # show trail state');
     console.log('  git mark verify           # verify trail against Bitcoin');
+    console.log('  git mark badge            # print README badge markdown');
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitmark",
-  "version": "0.0.78",
+  "version": "0.0.79",
   "type": "module",
   "description": "Anchor git commits to Bitcoin via blocktrails",
   "main": "bin/git-mark.js",

package/test/git-mark.test.js

@@ -6,7 +6,8 @@ import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
 import {
   taggedHash, btScalar, deriveChainedPrivkey, deriveChainedPubkey,
   pubkeyToAddress, parseTxoUri, p2trScript, CHAINS, isDirty, loadFullTrail, loadTrailFromNotes,
-  resolveVoucher, consumeVoucher, buildTransaction
+  resolveVoucher, consumeVoucher, buildTransaction,
+  parseGithubRemote, explorerTxUrl, badgeMarkdown
 } from '../bin/git-mark.js';
 import { unifiedSighash, parseTransaction, SCRIPT_TYPE_TAPROOT } from '../lib/unified-sighash.js';
 import { schnorr } from '@noble/curves/secp256k1';
@@ -438,3 +439,37 @@ describe('Signing', () => {
     assert.notDeepStrictEqual(plain.inputs[0].witness[0], unified.inputs[0].witness[0].slice(0, 64));
   });
 });
+
+describe('Badge', () => {
+  it('reads owner and repo from GitHub remotes in every form', () => {
+    for (const url of [
+      'https://github.com/melvincarvalho/delivery-day.git',
+      'https://github.com/melvincarvalho/delivery-day',
+      'git@github.com:melvincarvalho/delivery-day.git',
+      'ssh://git@github.com/melvincarvalho/delivery-day.git',
+    ]) assert.deepStrictEqual(parseGithubRemote(url), { owner: 'melvincarvalho', repo: 'delivery-day' }, url);
+  });
+
+  it('returns null for remotes not on GitHub', () => {
+    assert.strictEqual(parseGithubRemote('https://gitlab.com/a/b.git'), null);
+    assert.strictEqual(parseGithubRemote(''), null);
+  });
+
+  it('links a transaction on the chain explorer', () => {
+    assert.strictEqual(explorerTxUrl('txbt4', 'ab'), 'https://mempool.guide/testnet4/tx/ab');
+    assert.strictEqual(explorerTxUrl('xbt', 'ab'), 'https://mempool.kilombino.com/tx/ab');
+    assert.strictEqual(explorerTxUrl('btc', 'ab'), 'https://mempool.space/tx/ab');
+    assert.strictEqual(explorerTxUrl('nope', 'ab'), null);
+  });
+
+  it('builds a shields.io dynamic JSON badge counting states', () => {
+    const md = badgeMarkdown({
+      trailUrl: 'https://raw.githubusercontent.com/melvincarvalho/delivery-day/gh-pages/blocktrails.json',
+      chain: 'txbt4',
+      link: 'https://mempool.guide/testnet4/tx/ab',
+    });
+    assert.strictEqual(md,
+      '[![gitmarks](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmelvincarvalho%2Fdelivery-day%2Fgh-pages%2Fblocktrails.json' +
+      '&query=%24.states.length&label=gitmarks&suffix=%20%C2%B7%20txbt4&color=f7931a)](https://mempool.guide/testnet4/tx/ab)');
+  });
+});