@lumenflow/cli 5.4.0 → 5.7.12

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

@@ -1,263 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-import type { ToolOutput } from '@lumenflow/kernel';
-import { RUNTIME_CLI_COMMANDS, runtimeCliAdapter } from './runtime-cli-adapter.js';
-
-const AGENT_TOOLS = {
-  AGENT_SESSION: 'agent:session',
-  AGENT_SESSION_END: 'agent:session-end',
-  AGENT_LOG_ISSUE: 'agent:log-issue',
-  AGENT_ISSUES_QUERY: 'agent:issues-query',
-} as const;
-
-type AgentToolName = (typeof AGENT_TOOLS)[keyof typeof AGENT_TOOLS];
-
-const AGENT_TOOL_ERROR_CODES: Record<AgentToolName, string> = {
-  'agent:session': 'AGENT_SESSION_ERROR',
-  'agent:session-end': 'AGENT_SESSION_END_ERROR',
-  'agent:log-issue': 'AGENT_LOG_ISSUE_ERROR',
-  'agent:issues-query': 'AGENT_ISSUES_QUERY_ERROR',
-};
-
-const AGENT_TOOL_COMMANDS: Record<
-  AgentToolName,
-  (typeof RUNTIME_CLI_COMMANDS)[keyof typeof RUNTIME_CLI_COMMANDS]
-> = {
-  'agent:session': RUNTIME_CLI_COMMANDS.AGENT_SESSION,
-  'agent:session-end': RUNTIME_CLI_COMMANDS.AGENT_SESSION_END,
-  'agent:log-issue': RUNTIME_CLI_COMMANDS.AGENT_LOG_ISSUE,
-  'agent:issues-query': RUNTIME_CLI_COMMANDS.AGENT_ISSUES_QUERY,
-};
-
-const MISSING_PARAMETER_MESSAGES = {
-  WU_REQUIRED: 'wu is required',
-  TIER_REQUIRED: 'tier is required',
-  CATEGORY_REQUIRED: 'category is required',
-  SEVERITY_REQUIRED: 'severity is required',
-  TITLE_REQUIRED: 'title is required',
-  DESCRIPTION_REQUIRED: 'description 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 runAgentCommand(
-  toolName: AgentToolName,
-  args: string[],
-): Promise<CommandExecutionResult> {
-  return runtimeCliAdapter.run(AGENT_TOOL_COMMANDS[toolName], args);
-}
-
-function createMissingParameterOutput(message: string): ToolOutput {
-  return {
-    success: false,
-    error: {
-      code: 'MISSING_PARAMETER',
-      message,
-    },
-  };
-}
-
-function createFailureOutput(
-  toolName: AgentToolName,
-  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: AGENT_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: AgentToolName,
-  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 executeAgentTool(toolName: AgentToolName, args: string[]): Promise<ToolOutput> {
-  const execution = await runAgentCommand(toolName, args);
-  if (!execution.ok) {
-    return createFailureOutput(toolName, execution);
-  }
-  return createSuccessOutput(toolName, execution);
-}
-
-export async function agentSessionTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const wu = toStringValue(parsed.wu);
-  if (!wu) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
-  }
-
-  const tier = toIntegerString(parsed.tier);
-  if (!tier) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.TIER_REQUIRED);
-  }
-
-  const args = ['--wu', wu, '--tier', tier];
-  const agentType = toStringValue(parsed.agent_type);
-  if (agentType) {
-    args.push('--agent-type', agentType);
-  }
-
-  return executeAgentTool(AGENT_TOOLS.AGENT_SESSION, args);
-}
-
-export async function agentSessionEndTool(_input: unknown): Promise<ToolOutput> {
-  return executeAgentTool(AGENT_TOOLS.AGENT_SESSION_END, []);
-}
-
-export async function agentLogIssueTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const category = toStringValue(parsed.category);
-  if (!category) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.CATEGORY_REQUIRED);
-  }
-  const severity = toStringValue(parsed.severity);
-  if (!severity) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.SEVERITY_REQUIRED);
-  }
-  const title = toStringValue(parsed.title);
-  if (!title) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.TITLE_REQUIRED);
-  }
-  const description = toStringValue(parsed.description);
-  if (!description) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.DESCRIPTION_REQUIRED);
-  }
-
-  const args = [
-    '--category',
-    category,
-    '--severity',
-    severity,
-    '--title',
-    title,
-    '--description',
-    description,
-  ];
-  const resolution = toStringValue(parsed.resolution);
-  if (resolution) {
-    args.push('--resolution', resolution);
-  }
-
-  for (const tag of toStringArray(parsed.tags)) {
-    args.push('--tag', tag);
-  }
-
-  const step = toStringValue(parsed.step);
-  if (step) {
-    args.push('--step', step);
-  }
-
-  for (const file of toStringArray(parsed.files)) {
-    args.push('--file', file);
-  }
-
-  return executeAgentTool(AGENT_TOOLS.AGENT_LOG_ISSUE, args);
-}
-
-export async function agentIssuesQueryTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const args = ['summary'];
-
-  const since = toIntegerString(parsed.since);
-  if (since) {
-    args.push('--since', since);
-  }
-  const category = toStringValue(parsed.category);
-  if (category) {
-    args.push('--category', category);
-  }
-  const severity = toStringValue(parsed.severity);
-  if (severity) {
-    args.push('--severity', severity);
-  }
-
-  return executeAgentTool(AGENT_TOOLS.AGENT_ISSUES_QUERY, args);
-}

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

@@ -1,66 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-/* eslint-disable security/detect-non-literal-fs-filename */
-import { appendFile, mkdir } from 'node:fs/promises';
-import path from 'node:path';
-import { UTF8_ENCODING } from '../constants.js';
-
-export interface RecordDelegationInput {
-  parentWuId: string;
-  targetWuId: string;
-  lane: string;
-  registryPath: string;
-  lineage?: string[];
-}
-
-export interface RecordDelegationResult {
-  success: boolean;
-  delegationId: string;
-}
-
-function migrateLegacyStatePath(registryPath: string): string {
-  const normalized = registryPath.replace(/\\/g, '/');
-  if (normalized.startsWith('.lumenflow/state/')) {
-    return path.join('runtime', 'state', normalized.slice('.lumenflow/state/'.length));
-  }
-
-  const legacySegment = '/.lumenflow/state/';
-  const segmentIndex = normalized.indexOf(legacySegment);
-  if (segmentIndex < 0) {
-    return registryPath;
-  }
-
-  return [
-    normalized.slice(0, segmentIndex),
-    'runtime',
-    'state',
-    normalized.slice(segmentIndex + legacySegment.length),
-  ]
-    .filter(Boolean)
-    .join('/');
-}
-
-export async function recordDelegationTool(
-  input: RecordDelegationInput,
-): Promise<RecordDelegationResult> {
-  const registryPath = migrateLegacyStatePath(input.registryPath);
-  const delegationId = `dlg-${input.parentWuId.toLowerCase()}-${input.targetWuId.toLowerCase()}`;
-  const entry = {
-    id: delegationId,
-    parentWuId: input.parentWuId,
-    targetWuId: input.targetWuId,
-    lane: input.lane,
-    lineage: input.lineage ?? [],
-    delegatedAt: new Date().toISOString(),
-    status: 'pending',
-  };
-
-  await mkdir(path.dirname(registryPath), { recursive: true });
-  await appendFile(registryPath, `${JSON.stringify(entry)}\n`, UTF8_ENCODING);
-
-  return {
-    success: true,
-    delegationId,
-  };
-}

package/packs/software-delivery/tool-impl/flow-metrics-tools.ts

@@ -1,219 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-/**
- * @file flow-metrics-tools.ts
- * @description Software-delivery pack handlers for flow/metrics tools.
- *
- * WU-1905: Migrated from in-process resolver stubs in runtime-tool-resolver.ts
- * to native software-delivery pack handlers.
- */
-
-import type { ToolOutput } from '@lumenflow/kernel';
-import { RUNTIME_CLI_COMMANDS, runtimeCliAdapter } from './runtime-cli-adapter.js';
-
-// --- Tool name constants ---
-
-const FLOW_METRICS_TOOLS = {
-  FLOW_BOTTLENECKS: 'flow:bottlenecks',
-  FLOW_REPORT: 'flow:report',
-  METRICS: 'metrics',
-  METRICS_SNAPSHOT: 'metrics:snapshot',
-} as const;
-
-type FlowMetricsToolName = (typeof FLOW_METRICS_TOOLS)[keyof typeof FLOW_METRICS_TOOLS];
-
-// --- Error code mapping ---
-
-const FLOW_METRICS_TOOL_ERROR_CODES: Record<FlowMetricsToolName, string> = {
-  'flow:bottlenecks': 'FLOW_BOTTLENECKS_ERROR',
-  'flow:report': 'FLOW_REPORT_ERROR',
-  metrics: 'METRICS_ERROR',
-  'metrics:snapshot': 'METRICS_SNAPSHOT_ERROR',
-};
-
-const FLOW_METRICS_TOOL_COMMANDS: Record<
-  FlowMetricsToolName,
-  (typeof RUNTIME_CLI_COMMANDS)[keyof typeof RUNTIME_CLI_COMMANDS]
-> = {
-  'flow:bottlenecks': RUNTIME_CLI_COMMANDS.FLOW_BOTTLENECKS,
-  'flow:report': RUNTIME_CLI_COMMANDS.FLOW_REPORT,
-  metrics: RUNTIME_CLI_COMMANDS.METRICS,
-  'metrics:snapshot': RUNTIME_CLI_COMMANDS.METRICS_SNAPSHOT,
-};
-
-// --- Input helpers ---
-
-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 toNumberValue(value: unknown): number | null {
-  if (typeof value === 'number' && Number.isFinite(value)) {
-    return value;
-  }
-  return null;
-}
-
-// --- Command execution ---
-
-interface CommandExecutionResult {
-  ok: boolean;
-  status: number;
-  stdout: string;
-  stderr: string;
-  executionError?: string;
-}
-
-async function runFlowMetricsCommand(
-  toolName: FlowMetricsToolName,
-  args: string[],
-): Promise<CommandExecutionResult> {
-  return runtimeCliAdapter.run(FLOW_METRICS_TOOL_COMMANDS[toolName], args);
-}
-
-function createFailureOutput(
-  toolName: FlowMetricsToolName,
-  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: FLOW_METRICS_TOOL_ERROR_CODES[toolName],
-      message,
-      details: {
-        exit_code: execution.status,
-        stdout: execution.stdout,
-        stderr: execution.stderr,
-      },
-    },
-  };
-}
-
-function createSuccessOutput(
-  toolName: FlowMetricsToolName,
-  execution: CommandExecutionResult,
-): ToolOutput {
-  const message = execution.stdout.trim().length > 0 ? execution.stdout.trim() : `${toolName} ran`;
-  return {
-    success: true,
-    data: {
-      message,
-    },
-  };
-}
-
-async function executeFlowMetricsTool(
-  toolName: FlowMetricsToolName,
-  args: string[],
-): Promise<ToolOutput> {
-  const execution = await runFlowMetricsCommand(toolName, args);
-  if (!execution.ok) {
-    return createFailureOutput(toolName, execution);
-  }
-  return createSuccessOutput(toolName, execution);
-}
-
-// --- Public tool handlers ---
-
-/**
- * flow:bottlenecks handler -- identifies flow bottlenecks via CLI.
- */
-export async function flowBottlenecksTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const args: string[] = [];
-
-  const limit = toNumberValue(parsed.limit);
-  if (limit !== null) {
-    args.push('--limit', String(limit));
-  }
-
-  const format = toStringValue(parsed.format);
-  if (format) {
-    args.push('--format', format);
-  }
-
-  return executeFlowMetricsTool(FLOW_METRICS_TOOLS.FLOW_BOTTLENECKS, args);
-}
-
-/**
- * flow:report handler -- generates flow metrics report via CLI.
- */
-export async function flowReportTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const args: string[] = [];
-
-  const start = toStringValue(parsed.start);
-  if (start) {
-    args.push('--start', start);
-  }
-
-  const end = toStringValue(parsed.end);
-  if (end) {
-    args.push('--end', end);
-  }
-
-  const days = toNumberValue(parsed.days);
-  if (days !== null) {
-    args.push('--days', String(days));
-  }
-
-  const format = toStringValue(parsed.format);
-  if (format) {
-    args.push('--format', format);
-  }
-
-  return executeFlowMetricsTool(FLOW_METRICS_TOOLS.FLOW_REPORT, args);
-}
-
-/**
- * metrics handler -- unified workflow metrics command via CLI.
- */
-export async function metricsTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const args: string[] = [];
-
-  const subcommand = toStringValue(parsed.subcommand);
-  if (subcommand) {
-    args.push(subcommand);
-  }
-
-  const days = toNumberValue(parsed.days);
-  if (days !== null) {
-    args.push('--days', String(days));
-  }
-
-  const format = toStringValue(parsed.format);
-  if (format) {
-    args.push('--format', format);
-  }
-
-  return executeFlowMetricsTool(FLOW_METRICS_TOOLS.METRICS, args);
-}
-
-/**
- * metrics:snapshot handler -- captures metrics snapshot via CLI.
- */
-export async function metricsSnapshotTool(_input: unknown): Promise<ToolOutput> {
-  return executeFlowMetricsTool(FLOW_METRICS_TOOLS.METRICS_SNAPSHOT, []);
-}

package/packs/software-delivery/tool-impl/git-runner.ts

@@ -1,113 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-import { execFileSync } from 'node:child_process';
-import { UTF8_ENCODING } from '../constants.js';
-
-const GIT_BINARY_ENV_VAR = 'LUMENFLOW_GIT_BINARY';
-const POSIX_GIT_BINARY = 'git';
-const WINDOWS_GIT_BINARY = 'git.exe';
-
-export interface GitCommandResult {
-  ok: boolean;
-  stdout: string;
-  stderr: string;
-  status: number;
-}
-
-function firstNonEmptyLine(value: unknown): string | null {
-  if (typeof value !== 'string') {
-    return null;
-  }
-  const line = value
-    .split(/\r?\n/)
-    .map((entry) => entry.trim())
-    .find((entry) => entry.length > 0);
-  return line ?? null;
-}
-
-function resolveGitBinaryFromPath(): string | null {
-  const lookupCommand = process.platform === 'win32' ? 'where' : 'which';
-  const lookupTarget = process.platform === 'win32' ? WINDOWS_GIT_BINARY : POSIX_GIT_BINARY;
-  const lookupResult = runCommand(lookupCommand, [lookupTarget], {});
-
-  if (!lookupResult || lookupResult.status !== 0) {
-    return null;
-  }
-  return firstNonEmptyLine(lookupResult.stdout);
-}
-
-export function resolveGitBinary(): string {
-  const configured = process.env[GIT_BINARY_ENV_VAR]?.trim();
-  if (configured && configured.length > 0) {
-    return configured;
-  }
-  const resolved = resolveGitBinaryFromPath();
-  if (resolved) {
-    return resolved;
-  }
-  return process.platform === 'win32' ? WINDOWS_GIT_BINARY : POSIX_GIT_BINARY;
-}
-
-export const GIT_BINARY = resolveGitBinary();
-
-export function runGit(
-  args: string[],
-  options: { cwd?: string; gitBinary?: string } = {},
-): GitCommandResult {
-  const result = runCommand(options.gitBinary ?? GIT_BINARY, args, { cwd: options.cwd });
-  return {
-    ok: result.status === 0,
-    stdout: result.stdout,
-    stderr: result.stderr,
-    status: result.status ?? 1,
-  };
-}
-
-function runCommand(command: string, args: string[], options: { cwd?: string }): GitCommandResult {
-  try {
-    const stdout = execFileSync(command, args, {
-      cwd: options.cwd,
-      encoding: UTF8_ENCODING,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    return {
-      ok: true,
-      stdout,
-      stderr: '',
-      status: 0,
-    };
-  } catch (error: unknown) {
-    if (error && typeof error === 'object') {
-      const typedError = error as {
-        status?: number;
-        stdout?: string | Buffer;
-        stderr?: string | Buffer;
-        message?: string;
-      };
-      return {
-        ok: false,
-        stdout: toCommandOutput(typedError.stdout),
-        stderr: toCommandOutput(typedError.stderr) || (typedError.message ?? ''),
-        status: typeof typedError.status === 'number' ? typedError.status : 1,
-      };
-    }
-
-    return {
-      ok: false,
-      stdout: '',
-      stderr: String(error),
-      status: 1,
-    };
-  }
-}
-
-function toCommandOutput(value: string | Buffer | undefined): string {
-  if (typeof value === 'string') {
-    return value;
-  }
-  if (value instanceof Buffer) {
-    return value.toString(UTF8_ENCODING);
-  }
-  return '';
-}