@lumenflow/cli 3.1.2 → 3.1.3

package/packs/software-delivery/pack-registration.ts

@@ -0,0 +1,113 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { createHash } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  SHA256_ALGORITHM,
+  SOFTWARE_DELIVERY_MANIFEST_FILE_NAME,
+  UTF8_ENCODING,
+} from './constants.js';
+import { SOFTWARE_DELIVERY_MANIFEST, type SoftwareDeliveryPackManifest } from './manifest.js';
+
+const NULL_BYTE_BUFFER = Buffer.from([0]);
+const DEFAULT_EXCLUSIONS = ['node_modules/', '.git/', 'dist/', '.DS_Store'];
+
+function getDefaultPackRoot(): string {
+  return path.dirname(fileURLToPath(import.meta.url));
+}
+
+function normalizeRelativePath(root: string, absolutePath: string): string {
+  return path.relative(root, absolutePath).split(path.sep).join('/');
+}
+
+function shouldExclude(relativePath: string, exclusions: readonly string[]): boolean {
+  return exclusions.some((excluded) => {
+    if (excluded.endsWith('/')) {
+      return relativePath.startsWith(excluded);
+    }
+    return relativePath === excluded || relativePath.endsWith(`/${excluded}`);
+  });
+}
+
+async function collectFilesRecursive(root: string, directory: string): Promise<string[]> {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const sortedEntries = [...entries].sort((left, right) => left.name.localeCompare(right.name));
+  const files: string[] = [];
+
+  for (const entry of sortedEntries) {
+    const absolutePath = path.join(directory, entry.name);
+    const relativePath = normalizeRelativePath(root, absolutePath);
+    if (entry.isDirectory()) {
+      files.push(...(await collectFilesRecursive(root, absolutePath)));
+      continue;
+    }
+    files.push(relativePath);
+  }
+
+  return files;
+}
+
+async function listPackFiles(packRoot: string, exclusions: readonly string[]): Promise<string[]> {
+  const absoluteRoot = path.resolve(packRoot);
+  const allFiles = await collectFilesRecursive(absoluteRoot, absoluteRoot);
+  return allFiles.filter((relativePath) => !shouldExclude(relativePath, exclusions)).sort();
+}
+
+export async function computeSoftwareDeliveryPackIntegrity(
+  packRoot = getDefaultPackRoot(),
+  exclusions: readonly string[] = DEFAULT_EXCLUSIONS,
+): Promise<`sha256:${string}`> {
+  const absoluteRoot = path.resolve(packRoot);
+  const files = await listPackFiles(absoluteRoot, exclusions);
+  const digestChunks: Buffer[] = [];
+
+  for (const relativePath of files) {
+    const fileContents = await readFile(path.join(absoluteRoot, relativePath));
+    const fileHash = createHash(SHA256_ALGORITHM).update(fileContents).digest('hex');
+    digestChunks.push(Buffer.from(relativePath, UTF8_ENCODING));
+    digestChunks.push(NULL_BYTE_BUFFER);
+    digestChunks.push(Buffer.from(fileHash, UTF8_ENCODING));
+    digestChunks.push(NULL_BYTE_BUFFER);
+  }
+
+  const combinedDigest = createHash(SHA256_ALGORITHM)
+    .update(digestChunks.length === 0 ? Buffer.alloc(0) : Buffer.concat(digestChunks))
+    .digest('hex');
+
+  return `sha256:${combinedDigest}`;
+}
+
+export async function loadSoftwareDeliveryManifest(
+  packRoot = getDefaultPackRoot(),
+): Promise<SoftwareDeliveryPackManifest> {
+  const manifestPath = path.join(path.resolve(packRoot), SOFTWARE_DELIVERY_MANIFEST_FILE_NAME);
+  await readFile(manifestPath, UTF8_ENCODING);
+  return structuredClone(SOFTWARE_DELIVERY_MANIFEST);
+}
+
+export interface RegisteredSoftwareDeliveryPack {
+  manifest: SoftwareDeliveryPackManifest;
+  packRoot: string;
+  manifestPath: string;
+  integrity: `sha256:${string}`;
+}
+
+export async function registerSoftwareDeliveryPack(options?: {
+  packRoot?: string;
+  exclusions?: readonly string[];
+}): Promise<RegisteredSoftwareDeliveryPack> {
+  const packRoot = path.resolve(options?.packRoot ?? getDefaultPackRoot());
+  const exclusions = options?.exclusions ?? DEFAULT_EXCLUSIONS;
+  const manifest = await loadSoftwareDeliveryManifest(packRoot);
+  const integrity = await computeSoftwareDeliveryPackIntegrity(packRoot, exclusions);
+
+  return {
+    manifest,
+    packRoot,
+    manifestPath: path.join(packRoot, SOFTWARE_DELIVERY_MANIFEST_FILE_NAME),
+    integrity,
+  };
+}

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

@@ -0,0 +1,263 @@
+// 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 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

@@ -0,0 +1,66 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/* 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

@@ -0,0 +1,219 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * @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, []);
+}