spotme 0.1.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "spotme",
+  "version": "0.1.0",
+  "description": "SpotMe — gym mode for agentic coding. Works with OpenCode and Pi.",
+  "author": {
+    "name": "wtfzambo"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./opencode": "./dist/opencode.js",
+    "./pi": "./dist/pi.js"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wtfzambo/spotme"  },
+  "scripts": {
+    "build": "bun build src/index.ts src/opencode.ts src/pi.ts --outdir dist --target bun",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write src"
+  },
+  "keywords": [
+    "pi-package",
+    "opencode-plugin",
+    "spotme",
+    "gym-mode",
+    "coding-agent"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/pi.ts"
+    ],
+    "skills": [
+      "."
+    ]
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "latest",
+    "@opencode-ai/plugin": "^1.14.0",
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/bun": "^1.1.0",
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "8.47.0",
+    "@typescript-eslint/parser": "8.47.0",
+    "backlog.md": "^1.45.1",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-prettier": "^5.1.3",
+    "prettier": "^3.2.4",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.47.0"
+  }
+}

package/src/engine.ts

@@ -0,0 +1,162 @@
+// ─── SpotMe Engine ─────────────────────────────────────────────────────────
+// Platform-agnostic core logic. Adapters (OpenCode, Pi, etc.) delegate here.
+
+import { blockedMessage, exerciseReadyMessage, statusMessage } from './prompts.js';
+import type { Difficulty, SpotMeState } from './types.js';
+import { CODE_WRITE_TOOLS, parseArgs } from './types.js';
+
+// ─── Platform adapter interface ─────────────────────────────────────────────
+
+export interface PlatformAdapter {
+  /** Resolve a raw file path (possibly absolute) to { fullPath, relativePath }. */
+  resolvePath(_rawPath: string): { fullPath: string; relativePath: string };
+
+  /** Return true if the file at `fullPath` exists on disk. */
+  fileExists(_fullPath: string): Promise<boolean>;
+}
+
+// ─── Return types for engine methods ────────────────────────────────────────
+
+export interface ActivateResult {
+  message: string;
+}
+
+export interface ExerciseResult {
+  message: string;
+  filePath: string;
+}
+
+export type WriteInterceptResult = { blocked: false } | { blocked: true; message: string };
+
+// ─── Engine ─────────────────────────────────────────────────────────────────
+
+export class SpotMeEngine {
+  readonly state: SpotMeState;
+  private exercisePending = false;
+  private readonly platform: PlatformAdapter;
+
+  constructor(platform: PlatformAdapter) {
+    this.platform = platform;
+    this.state = {
+      enabled: false,
+      difficulty: 'medium',
+      every: 2,
+      counter: 0,
+      exercise: null,
+    };
+  }
+
+  // ── Lifecycle ───────────────────────────────────────────────────────────
+
+  /**
+   * Activate SpotMe with the given (or current) settings.
+   * Called by the /spotme:on command hook or the spotme_on tool.
+   */
+  activate(args?: { difficulty?: Difficulty; every?: number }): ActivateResult {
+    if (args?.difficulty) this.state.difficulty = args.difficulty;
+    if (args?.every) this.state.every = Math.max(1, Math.floor(args.every));
+    this.state.enabled = true;
+    this.state.counter = 0;
+    this.state.exercise = null;
+    this.exercisePending = false;
+    return {
+      message: `🏋️ SpotMe is on. Difficulty: ${this.state.difficulty}. Triggering every ${this.state.every} code write(s).`,
+    };
+  }
+
+  /**
+   * Activate from raw CLI args string (e.g. "hard --every 3").
+   * Parses args using current state as defaults.
+   */
+  activateFromArgs(rawArgs: string): ActivateResult {
+    const parsed = parseArgs(rawArgs, this.state);
+    return this.activate(parsed);
+  }
+
+  /** Deactivate SpotMe entirely. */
+  deactivate(): void {
+    this.state.enabled = false;
+    this.state.exercise = null;
+    this.state.counter = 0;
+    this.exercisePending = false;
+  }
+
+  // ── Exercise lifecycle ──────────────────────────────────────────────────
+
+  /**
+   * Record an exercise start. Called by the spotme_exercise tool AFTER the
+   * scaffold file has been written.
+   */
+  async recordExercise(
+    unit: string,
+    rawFilePath: string,
+    difficulty: Difficulty
+  ): Promise<ExerciseResult> {
+    const { fullPath, relativePath } = this.platform.resolvePath(rawFilePath);
+
+    if (!(await this.platform.fileExists(fullPath))) {
+      throw new Error(
+        `Scaffold file not found at ${fullPath}. Write the scaffold with the Write tool first, then call spotme_exercise.`
+      );
+    }
+
+    this.exercisePending = false;
+    this.state.exercise = {
+      active: true,
+      unit,
+      filePath: relativePath,
+      difficulty,
+    };
+    this.state.counter = 0;
+
+    return {
+      message: exerciseReadyMessage(unit, relativePath, difficulty),
+      filePath: relativePath,
+    };
+  }
+
+  /** Close the current exercise. Called by spotme_end tool. */
+  endExercise(): string {
+    this.state.exercise = null;
+    this.state.counter = 0;
+    this.exercisePending = false;
+    return '✅ Exercise closed. Counter reset. Resuming normal mode.';
+  }
+
+  // ── Status ──────────────────────────────────────────────────────────────
+
+  getStatus(): string {
+    return statusMessage(this.state);
+  }
+
+  // ── Write interception ────────────────────────────────────────────────
+
+  /**
+   * Called before every tool execution. Returns whether the write should be
+   * blocked (exercise trigger) or allowed.
+   *
+   * @param toolName - Name of the tool being executed.
+   * @param filePath - File path argument from the tool call (may be empty).
+   */
+  interceptWriteToolCall(toolName: string, filePath: string): WriteInterceptResult {
+    if (!this.state.enabled) return { blocked: false };
+
+    // Bypass: scaffold write in progress, or exercise active (user implementing).
+    if (this.exercisePending || this.state.exercise?.active) return { blocked: false };
+
+    // Only count code-writing tools.
+    if (!CODE_WRITE_TOOLS.has(toolName)) return { blocked: false };
+
+    this.state.counter++;
+    if (this.state.counter >= this.state.every) {
+      this.state.counter = 0;
+      this.exercisePending = true;
+      return {
+        blocked: true,
+        message: blockedMessage(toolName, filePath, this.state.difficulty),
+      };
+    }
+
+    return { blocked: false };
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+// Package entry point
+export { SpotMePlugin } from './opencode.js';

package/src/opencode.ts

@@ -0,0 +1,156 @@
+// ─── OpenCode adapter ───────────────────────────────────────────────────────
+// Thin wiring layer: connects SpotMeEngine to OpenCode's plugin API.
+
+import { type Plugin, tool } from '@opencode-ai/plugin';
+import { SpotMeEngine } from './engine.js';
+import { PROMPTS } from './prompts.js';
+import type { Difficulty } from './types.js';
+
+export const SpotMePlugin: Plugin = async ({ directory, client }) => {
+  const engine = new SpotMeEngine({
+    resolvePath(rawPath) {
+      const fullPath = rawPath.startsWith('/') ? rawPath : `${directory}/${rawPath}`;
+      const relativePath = fullPath.startsWith(`${directory}/`)
+        ? fullPath.slice(directory.length + 1)
+        : rawPath;
+      return { fullPath, relativePath };
+    },
+    async fileExists(fullPath) {
+      return Bun.file(fullPath).exists();
+    },
+  });
+
+  // ─── Tools ──────────────────────────────────────────────────────────────
+
+  const spotme_on = tool({
+    description: 'Activate SpotMe gym mode with the specified difficulty and frequency.',
+    args: {
+      difficulty: tool.schema
+        .enum(['lite', 'medium', 'hard'])
+        .default('medium')
+        .describe('Exercise difficulty (default: medium)'),
+      every: tool.schema
+        .number()
+        .default(2)
+        .describe('How many code writes before triggering an exercise (default: 2)'),
+    },
+    async execute(args) {
+      const result = engine.activate({
+        difficulty: args.difficulty as Difficulty,
+        every: args.every,
+      });
+      return result.message;
+    },
+  });
+
+  const spotme_exercise = tool({
+    description:
+      'Record the start of a SpotMe coding exercise. Call this AFTER writing the scaffold with the Write tool.',
+    args: {
+      unit: tool.schema
+        .string()
+        .describe("Name of the unit being exercised (e.g. 'UserAuth.login')"),
+      filePath: tool.schema
+        .string()
+        .describe('Path to the scaffold file (already written to disk)'),
+      difficulty: tool.schema
+        .enum(['lite', 'medium', 'hard'])
+        .describe('Difficulty — must match the active session setting'),
+    },
+    async execute(args) {
+      const result = await engine.recordExercise(
+        args.unit,
+        args.filePath,
+        args.difficulty as Difficulty
+      );
+      return result.message;
+    },
+  });
+
+  const spotme_status = tool({
+    description: 'Show the current SpotMe session status.',
+    args: {},
+    async execute() {
+      return engine.getStatus();
+    },
+  });
+
+  const spotme_end = tool({
+    description:
+      'Close the current SpotMe exercise. Call this after reviewing, solving, or skipping.',
+    args: {},
+    async execute() {
+      return engine.endExercise();
+    },
+  });
+
+  // ─── Commands ─────────────────────────────────────────────────────────────
+
+  const commands: Record<string, { description: string; template: string }> = {
+    'spotme:on': {
+      description: 'Enable SpotMe gym mode [lite|medium|hard] [--every N]',
+      template: PROMPTS.ON,
+    },
+    'spotme:off': { description: 'Disable SpotMe gym mode', template: PROMPTS.OFF },
+    'spotme:status': { description: 'Show current SpotMe status', template: PROMPTS.STATUS },
+    'spotme:done': {
+      description: 'Submit your implementation for SpotMe review',
+      template: PROMPTS.DONE,
+    },
+    'spotme:hint': {
+      description: 'Get a hint for the current exercise',
+      template: PROMPTS.HINT,
+    },
+    'spotme:solve': {
+      description: 'Concede — let the agent finish the exercise',
+      template: PROMPTS.SOLVE,
+    },
+    'spotme:skip': { description: 'Skip this exercise', template: PROMPTS.SKIP },
+    'spotme:rep': {
+      description: 'Request an on-demand SpotMe exercise',
+      template: PROMPTS.REP,
+    },
+  };
+
+  // ─── Hooks ────────────────────────────────────────────────────────────────
+
+  return {
+    config: async (cfg) => {
+      cfg.command = cfg.command ?? {};
+      for (const [name, def] of Object.entries(commands)) {
+        cfg.command[name] = { template: def.template, description: def.description };
+      }
+    },
+
+    tool: { spotme_on, spotme_exercise, spotme_status, spotme_end },
+
+    'tool.execute.before': async (input, output) => {
+      const filePath = (output.args?.filePath ?? output.args?.path ?? '') as string;
+      const result = engine.interceptWriteToolCall(input.tool, filePath);
+      if (result.blocked) throw new Error(result.message);
+    },
+
+    'command.execute.before': async (input) => {
+      const { command, arguments: rawArgs } = input;
+
+      if (command === 'spotme:on') {
+        engine.activateFromArgs(rawArgs);
+        await client.tui.showToast({
+          body: {
+            title: 'SpotMe',
+            message: `🏋️ On — ${engine.state.difficulty}, every ${engine.state.every} write(s)`,
+            variant: 'success',
+          },
+        });
+        return;
+      }
+
+      if (command === 'spotme:off') {
+        engine.deactivate();
+        await client.tui.showToast({
+          body: { title: 'SpotMe', message: '⏹️ Off — normal coding resumed', variant: 'info' },
+        });
+      }
+    },
+  };
+};

package/src/pi.ts

@@ -0,0 +1,141 @@
+// ─── Pi adapter ─────────────────────────────────────────────────────────────
+// Thin wiring layer: connects SpotMeEngine to Pi's extension API.
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { isToolCallEventType } from '@earendil-works/pi-coding-agent';
+import { Type } from '@sinclair/typebox';
+import { access } from 'fs/promises';
+import { join } from 'path';
+import { SpotMeEngine } from './engine.js';
+import { PROMPTS } from './prompts.js';
+import type { Difficulty } from './types.js';
+import { CODE_WRITE_TOOLS } from './types.js';
+
+export default function (pi: ExtensionAPI) {
+  // Engine is instantiated lazily per-command since Pi doesn't provide cwd at init.
+  // We create it once and use ctx.cwd at tool-execution time.
+  let engineCwd: string | null = null;
+
+  const engine = new SpotMeEngine({
+    resolvePath(rawPath) {
+      const cwd = engineCwd ?? process.cwd();
+      const fullPath = rawPath.startsWith('/') ? rawPath : join(cwd, rawPath);
+      const relativePath = fullPath.startsWith(cwd + '/')
+        ? fullPath.slice(cwd.length + 1)
+        : rawPath;
+      return { fullPath, relativePath };
+    },
+    async fileExists(fullPath) {
+      try {
+        await access(fullPath);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  });
+
+  // ─── Tool: spotme_exercise ─────────────────────────────────────────────
+
+  pi.registerTool({
+    name: 'spotme_exercise',
+    label: 'SpotMe Exercise',
+    description:
+      'Record the start of a SpotMe coding exercise. Call this AFTER writing the scaffold with the Write tool.',
+    parameters: Type.Object({
+      unit: Type.String({ description: 'Name of the unit being exercised' }),
+      filePath: Type.String({ description: 'Path to the scaffold file (already written to disk)' }),
+      difficulty: Type.Union([Type.Literal('lite'), Type.Literal('medium'), Type.Literal('hard')], {
+        description: 'Difficulty — must match the active session setting',
+      }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      engineCwd = ctx.cwd ?? process.cwd();
+      const result = await engine.recordExercise(
+        params.unit,
+        params.filePath,
+        params.difficulty as Difficulty
+      );
+      return { content: [{ type: 'text' as const, text: result.message }], details: {} };
+    },
+  });
+
+  // ─── Commands ─────────────────────────────────────────────────────────────
+
+  pi.registerCommand('spotme:on', {
+    description: 'Enable SpotMe gym mode [lite|medium|hard] [--every N]',
+    handler: async (args) => {
+      engine.activateFromArgs(args ?? '');
+      pi.sendUserMessage(PROMPTS.ON);
+    },
+  });
+
+  pi.registerCommand('spotme:off', {
+    description: 'Disable SpotMe gym mode',
+    handler: async () => {
+      engine.deactivate();
+      pi.sendUserMessage(PROMPTS.OFF);
+    },
+  });
+
+  pi.registerCommand('spotme:status', {
+    description: 'Show current SpotMe status',
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(engine.getStatus(), 'info');
+    },
+  });
+
+  pi.registerCommand('spotme:done', {
+    description: 'Submit your implementation for review',
+    handler: async () => {
+      engine.endExercise();
+      pi.sendUserMessage(PROMPTS.DONE);
+    },
+  });
+
+  pi.registerCommand('spotme:hint', {
+    description: 'Get a targeted hint for the current exercise',
+    handler: async () => {
+      pi.sendUserMessage(PROMPTS.HINT);
+    },
+  });
+
+  pi.registerCommand('spotme:solve', {
+    description: 'Concede — let the agent complete the exercise',
+    handler: async () => {
+      engine.endExercise();
+      pi.sendUserMessage(PROMPTS.SOLVE);
+    },
+  });
+
+  pi.registerCommand('spotme:skip', {
+    description: 'Skip this exercise with no penalty',
+    handler: async () => {
+      engine.endExercise();
+      pi.sendUserMessage(PROMPTS.SKIP);
+    },
+  });
+
+  pi.registerCommand('spotme:rep', {
+    description: 'Request an on-demand SpotMe exercise',
+    handler: async () => {
+      pi.sendUserMessage(PROMPTS.REP);
+    },
+  });
+
+  // ─── Hook: intercept code-writing tool calls ──────────────────────────
+
+  pi.on('tool_call', async (event) => {
+    if (!CODE_WRITE_TOOLS.has(event.toolName)) return;
+
+    const filePath =
+      isToolCallEventType('write', event) || isToolCallEventType('edit', event)
+        ? event.input.path
+        : '';
+
+    const result = engine.interceptWriteToolCall(event.toolName, filePath);
+    if (result.blocked) {
+      return { block: true, reason: result.message };
+    }
+  });
+}

package/src/prompts.ts

@@ -0,0 +1,152 @@
+// ─── All prompt templates and display messages ─────────────────────────────
+// Single source of truth for every string the LLM or user sees.
+
+import type { Difficulty, SpotMeState } from './types.js';
+
+// ─── Difficulty labels ────────────────────────────────────────────────────────
+
+function difficultyLabel(d: Difficulty): string {
+  switch (d) {
+    case 'lite':
+      return 'signature + structure provided — implement the body';
+    case 'medium':
+      return 'signature provided — implement the logic';
+    case 'hard':
+      return 'spec only — design and implement from scratch';
+  }
+}
+
+// ─── Comment syntax helpers ────────────────────────────────────────────────────
+
+const EXT_COMMENT: Record<string, { open: string; close?: string }> = {
+  // C-style
+  ts: { open: '//' },
+  tsx: { open: '//' },
+  js: { open: '//' },
+  jsx: { open: '//' },
+  java: { open: '//' },
+  c: { open: '//' },
+  cpp: { open: '//' },
+  cs: { open: '//' },
+  go: { open: '//' },
+  swift: { open: '//' },
+  kt: { open: '//' },
+  rs: { open: '//' },
+  php: { open: '//' },
+  dart: { open: '//' },
+  // Hash-style
+  py: { open: '#' },
+  rb: { open: '#' },
+  sh: { open: '#' },
+  bash: { open: '#' },
+  zsh: { open: '#' },
+  yaml: { open: '#' },
+  yml: { open: '#' },
+  toml: { open: '#' },
+  r: { open: '#' },
+  // Block-style
+  html: { open: '<!--', close: '-->' },
+  xml: { open: '<!--', close: '-->' },
+  svg: { open: '<!--', close: '-->' },
+  css: { open: '/*', close: '*/' },
+  scss: { open: '//' },
+  sass: { open: '//' },
+  less: { open: '//' },
+  // Double-dash
+  lua: { open: '--' },
+  sql: { open: '--' },
+  // Lisp-style
+  el: { open: ';;' },
+  clj: { open: ';;' },
+};
+
+function commentForFile(filePath: string): string {
+  const ext = filePath.split('.').pop()?.toLowerCase() ?? '';
+  const syntax = EXT_COMMENT[ext] ?? { open: '//' };
+  return syntax.close
+    ? `${syntax.open} SPOTME: <description> ${syntax.close}`
+    : `${syntax.open} SPOTME: <description>`;
+}
+
+// ─── Display messages (returned to user / LLM as tool output) ──────────────
+
+export function statusMessage(state: SpotMeState): string {
+  const lines = [
+    `SpotMe: ${state.enabled ? '🟢 on' : '⚪ off'}`,
+    `Difficulty: ${state.difficulty}`,
+    `Trigger every: ${state.every} code write(s)`,
+    `Counter: ${state.counter}/${state.every}`,
+  ];
+  if (state.exercise?.active) {
+    lines.push(`Active exercise: ${state.exercise.unit} (${state.exercise.filePath})`);
+  }
+  return lines.join('\n');
+}
+
+export function exerciseReadyMessage(
+  unit: string,
+  filePath: string,
+  difficulty: Difficulty
+): string {
+  return [
+    `🏋️ Exercise ready: **${unit}**`,
+    `Difficulty: ${difficulty} — ${difficultyLabel(difficulty)}`,
+    `File: \`${filePath}\``,
+    ``,
+    `Edit the file in your editor. Replace the \`# SPOTME:\` marker with your implementation.`,
+    ``,
+    `Your options:`,
+    `  \`/spotme:hint\`  — get a targeted hint`,
+    `  \`/spotme:solve\` — concede and let the agent finish`,
+    `  \`/spotme:skip\`  — skip this exercise`,
+    `  \`/spotme:done\`  — submit your implementation for review`,
+  ].join('\n');
+}
+
+export function blockedMessage(toolName: string, filePath: string, difficulty: Difficulty): string {
+  const marker = commentForFile(filePath);
+  const scaffoldStep =
+    toolName === 'edit' && filePath
+      ? `Edit \`${filePath}\` to add a \`${marker}\` comment at the location where the implementation should go.`
+      : filePath
+        ? `Write the scaffold to \`${filePath}\` using the Write tool. Include a \`${marker}\` comment where the implementation should go.`
+        : `Write the scaffold file using the Write tool. Include a \`${marker}\` comment (use appropriate comment syntax for the language) where the implementation should go.`;
+
+  return [
+    `[SpotMe] Counter reached — time for an exercise!`,
+    ``,
+    `Follow these steps in order:`,
+    `1. ${scaffoldStep}`,
+    `2. Call \`spotme_exercise\` with the unit name, the file path, and difficulty "${difficulty}".`,
+    `3. Display the full return value of \`spotme_exercise\` verbatim to the user (do not summarize).`,
+  ].join('\n');
+}
+
+// ─── LLM instruction templates (injected as command templates / user messages) ─
+
+export const PROMPTS = {
+  /** /spotme:on — confirm settings after hook already set state. */
+  ON: 'SpotMe gym mode was just activated. Call `spotme_status` to get the current settings, then confirm them to the user in one sentence.',
+
+  /** /spotme:off — brief confirmation. */
+  OFF: 'Confirm that SpotMe gym mode is now off and you will resume writing code normally.',
+
+  /** /spotme:status — display current state. */
+  STATUS: 'Call the `spotme_status` tool and display the result to the user.',
+
+  /** /spotme:done — review user's implementation, then close. */
+  DONE: "Call `spotme_status` to get the active exercise details. Read the exercise file. Evaluate the user's implementation: (1) what they got right — 1-2 sentences, specific; (2) what could be better — concrete, no vague feedback; (3) next steps only if incomplete. Do NOT show your own solution. Resume the original task and complete any remaining code. Call `spotme_end` as the LAST thing you do.",
+
+  /** /spotme:hint — one hint, no spoilers. */
+  HINT: 'Give one targeted hint for the current SpotMe exercise. Point toward the approach without revealing the implementation. One paragraph max.',
+
+  /** /spotme:solve — write solution BEFORE closing exercise. */
+  SOLVE:
+    'Call `spotme_status` to get the active exercise details. Read the exercise file. Write the solution (replace the SPOTME marker if still present, or improve what the user wrote). Briefly note the key pattern the user should remember. Resume the original task and complete any remaining code. Call `spotme_end` as the LAST thing you do.',
+
+  /** /spotme:skip — complete the code, then close. */
+  SKIP: 'The human is skipping this exercise. Resume the original task and complete the code normally. Call `spotme_end` as the LAST thing you do.',
+
+  /** /spotme:rep — on-demand exercise. */
+  REP: 'The human wants a coding exercise. Write the scaffold for the next logical unit using the Write tool (use a `# SPOTME: <description>` marker where the human should implement), then call `spotme_exercise` with the unit name, file path, and difficulty.',
+} as const;