hearback 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Team Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# hearback
+
+Add [hearback](https://github.com/agent-team-foundation/hearback) — user feedback → GitHub Issues → email notification loop — to any product with one command.
+
+```bash
+npx hearback init
+```
+
+Auto-detects your framework (Next.js, Express, Hono, or AI Agent), injects the middleware / widget / env vars, and optionally sets up the notification GitHub Action.
+
+## What it does
+
+- **Next.js**: generates `app/api/feedback/[...path]/route.ts`, adds `<Script>` to `layout.tsx`
+- **Express / Hono**: injects `feedbackHandler` middleware + widget `<script>` tag into your HTML
+- **AI Agent (OpenAI / Anthropic / LangChain)**: injects `feedbackSkill` setup into your agent entry file
+
+Writes `FEEDBACK_REPO` and `GITHUB_TOKEN` to `.env`. Optionally creates `.github/workflows/feedback-notify.yml` for email notifications on issue close.
+
+See the [main repo](https://github.com/agent-team-foundation/hearback) for architecture, manual setup, and integration examples.
+
+## License
+
+MIT

package/bin/hearback.js

@@ -0,0 +1,489 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { execSync } from 'node:child_process';
+
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+
+function log(msg) { console.log(msg); }
+function step(n, msg) { log(`\n${CYAN}[${n}]${RESET} ${BOLD}${msg}${RESET}`); }
+function done(msg) { log(`  ${GREEN}✓${RESET} ${msg}`); }
+function info(msg) { log(`  ${DIM}${msg}${RESET}`); }
+function warn(msg) { log(`  ${YELLOW}⚠${RESET} ${msg}`); }
+
+async function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`  ${question} `, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function confirm(question) {
+  const answer = await ask(`${question} (Y/n)`);
+  return answer === '' || answer.toLowerCase().startsWith('y');
+}
+
+// --- File finders ---
+
+function findServerEntry(cwd) {
+  // Common server entry file patterns
+  const candidates = [
+    'src/server.ts', 'src/server.js',
+    'src/app.ts', 'src/app.js',
+    'src/index.ts', 'src/index.js',
+    'server.ts', 'server.js',
+    'app.ts', 'app.js',
+    'index.ts', 'index.js',
+  ];
+
+  for (const candidate of candidates) {
+    const fullPath = join(cwd, candidate);
+    if (!existsSync(fullPath)) continue;
+    const content = readFileSync(fullPath, 'utf-8');
+    // Must look like a server file (imports express/hono/fastify or has listen/app.use)
+    if (content.includes('express') || content.includes('hono') || content.includes('fastify') ||
+        content.includes('.listen(') || content.includes('app.use(') || content.includes('createServer')) {
+      return { path: candidate, fullPath, content };
+    }
+  }
+  return null;
+}
+
+function findHtmlLayout(cwd) {
+  // Look for HTML files that have </body>
+  const candidates = [
+    'src/index.html', 'public/index.html', 'index.html',
+    'views/layout.ejs', 'views/layout.hbs',
+    'templates/base.html', 'templates/layout.html',
+  ];
+
+  for (const candidate of candidates) {
+    const fullPath = join(cwd, candidate);
+    if (!existsSync(fullPath)) continue;
+    const content = readFileSync(fullPath, 'utf-8');
+    if (content.includes('</body>')) {
+      return { path: candidate, fullPath, content };
+    }
+  }
+  return null;
+}
+
+function findNextjsLayout(cwd) {
+  const candidates = [
+    'src/app/layout.tsx', 'src/app/layout.jsx', 'src/app/layout.js',
+    'app/layout.tsx', 'app/layout.jsx', 'app/layout.js',
+  ];
+
+  for (const candidate of candidates) {
+    const fullPath = join(cwd, candidate);
+    if (!existsSync(fullPath)) continue;
+    return { path: candidate, fullPath, content: readFileSync(fullPath, 'utf-8') };
+  }
+  return null;
+}
+
+function findAgentEntry(cwd) {
+  const candidates = [
+    'src/agent.ts', 'src/agent.js',
+    'src/index.ts', 'src/index.js',
+    'agent.ts', 'agent.js',
+    'index.ts', 'index.js',
+  ];
+
+  for (const candidate of candidates) {
+    const fullPath = join(cwd, candidate);
+    if (!existsSync(fullPath)) continue;
+    const content = readFileSync(fullPath, 'utf-8');
+    if (content.includes('openai') || content.includes('anthropic') || content.includes('langchain') ||
+        content.includes('ChatOpenAI') || content.includes('Anthropic')) {
+      return { path: candidate, fullPath, content };
+    }
+  }
+  return null;
+}
+
+// --- Injectors ---
+
+function injectImportAndMiddleware(content, isTs) {
+  const importLine = `import { feedbackHandler } from 'hearback-server';`;
+  const middlewareBlock = [
+    '',
+    '// hearback feedback widget',
+    `app.use('/feedback', feedbackHandler({`,
+    `  repo: process.env.FEEDBACK_REPO${isTs ? '!' : ''},`,
+    `  githubToken: process.env.GITHUB_TOKEN${isTs ? '!' : ''},`,
+    `}));`,
+  ].join('\n');
+
+  if (content.includes('hearback-server')) return content;
+
+  const lines = content.split('\n');
+  const result = [];
+  let importInserted = false;
+  let middlewareInserted = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Insert import after the last import/require line
+    if (!importInserted && (line.startsWith('import ') || line.includes('require('))) {
+      // Check if next line is NOT an import — insert after this one
+      const nextLine = lines[i + 1] ?? '';
+      if (!nextLine.startsWith('import ') && !nextLine.includes('require(')) {
+        result.push(line);
+        result.push(importLine);
+        importInserted = true;
+        continue;
+      }
+    }
+
+    // Insert middleware before .listen()
+    if (!middlewareInserted && line.includes('.listen(')) {
+      result.push(middlewareBlock);
+      middlewareInserted = true;
+    }
+
+    result.push(line);
+  }
+
+  // Fallback: add import at top if no imports found
+  if (!importInserted) {
+    result.unshift(importLine);
+  }
+
+  // Fallback: add middleware at end if no .listen() found
+  if (!middlewareInserted) {
+    result.push(middlewareBlock);
+  }
+
+  return result.join('\n');
+}
+
+function injectWidgetScript(content, endpoint) {
+  const scriptTag = `<script src="https://unpkg.com/hearback-widget/dist/widget.js" data-endpoint="${endpoint}"></script>`;
+
+  if (content.includes('hearback-widget')) return content;
+
+  // Insert before </body>
+  return content.replace('</body>', `  ${scriptTag}\n</body>`);
+}
+
+function injectNextjsWidget(content, endpoint) {
+  const scriptImport = `import Script from 'next/script';`;
+  const scriptTag = `        <Script src="https://unpkg.com/hearback-widget/dist/widget.js" data-endpoint="${endpoint}" strategy="lazyOnload" />`;
+
+  if (content.includes('hearback-widget')) return content;
+
+  // Add Script import if not present — find the LAST import statement and
+  // insert after it. If no imports exist, prepend to the file.
+  let result = content;
+  if (!result.includes("from 'next/script'") && !result.includes('from "next/script"')) {
+    const lines = result.split('\n');
+    let lastImportIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+      if (/^import\s/.test(lines[i])) lastImportIdx = i;
+    }
+    if (lastImportIdx >= 0) {
+      lines.splice(lastImportIdx + 1, 0, scriptImport);
+    } else {
+      lines.unshift(scriptImport);
+    }
+    result = lines.join('\n');
+  }
+
+  // Add before </body>. Put on its own line (preserve surrounding whitespace).
+  result = result.replace(/(\s*)<\/body>/, `\n${scriptTag}$1</body>`);
+
+  return result;
+}
+
+// --- Detect project type ---
+
+function detectProject(cwd) {
+  const pkgPath = join(cwd, 'package.json');
+  if (!existsSync(pkgPath)) return { type: 'unknown' };
+
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+  if (deps['next']) {
+    return { type: 'nextjs', pkg, deps };
+  }
+  if (deps['express']) return { type: 'express', pkg, deps };
+  if (deps['hono']) return { type: 'hono', pkg, deps };
+  if (deps['openai'] || deps['@anthropic-ai/sdk'] || deps['langchain'] || deps['@langchain/core']) {
+    return { type: 'agent', pkg, deps };
+  }
+  if (deps['fastify']) return { type: 'fastify', pkg, deps };
+
+  return { type: 'node', pkg, deps };
+}
+
+// --- Templates ---
+
+const NEXTJS_ROUTE = `import { NextRequest, NextResponse } from 'next/server';
+import { createFeedbackHandler } from 'hearback-server';
+
+const handler = createFeedbackHandler({
+  repo: process.env.FEEDBACK_REPO!,
+  githubToken: process.env.GITHUB_TOKEN!,
+  llm: process.env.OPENAI_API_KEY ? { apiKey: process.env.OPENAI_API_KEY } : undefined,
+});
+
+async function handleRequest(req: NextRequest) {
+  const url = new URL(req.url);
+  const path = url.pathname.replace('/api/feedback', '') || '/';
+  const body = req.method === 'POST' ? await req.json() : undefined;
+
+  const result = await handler.handle({
+    method: req.method,
+    path,
+    body,
+    ip: req.headers.get('x-forwarded-for')?.split(',')[0] ?? '127.0.0.1',
+    headers: Object.fromEntries(req.headers.entries()),
+  });
+
+  if (result.body && typeof result.body === 'object' && 'getReader' in (result.body as object)) {
+    return new Response(result.body as ReadableStream, {
+      status: result.status,
+      headers: result.headers,
+    });
+  }
+
+  return NextResponse.json(result.body, {
+    status: result.status,
+    headers: result.headers,
+  });
+}
+
+export const GET = handleRequest;
+export const POST = handleRequest;
+export const OPTIONS = handleRequest;
+`;
+
+const NOTIFY_WORKFLOW = `name: Notify Reporter
+on:
+  issues:
+    types: [closed, labeled]
+jobs:
+  notify:
+    if: |
+      (github.event.action == 'closed' && contains(github.event.issue.labels.*.name, 'hearback')) ||
+      (github.event.action == 'labeled' && github.event.label.name == 'feedback-responded')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          repository: agent-team-foundation/hearback
+          ref: v0.1.0
+          path: .hearback
+      - uses: ./.hearback/.github/actions/notify
+        with:
+          github-token: \${{ secrets.GITHUB_TOKEN }}
+          resend-api-key: \${{ secrets.RESEND_API_KEY }}
+`;
+
+// --- Main ---
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === 'help' || command === '--help') {
+    log(`
+${BOLD}hearback${RESET} — add user feedback loop to any product
+
+${BOLD}Usage:${RESET}
+  npx hearback init     Set up hearback in the current project
+  npx hearback help     Show this help
+`);
+    return;
+  }
+
+  if (command !== 'init') {
+    log(`Unknown command: ${command}. Run "npx hearback help" for usage.`);
+    process.exit(1);
+  }
+
+  const cwd = process.cwd();
+
+  log(`\n${BOLD}🎯 hearback init${RESET}`);
+  log(`${DIM}Add user feedback → GitHub Issues → email notification${RESET}`);
+
+  // Step 1: Detect
+  step(1, 'Detecting project...');
+  const project = detectProject(cwd);
+
+  if (project.type === 'unknown') {
+    warn('No package.json found. Run this from your project root.');
+    process.exit(1);
+  }
+
+  const typeLabels = {
+    nextjs: 'Next.js',
+    express: 'Express',
+    hono: 'Hono',
+    fastify: 'Fastify',
+    agent: 'AI Agent',
+    node: 'Node.js',
+  };
+  done(`${typeLabels[project.type] ?? project.type} project`);
+
+  // Step 2: Collect info
+  step(2, 'Configuration');
+  const repo = await ask('GitHub repo for issues (owner/name):');
+  if (!repo || !repo.includes('/')) {
+    warn('Invalid repo format. Expected: owner/name');
+    process.exit(1);
+  }
+
+  // Step 3: Install
+  step(3, 'Installing packages...');
+
+  const pkgToInstall = project.type === 'agent' ? 'hearback-agent-skill' : 'hearback-server';
+  try {
+    execSync(`npm install ${pkgToInstall}`, { cwd, stdio: 'pipe' });
+    done(`${pkgToInstall} installed`);
+  } catch {
+    warn(`Could not install ${pkgToInstall} (not yet published to npm)`);
+    info(`When available, run: npm install ${pkgToInstall}`);
+  }
+
+  // Step 4: Generate & inject
+  step(4, 'Injecting code...');
+
+  let widgetEndpoint = '/feedback';
+
+  if (project.type === 'nextjs') {
+    // Create API route
+    const appBase = existsSync(join(cwd, 'src/app')) ? 'src/app' : 'app';
+    const routeDir = join(cwd, appBase, 'api/feedback/[...path]');
+    mkdirSync(routeDir, { recursive: true });
+    writeFileSync(join(routeDir, 'route.ts'), NEXTJS_ROUTE);
+    done(`Created ${appBase}/api/feedback/[...path]/route.ts`);
+
+    widgetEndpoint = '/api/feedback';
+
+    // Inject widget into layout
+    const layout = findNextjsLayout(cwd);
+    if (layout) {
+      const updated = injectNextjsWidget(layout.content, widgetEndpoint);
+      if (updated !== layout.content) {
+        writeFileSync(layout.fullPath, updated);
+        done(`Added widget to ${layout.path}`);
+      }
+    } else {
+      warn('Could not find layout file — add the widget script manually:');
+      info(`<Script src="https://unpkg.com/hearback-widget/dist/widget.js" data-endpoint="${widgetEndpoint}" strategy="lazyOnload" />`);
+    }
+
+  } else if (project.type === 'agent') {
+    // Agent project — inject skill setup
+    const entry = findAgentEntry(cwd);
+    if (entry) {
+      const isTs = entry.path.endsWith('.ts');
+      const importLine = `import { feedbackSkill } from 'hearback-agent-skill';\n`;
+      const setupBlock = `\n// hearback feedback skill\nconst hearbackSkill = feedbackSkill({\n  repo: process.env.FEEDBACK_REPO${isTs ? '!' : ''},\n  githubToken: process.env.GITHUB_TOKEN${isTs ? '!' : ''},\n});\n// hearbackSkill.instructions → add to system prompt\n// hearbackSkill.tools.openai  → register as tools\n// hearbackSkill.handlers      → execute tool calls\n`;
+
+      let content = entry.content;
+      if (!content.includes('hearback-agent-skill')) {
+        const lastImportIdx = Math.max(content.lastIndexOf('import '), content.lastIndexOf('require('));
+        if (lastImportIdx !== -1) {
+          const lineEnd = content.indexOf('\n', lastImportIdx);
+          content = content.slice(0, lineEnd + 1) + importLine + content.slice(lineEnd + 1);
+        } else {
+          content = importLine + content;
+        }
+        content += setupBlock;
+        writeFileSync(entry.fullPath, content);
+        done(`Injected skill setup into ${entry.path}`);
+      } else {
+        info(`${entry.path} already has hearback-agent-skill`);
+      }
+    } else {
+      warn('Could not find agent entry file');
+      info('Add to your agent setup:');
+      log(`\n  ${DIM}import { feedbackSkill } from 'hearback-agent-skill';${RESET}\n`);
+    }
+
+  } else {
+    // Express / Hono / Fastify / generic Node
+    const serverFile = findServerEntry(cwd);
+    if (serverFile) {
+      const isTs = serverFile.path.endsWith('.ts');
+      const updated = injectImportAndMiddleware(serverFile.content, isTs);
+      if (updated !== serverFile.content) {
+        writeFileSync(serverFile.fullPath, updated);
+        done(`Injected middleware into ${serverFile.path}`);
+      } else {
+        info(`${serverFile.path} already has hearback middleware`);
+      }
+    } else {
+      warn('Could not find server entry file');
+      info('Add to your server:');
+      log(`\n  ${DIM}import { feedbackHandler } from 'hearback-server';`);
+      log(`  app.use('/feedback', feedbackHandler({ repo: process.env.FEEDBACK_REPO, githubToken: process.env.GITHUB_TOKEN }));${RESET}\n`);
+    }
+
+    // Inject widget into HTML
+    const html = findHtmlLayout(cwd);
+    if (html) {
+      const updated = injectWidgetScript(html.content, widgetEndpoint);
+      if (updated !== html.content) {
+        writeFileSync(html.fullPath, updated);
+        done(`Added widget to ${html.path}`);
+      }
+    } else {
+      info('No HTML file found — add before </body>:');
+      log(`\n  ${DIM}<script src="https://unpkg.com/hearback-widget/dist/widget.js" data-endpoint="${widgetEndpoint}"></script>${RESET}\n`);
+    }
+  }
+
+  // Env vars
+  const envFile = existsSync(join(cwd, '.env.local')) ? '.env.local' : '.env';
+  const envPath = join(cwd, envFile);
+  const envContent = existsSync(envPath) ? readFileSync(envPath, 'utf-8') : '';
+
+  const newVars = [];
+  if (!envContent.includes('FEEDBACK_REPO')) newVars.push(`FEEDBACK_REPO=${repo}`);
+  if (!envContent.includes('GITHUB_TOKEN')) newVars.push(`GITHUB_TOKEN=  # Create at https://github.com/settings/tokens?type=beta (needs issues:write + contents:write)`);
+
+  if (newVars.length > 0) {
+    const addition = '\n# hearback\n' + newVars.join('\n') + '\n';
+    writeFileSync(envPath, envContent + addition);
+    done(`Added env vars to ${envFile}`);
+  }
+
+  // Step 5: Notification workflow
+  step(5, 'Notification loop');
+  const wantNotify = await confirm('Set up email notifications when issues are fixed?');
+
+  if (wantNotify) {
+    const workflowDir = join(cwd, '.github/workflows');
+    mkdirSync(workflowDir, { recursive: true });
+    writeFileSync(join(workflowDir, 'feedback-notify.yml'), NOTIFY_WORKFLOW);
+    done('Created .github/workflows/feedback-notify.yml');
+    info('Add RESEND_API_KEY to your repo secrets (free at resend.com)');
+  }
+
+  // Done
+  log(`\n${GREEN}${BOLD}✓ hearback is ready!${RESET}\n`);
+  log(`${DIM}Next steps:`);
+  log(`  1. Add your GITHUB_TOKEN to ${envFile}`);
+  log(`  2. Run your dev server and test the feedback button${RESET}\n`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "hearback",
+  "version": "0.1.0",
+  "description": "Add user feedback → GitHub Issues → email notification loop to any product with one command. Works with Next.js, Express, Hono, and AI agents.",
+  "type": "module",
+  "bin": {
+    "hearback": "./bin/hearback.js"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "echo 'no build needed'",
+    "clean": "echo 'nothing to clean'"
+  },
+  "keywords": [
+    "hearback",
+    "feedback",
+    "bug-report",
+    "github-issues",
+    "cli",
+    "init",
+    "scaffold",
+    "widget",
+    "agent",
+    "nextjs",
+    "express"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agent-team-foundation/hearback.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/agent-team-foundation/hearback/issues"
+  },
+  "homepage": "https://github.com/agent-team-foundation/hearback#readme",
+  "license": "MIT"
+}