tokens-for-good 0.4.5 → 0.4.7

package/README.md

@@ -15,7 +15,7 @@ Works with Claude Code, OpenCode, Cursor, Windsurf, Devin, and Qwen Code as an M
 
    init is interactive: it asks for your API key, the cadence you want (daily / weekly / hourly / one-off), and then writes everything — MCP config, SessionStart hook, `/tfg` and `/tfg-schedule` skills, and your preference — in one shot.
 
-3. **Open Claude Code.** Your first session acts on the cadence you picked automatically:
+3. **Open your AI coding tool.** Your first session acts on the cadence you picked automatically:
    - Scheduled → it sets up `/schedule` via the `/tfg-schedule` skill.
    - One-off → it kicks off a single research task via the `/tfg` skill.
 

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "tokens-for-good",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "type": "module",
   "description": "Donate your spare AI tokens to research nonprofits for Fierce Philanthropy",
+  "homepage": "https://tokensforgood.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Tokens-for-Good/tokens-for-good.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Tokens-for-Good/tokens-for-good/issues"
+  },
   "bin": {
     "tokens-for-good": "src/cli.js"
   },
@@ -26,6 +34,9 @@
     "social-impact"
   ],
   "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "prompts": "^2.4.2",

package/pipeline/03-humanize/PROMPT.md

@@ -1,4 +1,4 @@
-# Step 3: Humanize — Claude Code Instructions
+# Step 3: Humanize — Instructions
 
 ## Inputs
 

package/skills/tfg.md

@@ -21,7 +21,7 @@ The user wants to complete one Tokens for Good research cycle.
 
 ## If something goes wrong
 
-- **`claim_org` returns an error about an API key** → run `npx tokens-for-good init` in terminal and restart Claude Code.
+- **`claim_org` returns an error about an API key** → run `npx tokens-for-good init` in terminal and restart your AI tool.
 - **A citation fails verification** → fix it or remove the claim it supported. Don't submit reports with broken citations.
 - **User interrupts mid-research** → the claim will auto-expire on the server side. No cleanup needed.
 

package/src/cli.js

@@ -1,57 +1,92 @@
-#!/usr/bin/env node
-
-// CLI entry point for tokens-for-good.
-// Usage:
-//   npx tokens-for-good init                  Interactive first-time setup
-//   npx tokens-for-good session-start-hook    SessionStart hook (used by Claude Code)
-//   npx tokens-for-good --mcp                 Start as MCP server (default)
-//   npx tokens-for-good --status              Show project status
-//   npx tokens-for-good --impact              Show your contribution stats
-
-const args = process.argv.slice(2);
-const first = args[0];
-
-if (first === 'init') {
-  const { runInit } = await import('./init.js');
-  await runInit();
-} else if (first === 'session-start-hook') {
-  const { runSessionStartHook } = await import('./session-start-hook.js');
-  runSessionStartHook();
-} else if (args.includes('--status') || first === 'status') {
-  const { ApiClient } = await import('./api-client.js');
-  try {
-    const client = new ApiClient(process.env.TFG_API_KEY || 'public');
-    const status = await client.getStatus();
-    console.log('\nTokens for Good - Project Status\n');
-    console.log(`Total orgs: ${status.total_orgs}`);
-    console.log(`Pending research: ${status.pending_orgs}`);
-    console.log(`Active contributors (7d): ${status.active_contributors_7d}`);
-    console.log('\nQueue:');
-    for (const [k, v] of Object.entries(status.queue || {})) {
-      console.log(`  ${k}: ${v}`);
-    }
-    console.log('\nTop Contributors:');
-    (status.top_contributors || []).forEach((c, i) => {
-      console.log(`  ${i + 1}. @${c.github_handle} (${c.total_orgs} orgs, ${c.tier})`);
-    });
-  } catch (err) {
-    console.error('Error:', err.message);
-  }
-} else if (args.includes('--impact') || first === 'impact') {
-  const { ApiClient } = await import('./api-client.js');
-  try {
-    const client = new ApiClient(process.env.TFG_API_KEY);
-    const result = await client.getImpact();
-    const c = result.contributor;
-    console.log(`\nYour Impact (@${c.github_handle})\n`);
-    console.log(`Tier: ${c.tier}`);
-    console.log(`Orgs researched: ${c.total_orgs}`);
-    console.log(`Acceptance rate: ${c.acceptance_rate}%`);
-    console.log(`Automation: ${c.has_schedule ? 'Active' : 'Not set up'}`);
-  } catch (err) {
-    console.error('Error:', err.message);
-  }
-} else {
-  // Default: start MCP server
-  await import('./mcp-server.js');
-}
+#!/usr/bin/env node
+
+// CLI entry point for tokens-for-good.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+const HELP = `tokens-for-good v${pkg.version}
+Donate your spare AI tokens to research nonprofits for Fierce Philanthropy.
+
+Usage:
+  npx tokens-for-good <command> [options]
+
+Commands:
+  init                  Interactive first-time setup (API key, causes, cadence)
+  session-start-hook    Emit the SessionStart hook payload (used by your agent)
+  status                Show project-wide research stats
+  impact                Show your own contribution stats (needs TFG_API_KEY)
+
+Options:
+  --status              Same as the "status" command
+  --impact              Same as the "impact" command
+  -v, --version         Print the installed version
+  -h, --help            Show this help
+
+With no command (or --mcp), tokens-for-good starts as an MCP server over
+stdio. That is how your editor's MCP client launches it.
+
+Docs: https://github.com/Tokens-for-Good/tokens-for-good`;
+
+const args = process.argv.slice(2);
+const first = args[0];
+
+if (args.includes('-v') || args.includes('--version')) {
+  console.log(pkg.version);
+} else if (args.includes('-h') || args.includes('--help') || first === 'help') {
+  console.log(HELP);
+} else if (first === 'init') {
+  const { runInit } = await import('./init.js');
+  await runInit();
+} else if (first === 'session-start-hook') {
+  const { runSessionStartHook } = await import('./session-start-hook.js');
+  runSessionStartHook();
+} else if (args.includes('--status') || first === 'status') {
+  const { ApiClient } = await import('./api-client.js');
+  try {
+    const client = new ApiClient(process.env.TFG_API_KEY || 'public');
+    const status = await client.getStatus();
+    const sys = status.system_stats || status;
+    console.log('\nTokens for Good - Project Status\n');
+    console.log(`Total orgs: ${sys.total_organizations ?? status.total_orgs ?? 'n/a'}`);
+    console.log(`Pending research: ${sys.pending_organizations ?? status.pending_orgs ?? 'n/a'}`);
+    console.log(`Active contributors (7d): ${sys.active_contributors_7_days ?? status.active_contributors_7d ?? 'n/a'}`);
+    console.log('\nQueue:');
+    for (const [k, v] of Object.entries(status.queue_status || status.queue || {})) {
+      console.log(`  ${k}: ${v}`);
+    }
+    console.log('\nTop Contributors:');
+    (status.top_contributors || []).forEach((c, i) => {
+      const name = c.display_name || (c.github_handle ? '@' + c.github_handle : 'anonymous');
+      console.log(`  ${c.rank ?? i + 1}. ${name} (${c.total_organizations ?? c.total_orgs} orgs, ${c.tier})`);
+    });
+  } catch (err) {
+    console.error('Error:', err.message);
+  }
+} else if (args.includes('--impact') || first === 'impact') {
+  const { ApiClient } = await import('./api-client.js');
+  try {
+    const client = new ApiClient(process.env.TFG_API_KEY);
+    const result = await client.getImpact();
+    const c = result.contributor;
+    console.log(`\nYour Impact (@${c.github_handle})\n`);
+    console.log(`Tier: ${c.tier}`);
+    console.log(`Orgs researched: ${c.total_orgs}`);
+    console.log(`Acceptance rate: ${c.acceptance_rate}%`);
+    console.log(`Automation: ${c.has_schedule ? 'Active' : 'Not set up'}`);
+  } catch (err) {
+    console.error('Error:', err.message);
+  }
+} else if (args.length === 0 || args.includes('--mcp')) {
+  // Default: start the MCP server. This is how the editor's MCP client launches us
+  // (init writes the config with the --mcp flag).
+  await import('./mcp-server.js');
+} else {
+  // Unrecognized command/flag: show help instead of silently starting the server.
+  console.error(`Unknown command: ${args.join(' ')}\n`);
+  console.log(HELP);
+  process.exitCode = 1;
+}

package/src/mcp-server.js

@@ -17,7 +17,7 @@ const STATE_FILE = join(homedir(), '.tokens-for-good', 'state.json');
 
 const INIT_GUARD_MESSAGE = `Tokens for Good setup isn't complete on this machine yet.
 
-Tell the user to run this in their terminal (not in Claude), then restart Claude Code:
+Tell the user to run this in their terminal (not here in the chat), then restart their AI tool:
 
   npx tokens-for-good init
 
@@ -50,7 +50,7 @@ const server = new McpServer({
 
 // --- No-key onboarding message ---
 
-const NO_KEY_INSTRUCTIONS = `The user wants to set up Tokens for Good. Tell them to run this in their terminal (not here in Claude), then restart Claude Code:
+const NO_KEY_INSTRUCTIONS = `The user wants to set up Tokens for Good. Tell them to run this in their terminal (not here in the chat), then restart their AI tool:
 
   npx tokens-for-good init
 
@@ -60,7 +60,7 @@ The command walks them through everything in under a minute:
 3. Pick a cadence: **daily** (recommended), weekly, hourly, or one-off
 4. Confirm
 
-init writes everything — MCP config, SessionStart hook, /tfg and /tfg-schedule skills, and their recorded preference — in one shot. The first Claude Code session after init runs their chosen flow automatically.
+init writes everything — MCP config, SessionStart hook, /tfg and /tfg-schedule skills, and their recorded preference — in one shot. The first session after init runs their chosen flow automatically.
 
 **What is Tokens for Good?** A way for developers to donate their spare AI subscription tokens to research nonprofit organizations for Fierce Philanthropy's social impact directory. Each org takes ~5 minutes and ~$0.20 in tokens. Contributors get credit on a public leaderboard.`;
 
@@ -225,12 +225,14 @@ server.tool('research_status', 'See the overall Tokens for Good project progress
   try {
     const clientForStatus = client || new ApiClient('dummy'); // Status is public
     const result = await clientForStatus.getStatus();
+    const sys = result.system_stats || result;
+    const queue = result.queue_status || result.queue || {};
     const topList = result.top_contributors?.map((c, i) =>
-      `${i + 1}. @${c.github_handle} (${c.total_orgs} orgs, ${c.tier})`
+      `${c.rank ?? i + 1}. ${c.display_name || (c.github_handle ? '@' + c.github_handle : 'anonymous')} (${c.total_organizations ?? c.total_orgs} orgs, ${c.tier})`
     ).join('\n') || 'No contributors yet';
 
     return {
-      content: [{ type: 'text', text: `Tokens for Good Progress:\n\nTotal orgs: ${result.total_orgs}\nPending research: ${result.pending_orgs}\nActive contributors (7d): ${result.active_contributors_7d}\n\nQueue:\n${Object.entries(result.queue || {}).map(([k, v]) => `  ${k}: ${v}`).join('\n')}\n\nTop Contributors:\n${topList}` }],
+      content: [{ type: 'text', text: `Tokens for Good Progress:\n\nTotal orgs: ${sys.total_organizations ?? result.total_orgs}\nPending research: ${sys.pending_organizations ?? result.pending_orgs}\nActive contributors (7d): ${sys.active_contributors_7_days ?? result.active_contributors_7d}\n\nQueue:\n${Object.entries(queue).map(([k, v]) => `  ${k}: ${v}`).join('\n')}\n\nTop Contributors:\n${topList}` }],
     };
   } catch (err) {
     return { content: [{ type: 'text', text: `Error: ${err.message}` }] };

package/src/session-start-hook.js

@@ -33,7 +33,7 @@ export function runSessionStartHook() {
     const daysSince = last ? Math.floor((Date.now() - last.getTime()) / 86_400_000) : Infinity;
     if (daysSince >= 7) {
       emit(
-        "Tokens for Good: It's been a while — say 'run /tfg' to research one org now, " +
+        "Tokens for Good: It's been a while. Say 'run /tfg' to research one org now, " +
         "or 'run /tfg-schedule daily' to automate it from here on."
       );
     }