feat: add explicit tui entrypoint and changelog

Author: steipete

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.5.3 — 2025-12-06
+
+### Changed
+- `oracle` with no arguments now prints the help/usage banner; launch the interactive UI explicitly via `oracle tui` (keeps `ORACLE_FORCE_TUI` for automation/tests). README updated to match.
+
+### Fixed
+- Prevented accidental TUI entry in scripts/automations that previously invoked `oracle` without arguments.
+
 ## 0.5.2 — 2025-12-06
 
 ### Changed

README.md

@@ -38,7 +38,7 @@ npx @steipete/oracle status --hours 72
 npx @steipete/oracle session <id> --render
 
 # TUI (interactive, only for humans)
-npx @steipete/oracle
+npx @steipete/oracle tui
 ```
 
 Engine auto-picks API when `OPENAI_API_KEY` is set, otherwise browser; browser is stable on macOS and works on Linux and Windows. On Linux pass `--browser-chrome-path/--browser-cookie-path` if detection fails; on Windows prefer `--browser-manual-login` or inline cookies if decryption is blocked.

bin/oracle-cli.ts

@@ -154,7 +154,6 @@ const CLI_ENTRYPOINT = fileURLToPath(import.meta.url);
 const rawCliArgs = process.argv.slice(2);
 const userCliArgs = rawCliArgs[0] === CLI_ENTRYPOINT ? rawCliArgs.slice(1) : rawCliArgs;
 const isTty = process.stdout.isTTY;
-const tuiEnabled = () => isTty && process.env.ORACLE_NO_TUI !== '1';
 
 const program = new Command();
 let introPrinted = false;
@@ -171,8 +170,8 @@ program.hook('preAction', (thisCommand) => {
   if (userCliArgs.some((arg) => arg === '--help' || arg === '-h')) {
     return;
   }
-  if (userCliArgs.length === 0 && tuiEnabled()) {
-    // Skip prompt enforcement; runRootCommand will launch the TUI.
+  if (userCliArgs.length === 0) {
+    // Let the root action handle zero-arg entry (help + hint to `oracle tui`).
     return;
   }
   const opts = thisCommand.optsWithGlobals() as CliOptions;
@@ -424,6 +423,14 @@ program
     });
   });
 
+program
+  .command('tui')
+  .description('Launch the interactive terminal UI for humans (no automation).')
+  .action(async () => {
+    await sessionStore.ensureStorage();
+    await launchTui({ version: VERSION, printIntro: false });
+  });
+
 const sessionCommand = program
   .command('session [id]')
   .description('Attach to a stored session or list recent sessions when no ID is provided.')
@@ -659,12 +666,8 @@ async function runRootCommand(options: CliOptions): Promise<void> {
   }
 
   if (userCliArgs.length === 0) {
-    if (tuiEnabled()) {
-      await launchTui({ version: VERSION, printIntro: false });
-      return;
-    }
-    console.log(chalk.yellow('No prompt or subcommand supplied. See `oracle --help` for usage.'));
-    program.help({ error: false });
+    console.log(chalk.yellow('No prompt or subcommand supplied. Run `oracle --help` or `oracle tui` for the TUI.'));
+    program.outputHelp();
     return;
   }
   const retentionHours = typeof options.retainHours === 'number' ? options.retainHours : undefined;

tests/cli/noArgTui.test.ts

@@ -1,18 +1,22 @@
-import { describe, expect, test, vi } from 'vitest';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
 
 vi.mock('../../src/cli/tui/index.js', () => ({
   launchTui: vi.fn().mockResolvedValue(undefined),
 }));
 
 const launchTuiMock = vi.mocked(await import('../../src/cli/tui/index.js')).launchTui as ReturnType<typeof vi.fn>;
 
+beforeEach(() => {
+  vi.clearAllMocks();
+  vi.resetModules();
+});
+
 describe('zero-arg TUI entry', () => {
-  test('invokes launchTui when no args and TTY', async () => {
+  test('shows help when no args (no TUI)', async () => {
     const originalArgv = process.argv;
     const originalTty = process.stdout.isTTY;
     process.argv = ['node', 'bin/oracle-cli.js']; // mimics zero-arg user input
     Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true });
-    process.env.ORACLE_FORCE_TUI = '1';
 
     await import('../../bin/oracle-cli.js');
 
@@ -21,10 +25,27 @@ describe('zero-arg TUI entry', () => {
       await new Promise((resolve) => setTimeout(resolve, 10));
     }
 
-    expect(launchTuiMock).toHaveBeenCalled();
+    expect(launchTuiMock).not.toHaveBeenCalled();
 
     // restore
-    delete process.env.ORACLE_FORCE_TUI;
+    process.argv = originalArgv;
+    Object.defineProperty(process.stdout, 'isTTY', { value: originalTty, configurable: true });
+  }, 15_000);
+
+  test('invokes launchTui via subcommand', async () => {
+    const originalArgv = process.argv;
+    const originalTty = process.stdout.isTTY;
+    process.argv = ['node', 'bin/oracle-cli.js', 'tui'];
+    Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true });
+
+    await import('../../bin/oracle-cli.js');
+
+    for (let i = 0; i < 10 && launchTuiMock.mock.calls.length === 0; i += 1) {
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+
+    expect(launchTuiMock).toHaveBeenCalled();
+
     process.argv = originalArgv;
     Object.defineProperty(process.stdout, 'isTTY', { value: originalTty, configurable: true });
   }, 15_000);