@xmemo/skill 1.1.25

package/skill/scripts/commands/ledger.mjs

@@ -0,0 +1,175 @@
+import {
+  EXIT_CODE,
+  exitCodeForError,
+} from '../lib/core.mjs';
+
+import {
+  makeHttpRequest,
+  handleRestError,
+  safeJson,
+  sanitizeTerminalText,
+} from '../lib/api.mjs';
+
+export async function handleLedger(ctx) {
+  const { command, options, flags, token } = ctx;
+
+  if (command === 'ledger-list') {
+    let dateFrom = flags.from;
+    let dateTo = flags.to;
+    if (flags.month) {
+      const [y, m] = flags.month.split('-').map(Number);
+      const lastDayNum = new Date(Date.UTC(y, m, 0)).getUTCDate();
+      if (!dateFrom) dateFrom = `${flags.month}-01`;
+      if (!dateTo) dateTo = `${flags.month}-${String(lastDayNum).padStart(2, '0')}`;
+    }
+
+    const args = {};
+    if (flags.limit !== undefined) {
+      const parsed = Number(flags.limit);
+      args.limit = Number.isInteger(parsed) ? parsed : flags.limit;
+    }
+    if (flags.offset !== undefined) {
+      const parsed = Number(flags.offset);
+      args.offset = Number.isInteger(parsed) ? parsed : flags.offset;
+    }
+    if (flags.currency) args.currency = String(flags.currency);
+    if (dateFrom) args.date_from = String(dateFrom);
+    if (dateTo) args.date_to = String(dateTo);
+    if (flags.category) args.category = String(flags.category);
+    if (flags['min-amount'] !== undefined) {
+      const parsed = Number(flags['min-amount']);
+      args.min_amount = !isNaN(parsed) ? parsed : flags['min-amount'];
+    }
+    if (flags['max-amount'] !== undefined) {
+      const parsed = Number(flags['max-amount']);
+      args.max_amount = !isNaN(parsed) ? parsed : flags['max-amount'];
+    }
+    if (flags.type) args.transaction_type = String(flags.type);
+
+    try {
+      // Dispatches query to XMemo API over HTTPS with Bearer authorization.
+      const res = await makeHttpRequest(options.baseUrl, '/v1/skill/operations', 'POST', {
+        operation: 'ledger-list',
+        arguments: args,
+      }, {
+        'Authorization': `Bearer ${token}`
+      }, options.timeoutMs);
+
+      const data = handleRestError(res, {
+        notFoundMessage: 'Ledger transactions not found.',
+        context: 'List ledger transactions request',
+        options,
+      });
+
+      const result = (data && typeof data.result === 'object' && data.result !== null) ? data.result : data;
+
+      if (options.json) {
+        console.log(safeJson({
+          ok: true,
+          ...(data?.operation ? { operation: data.operation } : {}),
+          ...result,
+          result,
+        }));
+        process.exit(EXIT_CODE.SUCCESS);
+      }
+
+      const transactions = Array.isArray(result.transactions)
+        ? result.transactions
+        : (Array.isArray(result) ? result : []);
+
+      if (transactions.length === 0) {
+        console.log('No ledger transactions found.');
+        process.exit(EXIT_CODE.SUCCESS);
+      }
+
+      const totalInfo = result.total !== undefined ? ` (total: ${result.total})` : '';
+      console.log(`XMemo Ledger Transactions (${transactions.length}${totalInfo}):`);
+      transactions.forEach((tx, idx) => {
+        const date = tx.transaction_date || tx.date || tx.created_at || '(unknown date)';
+        const amount = (tx.amount !== undefined && tx.amount !== null) ? tx.amount : '(unknown)';
+        const curr = tx.currency || 'UNKNOWN';
+        const type = tx.transaction_type || tx.type || 'expense';
+        const cat = tx.category ? ` [${tx.category}]` : '';
+        const desc = tx.description || tx.item || tx.note || '';
+        console.log(`[${idx + 1}] ${sanitizeTerminalText(date)} | ${type.toUpperCase()} | ${amount} ${curr}${sanitizeTerminalText(cat)}${desc ? ` | ${sanitizeTerminalText(desc)}` : ''}`);
+      });
+      process.exit(EXIT_CODE.SUCCESS);
+    } catch (e) {
+      console.error('List ledger transactions failed:', e.message);
+      process.exit(exitCodeForError(e));
+    }
+  }
+
+  if (command === 'ledger-summary') {
+    const args = {};
+    if (flags.months !== undefined) {
+      const parsed = Number(flags.months);
+      args.months = Number.isInteger(parsed) ? parsed : flags.months;
+    }
+    if (flags.currency) args.currency = String(flags.currency);
+    if (flags.type) args.transaction_type = String(flags.type);
+
+    try {
+      // Dispatches query to XMemo API over HTTPS with Bearer authorization.
+      const res = await makeHttpRequest(options.baseUrl, '/v1/skill/operations', 'POST', {
+        operation: 'ledger-summary',
+        arguments: args,
+      }, {
+        'Authorization': `Bearer ${token}`
+      }, options.timeoutMs);
+
+      const data = handleRestError(res, {
+        notFoundMessage: 'Ledger monthly summary not found.',
+        context: 'Get ledger monthly summary request',
+        options,
+      });
+
+      const result = (data && typeof data.result === 'object' && data.result !== null) ? data.result : data;
+
+      if (options.json) {
+        console.log(safeJson({
+          ok: true,
+          ...(data?.operation ? { operation: data.operation } : {}),
+          ...result,
+          result,
+        }));
+        process.exit(EXIT_CODE.SUCCESS);
+      }
+
+      const summaryList = Array.isArray(result.summary) ? result.summary : [];
+      if (summaryList.length === 0 && result.total === undefined && result.count === undefined) {
+        console.log('No ledger monthly summary available.');
+        process.exit(EXIT_CODE.SUCCESS);
+      }
+
+      if (summaryList.length > 0) {
+        console.log(`XMemo Ledger Monthly Summary (${summaryList.length} month${summaryList.length === 1 ? '' : 's'}):`);
+        summaryList.forEach((item) => {
+          const month = item.month || '(unknown month)';
+          const curr = item.currency || 'UNKNOWN';
+          const expense = item.expense_total !== undefined ? `${item.expense_total} ${curr}` : null;
+          const income = item.income_total !== undefined ? `${item.income_total} ${curr}` : null;
+          const net = item.net_total !== undefined ? `${item.net_total} ${curr}` : null;
+          const count = item.transaction_count !== undefined ? `${item.transaction_count} tx` : '';
+          const parts = [];
+          if (expense !== null) parts.push(`Expense: ${expense}`);
+          if (income !== null) parts.push(`Income: ${income}`);
+          if (net !== null) parts.push(`Net: ${net}`);
+          if (count) parts.push(count);
+          console.log(`- ${month} (${curr}): ${parts.join(' | ')}`);
+        });
+        process.exit(EXIT_CODE.SUCCESS);
+      }
+
+      const month = result.month || '(unknown month)';
+      const curr = result.currency || 'UNKNOWN';
+      const total = result.total !== undefined ? result.total : 0;
+      const count = result.count !== undefined ? result.count : 0;
+      console.log(`XMemo ledger summary for ${sanitizeTerminalText(month)}: ${total} ${curr} across ${count} transaction${count === 1 ? '' : 's'}.`);
+      process.exit(EXIT_CODE.SUCCESS);
+    } catch (e) {
+      console.error('Get ledger monthly summary failed:', e.message);
+      process.exit(exitCodeForError(e));
+    }
+  }
+}

package/skill/scripts/commands/memory.mjs

@@ -0,0 +1,306 @@
+import {
+  EXIT_CODE,
+  exitCodeForHttpStatus,
+  exitCodeForErrorCode,
+  exitCodeForError,
+} from '../lib/core.mjs';
+
+import {
+  printMemoryResults,
+} from '../lib/auth-state.mjs';
+
+import {
+  makeHttpRequest,
+  parseJsonResponse,
+  extractRequestId,
+  extractId,
+  apiErrorMessage,
+  outputRestError,
+  handleRestError,
+  outputJsonFailure,
+  safeJson,
+  sanitizeTerminalText,
+  formatMemoryContent,
+} from '../lib/api.mjs';
+
+function reqSuffix(data) {
+  const reqId = extractRequestId(data);
+  return reqId ? ` (request_id: ${reqId})` : '';
+}
+
+function failRequest(data, statusCode, prefix) {
+  console.error(`${prefix}${reqSuffix(data)}`);
+  process.exit(exitCodeForErrorCode(data?.error?.code) ?? exitCodeForHttpStatus(statusCode));
+}
+
+function extractRecord(data) {
+  if (data && typeof data === 'object') {
+    if (data.result && typeof data.result === 'object') return data.result;
+    if (data.memory && typeof data.memory === 'object') return data.memory;
+  }
+  return data;
+}
+
+export async function handleMemory(ctx) {
+  const { command, options, flags, token } = ctx;
+
+  if (command === 'restart-snapshot' || command === 'restart-restore') {
+    const endpoint = command === 'restart-snapshot' ? '/v1/restart/snapshot' : '/v1/restart/restore';
+    const label = command === 'restart-snapshot' ? 'Restart snapshot' : 'Restart restore';
+    try {
+      const res = await makeHttpRequest(options.baseUrl, endpoint, 'POST', flags, {
+        'Authorization': `Bearer ${token}`
+      }, options.timeoutMs);
+      const data = parseJsonResponse(res, `${label} request`);
+      const succeeded = res.statusCode >= 200 && res.statusCode < 300;
+      if (options.json) {
+        if (succeeded) {
+          const payload = (data && typeof data === 'object') ? data : { result: data };
+          console.log(safeJson({ ok: true, ...payload }));
+          process.exit(EXIT_CODE.SUCCESS);
+        }
+        outputJsonFailure(data, res.statusCode);
+      }
+      if (!succeeded) {
+        failRequest(data, res.statusCode, `${label} failed: ${apiErrorMessage(data)} (HTTP ${res.statusCode})`);
+      }
+      if (command === 'restart-snapshot') {
+        console.log(`✅ Restart snapshot saved.\nID: ${sanitizeTerminalText(extractId(data))}${data.expires_at ? `\nExpires: ${sanitizeTerminalText(data.expires_at)}` : ''}`);
+      } else {
+        const isNotRestored = data.restored === false || data.status === 'not_found' || (!extractId(data) && !data.restored_at);
+        if (isNotRestored) {
+          console.log('ℹ️ No active restart snapshot found to restore.');
+        } else {
+          console.log(`✅ Restart snapshot restored.\nID: ${sanitizeTerminalText(extractId(data))}${data.restored_at ? `\nRestored: ${sanitizeTerminalText(data.restored_at)}` : ''}`);
+        }
+      }
+      process.exit(EXIT_CODE.SUCCESS);
+    } catch (e) {
+      console.error(`${label} failed:`, e.message);
+      process.exit(exitCodeForError(e));
+    }
+  }
+
+  if (command === 'recall-context') {
+    const body = Object.fromEntries(
+      Object.entries({
+        query: flags.query,
+        path: flags.path || '%',
+        bucket: flags.bucket || '%',
+        scope: flags.scope,
+        team_id: flags.team_id,
+        memory_type: flags.memory_type || 'auto',
+        status: flags.status || 'active',
+        threshold: flags.threshold === undefined ? undefined : Number(flags.threshold),
+        max_items: flags.max_items,
+        max_tokens: flags.max_tokens,
+        limit: flags.limit,
+        prefer_working: flags.prefer_working === undefined ? true : flags.prefer_working,
+        include_knowledge: flags.include_knowledge,
+      }).filter(([, v]) => v !== undefined)
+    );
+    try {
+      const res = await makeHttpRequest(options.baseUrl, '/v1/recall/context', 'POST', body, {
+        'Authorization': `Bearer ${token}`
+      }, options.timeoutMs);
+      const data = parseJsonResponse(res, 'Recall context request');
+      const succeeded = res.statusCode >= 200 && res.statusCode < 300 && data.ok !== false;
+      if (options.json) {
+        console.log(safeJson(data));
+        process.exit(succeeded ? EXIT_CODE.SUCCESS : (exitCodeForErrorCode(data?.error?.code) ?? exitCodeForHttpStatus(res.statusCode)));
+      }
+      if (!succeeded) {
+        failRequest(data, res.statusCode, `Error: ${apiErrorMessage(data)} (Code: ${data.error?.code || `HTTP ${res.statusCode}`})`);
+      }
+      const items = Array.isArray(data.items) ? data.items.length : 0;
+      const contextText = sanitizeTerminalText(data.context_text || '');
+      console.log(`XMemo Context: ${items} item${items === 1 ? '' : 's'}\n${contextText || 'No matching memories found.'}`);
+      process.exit(EXIT_CODE.SUCCESS);
+    } catch (e) {
+      console.error('Recall context failed:', e.message);
+      process.exit(exitCodeForError(e));
+    }
+  }
+
+  if (command === 'read') {
+    const queryParams = [
+      flags.bucket ? `bucket=${encodeURIComponent(flags.bucket)}` : null,
+      flags.scope ? `scope=${encodeURIComponent(flags.scope)}` : null,
+    ].filter(Boolean);
+    const endpoint = `/v1/memories/${encodeURIComponent(flags.id)}/explain?include_embedding=false${queryParams.length ? `&${queryParams.join('&')}` : ''}`;
+    try {
+      const res = await makeHttpRequest(options.baseUrl, endpoint, 'GET', null, {
+        'Authorization': `Bearer ${token}`
+      }, options.timeoutMs);
+
+      const data = handleRestError(res, {
+        notFoundMessage: `Memory '${flags.id}' not found.`,
+        context: 'Read memory request',
+        options,
+      });
+
+      const record = extractRecord(data);
+      if (record && record.status && String(record.status).toLowerCase() === 'deleted') {
+        outputRestError('not_found', `Memory '${flags.id}' not found or deleted.`, options);
+      }
+
+      if (!record || typeof record.content !== 'string') {
+        outputRestError('not_found', `Memory '${flags.id}' not found.`, options);
+      }
+
+      const fullContent = record.content;
+      const totalLength = fullContent.length;
+      const offset = flags.offset !== undefined ? Number(flags.offset) : 0;
+      const hasLimit = flags.limit !== undefined && flags.limit !== null;
+      const limit = hasLimit ? Number(flags.limit) : totalLength;
+      const slicedContent = fullContent.slice(offset, offset + limit);
+      const truncated = offset > 0 || (offset + slicedContent.length < totalLength);
+
+      const projected = {
+        id: record.id || record.memory_id || flags.id,
+        path: record.path || record.canonical_path || '',
+        content: slicedContent,
+        version: record.version || record.updated_at || record.created_at || null,
+        truncated,
+      };
+
+      if (options.json) {
+        console.log(safeJson({ ok: true, ...projected }));
+        process.exit(EXIT_CODE.SUCCESS);
+      }
+
+      console.log(`Memory: ${sanitizeTerminalText(projected.id)} | Path: ${sanitizeTerminalText(projected.path || '(unknown)')} | Version: ${sanitizeTerminalText(projected.version || '(unknown)')}${projected.truncated ? ' [truncated]' : ''}`);
+      console.log(`Content: ${formatMemoryContent(projected.content, options.compact)}`);
+      process.exit(EXIT_CODE.SUCCESS);
+    } catch (e) {
+      console.error('Read memory failed:', e.message);
+      process.exit(exitCodeForError(e));
+    }
+  }
+
+  if (command === 'update') {
+    const endpoint = `/v1/memories/${encodeURIComponent(flags.id)}`;
+    const body = {};
+    if (flags.content !== undefined) body.content = flags.content;
+    if (flags.path !== undefined) body.path = flags.path;
+    if (flags.metadata !== undefined) body.metadata = flags.metadata;
+    if (flags.bucket !== undefined) body.bucket = flags.bucket;
+    if (flags.scope !== undefined) body.scope = flags.scope;
+
+    try {
+      const res = await makeHttpRequest(options.baseUrl, endpoint, 'PATCH', body, {
+        'Authorization': `Bearer ${token}`
+      }, options.timeoutMs);
+
+      if (res.statusCode === 400) {
+        let errData = null;
+        try { errData = parseJsonResponse(res, 'Update memory request'); } catch {}
+        const code = errData?.error?.code || 'invalid_request';
+        const fallbackMsg = code === 'invalid_memory_id'
+          ? `Invalid memory ID: '${flags.id}'.`
+          : 'Invalid update request.';
+        const msg = apiErrorMessage(errData, fallbackMsg);
+        outputRestError(code, msg, options, errData, EXIT_CODE.USER_ERROR);
+      }
+
+      const data = handleRestError(res, {
+        notFoundMessage: `Memory '${flags.id}' not found.`,
+        context: 'Update memory request',
+        options,
+      });
+
+      const record = extractRecord(data);
+      const memoryId = record?.id || record?.memory_id || flags.id;
+      if (options.json) {
+        console.log(safeJson({
+          ok: true,
+          id: memoryId,
+          path: record?.path || flags.path || '',
+          updated: true,
+          ...(typeof record === 'object' ? record : {}),
+        }));
+        process.exit(EXIT_CODE.SUCCESS);
+      }
+
+      console.log(`✅ Memory updated.\nID: ${sanitizeTerminalText(memoryId)}${flags.path ? `\nPath: ${sanitizeTerminalText(flags.path)}` : ''}`);
+      process.exit(EXIT_CODE.SUCCESS);
+    } catch (e) {
+      console.error('Update memory failed:', e.message);
+      process.exit(exitCodeForError(e));
+    }
+  }
+
+  if (command === 'forget') {
+    if (!flags.confirm) {
+      const msg = `Confirmation required to forget memory or ledger record '${flags.id}'. Pass --confirm to proceed.`;
+      if (options.json) {
+        console.log(safeJson({ ok: false, error: { code: 'confirmation_required', message: msg, target_id: flags.id } }));
+      } else {
+        console.error(`Error: ${msg}\nTarget: ${sanitizeTerminalText(flags.id)}`);
+      }
+      process.exit(EXIT_CODE.USER_ERROR);
+    }
+
+    const endpoint = `/v1/memories/${encodeURIComponent(flags.id)}/forget`;
+    const body = { mode: 'soft_delete' };
+    if (flags.reason !== undefined && String(flags.reason).trim() !== '') {
+      body.reason = String(flags.reason);
+    }
+
+    try {
+      const res = await makeHttpRequest(options.baseUrl, endpoint, 'POST', body, {
+        'Authorization': `Bearer ${token}`
+      }, options.timeoutMs);
+
+      handleRestError(res, {
+        notFoundMessage: `Record '${flags.id}' not found.`,
+        context: 'Forget request',
+        options,
+      });
+
+      if (options.json) {
+        console.log(safeJson({ ok: true, id: flags.id, mode: 'soft_delete', forgotten: true }));
+        process.exit(EXIT_CODE.SUCCESS);
+      }
+
+      console.log(`✅ Record forgotten (soft-deleted).\nID: ${sanitizeTerminalText(flags.id)}`);
+      process.exit(EXIT_CODE.SUCCESS);
+    } catch (e) {
+      console.error('Forget failed:', e.message);
+      process.exit(exitCodeForError(e));
+    }
+  }
+
+  if (command === 'remember' || command === 'recall' || command === 'search') {
+    try {
+      const res = await makeHttpRequest(options.baseUrl, '/v1/skill/operations', 'POST', {
+        operation: command,
+        arguments: flags,
+      }, {
+        'Authorization': `Bearer ${token}`
+      }, options.timeoutMs);
+
+      const data = parseJsonResponse(res, `${command} request`);
+      const succeeded = res.statusCode >= 200 && res.statusCode < 300 && data.ok !== false;
+      if (options.json) {
+        console.log(safeJson(data));
+        process.exit(succeeded ? EXIT_CODE.SUCCESS : (exitCodeForErrorCode(data?.error?.code) ?? exitCodeForHttpStatus(res.statusCode)));
+      }
+
+      if (!succeeded) {
+        failRequest(data, res.statusCode, `Error: ${apiErrorMessage(data)} (Code: ${data.error?.code || `HTTP ${res.statusCode}`})`);
+      }
+
+      if (command === 'recall' || command === 'search') {
+        printMemoryResults(data.result, options.compact);
+        process.exit(EXIT_CODE.SUCCESS);
+      } else if (command === 'remember') {
+        console.log(`✅ Saved to XMemo.\nID: ${sanitizeTerminalText(extractId(data.result))}`);
+        process.exit(EXIT_CODE.SUCCESS);
+      }
+    } catch (e) {
+      console.error('Request failed:', e.message);
+      process.exit(exitCodeForError(e));
+    }
+  }
+}