@lumenflow/cli 3.6.6 → 3.6.7

package/packs/sidekick/tool-impl/shared.ts

@@ -0,0 +1,124 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { randomBytes } from 'node:crypto';
+import type { AuditEvent } from './storage.js';
+
+export interface ToolContextLike {
+  tool_name?: string;
+  receipt_id?: string;
+}
+
+export interface ToolOutput {
+  success: boolean;
+  data?: Record<string, unknown>;
+  error?: { code: string; message: string; details?: Record<string, unknown> };
+  metadata?: Record<string, unknown>;
+}
+
+export function toRecord(input: unknown): Record<string, unknown> {
+  if (input && typeof input === 'object' && !Array.isArray(input)) {
+    return input as Record<string, unknown>;
+  }
+  return {};
+}
+
+export function asNonEmptyString(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+export function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const items: string[] = [];
+  for (const entry of value) {
+    const normalized = asNonEmptyString(entry);
+    if (normalized) {
+      items.push(normalized);
+    }
+  }
+  return [...new Set(items)];
+}
+
+export function asInteger(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return Math.trunc(value);
+  }
+  if (typeof value === 'string') {
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+
+export function isDryRun(input: Record<string, unknown>): boolean {
+  return input.dry_run === true;
+}
+
+export function nowIso(): string {
+  return new Date().toISOString();
+}
+
+export function createId(prefix: string): string {
+  return `${prefix}-${randomBytes(4).toString('hex')}`;
+}
+
+export function failure(
+  code: string,
+  message: string,
+  details?: Record<string, unknown>,
+): ToolOutput {
+  return {
+    success: false,
+    error: {
+      code,
+      message,
+      ...(details ? { details } : {}),
+    },
+  };
+}
+
+export function success(data: Record<string, unknown>): ToolOutput {
+  return {
+    success: true,
+    data,
+  };
+}
+
+export function matchesTags(requiredTags: string[], candidateTags: string[]): boolean {
+  if (requiredTags.length === 0) {
+    return true;
+  }
+  const candidateSet = new Set(candidateTags.map((tag) => tag.toLowerCase()));
+  return requiredTags.every((tag) => candidateSet.has(tag.toLowerCase()));
+}
+
+export function includesText(haystack: string, needle: string | null): boolean {
+  if (!needle) {
+    return true;
+  }
+  return haystack.toLowerCase().includes(needle.toLowerCase());
+}
+
+export function buildAuditEvent(input: {
+  tool: string;
+  op: AuditEvent['op'];
+  context?: ToolContextLike;
+  ids?: string[];
+  details?: Record<string, unknown>;
+}): AuditEvent {
+  return {
+    id: createId('evt'),
+    ts: nowIso(),
+    tool: input.tool,
+    op: input.op,
+    actor: input.context?.receipt_id,
+    ids: input.ids,
+    details: input.details,
+  };
+}

package/packs/sidekick/tool-impl/storage.ts

@@ -0,0 +1,315 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomBytes } from 'node:crypto';
+import { appendFile, mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const UTF8_ENCODING = 'utf8';
+const DEFAULT_LOCK_TIMEOUT_MS = 10_000;
+const LOCK_RETRY_INTERVAL_MS = 25;
+const STALE_LOCK_MS = 30_000;
+const RANDOM_BYTES_LENGTH = 4;
+
+// ---------------------------------------------------------------------------
+// Domain types
+// ---------------------------------------------------------------------------
+
+export type TaskPriority = 'P0' | 'P1' | 'P2' | 'P3';
+export type TaskStatus = 'pending' | 'done';
+export type MemoryType = 'fact' | 'preference' | 'note';
+
+export interface TaskRecord {
+  id: string;
+  title: string;
+  description?: string;
+  priority: TaskPriority;
+  status: TaskStatus;
+  tags: string[];
+  due_at?: string;
+  note?: string;
+  created_at: string;
+  updated_at: string;
+  completed_at?: string;
+}
+
+export interface MemoryRecord {
+  id: string;
+  type: MemoryType;
+  content: string;
+  tags: string[];
+  created_at: string;
+  updated_at: string;
+}
+
+export interface ChannelRecord {
+  id: string;
+  name: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface ChannelMessageRecord {
+  id: string;
+  channel_id: string;
+  sender: string;
+  content: string;
+  created_at: string;
+}
+
+export interface RoutineStepRecord {
+  tool: string;
+  input: Record<string, unknown>;
+}
+
+export interface RoutineRecord {
+  id: string;
+  name: string;
+  steps: RoutineStepRecord[];
+  created_at: string;
+  updated_at: string;
+}
+
+export interface SidekickStores {
+  tasks: TaskRecord[];
+  memories: MemoryRecord[];
+  channels: ChannelRecord[];
+  messages: ChannelMessageRecord[];
+  routines: RoutineRecord[];
+}
+
+export type StoreName = keyof SidekickStores;
+
+// ---------------------------------------------------------------------------
+// Audit types
+// ---------------------------------------------------------------------------
+
+export interface AuditEvent {
+  id: string;
+  ts: string;
+  tool: string;
+  op: 'create' | 'read' | 'update' | 'delete' | 'execute' | 'export';
+  actor?: string;
+  ids?: string[];
+  details?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// StoragePort (hexagonal port)
+// ---------------------------------------------------------------------------
+
+export interface StoragePort {
+  getRootDir(): string;
+  withLock<T>(fn: () => Promise<T>): Promise<T>;
+  readStore<K extends StoreName>(store: K): Promise<SidekickStores[K]>;
+  writeStore<K extends StoreName>(store: K, data: SidekickStores[K]): Promise<void>;
+  appendAudit(event: AuditEvent): Promise<void>;
+  readAuditEvents(): Promise<AuditEvent[]>;
+}
+
+// ---------------------------------------------------------------------------
+// File-path mapping
+// ---------------------------------------------------------------------------
+
+const STORE_FILE_PATHS: Record<StoreName, string> = {
+  tasks: 'tasks/tasks.json',
+  memories: 'memory/memories.json',
+  channels: 'channels/channels.json',
+  messages: 'channels/messages.json',
+  routines: 'routines/routines.json',
+};
+
+const STORE_DEFAULTS: SidekickStores = {
+  tasks: [],
+  memories: [],
+  channels: [],
+  messages: [],
+  routines: [],
+};
+
+const AUDIT_FILE_PATH = 'audit/events.jsonl';
+const LOCK_FILE_PATH = '.lock';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function cloneStore<K extends StoreName>(store: K, value: SidekickStores[K]): SidekickStores[K] {
+  if (Array.isArray(value)) {
+    return value.map((entry) => ({ ...entry })) as SidekickStores[K];
+  }
+  return structuredClone(value) as SidekickStores[K];
+}
+
+function randomToken(): string {
+  return randomBytes(RANDOM_BYTES_LENGTH).toString('hex');
+}
+
+function nowMs(): number {
+  return Date.now();
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+async function ensureParentDir(filePath: string): Promise<void> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+}
+
+async function writeJsonAtomic(filePath: string, data: unknown): Promise<void> {
+  await ensureParentDir(filePath);
+  const tmpPath = `${filePath}.tmp-${process.pid}-${randomToken()}`;
+  await writeFile(tmpPath, `${JSON.stringify(data, null, 2)}\n`, UTF8_ENCODING);
+  await rename(tmpPath, filePath);
+}
+
+async function readJsonFile<T>(filePath: string, fallback: T): Promise<T> {
+  try {
+    const raw = await readFile(filePath, UTF8_ENCODING);
+    return JSON.parse(raw) as T;
+  } catch (error) {
+    const nodeError = error as NodeJS.ErrnoException;
+    if (nodeError.code === 'ENOENT') {
+      await writeJsonAtomic(filePath, fallback);
+      return fallback;
+    }
+    throw error;
+  }
+}
+
+async function maybeRemoveStaleLock(lockPath: string): Promise<void> {
+  try {
+    const metadata = await stat(lockPath);
+    const ageMs = nowMs() - metadata.mtimeMs;
+    if (ageMs > STALE_LOCK_MS) {
+      await rm(lockPath, { force: true });
+    }
+  } catch {
+    // Ignore races for lock cleanup.
+  }
+}
+
+async function withFileLock<T>(lockPath: string, fn: () => Promise<T>): Promise<T> {
+  const deadline = nowMs() + DEFAULT_LOCK_TIMEOUT_MS;
+  let handle: Awaited<ReturnType<typeof open>> | null = null;
+
+  while (nowMs() < deadline) {
+    try {
+      await ensureParentDir(lockPath);
+      handle = await open(lockPath, 'wx');
+      await handle.writeFile(`${process.pid}:${nowMs()}`, UTF8_ENCODING);
+      break;
+    } catch (error) {
+      const nodeError = error as NodeJS.ErrnoException;
+      if (nodeError.code !== 'EEXIST') {
+        throw error;
+      }
+      await maybeRemoveStaleLock(lockPath);
+      await sleep(LOCK_RETRY_INTERVAL_MS);
+    }
+  }
+
+  if (!handle) {
+    throw new Error(`Timed out waiting for sidekick storage lock at ${lockPath}.`);
+  }
+
+  try {
+    return await fn();
+  } finally {
+    await handle.close();
+    await rm(lockPath, { force: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// FsStoragePort (filesystem adapter)
+// ---------------------------------------------------------------------------
+
+export class FsStoragePort implements StoragePort {
+  private readonly rootDir: string;
+
+  constructor(rootDir = path.resolve(process.cwd(), '.sidekick')) {
+    this.rootDir = rootDir;
+  }
+
+  getRootDir(): string {
+    return this.rootDir;
+  }
+
+  async withLock<T>(fn: () => Promise<T>): Promise<T> {
+    return withFileLock(path.join(this.rootDir, LOCK_FILE_PATH), fn);
+  }
+
+  async readStore<K extends StoreName>(store: K): Promise<SidekickStores[K]> {
+    const storePath = path.join(this.rootDir, STORE_FILE_PATHS[store]);
+    const fallback = cloneStore(store, STORE_DEFAULTS[store]);
+    const data = await readJsonFile(storePath, fallback);
+    return cloneStore(store, data);
+  }
+
+  async writeStore<K extends StoreName>(store: K, data: SidekickStores[K]): Promise<void> {
+    const storePath = path.join(this.rootDir, STORE_FILE_PATHS[store]);
+    await writeJsonAtomic(storePath, data);
+  }
+
+  async appendAudit(event: AuditEvent): Promise<void> {
+    const auditPath = path.join(this.rootDir, AUDIT_FILE_PATH);
+    await ensureParentDir(auditPath);
+    await appendFile(auditPath, `${JSON.stringify(event)}\n`, UTF8_ENCODING);
+  }
+
+  async readAuditEvents(): Promise<AuditEvent[]> {
+    const auditPath = path.join(this.rootDir, AUDIT_FILE_PATH);
+    let raw: string;
+    try {
+      raw = await readFile(auditPath, UTF8_ENCODING);
+    } catch (error) {
+      const nodeError = error as NodeJS.ErrnoException;
+      if (nodeError.code === 'ENOENT') {
+        return [];
+      }
+      throw error;
+    }
+
+    const events: AuditEvent[] = [];
+    for (const line of raw.split('\n')) {
+      const trimmed = line.trim();
+      if (trimmed.length === 0) {
+        continue;
+      }
+      try {
+        events.push(JSON.parse(trimmed) as AuditEvent);
+      } catch {
+        // Skip malformed audit lines and keep the stream readable.
+      }
+    }
+    return events;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Injection helpers (AsyncLocalStorage-based)
+// ---------------------------------------------------------------------------
+
+const storageContext = new AsyncLocalStorage<StoragePort>();
+let defaultStoragePort: StoragePort = new FsStoragePort();
+
+export function setDefaultStoragePort(port: StoragePort): void {
+  defaultStoragePort = port;
+}
+
+export function getStoragePort(): StoragePort {
+  return storageContext.getStore() ?? defaultStoragePort;
+}
+
+export async function runWithStoragePort<T>(port: StoragePort, fn: () => Promise<T>): Promise<T> {
+  return storageContext.run(port, fn);
+}

package/packs/sidekick/tool-impl/system-tools.ts

@@ -0,0 +1,155 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { getStoragePort } from './storage.js';
+import {
+  asNonEmptyString,
+  buildAuditEvent,
+  failure,
+  nowIso,
+  success,
+  toRecord,
+  type ToolContextLike,
+  type ToolOutput,
+} from './shared.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const TOOL_NAMES = {
+  INIT: 'sidekick:init',
+  STATUS: 'sidekick:status',
+  EXPORT: 'sidekick:export',
+} as const;
+
+const STORE_NAMES = ['tasks', 'memories', 'channels', 'messages', 'routines'] as const;
+
+// ---------------------------------------------------------------------------
+// sidekick:init (idempotent)
+// ---------------------------------------------------------------------------
+
+async function initTool(context?: ToolContextLike): Promise<ToolOutput> {
+  const storage = getStoragePort();
+
+  // Touch every store to ensure directories and files are created
+  for (const store of STORE_NAMES) {
+    await storage.readStore(store);
+  }
+
+  await storage.appendAudit(
+    buildAuditEvent({
+      tool: TOOL_NAMES.INIT,
+      op: 'create',
+      context,
+      details: { root_dir: storage.getRootDir() },
+    }),
+  );
+
+  return success({
+    initialized: true,
+    root_dir: storage.getRootDir(),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// sidekick:status
+// ---------------------------------------------------------------------------
+
+async function statusTool(context?: ToolContextLike): Promise<ToolOutput> {
+  const storage = getStoragePort();
+  const [tasks, memories, channels, messages, routines, audit] = await Promise.all([
+    storage.readStore('tasks'),
+    storage.readStore('memories'),
+    storage.readStore('channels'),
+    storage.readStore('messages'),
+    storage.readStore('routines'),
+    storage.readAuditEvents(),
+  ]);
+
+  const pendingTasks = tasks.filter((task) => task.status === 'pending').length;
+  const completedTasks = tasks.filter((task) => task.status === 'done').length;
+
+  await storage.appendAudit(
+    buildAuditEvent({
+      tool: TOOL_NAMES.STATUS,
+      op: 'read',
+      context,
+      details: { task_count: tasks.length },
+    }),
+  );
+
+  return success({
+    task_count: tasks.length,
+    pending_tasks: pendingTasks,
+    completed_tasks: completedTasks,
+    memory_entries: memories.length,
+    channels: channels.length,
+    messages: messages.length,
+    routines: routines.length,
+    audit_events: audit.length,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// sidekick:export (READ-ONLY -- returns data, no file write)
+// ---------------------------------------------------------------------------
+
+async function exportTool(input: unknown, context?: ToolContextLike): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const includeAudit = parsed.include_audit !== false;
+
+  const storage = getStoragePort();
+  const [tasks, memories, channels, messages, routines, audit] = await Promise.all([
+    storage.readStore('tasks'),
+    storage.readStore('memories'),
+    storage.readStore('channels'),
+    storage.readStore('messages'),
+    storage.readStore('routines'),
+    storage.readAuditEvents(),
+  ]);
+
+  await storage.appendAudit(
+    buildAuditEvent({
+      tool: TOOL_NAMES.EXPORT,
+      op: 'export',
+      context,
+      details: { include_audit: includeAudit },
+    }),
+  );
+
+  return success({
+    exported_at: nowIso(),
+    version: '0.1.0',
+    data: {
+      tasks,
+      memories,
+      channels,
+      messages,
+      routines,
+      ...(includeAudit ? { audit } : {}),
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Router (default export)
+// ---------------------------------------------------------------------------
+
+export default async function systemTools(
+  input: unknown,
+  context?: ToolContextLike,
+): Promise<ToolOutput> {
+  const toolName = asNonEmptyString(context?.tool_name) ?? '';
+
+  switch (toolName) {
+    case TOOL_NAMES.INIT:
+      return initTool(context);
+    case TOOL_NAMES.STATUS:
+      return statusTool(context);
+    case TOOL_NAMES.EXPORT:
+      return exportTool(input, context);
+    default:
+      return failure('UNKNOWN_TOOL', `Unknown system tool: ${toolName || 'unknown'}`);
+  }
+}