@prustogi/buddy 0.3.0

package/src/lib/paths.js

@@ -0,0 +1,59 @@
+import { existsSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Walk upward from cwd looking for a repo root signal (.git or .buddy or package.json).
+// Falls back to cwd if nothing is found.
+export function findRepoRoot(start = process.cwd()) {
+  let dir = resolve(start);
+  while (true) {
+    if (
+      existsSync(join(dir, '.git')) ||
+      existsSync(join(dir, '.buddy')) ||
+      existsSync(join(dir, 'package.json'))
+    ) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return resolve(start);
+    dir = parent;
+  }
+}
+
+export function buddyDir(repoRoot = findRepoRoot()) {
+  return join(repoRoot, '.buddy');
+}
+
+export function packageRoot() {
+  return resolve(__dirname, '..', '..');
+}
+
+export function templatesDir() {
+  return join(packageRoot(), 'templates', '.buddy');
+}
+
+export function agentPromptPath() {
+  return join(packageRoot(), 'agents', 'buddy.agent.md');
+}
+
+export function claudeAgentPromptPath() {
+  return join(packageRoot(), 'agents', 'buddy-claude.agent.md');
+}
+
+export function isDir(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function isFile(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}

package/src/lib/redact.js

@@ -0,0 +1,46 @@
+// Redact secrets from URLs before storing them.
+// Returns { url, redacted: boolean, warnings: string[] }.
+
+const SENSITIVE_QUERY_KEYS = [
+  'token', 'access_token', 'refresh_token', 'id_token',
+  'apikey', 'api_key', 'auth', 'authorization',
+  'password', 'pwd', 'secret', 'client_secret',
+  'sig', 'signature', 'sas', 'sastoken',
+  'key', 'private_key',
+];
+
+export function redactUrl(input) {
+  const warnings = [];
+  let url;
+  try {
+    url = new URL(input);
+  } catch {
+    return { url: input, redacted: false, warnings: ['Not a valid URL — stored as-is.'] };
+  }
+
+  let redacted = false;
+
+  if (url.username || url.password) {
+    url.username = '';
+    url.password = '';
+    warnings.push('Stripped userinfo (user:pass@) from URL.');
+    redacted = true;
+  }
+
+  for (const key of [...url.searchParams.keys()]) {
+    if (SENSITIVE_QUERY_KEYS.includes(key.toLowerCase())) {
+      url.searchParams.set(key, 'REDACTED');
+      warnings.push(`Redacted query parameter: ${key}`);
+      redacted = true;
+    }
+  }
+
+  // Heuristic: hash fragment containing access_token=...
+  if (url.hash && /access_token=|id_token=/i.test(url.hash)) {
+    url.hash = '#REDACTED';
+    warnings.push('Redacted sensitive URL fragment.');
+    redacted = true;
+  }
+
+  return { url: url.toString(), redacted, warnings };
+}

package/src/lib/scaffold.js

@@ -0,0 +1,31 @@
+import { readdirSync, statSync, mkdirSync, copyFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Recursively copy a template directory tree without overwriting existing files.
+// Returns { created: string[], skipped: string[] }.
+export function copyTree(srcDir, dstDir) {
+  const created = [];
+  const skipped = [];
+  walk(srcDir, dstDir, created, skipped);
+  return { created, skipped };
+}
+
+function walk(src, dst, created, skipped) {
+  if (!existsSync(dst)) {
+    mkdirSync(dst, { recursive: true });
+  }
+  for (const entry of readdirSync(src)) {
+    const s = join(src, entry);
+    const d = join(dst, entry);
+    if (statSync(s).isDirectory()) {
+      walk(s, d, created, skipped);
+    } else {
+      if (existsSync(d)) {
+        skipped.push(d);
+      } else {
+        copyFileSync(s, d);
+        created.push(d);
+      }
+    }
+  }
+}

package/templates/.buddy/ARCHITECTURE.md

@@ -0,0 +1,28 @@
+🏠 [Home](./README_FOR_HUMANS.md) · [Getting Started](./GETTING_STARTED.md) · [Architecture](./ARCHITECTURE.md) · [Tech](./TECH_STACK.md) · [Integrations](./INTEGRATIONS.md) · [Repo Map](./MAP/repo_map.md) · [Links](./LINKS.md)
+
+---
+
+# Architecture
+
+> ⚠️ This is an **initial template**. After Buddy scans the repo, sections here will be marked either **Verified** (read from code/docs) or **Inferred** (Buddy's best guess — double-check).
+
+## Big picture
+
+*(One paragraph: what the system does, in plain words.)*
+
+## Major components
+
+| Component | Where in the code | Responsibility |
+|---|---|---|
+| *(tbd)* | *(tbd)* | *(tbd)* |
+
+## Request / data flow
+
+*(Describe a typical request from start to finish, end-to-end.)*
+
+1. *(tbd)*
+2. *(tbd)*
+
+## Key boundaries
+
+- *(What lives where; what depends on what.)*

package/templates/.buddy/CHANGELOG_SUMMARY.md

@@ -0,0 +1,9 @@
+🏠 [Home](./README_FOR_HUMANS.md) · [Getting Started](./GETTING_STARTED.md) · [Architecture](./ARCHITECTURE.md) · [Tech](./TECH_STACK.md) · [Integrations](./INTEGRATIONS.md) · [Repo Map](./MAP/repo_map.md) · [Links](./LINKS.md)
+
+---
+
+# Recent Changes (Human-Friendly)
+
+> Buddy summarizes recent commits here in plain words. Updated when you run `buddy precheck` and ask Buddy to "update buddy".
+
+*(empty — no commits scanned yet)*

package/templates/.buddy/GETTING_STARTED.md

@@ -0,0 +1,39 @@
+🏠 [Home](./README_FOR_HUMANS.md) · [Getting Started](./GETTING_STARTED.md) · [Architecture](./ARCHITECTURE.md) · [Tech](./TECH_STACK.md) · [Integrations](./INTEGRATIONS.md) · [Repo Map](./MAP/repo_map.md) · [Links](./LINKS.md)
+
+---
+
+# Getting Started
+
+> Buddy will fill this in after scanning the repo. Until then, here's a template.
+
+## Prerequisites
+
+- *(e.g. Node 18+, Python 3.11, Docker)*
+
+## Install
+
+```bash
+# Buddy will replace this with the real command from package.json / Makefile / etc.
+```
+
+## Run locally
+
+```bash
+# Buddy will replace this with the real command.
+```
+
+## Run tests
+
+```bash
+# Buddy will replace this with the real command.
+```
+
+## Common problems
+
+*(Buddy will collect these as it learns from the repo and your questions.)*
+
+## Where things live
+
+- **Logs:**
+- **Config:**
+- **Secrets / env vars:**

package/templates/.buddy/INDEX/links.json

@@ -0,0 +1,4 @@
+{
+  "schema_version": 1,
+  "links": []
+}

package/templates/.buddy/INTEGRATIONS.md

@@ -0,0 +1,15 @@
+🏠 [Home](./README_FOR_HUMANS.md) · [Getting Started](./GETTING_STARTED.md) · [Architecture](./ARCHITECTURE.md) · [Tech](./TECH_STACK.md) · [Integrations](./INTEGRATIONS.md) · [Repo Map](./MAP/repo_map.md) · [Links](./LINKS.md)
+
+---
+
+# External Integrations
+
+> Anything the project talks to: databases, queues, auth providers, third-party APIs.
+
+| Service | What it's used for | Where configured |
+|---|---|---|
+| *(tbd)* | *(tbd)* | *(tbd)* |
+
+## Secrets & env vars
+
+- *(Where they live; never paste actual values here.)*

package/templates/.buddy/LINKS.md

@@ -0,0 +1,30 @@
+🏠 [Home](./README_FOR_HUMANS.md) · [Getting Started](./GETTING_STARTED.md) · [Architecture](./ARCHITECTURE.md) · [Tech](./TECH_STACK.md) · [Integrations](./INTEGRATIONS.md) · [Repo Map](./MAP/repo_map.md) · [Links](./LINKS.md)
+
+---
+
+# Important Links
+
+> External docs, design docs, runbooks, dashboards — anything a teammate would want to know about.
+
+Add a link from the terminal:
+```bash
+buddy link https://example.com/doc --title "Payments design" --tags architecture,payments --relevance must-read
+```
+
+Or ask Buddy in Copilot CLI: *"here's a link: https://… it's our oncall runbook."*
+
+> ⚠️ Buddy never reads the linked page. It only stores metadata. If you want a summary, paste the contents into the chat.
+
+---
+
+## Must-read
+
+*(none yet)*
+
+## Helpful
+
+*(none yet)*
+
+## Optional
+
+*(none yet)*

package/templates/.buddy/MAP/data_flow.md

@@ -0,0 +1,13 @@
+🏠 [Home](../README_FOR_HUMANS.md) · [Getting Started](../GETTING_STARTED.md) · [Architecture](../ARCHITECTURE.md) · [Tech](../TECH_STACK.md) · [Integrations](../INTEGRATIONS.md) · [Repo Map](../MAP/repo_map.md) · [Links](../LINKS.md)
+
+---
+
+# Data Flow
+
+> The simple version: "X happens → it goes here → then here → then here."
+
+## Common flows
+
+### *(flow name)*
+1. *(tbd)*
+2. *(tbd)*

package/templates/.buddy/MAP/entry_points.md

@@ -0,0 +1,11 @@
+🏠 [Home](../README_FOR_HUMANS.md) · [Getting Started](../GETTING_STARTED.md) · [Architecture](../ARCHITECTURE.md) · [Tech](../TECH_STACK.md) · [Integrations](../INTEGRATIONS.md) · [Repo Map](../MAP/repo_map.md) · [Links](../LINKS.md)
+
+---
+
+# Entry Points
+
+> Where execution starts. Servers, CLIs, jobs, schedulers — anything that runs.
+
+| Entry | File | What it does |
+|---|---|---|
+| *(tbd)* | *(tbd)* | *(tbd)* |

package/templates/.buddy/MAP/repo_map.md

@@ -0,0 +1,17 @@
+🏠 [Home](../README_FOR_HUMANS.md) · [Getting Started](../GETTING_STARTED.md) · [Architecture](../ARCHITECTURE.md) · [Tech](../TECH_STACK.md) · [Integrations](../INTEGRATIONS.md) · [Repo Map](../MAP/repo_map.md) · [Links](../LINKS.md)
+
+---
+
+# Repo Map
+
+> A folder-by-folder tour of where things live and where to start reading.
+
+## Top-level folders
+
+| Folder | Purpose | Start here? |
+|---|---|---|
+| *(tbd)* | *(tbd)* | *(tbd)* |
+
+## Where to start reading code
+
+1. *(tbd — Buddy will recommend a reading order)*

package/templates/.buddy/NOTES/assumptions.md

@@ -0,0 +1,9 @@
+🏠 [Home](../README_FOR_HUMANS.md) · [Getting Started](../GETTING_STARTED.md) · [Architecture](../ARCHITECTURE.md) · [Tech](../TECH_STACK.md) · [Integrations](../INTEGRATIONS.md) · [Repo Map](../MAP/repo_map.md) · [Links](../LINKS.md)
+
+---
+
+# Assumptions
+
+> Anything Buddy guessed at. **These are not facts.** Verify before relying on them.
+
+*(none yet)*

package/templates/.buddy/NOTES/open_questions.md

@@ -0,0 +1,9 @@
+🏠 [Home](../README_FOR_HUMANS.md) · [Getting Started](../GETTING_STARTED.md) · [Architecture](../ARCHITECTURE.md) · [Tech](../TECH_STACK.md) · [Integrations](../INTEGRATIONS.md) · [Repo Map](../MAP/repo_map.md) · [Links](../LINKS.md)
+
+---
+
+# Open Questions
+
+> Things Buddy couldn't figure out from the repo alone. Help fill these in!
+
+*(none yet)*

package/templates/.buddy/README_FOR_HUMANS.md

@@ -0,0 +1,44 @@
+# Welcome! 👋
+
+Hi there! I'm **Buddy**. This file is your home page in this repo.
+
+> **First time here?** This file (and everything in `.buddy/`) is auto-generated to help you understand the project quickly. If sections below look empty or generic, ask Buddy in Copilot CLI: *"Scan this repo and fill in .buddy/."*
+
+---
+
+## What is this project?
+
+*(Buddy will fill this in after the first scan.)*
+
+- **What it does:**
+- **Who uses it:**
+- **Why it exists:**
+
+## Big-picture concepts
+
+*(The 3-5 ideas you need to know before reading any code.)*
+
+## Quick links
+
+- 🚀 **Just want to run it?** → [`GETTING_STARTED.md`](./GETTING_STARTED.md)
+- 🗺️ **Where does code live?** → [`MAP/repo_map.md`](./MAP/repo_map.md)
+- 🏛️ **How is it built?** → [`ARCHITECTURE.md`](./ARCHITECTURE.md)
+- 🧰 **What tech does it use?** → [`TECH_STACK.md`](./TECH_STACK.md)
+- 🔌 **What does it talk to?** → [`INTEGRATIONS.md`](./INTEGRATIONS.md)
+- 📎 **Important external docs** → [`LINKS.md`](./LINKS.md)
+- ❓ **Things Buddy isn't sure about** → [`NOTES/open_questions.md`](./NOTES/open_questions.md)
+
+---
+
+## How to use Buddy
+
+In your terminal:
+- `buddy status` — Is the knowledge here up to date?
+- `buddy precheck` — Show docs that may be stale based on recent changes.
+- `buddy open <name>` — Open a Buddy doc (try: `buddy open getting-started`).
+- `buddy link <url>` — Save an important link with safe redaction.
+
+In Copilot CLI (after `buddy agent` and `/agents add buddy`):
+- Ask: *"Scan this repo and fill in .buddy/"*
+- Ask: *"Where does login happen?"*
+- Ask: *"Update buddy for my changes"* (before committing)

package/templates/.buddy/TECH_STACK.md

@@ -0,0 +1,27 @@
+🏠 [Home](./README_FOR_HUMANS.md) · [Getting Started](./GETTING_STARTED.md) · [Architecture](./ARCHITECTURE.md) · [Tech](./TECH_STACK.md) · [Integrations](./INTEGRATIONS.md) · [Repo Map](./MAP/repo_map.md) · [Links](./LINKS.md)
+
+---
+
+# Tech Stack
+
+> Buddy fills this in based on actual repo evidence (package.json, requirements.txt, go.mod, pom.xml, etc.).
+
+## Languages
+
+- *(tbd)*
+
+## Frameworks
+
+- *(tbd)*
+
+## Build & package
+
+- *(tbd)*
+
+## Tests
+
+- *(tbd)*
+
+## CI / Deploy
+
+- *(tbd)*