feat(cli): interactive TUI with keyboard navigation, search, and adaptive layout

Adds interactive mode to CLI browsing commands (notes list/get/relations,
search, conversations, tags) with arrow key navigation, view stack routing,
adaptive dual-pane/inline preview layout, and zh/en i18n support.

Co-Authored-By: Rayner Zeng <1361209507@qq.com>

Author: ZengLiangYi

package-lock.json

@@ -49,7 +49,7 @@
     "commander": "^14.0.3",
     "dotenv": "^16.5.0",
     "fastify": "^5.3.3",
-    "ink": "^6.8.0",
+    "ink": "^7.0.0",
     "p-queue": "^8.1.0",
     "react": "^19.2.4",
     "sql.js": "^1.12.0",

server/package.json

@@ -4,6 +4,8 @@ import {
   shouldOutputJson, outputJson,
   printHeader, printTable, truncate,
 } from '../formatter.js';
+import { isInteractive } from '../interactive.js';
+import { renderApp } from '../ui/renderApp.js';
 
 export function registerConversationsCommand(program: Command) {
   program
@@ -19,6 +21,19 @@ export function registerConversationsCommand(program: Command) {
       const client = new CrystalClient(globalOpts.baseUrl);
 
       try {
+        // Interactive mode
+        if (isInteractive(globalOpts)) {
+          await renderApp(client, {
+            type: 'conversations',
+            props: {
+              source: opts.source,
+              status: opts.status,
+              search: opts.search,
+            },
+          });
+          return;
+        }
+
         const data = await client.getConversations({
           source: opts.source,
           status: opts.status,

server/src/cli/commands/conversations.ts

@@ -4,6 +4,8 @@ import {
   shouldOutputJson, outputJson,
   printHeader, printTable, printKeyValue, printError, truncate,
 } from '../formatter.js';
+import { isInteractive } from '../interactive.js';
+import { renderApp } from '../ui/renderApp.js';
 
 export function registerNotesCommand(program: Command) {
   const notes = program
@@ -22,6 +24,15 @@ export function registerNotesCommand(program: Command) {
       const client = new CrystalClient(globalOpts.baseUrl);
 
       try {
+        // Interactive mode
+        if (isInteractive(globalOpts)) {
+          await renderApp(client, {
+            type: 'notes-list',
+            props: { tagFilter: opts.tag },
+          });
+          return;
+        }
+
         const page = Math.max(1, Number(opts.page));
         const limit = Number(opts.limit);
         const offset = (page - 1) * limit;
@@ -69,6 +80,15 @@ export function registerNotesCommand(program: Command) {
       const client = new CrystalClient(globalOpts.baseUrl);
 
       try {
+        // Interactive mode
+        if (isInteractive(globalOpts)) {
+          await renderApp(client, {
+            type: 'note-detail',
+            props: { noteId: Number(id) },
+          });
+          return;
+        }
+
         const note = await client.getNote(Number(id));
 
         if (shouldOutputJson(globalOpts.json)) {
@@ -122,6 +142,15 @@ export function registerNotesCommand(program: Command) {
       const client = new CrystalClient(globalOpts.baseUrl);
 
       try {
+        // Interactive mode
+        if (isInteractive(globalOpts)) {
+          await renderApp(client, {
+            type: 'relations',
+            props: { noteId: Number(id) },
+          });
+          return;
+        }
+
         const relations = await client.getNoteRelations(Number(id));
 
         if (shouldOutputJson(globalOpts.json)) {

server/src/cli/commands/notes.ts

@@ -4,6 +4,8 @@ import {
   shouldOutputJson, outputJson,
   printHeader, printTable, printError, truncate,
 } from '../formatter.js';
+import { isInteractive } from '../interactive.js';
+import { renderApp } from '../ui/renderApp.js';
 
 export function registerSearchCommand(program: Command) {
   program
@@ -15,6 +17,15 @@ export function registerSearchCommand(program: Command) {
       const client = new CrystalClient(globalOpts.baseUrl);
 
       try {
+        // Interactive mode
+        if (isInteractive(globalOpts)) {
+          await renderApp(client, {
+            type: 'search',
+            props: { initialQuery: query },
+          });
+          return;
+        }
+
         const results = await client.search(query, Number(opts.limit));
 
         if (shouldOutputJson(globalOpts.json)) {

server/src/cli/commands/search.ts

@@ -4,6 +4,8 @@ import {
   shouldOutputJson, outputJson,
   printHeader, printTable, printError,
 } from '../formatter.js';
+import { isInteractive } from '../interactive.js';
+import { renderApp } from '../ui/renderApp.js';
 
 export function registerTagsCommand(program: Command) {
   program
@@ -14,6 +16,15 @@ export function registerTagsCommand(program: Command) {
       const client = new CrystalClient(globalOpts.baseUrl);
 
       try {
+        // Interactive mode
+        if (isInteractive(globalOpts)) {
+          await renderApp(client, {
+            type: 'tags',
+            props: {},
+          });
+          return;
+        }
+
         const tags = await client.listTags();
 
         if (shouldOutputJson(globalOpts.json)) {

server/src/cli/commands/tags.ts

@@ -46,7 +46,7 @@ export function printKeyValue(key: string, value: string | number | boolean): vo
  * Get the display width of a string in terminal columns.
  * CJK characters occupy 2 columns; ASCII characters occupy 1.
  */
-function displayWidth(str: string): number {
+export function displayWidth(str: string): number {
   let w = 0;
   for (const ch of str) {
     const code = ch.codePointAt(0)!;
@@ -72,12 +72,12 @@ function displayWidth(str: string): number {
 }
 
 /** Pad string to target display width (handles CJK double-width characters). */
-function padEndDisplay(str: string, targetWidth: number): string {
+export function padEndDisplay(str: string, targetWidth: number): string {
   const gap = targetWidth - displayWidth(str);
   return gap > 0 ? str + ' '.repeat(gap) : str;
 }
 
-function padStartDisplay(str: string, targetWidth: number): string {
+export function padStartDisplay(str: string, targetWidth: number): string {
   const gap = targetWidth - displayWidth(str);
   return gap > 0 ? ' '.repeat(gap) + str : str;
 }

server/src/cli/formatter.ts

@@ -15,7 +15,8 @@ program
   .description('ChatCrystal — AI conversation knowledge crystallization tool')
   .version(pkg.version)
   .option('-b, --base-url <url>', 'Server base URL', 'http://localhost:3721')
-  .option('--json', 'Force JSON output (override TTY detection)');
+  .option('--json', 'Force JSON output (override TTY detection)')
+  .option('--no-interactive', 'Disable interactive mode (always use plain output)');
 
 // Import and register subcommands
 import { registerStatusCommand } from './commands/status.js';

server/src/cli/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Determine if the current command should run in interactive (Ink) mode.
+ * Interactive mode requires: TTY stdout, no --json flag, no --no-interactive flag.
+ */
+export function isInteractive(globalOpts: { json?: boolean; noInteractive?: boolean }): boolean {
+  const isTTY = process.stdout.isTTY ?? false;
+  return isTTY && !globalOpts.json && !globalOpts.noInteractive;
+}