@towles/tool 0.0.20 → 0.0.48

package/src/commands/install.ts

@@ -0,0 +1,154 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { homedir } from "node:os";
+import { Flags } from "@oclif/core";
+import pc from "picocolors";
+import consola from "consola";
+import { BaseCommand } from "./base.js";
+
+const CLAUDE_SETTINGS_PATH = path.join(homedir(), ".claude", "settings.json");
+
+interface ClaudeSettings {
+  cleanupPeriodDays?: number;
+  alwaysThinkingEnabled?: boolean;
+  hooks?: Record<string, unknown[]>;
+  [key: string]: unknown;
+}
+
+/**
+ * Install and configure towles-tool with Claude Code
+ */
+export default class Install extends BaseCommand {
+  static override description =
+    "Configure Claude Code settings and optionally enable observability";
+
+  static override examples = [
+    {
+      description: "Configure Claude Code settings",
+      command: "<%= config.bin %> <%= command.id %>",
+    },
+    {
+      description: "Include OTEL setup instructions",
+      command: "<%= config.bin %> <%= command.id %> --observability",
+    },
+  ];
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    observability: Flags.boolean({
+      char: "o",
+      description: "Show OTEL setup instructions and configure SubagentStop hook",
+      default: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(Install);
+
+    this.log(pc.bold("\n🔧 towles-tool install\n"));
+
+    // Load or create Claude settings
+    let claudeSettings: ClaudeSettings = {};
+    if (fs.existsSync(CLAUDE_SETTINGS_PATH)) {
+      try {
+        const content = fs.readFileSync(CLAUDE_SETTINGS_PATH, "utf-8");
+        claudeSettings = JSON.parse(content);
+        this.log(pc.dim(`Found existing Claude settings at ${CLAUDE_SETTINGS_PATH}`));
+      } catch {
+        this.log(
+          pc.yellow(`Warning: Could not parse ${CLAUDE_SETTINGS_PATH}, will create fresh settings`),
+        );
+      }
+    } else {
+      this.log(pc.dim(`No Claude settings file found, will create one`));
+    }
+
+    // Configure recommended settings
+    let modified = false;
+
+    // Prevent log deletion (set to ~274 years)
+    if (claudeSettings.cleanupPeriodDays !== 99999) {
+      claudeSettings.cleanupPeriodDays = 99999;
+      modified = true;
+      this.log(pc.green("✓ Set cleanupPeriodDays: 99999 (prevent log deletion)"));
+    } else {
+      this.log(pc.dim("✓ cleanupPeriodDays already set to 99999"));
+    }
+
+    // Enable thinking by default
+    if (claudeSettings.alwaysThinkingEnabled !== true) {
+      claudeSettings.alwaysThinkingEnabled = true;
+      modified = true;
+      this.log(pc.green("✓ Set alwaysThinkingEnabled: true"));
+    } else {
+      this.log(pc.dim("✓ alwaysThinkingEnabled already set to true"));
+    }
+
+    // Save settings if modified
+    if (modified) {
+      this.saveClaudeSettings(claudeSettings);
+      this.log(pc.green(`\n✓ Saved Claude settings to ${CLAUDE_SETTINGS_PATH}`));
+    }
+
+    // Show observability setup if requested
+    if (flags.observability) {
+      this.log(pc.bold("\n📊 Observability Setup\n"));
+      this.showOtelInstructions();
+    }
+
+    this.log(pc.bold(pc.green("\n✅ Installation complete!\n")));
+
+    // Offer to install plugins from marketplace
+    this.log(pc.cyan("To install plugins from the Claude Code marketplace:"));
+    this.log(
+      pc.dim("  claude /plugins marketplace add https://github.com/ChrisTowles/towles-tool"),
+    );
+    this.log("");
+
+    const answer = await consola.prompt("Install tt-core plugin from marketplace now?", {
+      type: "confirm",
+      initial: true,
+    });
+
+    if (answer) {
+      const { x } = await import("tinyexec");
+      this.log("");
+
+      const result = await x("claude", ["plugin", "install", "tt@towles-tool", "--scope", "user"]);
+      if (result.stdout) this.log(result.stdout);
+      if (result.stderr) this.log(pc.dim(result.stderr));
+      if (result.exitCode === 0) {
+        this.log(pc.green("✓ tt-core plugin installed"));
+      } else {
+        this.log(pc.yellow(`Command exited with code ${result.exitCode}`));
+      }
+    }
+
+    this.log("");
+  }
+
+  private saveClaudeSettings(settings: ClaudeSettings): void {
+    const dir = path.dirname(CLAUDE_SETTINGS_PATH);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(settings, null, 2));
+  }
+
+  private showOtelInstructions(): void {
+    this.log(pc.cyan("Add these environment variables to your shell profile:\n"));
+
+    consola.box(`export CLAUDE_CODE_ENABLE_TELEMETRY=1
+export OTEL_METRICS_EXPORTER=otlp
+export OTEL_LOGS_EXPORTER=otlp
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317`);
+
+    this.log("");
+    this.log(
+      pc.dim("For more info, see: https://github.com/anthropics/claude-code-monitoring-guide"),
+    );
+    this.log("");
+    this.log(pc.cyan("Quick cost analysis (no setup required):"));
+    this.log(pc.dim("  npx ccusage@latest --breakdown"));
+  }
+}

package/src/commands/journal/daily-notes.ts

@@ -0,0 +1,70 @@
+import { existsSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import consola from "consola";
+import { colors } from "consola/utils";
+import { BaseCommand } from "../base.js";
+import { JOURNAL_TYPES } from "../../types/journal.js";
+import {
+  createJournalContent,
+  ensureDirectoryExists,
+  ensureTemplatesExist,
+  generateJournalFileInfoByType,
+  openInEditor,
+} from "../../lib/journal/utils.js";
+
+/**
+ * Create or open daily notes journal file
+ */
+export default class DailyNotes extends BaseCommand {
+  static override aliases = ["today"];
+  static override description = "Weekly files with daily sections for ongoing work and notes";
+
+  static override examples = [
+    {
+      description: "Open weekly notes for today",
+      command: "<%= config.bin %> <%= command.id %>",
+    },
+    { description: "Using alias", command: "<%= config.bin %> today" },
+  ];
+
+  async run(): Promise<void> {
+    await this.parse(DailyNotes);
+
+    try {
+      const journalSettings = this.settings.settings.journalSettings;
+      const templateDir = journalSettings.templateDir;
+
+      // Ensure templates exist on first run
+      ensureTemplatesExist(templateDir);
+
+      const currentDate = new Date();
+      const fileInfo = generateJournalFileInfoByType({
+        journalSettings,
+        date: currentDate,
+        type: JOURNAL_TYPES.DAILY_NOTES,
+        title: "",
+      });
+
+      // Ensure journal directory exists
+      ensureDirectoryExists(path.dirname(fileInfo.fullPath));
+
+      if (existsSync(fileInfo.fullPath)) {
+        consola.info(`Opening existing daily-notes file: ${colors.cyan(fileInfo.fullPath)}`);
+      } else {
+        const content = createJournalContent({ mondayDate: fileInfo.mondayDate, templateDir });
+        consola.info(`Creating new daily-notes file: ${colors.cyan(fileInfo.fullPath)}`);
+        writeFileSync(fileInfo.fullPath, content, "utf8");
+      }
+
+      await openInEditor({
+        editor: this.settings.settings.preferredEditor,
+        filePath: fileInfo.fullPath,
+        folderPath: journalSettings.baseFolder,
+      });
+    } catch (error) {
+      consola.warn(`Error creating daily-notes file:`, error);
+      process.exit(1);
+    }
+  }
+}

package/src/commands/journal/meeting.ts

@@ -0,0 +1,89 @@
+import { existsSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { Args } from "@oclif/core";
+import consola from "consola";
+import { colors } from "consola/utils";
+import { BaseCommand } from "../base.js";
+import { JOURNAL_TYPES } from "../../types/journal.js";
+import {
+  createMeetingContent,
+  ensureDirectoryExists,
+  ensureTemplatesExist,
+  generateJournalFileInfoByType,
+  openInEditor,
+} from "../../lib/journal/utils.js";
+
+/**
+ * Create or open meeting notes file
+ */
+export default class Meeting extends BaseCommand {
+  static override description = "Structured meeting notes with agenda and action items";
+
+  static override args = {
+    title: Args.string({
+      description: "Meeting title",
+      required: false,
+    }),
+  };
+
+  static override examples = [
+    {
+      description: "Create meeting note (prompts for title)",
+      command: "<%= config.bin %> <%= command.id %>",
+    },
+    {
+      description: "Create with title",
+      command: '<%= config.bin %> <%= command.id %> "Sprint Planning"',
+    },
+    { description: "Using alias", command: '<%= config.bin %> m "Standup"' },
+  ];
+
+  async run(): Promise<void> {
+    const { args } = await this.parse(Meeting);
+
+    try {
+      const journalSettings = this.settings.settings.journalSettings;
+      const templateDir = journalSettings.templateDir;
+
+      // Ensure templates exist on first run
+      ensureTemplatesExist(templateDir);
+
+      // Prompt for title if not provided
+      let title = args.title || "";
+      if (title.trim().length === 0) {
+        title = await consola.prompt(`Enter meeting title:`, {
+          type: "text",
+        });
+      }
+
+      const currentDate = new Date();
+      const fileInfo = generateJournalFileInfoByType({
+        journalSettings,
+        date: currentDate,
+        type: JOURNAL_TYPES.MEETING,
+        title,
+      });
+
+      // Ensure journal directory exists
+      ensureDirectoryExists(path.dirname(fileInfo.fullPath));
+
+      if (existsSync(fileInfo.fullPath)) {
+        consola.info(`Opening existing meeting file: ${colors.cyan(fileInfo.fullPath)}`);
+      } else {
+        const content = createMeetingContent({ title, date: currentDate, templateDir });
+        consola.info(`Creating new meeting file: ${colors.cyan(fileInfo.fullPath)}`);
+        writeFileSync(fileInfo.fullPath, content, "utf8");
+      }
+
+      await openInEditor({
+        editor: this.settings.settings.preferredEditor,
+        filePath: fileInfo.fullPath,
+        folderPath: journalSettings.baseFolder,
+      });
+    } catch (error) {
+      consola.warn(`Error creating meeting file:`, error);
+      process.exit(1);
+    }
+  }
+}

package/src/commands/journal/note.ts

@@ -0,0 +1,89 @@
+import { existsSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { Args } from "@oclif/core";
+import consola from "consola";
+import { colors } from "consola/utils";
+import { BaseCommand } from "../base.js";
+import { JOURNAL_TYPES } from "../../types/journal.js";
+import {
+  createNoteContent,
+  ensureDirectoryExists,
+  ensureTemplatesExist,
+  generateJournalFileInfoByType,
+  openInEditor,
+} from "../../lib/journal/utils.js";
+
+/**
+ * Create or open general-purpose note file
+ */
+export default class Note extends BaseCommand {
+  static override description = "General-purpose notes with structured sections";
+
+  static override args = {
+    title: Args.string({
+      description: "Note title",
+      required: false,
+    }),
+  };
+
+  static override examples = [
+    {
+      description: "Create note (prompts for title)",
+      command: "<%= config.bin %> <%= command.id %>",
+    },
+    {
+      description: "Create with title",
+      command: '<%= config.bin %> <%= command.id %> "Research Notes"',
+    },
+    { description: "Using alias", command: '<%= config.bin %> n "Ideas"' },
+  ];
+
+  async run(): Promise<void> {
+    const { args } = await this.parse(Note);
+
+    try {
+      const journalSettings = this.settings.settings.journalSettings;
+      const templateDir = journalSettings.templateDir;
+
+      // Ensure templates exist on first run
+      ensureTemplatesExist(templateDir);
+
+      // Prompt for title if not provided
+      let title = args.title || "";
+      if (title.trim().length === 0) {
+        title = await consola.prompt(`Enter note title:`, {
+          type: "text",
+        });
+      }
+
+      const currentDate = new Date();
+      const fileInfo = generateJournalFileInfoByType({
+        journalSettings,
+        date: currentDate,
+        type: JOURNAL_TYPES.NOTE,
+        title,
+      });
+
+      // Ensure journal directory exists
+      ensureDirectoryExists(path.dirname(fileInfo.fullPath));
+
+      if (existsSync(fileInfo.fullPath)) {
+        consola.info(`Opening existing note file: ${colors.cyan(fileInfo.fullPath)}`);
+      } else {
+        const content = createNoteContent({ title, date: currentDate, templateDir });
+        consola.info(`Creating new note file: ${colors.cyan(fileInfo.fullPath)}`);
+        writeFileSync(fileInfo.fullPath, content, "utf8");
+      }
+
+      await openInEditor({
+        editor: this.settings.settings.preferredEditor,
+        filePath: fileInfo.fullPath,
+        folderPath: journalSettings.baseFolder,
+      });
+    } catch (error) {
+      consola.warn(`Error creating note file:`, error);
+      process.exit(1);
+    }
+  }
+}

package/src/commands/ralph/plan/add.ts

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { Flags } from "@oclif/core";
+import consola from "consola";
+import { colors } from "consola/utils";
+import { BaseCommand } from "../../base.js";
+import {
+  DEFAULT_STATE_FILE,
+  loadState,
+  saveState,
+  createInitialState,
+  addPlanToState,
+  resolveRalphPath,
+} from "../../../lib/ralph/state.js";
+
+/**
+ * Add a new plan to ralph state from a file
+ */
+export default class PlanAdd extends BaseCommand {
+  static override description = "Add a new plan from a file";
+
+  static override examples = [
+    {
+      description: "Add a plan from a markdown file",
+      command: "<%= config.bin %> <%= command.id %> --file docs/plans/2025-01-18-feature.md",
+    },
+  ];
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    file: Flags.string({
+      char: "f",
+      description: "Path to plan file (markdown)",
+      required: true,
+    }),
+    stateFile: Flags.string({
+      char: "s",
+      description: `State file path (default: ${DEFAULT_STATE_FILE})`,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(PlanAdd);
+    const ralphSettings = this.settings.settings.ralphSettings;
+    const stateFile = resolveRalphPath(flags.stateFile, "stateFile", ralphSettings);
+
+    const filePath = resolve(flags.file);
+
+    if (!existsSync(filePath)) {
+      this.error(`Plan file not found: ${filePath}`);
+    }
+
+    const description = readFileSync(filePath, "utf-8").trim();
+
+    if (!description || description.length < 3) {
+      this.error("Plan file is empty or too short (min 3 chars)");
+    }
+
+    let state = loadState(stateFile);
+
+    if (!state) {
+      state = createInitialState();
+    }
+
+    const newPlan = addPlanToState(state, description);
+    saveState(state, stateFile);
+
+    // Show truncated description for display
+    const displayDesc = description.length > 80 ? `${description.slice(0, 80)}...` : description;
+    consola.log(colors.green(`✓ Added plan #${newPlan.id} from ${flags.file}`));
+    consola.log(colors.dim(`  ${displayDesc.split("\n")[0]}`));
+    consola.log(colors.dim(`State saved to: ${stateFile}`));
+    consola.log(colors.dim(`Total plans: ${state.plans.length}`));
+  }
+}

package/src/commands/ralph/plan/done.ts

@@ -0,0 +1,82 @@
+import { Args, Flags } from "@oclif/core";
+import consola from "consola";
+import { colors } from "consola/utils";
+import { BaseCommand } from "../../base.js";
+import {
+  DEFAULT_STATE_FILE,
+  loadState,
+  saveState,
+  resolveRalphPath,
+} from "../../../lib/ralph/state.js";
+
+/**
+ * Mark a ralph plan as done
+ */
+export default class PlanDone extends BaseCommand {
+  static override description = "Mark a plan as done by ID";
+
+  static override examples = [
+    { description: "Mark plan #1 as done", command: "<%= config.bin %> <%= command.id %> 1" },
+    {
+      description: "Mark done using custom state file",
+      command: "<%= config.bin %> <%= command.id %> 5 --stateFile custom-state.json",
+    },
+  ];
+
+  static override args = {
+    id: Args.integer({
+      description: "Plan ID to mark done",
+      required: true,
+    }),
+  };
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    stateFile: Flags.string({
+      char: "s",
+      description: `State file path (default: ${DEFAULT_STATE_FILE})`,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(PlanDone);
+    const ralphSettings = this.settings.settings.ralphSettings;
+    const stateFile = resolveRalphPath(flags.stateFile, "stateFile", ralphSettings);
+
+    const planId = args.id;
+
+    if (planId < 1) {
+      this.error("Invalid plan ID");
+    }
+
+    const state = loadState(stateFile);
+
+    if (!state) {
+      this.error(`No state file found at: ${stateFile}`);
+    }
+
+    const plan = state.plans.find((p) => p.id === planId);
+
+    if (!plan) {
+      this.error(`Plan #${planId} not found. Use: tt ralph plan list`);
+    }
+
+    if (plan.status === "done") {
+      consola.log(colors.yellow(`Plan #${planId} is already done.`));
+      return;
+    }
+
+    plan.status = "done";
+    plan.completedAt = new Date().toISOString();
+    saveState(state, stateFile);
+
+    consola.log(colors.green(`✓ Marked plan #${planId} as done: ${plan.description}`));
+
+    const remaining = state.plans.filter((p) => p.status !== "done").length;
+    if (remaining === 0) {
+      consola.log(colors.bold(colors.green("All plans complete!")));
+    } else {
+      consola.log(colors.dim(`Remaining plans: ${remaining}`));
+    }
+  }
+}

package/src/commands/ralph/plan/list.test.ts

@@ -0,0 +1,48 @@
+/**
+ * Integration tests for oclif ralph plan list command
+ * Note: --help output goes through oclif's own routing
+ */
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { runCommand } from "@oclif/test";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { writeFileSync, unlinkSync, existsSync } from "node:fs";
+
+describe("ralph plan list command", () => {
+  const tempStateFile = join(tmpdir(), `ralph-test-list-${Date.now()}.json`);
+
+  beforeAll(() => {
+    // Create state file with one plan to minimize output during tests
+    writeFileSync(
+      tempStateFile,
+      JSON.stringify({
+        version: 1,
+        iteration: 0,
+        maxIterations: 10,
+        status: "running",
+        tasks: [{ id: 1, description: "test", status: "done", addedAt: new Date().toISOString() }],
+        startedAt: new Date().toISOString(),
+      }),
+    );
+  });
+
+  afterAll(() => {
+    if (existsSync(tempStateFile)) unlinkSync(tempStateFile);
+  });
+
+  it("runs task list without error", async () => {
+    const { error } = await runCommand(["ralph:plan:list", "-s", tempStateFile]);
+    expect(error).toBeUndefined();
+  });
+
+  it("supports --format flag", async () => {
+    const { error } = await runCommand([
+      "ralph:plan:list",
+      "--format",
+      "markdown",
+      "-s",
+      tempStateFile,
+    ]);
+    expect(error).toBeUndefined();
+  });
+});