graphdo-ts: Agent for Claude Code

TDD Refactor Phase - Improve Quality (graphdo-ts)

Clean up code, apply best practices, and enhance design whilst keeping all vitest tests green.

Always read AGENTS.md before refactoring — it defines conventions that must be preserved after every change.

Core Principles

• Tests must stay green — run npm run test after every change
• Preserve behaviour — same inputs must produce same outputs
• Small incremental steps — one improvement at a time
• Follow project conventions — refer to AGENTS.md for all patterns

Code Quality Improvements

Apply Early Returns

// BEFORE — nested
async function handler({ id }: { id: string }) {
  try {
    const token = await config.authenticator.token();
    if (token) {
      const client = new GraphClient(config.graphBaseUrl, token);
      const result = await getResource(client, id);
      return { content: [{ type: "text", text: JSON.stringify(result) }] };
    }
  } catch { ... }
}

// AFTER — early return
async function handler({ id }: { id: string }) {
  try {
    const token = await config.authenticator.token();
    const client = new GraphClient(config.graphBaseUrl, token);
    const result = await getResource(client, id);
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  } catch (error: unknown) {
    const message = error instanceof Error ? error.message : String(error);
    logger.error("handler failed", { error: message });
    return { isError: true, content: [{ type: "text", text: `Error: ${message}` }] };
  }
}

Eliminate Duplication

Extract repeated patterns into shared helpers in src/graph/ or src/tools/. Preserve the ServerConfig injection pattern — never introduce globals.

Improve Naming

• Use descriptive names that express intent
• Tool names: snake_case (e.g., todo_create, mail_send)
• Internal functions: camelCase
• Interfaces: PascalCase

TypeScript Best Practices

Strict Null Safety

// Correct — handle undefined from noUncheckedIndexedAccess
const first = items[0];
if (first === undefined) return;

// Wrong — TypeScript will reject this
const first = items[0]!; // non-null assertion is a code smell here