@towles/tool 0.0.41 → 0.0.48

package/src/commands/install.ts

@@ -23,8 +23,14 @@ export default class Install extends BaseCommand {
     "Configure Claude Code settings and optionally enable observability";
 
   static override examples = [
-    "<%= config.bin %> install",
-    "<%= config.bin %> install --observability",
+    {
+      description: "Configure Claude Code settings",
+      command: "<%= config.bin %> <%= command.id %>",
+    },
+    {
+      description: "Include OTEL setup instructions",
+      command: "<%= config.bin %> <%= command.id %> --observability",
+    },
   ];
 
   static override flags = {

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

@@ -11,24 +11,28 @@ import {
   ensureTemplatesExist,
   generateJournalFileInfoByType,
   openInEditor,
-} from "./utils.js";
+} 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 = [
-    "<%= config.bin %> journal daily-notes",
-    "<%= config.bin %> journal today",
+    {
+      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.settingsFile.settings.journalSettings;
+      const journalSettings = this.settings.settings.journalSettings;
       const templateDir = journalSettings.templateDir;
 
       // Ensure templates exist on first run
@@ -54,7 +58,7 @@ export default class DailyNotes extends BaseCommand {
       }
 
       await openInEditor({
-        editor: this.settings.settingsFile.settings.preferredEditor,
+        editor: this.settings.settings.preferredEditor,
         filePath: fileInfo.fullPath,
         folderPath: journalSettings.baseFolder,
       });

package/src/commands/journal/meeting.ts

@@ -12,7 +12,7 @@ import {
   ensureTemplatesExist,
   generateJournalFileInfoByType,
   openInEditor,
-} from "./utils.js";
+} from "../../lib/journal/utils.js";
 
 /**
  * Create or open meeting notes file
@@ -28,16 +28,22 @@ export default class Meeting extends BaseCommand {
   };
 
   static override examples = [
-    "<%= config.bin %> journal meeting",
-    '<%= config.bin %> journal meeting "Sprint Planning"',
-    '<%= config.bin %> journal m "Standup"',
+    {
+      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.settingsFile.settings.journalSettings;
+      const journalSettings = this.settings.settings.journalSettings;
       const templateDir = journalSettings.templateDir;
 
       // Ensure templates exist on first run
@@ -71,7 +77,7 @@ export default class Meeting extends BaseCommand {
       }
 
       await openInEditor({
-        editor: this.settings.settingsFile.settings.preferredEditor,
+        editor: this.settings.settings.preferredEditor,
         filePath: fileInfo.fullPath,
         folderPath: journalSettings.baseFolder,
       });

package/src/commands/journal/note.ts

@@ -12,7 +12,7 @@ import {
   ensureTemplatesExist,
   generateJournalFileInfoByType,
   openInEditor,
-} from "./utils.js";
+} from "../../lib/journal/utils.js";
 
 /**
  * Create or open general-purpose note file
@@ -28,16 +28,22 @@ export default class Note extends BaseCommand {
   };
 
   static override examples = [
-    "<%= config.bin %> journal note",
-    '<%= config.bin %> journal note "Research Notes"',
-    '<%= config.bin %> journal n "Ideas"',
+    {
+      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.settingsFile.settings.journalSettings;
+      const journalSettings = this.settings.settings.journalSettings;
       const templateDir = journalSettings.templateDir;
 
       // Ensure templates exist on first run
@@ -71,7 +77,7 @@ export default class Note extends BaseCommand {
       }
 
       await openInEditor({
-        editor: this.settings.settingsFile.settings.preferredEditor,
+        editor: this.settings.settings.preferredEditor,
         filePath: fileInfo.fullPath,
         folderPath: journalSettings.baseFolder,
       });

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/{task → plan}/list.test.ts

@@ -1,5 +1,5 @@
 /**
- * Integration tests for oclif ralph task list command
+ * 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";
@@ -8,11 +8,11 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { writeFileSync, unlinkSync, existsSync } from "node:fs";
 
-describe("ralph task list command", () => {
+describe("ralph plan list command", () => {
   const tempStateFile = join(tmpdir(), `ralph-test-list-${Date.now()}.json`);
 
   beforeAll(() => {
-    // Create state file with one task to minimize output during tests
+    // Create state file with one plan to minimize output during tests
     writeFileSync(
       tempStateFile,
       JSON.stringify({
@@ -31,13 +31,13 @@ describe("ralph task list command", () => {
   });
 
   it("runs task list without error", async () => {
-    const { error } = await runCommand(["ralph:task:list", "-s", tempStateFile]);
+    const { error } = await runCommand(["ralph:plan:list", "-s", tempStateFile]);
     expect(error).toBeUndefined();
   });
 
   it("supports --format flag", async () => {
     const { error } = await runCommand([
-      "ralph:task:list",
+      "ralph:plan:list",
       "--format",
       "markdown",
       "-s",

package/src/commands/ralph/{task → plan}/list.ts

@@ -1,19 +1,21 @@
 import { Flags } from "@oclif/core";
 import pc from "picocolors";
 import { BaseCommand } from "../../base.js";
-import { DEFAULT_STATE_FILE, loadState, resolveRalphPath } from "../lib/state.js";
-import { formatTasksAsMarkdown } from "../lib/formatter.js";
+import { DEFAULT_STATE_FILE, loadState, resolveRalphPath } from "../../../lib/ralph/state.js";
+import { formatPlansAsMarkdown } from "../../../lib/ralph/formatter.js";
 
 /**
- * List all ralph tasks
+ * List all ralph plans
  */
-export default class TaskList extends BaseCommand {
-  static override description = "List all tasks";
+export default class PlanList extends BaseCommand {
+  static override description = "List all plans";
 
   static override examples = [
-    "<%= config.bin %> ralph task list",
-    "<%= config.bin %> ralph task list --format markdown",
-    "<%= config.bin %> ralph task list --label backend",
+    { description: "List all plans", command: "<%= config.bin %> <%= command.id %>" },
+    {
+      description: "Output as markdown",
+      command: "<%= config.bin %> <%= command.id %> --format markdown",
+    },
   ];
 
   static override flags = {
@@ -28,15 +30,11 @@ export default class TaskList extends BaseCommand {
       default: "default",
       options: ["default", "markdown"],
     }),
-    label: Flags.string({
-      char: "l",
-      description: "Filter tasks by label",
-    }),
   };
 
   async run(): Promise<void> {
-    const { flags } = await this.parse(TaskList);
-    const ralphSettings = this.settings.settingsFile.settings.ralphSettings;
+    const { flags } = await this.parse(PlanList);
+    const ralphSettings = this.settings.settings.ralphSettings;
     const stateFile = resolveRalphPath(flags.stateFile, "stateFile", ralphSettings);
 
     const state = loadState(stateFile);
@@ -46,63 +44,54 @@ export default class TaskList extends BaseCommand {
       return;
     }
 
-    // Filter by label if specified
-    let tasks = state.tasks;
-    if (flags.label) {
-      tasks = tasks.filter((t) => t.label === flags.label);
-      if (tasks.length === 0) {
-        this.log(pc.yellow(`No tasks with label: ${flags.label}`));
-        return;
-      }
-    }
+    const plans = state.plans;
 
-    if (tasks.length === 0) {
-      this.log(pc.yellow("No tasks in state file."));
-      this.log(pc.dim('Use: tt ralph task add "description"'));
+    if (plans.length === 0) {
+      this.log(pc.yellow("No plans in state file."));
+      this.log(pc.dim('Use: tt ralph plan add "description"'));
       return;
     }
 
     if (flags.format === "markdown") {
-      this.log(formatTasksAsMarkdown(tasks));
+      this.log(formatPlansAsMarkdown(plans));
       return;
     }
 
     // Default format output - compact with truncation
-    const ready = tasks.filter((t) => t.status === "ready");
-    const done = tasks.filter((t) => t.status === "done");
+    const ready = plans.filter((p) => p.status === "ready");
+    const done = plans.filter((p) => p.status === "done");
 
     const truncate = (s: string, len: number) => (s.length > len ? s.slice(0, len - 1) + "…" : s);
     const termWidth = process.stdout.columns || 120;
 
     // Summary header
-    const labelInfo = flags.label ? ` [${flags.label}]` : "";
     this.log(
-      pc.bold(`\nTasks${labelInfo}: `) +
+      pc.bold("\nPlans: ") +
         pc.green(`${done.length} done`) +
         pc.dim(" / ") +
         pc.yellow(`${ready.length} ready`),
     );
     this.log();
 
-    // Show ready tasks first (these are actionable)
+    // Show ready plans first (these are actionable)
     // Reserve ~10 chars for "  ○ #XX " prefix
     const descWidth = Math.max(40, termWidth - 12);
 
     if (ready.length > 0) {
-      for (const task of ready) {
+      for (const plan of ready) {
         const icon = pc.dim("○");
-        const id = pc.cyan(`#${task.id}`);
-        const desc = truncate(task.description, descWidth);
+        const id = pc.cyan(`#${plan.id}`);
+        const desc = truncate(plan.description, descWidth);
         this.log(`  ${icon} ${id} ${desc}`);
       }
     }
 
-    // Show done tasks collapsed
+    // Show done plans collapsed
     if (done.length > 0) {
       this.log(pc.dim(`  ─── ${done.length} completed ───`));
-      for (const task of done) {
-        const desc = truncate(task.description, descWidth - 5);
-        this.log(pc.dim(`  ✓ #${task.id} ${desc}`));
+      for (const plan of done) {
+        const desc = truncate(plan.description, descWidth - 5);
+        this.log(pc.dim(`  ✓ #${plan.id} ${desc}`));
       }
     }
     this.log();

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

@@ -0,0 +1,71 @@
+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";
+
+/**
+ * Remove a ralph plan by ID
+ */
+export default class PlanRemove extends BaseCommand {
+  static override description = "Remove a plan by ID";
+
+  static override examples = [
+    { description: "Remove plan #1", command: "<%= config.bin %> <%= command.id %> 1" },
+    {
+      description: "Remove from custom state file",
+      command: "<%= config.bin %> <%= command.id %> 5 --stateFile custom-state.json",
+    },
+  ];
+
+  static override args = {
+    id: Args.integer({
+      description: "Plan ID to remove",
+      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(PlanRemove);
+    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 planIndex = state.plans.findIndex((p) => p.id === planId);
+
+    if (planIndex === -1) {
+      this.error(`Plan #${planId} not found. Use: tt ralph plan list`);
+    }
+
+    const removedPlan = state.plans[planIndex];
+    state.plans.splice(planIndex, 1);
+    saveState(state, stateFile);
+
+    consola.log(colors.green(`✓ Removed plan #${planId}: ${removedPlan.description}`));
+    consola.log(colors.dim(`Remaining plans: ${state.plans.length}`));
+  }
+}