@lumenflow/cli 3.1.2 → 3.2.0

package/packs/software-delivery/tool-impl/lane-lock.ts

@@ -0,0 +1,246 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/* eslint-disable security/detect-non-literal-fs-filename */
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { UTF8_ENCODING } from '../constants.js';
+
+export interface LaneLockMetadata {
+  lane: string;
+  wuId: string;
+  owner: string;
+  timestamp: string;
+}
+
+export interface AcquireLaneLockInput {
+  lane: string;
+  wuId: string;
+  owner: string;
+  locksDir: string;
+  staleAfterMs?: number;
+}
+
+export interface AcquireLaneLockResult {
+  acquired: boolean;
+  is_stale: boolean;
+  lock_path: string;
+}
+
+export interface ReleaseLaneLockInput {
+  lane: string;
+  owner: string;
+  locksDir: string;
+}
+
+export interface ReleaseLaneLockResult {
+  released: boolean;
+  lock_path: string;
+}
+
+function laneToLockFileName(lane: string): string {
+  const chars: string[] = [];
+  for (const char of lane.toLowerCase()) {
+    if ((char >= 'a' && char <= 'z') || (char >= '0' && char <= '9')) {
+      chars.push(char);
+      continue;
+    }
+    if (chars[chars.length - 1] !== '-') {
+      chars.push('-');
+    }
+  }
+  let normalized = chars.join('');
+  while (normalized.startsWith('-')) {
+    normalized = normalized.slice(1);
+  }
+  while (normalized.endsWith('-')) {
+    normalized = normalized.slice(0, -1);
+  }
+  return `${normalized || 'lane'}.lock`;
+}
+
+function lockPathFor(input: { lane: string; locksDir: string }): string {
+  return path.join(input.locksDir, laneToLockFileName(input.lane));
+}
+
+function isStale(metadata: LaneLockMetadata, staleAfterMs: number): boolean {
+  const lockTime = new Date(metadata.timestamp).getTime();
+  return Number.isFinite(lockTime) && Date.now() - lockTime > staleAfterMs;
+}
+
+function staleTakeoverMarkerPath(lockPath: string): string {
+  return `${lockPath}.takeover`;
+}
+
+async function acquireTakeoverMarker(
+  markerPath: string,
+  metadata: LaneLockMetadata,
+): Promise<boolean> {
+  try {
+    await writeFile(markerPath, JSON.stringify(metadata), { encoding: UTF8_ENCODING, flag: 'wx' });
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+type LaneLockWarn = (message: string) => void;
+
+function writeWarning(message: string): void {
+  process.stderr.write(`${message}\n`);
+}
+
+export async function cleanupTakeoverMarker(
+  markerPath: string,
+  options: {
+    unlinkFile?: (targetPath: string) => Promise<void>;
+    warn?: LaneLockWarn;
+  } = {},
+): Promise<void> {
+  const unlinkFile = options.unlinkFile ?? unlink;
+  const warn: LaneLockWarn = options.warn ?? writeWarning;
+
+  try {
+    await unlinkFile(markerPath);
+  } catch (error) {
+    const nodeError = error as NodeJS.ErrnoException;
+    if (nodeError.code === 'ENOENT') {
+      return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    warn(`[lane-lock] failed to cleanup takeover marker at ${markerPath}: ${message}`);
+  }
+}
+
+export async function readLaneLockMetadata(lockPath: string): Promise<LaneLockMetadata | null> {
+  try {
+    const raw = await readFile(lockPath, UTF8_ENCODING);
+    const parsed = JSON.parse(raw) as LaneLockMetadata;
+    if (
+      typeof parsed.lane !== 'string' ||
+      typeof parsed.wuId !== 'string' ||
+      typeof parsed.owner !== 'string' ||
+      typeof parsed.timestamp !== 'string'
+    ) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export async function acquireLaneLockTool(
+  input: AcquireLaneLockInput,
+): Promise<AcquireLaneLockResult> {
+  await mkdir(input.locksDir, { recursive: true });
+  const lockPath = lockPathFor(input);
+  const staleAfterMs = input.staleAfterMs ?? 2 * 60 * 60 * 1000;
+  const nextMetadata: LaneLockMetadata = {
+    lane: input.lane,
+    wuId: input.wuId,
+    owner: input.owner,
+    timestamp: new Date().toISOString(),
+  };
+
+  try {
+    await writeFile(lockPath, JSON.stringify(nextMetadata), {
+      encoding: UTF8_ENCODING,
+      flag: 'wx',
+    });
+    return {
+      acquired: true,
+      is_stale: false,
+      lock_path: lockPath,
+    };
+  } catch (error) {
+    const isExists = (error as NodeJS.ErrnoException).code === 'EEXIST';
+    if (!isExists) {
+      throw error;
+    }
+
+    const existing = await readLaneLockMetadata(lockPath);
+    if (existing && isStale(existing, staleAfterMs)) {
+      const takeoverMarkerPath = staleTakeoverMarkerPath(lockPath);
+      const wonTakeoverRace = await acquireTakeoverMarker(takeoverMarkerPath, nextMetadata);
+      if (!wonTakeoverRace) {
+        return {
+          acquired: false,
+          is_stale: false,
+          lock_path: lockPath,
+        };
+      }
+
+      try {
+        const current = await readLaneLockMetadata(lockPath);
+        if (!current || !isStale(current, staleAfterMs)) {
+          return {
+            acquired: false,
+            is_stale: false,
+            lock_path: lockPath,
+          };
+        }
+
+        await unlink(lockPath).catch((unlinkError) => {
+          const nodeError = unlinkError as NodeJS.ErrnoException;
+          if (nodeError.code === 'ENOENT') {
+            return;
+          }
+          throw unlinkError;
+        });
+
+        try {
+          await writeFile(lockPath, JSON.stringify(nextMetadata), {
+            encoding: UTF8_ENCODING,
+            flag: 'wx',
+          });
+        } catch (writeError) {
+          if ((writeError as NodeJS.ErrnoException).code === 'EEXIST') {
+            return {
+              acquired: false,
+              is_stale: false,
+              lock_path: lockPath,
+            };
+          }
+          throw writeError;
+        }
+
+        return {
+          acquired: true,
+          is_stale: true,
+          lock_path: lockPath,
+        };
+      } finally {
+        await cleanupTakeoverMarker(takeoverMarkerPath);
+      }
+    }
+
+    return {
+      acquired: false,
+      is_stale: false,
+      lock_path: lockPath,
+    };
+  }
+}
+
+export async function releaseLaneLockTool(
+  input: ReleaseLaneLockInput,
+): Promise<ReleaseLaneLockResult> {
+  const lockPath = lockPathFor(input);
+  const metadata = await readLaneLockMetadata(lockPath);
+  if (!metadata || metadata.owner !== input.owner) {
+    return {
+      released: false,
+      lock_path: lockPath,
+    };
+  }
+
+  await unlink(lockPath);
+  return {
+    released: true,
+    lock_path: lockPath,
+  };
+}

package/packs/software-delivery/tool-impl/memory-tools.ts

@@ -0,0 +1,415 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import type { ToolOutput } from '@lumenflow/kernel';
+import { RUNTIME_CLI_COMMANDS, runtimeCliAdapter } from './runtime-cli-adapter.js';
+
+const MEMORY_TOOLS = {
+  MEM_INIT: 'mem:init',
+  MEM_START: 'mem:start',
+  MEM_READY: 'mem:ready',
+  MEM_CHECKPOINT: 'mem:checkpoint',
+  MEM_CLEANUP: 'mem:cleanup',
+  MEM_CONTEXT: 'mem:context',
+  MEM_CREATE: 'mem:create',
+  MEM_DELETE: 'mem:delete',
+  MEM_EXPORT: 'mem:export',
+  MEM_INBOX: 'mem:inbox',
+  MEM_SIGNAL: 'mem:signal',
+  MEM_SUMMARIZE: 'mem:summarize',
+  MEM_TRIAGE: 'mem:triage',
+  MEM_RECOVER: 'mem:recover',
+} as const;
+
+type MemoryToolName = (typeof MEMORY_TOOLS)[keyof typeof MEMORY_TOOLS];
+
+const MEMORY_TOOL_ERROR_CODES: Record<MemoryToolName, string> = {
+  'mem:init': 'MEM_INIT_ERROR',
+  'mem:start': 'MEM_START_ERROR',
+  'mem:ready': 'MEM_READY_ERROR',
+  'mem:checkpoint': 'MEM_CHECKPOINT_ERROR',
+  'mem:cleanup': 'MEM_CLEANUP_ERROR',
+  'mem:context': 'MEM_CONTEXT_ERROR',
+  'mem:create': 'MEM_CREATE_ERROR',
+  'mem:delete': 'MEM_DELETE_ERROR',
+  'mem:export': 'MEM_EXPORT_ERROR',
+  'mem:inbox': 'MEM_INBOX_ERROR',
+  'mem:signal': 'MEM_SIGNAL_ERROR',
+  'mem:summarize': 'MEM_SUMMARIZE_ERROR',
+  'mem:triage': 'MEM_TRIAGE_ERROR',
+  'mem:recover': 'MEM_RECOVER_ERROR',
+};
+
+const MEMORY_TOOL_COMMANDS: Record<
+  MemoryToolName,
+  (typeof RUNTIME_CLI_COMMANDS)[keyof typeof RUNTIME_CLI_COMMANDS]
+> = {
+  'mem:init': RUNTIME_CLI_COMMANDS.MEM_INIT,
+  'mem:start': RUNTIME_CLI_COMMANDS.MEM_START,
+  'mem:ready': RUNTIME_CLI_COMMANDS.MEM_READY,
+  'mem:checkpoint': RUNTIME_CLI_COMMANDS.MEM_CHECKPOINT,
+  'mem:cleanup': RUNTIME_CLI_COMMANDS.MEM_CLEANUP,
+  'mem:context': RUNTIME_CLI_COMMANDS.MEM_CONTEXT,
+  'mem:create': RUNTIME_CLI_COMMANDS.MEM_CREATE,
+  'mem:delete': RUNTIME_CLI_COMMANDS.MEM_DELETE,
+  'mem:export': RUNTIME_CLI_COMMANDS.MEM_EXPORT,
+  'mem:inbox': RUNTIME_CLI_COMMANDS.MEM_INBOX,
+  'mem:signal': RUNTIME_CLI_COMMANDS.MEM_SIGNAL,
+  'mem:summarize': RUNTIME_CLI_COMMANDS.MEM_SUMMARIZE,
+  'mem:triage': RUNTIME_CLI_COMMANDS.MEM_TRIAGE,
+  'mem:recover': RUNTIME_CLI_COMMANDS.MEM_RECOVER,
+};
+
+const MISSING_PARAMETER_MESSAGES = {
+  ID_REQUIRED: 'id is required',
+  WU_REQUIRED: 'wu is required',
+  MESSAGE_REQUIRED: 'message is required',
+} as const;
+
+interface CommandExecutionResult {
+  ok: boolean;
+  status: number;
+  stdout: string;
+  stderr: string;
+  executionError?: string;
+}
+
+function toRecord(input: unknown): Record<string, unknown> {
+  if (input && typeof input === 'object') {
+    return input as Record<string, unknown>;
+  }
+  return {};
+}
+
+function toStringValue(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function toStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .map((entry) => toStringValue(entry))
+    .filter((entry): entry is string => entry !== null);
+}
+
+function toIntegerString(value: unknown): string | null {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return String(Math.trunc(value));
+  }
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  }
+  return null;
+}
+
+async function runMemoryCommand(
+  toolName: MemoryToolName,
+  args: string[],
+): Promise<CommandExecutionResult> {
+  return runtimeCliAdapter.run(MEMORY_TOOL_COMMANDS[toolName], args);
+}
+
+function createMissingParameterOutput(message: string): ToolOutput {
+  return {
+    success: false,
+    error: {
+      code: 'MISSING_PARAMETER',
+      message,
+    },
+  };
+}
+
+function createFailureOutput(
+  toolName: MemoryToolName,
+  execution: CommandExecutionResult,
+): ToolOutput {
+  const stderrMessage = execution.stderr.trim();
+  const stdoutMessage = execution.stdout.trim();
+  const message =
+    execution.executionError ??
+    (stderrMessage.length > 0
+      ? stderrMessage
+      : stdoutMessage.length > 0
+        ? stdoutMessage
+        : `${toolName} failed`);
+  return {
+    success: false,
+    error: {
+      code: MEMORY_TOOL_ERROR_CODES[toolName],
+      message,
+      details: {
+        exit_code: execution.status,
+        stdout: execution.stdout,
+        stderr: execution.stderr,
+      },
+    },
+  };
+}
+
+function parseJsonOutput(stdout: string): unknown | null {
+  const trimmed = stdout.trim();
+  if (trimmed.length === 0) {
+    return null;
+  }
+  try {
+    return JSON.parse(trimmed) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+function createSuccessOutput(
+  toolName: MemoryToolName,
+  execution: CommandExecutionResult,
+): ToolOutput {
+  const parsedJson = parseJsonOutput(execution.stdout);
+  if (parsedJson !== null) {
+    return {
+      success: true,
+      data: parsedJson,
+    };
+  }
+
+  const message = execution.stdout.trim().length > 0 ? execution.stdout.trim() : `${toolName} ran`;
+  return {
+    success: true,
+    data: {
+      message,
+    },
+  };
+}
+
+async function executeMemoryTool(toolName: MemoryToolName, args: string[]): Promise<ToolOutput> {
+  const execution = await runMemoryCommand(toolName, args);
+  if (!execution.ok) {
+    return createFailureOutput(toolName, execution);
+  }
+  return createSuccessOutput(toolName, execution);
+}
+
+export async function memInitTool(input: unknown): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const wu = toStringValue(parsed.wu);
+  if (!wu) {
+    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
+  }
+
+  return executeMemoryTool(MEMORY_TOOLS.MEM_INIT, ['--wu', wu]);
+}
+
+export async function memStartTool(input: unknown): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const wu = toStringValue(parsed.wu);
+  if (!wu) {
+    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
+  }
+
+  const args = ['--wu', wu];
+  const lane = toStringValue(parsed.lane);
+  if (lane) {
+    args.push('--lane', lane);
+  }
+
+  return executeMemoryTool(MEMORY_TOOLS.MEM_START, args);
+}
+
+export async function memReadyTool(input: unknown): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const wu = toStringValue(parsed.wu);
+  if (!wu) {
+    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
+  }
+
+  return executeMemoryTool(MEMORY_TOOLS.MEM_READY, ['--wu', wu]);
+}
+
+export async function memCheckpointTool(input: unknown): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const wu = toStringValue(parsed.wu);
+  if (!wu) {
+    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
+  }
+
+  const args = ['--wu', wu];
+  const message = toStringValue(parsed.message);
+  if (message) {
+    args.push('--message', message);
+  }
+
+  return executeMemoryTool(MEMORY_TOOLS.MEM_CHECKPOINT, args);
+}
+
+export async function memCleanupTool(input: unknown): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const args: string[] = [];
+  if (parsed.dry_run === true) {
+    args.push('--dry-run');
+  }
+
+  return executeMemoryTool(MEMORY_TOOLS.MEM_CLEANUP, args);
+}
+
+export async function memContextTool(input: unknown): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const wu = toStringValue(parsed.wu);
+  if (!wu) {
+    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
+  }
+
+  const args = ['--wu', wu];
+  const lane = toStringValue(parsed.lane);
+  if (lane) {
+    args.push('--lane', lane);
+  }
+
+  return executeMemoryTool(MEMORY_TOOLS.MEM_CONTEXT, args);
+}
+
+export async function memCreateTool(input: unknown): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const message = toStringValue(parsed.message);
+  if (!message) {
+    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.MESSAGE_REQUIRED);
+  }
+
+  const wu = toStringValue(parsed.wu);
+  if (!wu) {
+    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
+  }
+
+  const args = [message, '--wu', wu];
+  const type = toStringValue(parsed.type);
+  if (type) {
+    args.push('--type', type);
+  }
+  const tags = toStringArray(parsed.tags);
+  if (tags.length > 0) {
+    args.push('--tags', tags.join(','));
+  }
+
+  return executeMemoryTool(MEMORY_TOOLS.MEM_CREATE, args);
+}
+
+export async function memDeleteTool(input: unknown): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const id = toStringValue(parsed.id);
+  if (!id) {
+    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.ID_REQUIRED);
+  }
+
+  return executeMemoryTool(MEMORY_TOOLS.MEM_DELETE, ['--id', id]);
+}
+
+export async function memExportTool(input: unknown): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const wu = toStringValue(parsed.wu);
+  if (!wu) {
+    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
+  }
+
+  const args = ['--wu', wu];
+  const format = toStringValue(parsed.format);
+  if (format) {
+    args.push('--format', format);
+  }
+
+  return executeMemoryTool(MEMORY_TOOLS.MEM_EXPORT, args);
+}
+
+export async function memInboxTool(input: unknown): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const args: string[] = [];
+  const since = toStringValue(parsed.since);
+  if (since) {
+    args.push('--since', since);
+  }
+  const wu = toStringValue(parsed.wu);
+  if (wu) {
+    args.push('--wu', wu);
+  }
+  const lane = toStringValue(parsed.lane);
+  if (lane) {
+    args.push('--lane', lane);
+  }
+
+  return executeMemoryTool(MEMORY_TOOLS.MEM_INBOX, args);
+}
+
+export async function memSignalTool(input: unknown): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const message = toStringValue(parsed.message);
+  if (!message) {
+    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.MESSAGE_REQUIRED);
+  }
+
+  const wu = toStringValue(parsed.wu);
+  if (!wu) {
+    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
+  }
+
+  return executeMemoryTool(MEMORY_TOOLS.MEM_SIGNAL, [message, '--wu', wu]);
+}
+
+export async function memSummarizeTool(input: unknown): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const wu = toStringValue(parsed.wu);
+  if (!wu) {
+    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
+  }
+
+  return executeMemoryTool(MEMORY_TOOLS.MEM_SUMMARIZE, ['--wu', wu]);
+}
+
+export async function memTriageTool(input: unknown): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const wu = toStringValue(parsed.wu);
+  if (!wu) {
+    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
+  }
+
+  const args = ['--wu', wu];
+  const promote = toStringValue(parsed.promote);
+  if (promote) {
+    args.push('--promote', promote);
+  }
+  const lane = toStringValue(parsed.lane);
+  if (lane) {
+    args.push('--lane', lane);
+  }
+
+  return executeMemoryTool(MEMORY_TOOLS.MEM_TRIAGE, args);
+}
+
+export async function memRecoverTool(input: unknown): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const wu = toStringValue(parsed.wu);
+  if (!wu) {
+    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
+  }
+
+  const args = ['--wu', wu];
+  const maxSize = toIntegerString(parsed.max_size);
+  if (maxSize) {
+    args.push('--max-size', maxSize);
+  }
+  const format = toStringValue(parsed.format);
+  if (format) {
+    args.push('--format', format);
+  }
+  if (parsed.quiet === true) {
+    args.push('--quiet');
+  }
+  const baseDir = toStringValue(parsed.base_dir);
+  if (baseDir) {
+    args.push('--base-dir', baseDir);
+  }
+
+  return executeMemoryTool(MEMORY_TOOLS.MEM_RECOVER, args);
+}

package/packs/software-delivery/tool-impl/pending-runtime-tools.ts

@@ -0,0 +1,21 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+interface PendingRuntimeMigrationOutput {
+  success: false;
+  error: {
+    code: 'TOOL_NOT_IMPLEMENTED';
+    message: string;
+  };
+}
+
+export async function pendingRuntimeMigrationTool(): Promise<PendingRuntimeMigrationOutput> {
+  return {
+    success: false,
+    error: {
+      code: 'TOOL_NOT_IMPLEMENTED',
+      message:
+        'Tool is declared in the software-delivery manifest but has not been migrated to a runtime handler yet.',
+    },
+  };
+}