@lumenflow/cli 4.24.0 → 5.0.0

package/packs/software-delivery/src/sandbox/sandbox-backend-linux.ts

@@ -0,0 +1,88 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { spawnSync } from 'node:child_process';
+import {
+  SANDBOX_BACKEND_IDS,
+  type SandboxBackend,
+  type SandboxExecutionPlan,
+  type SandboxExecutionRequest,
+} from './sandbox-profile.js';
+
+export interface LinuxSandboxBackendOptions {
+  commandExists?: (binary: string) => boolean;
+}
+
+const LINUX_SANDBOX_BINARY = 'bwrap';
+
+function defaultCommandExists(binary: string): boolean {
+  const probe = spawnSync(binary, ['--help'], { stdio: 'ignore' });
+  return !probe.error;
+}
+
+function buildUnavailablePlan(request: SandboxExecutionRequest): SandboxExecutionPlan {
+  if (request.allowUnsandboxedFallback) {
+    return {
+      backendId: SANDBOX_BACKEND_IDS.LINUX,
+      enforced: false,
+      failClosed: false,
+      warning:
+        'Running unsandboxed because bwrap is unavailable and fallback was explicitly enabled.',
+    };
+  }
+
+  return {
+    backendId: SANDBOX_BACKEND_IDS.LINUX,
+    enforced: false,
+    failClosed: true,
+    reason: 'Linux sandbox backend unavailable: required binary "bwrap" was not found.',
+  };
+}
+
+function buildInvocation(request: SandboxExecutionRequest) {
+  const writableBinds = request.profile.allowlist.writableRoots.flatMap((entry) => [
+    '--bind',
+    entry.normalizedPath,
+    entry.normalizedPath,
+  ]);
+
+  return {
+    command: LINUX_SANDBOX_BINARY,
+    args: [
+      '--die-with-parent',
+      '--new-session',
+      '--ro-bind',
+      '/',
+      '/',
+      ...writableBinds,
+      '--proc',
+      '/proc',
+      '--dev',
+      '/dev',
+      '--',
+      ...request.command,
+    ],
+  };
+}
+
+export function createLinuxSandboxBackend(
+  options: LinuxSandboxBackendOptions = {},
+): SandboxBackend {
+  const commandExists = options.commandExists || defaultCommandExists;
+
+  return {
+    id: SANDBOX_BACKEND_IDS.LINUX,
+    resolveExecution(request: SandboxExecutionRequest): SandboxExecutionPlan {
+      if (!commandExists(LINUX_SANDBOX_BINARY)) {
+        return buildUnavailablePlan(request);
+      }
+
+      return {
+        backendId: SANDBOX_BACKEND_IDS.LINUX,
+        enforced: true,
+        failClosed: false,
+        invocation: buildInvocation(request),
+      };
+    },
+  };
+}

package/packs/software-delivery/src/sandbox/sandbox-backend-macos.ts

@@ -0,0 +1,154 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { spawnSync } from 'node:child_process';
+import os from 'node:os';
+import {
+  SANDBOX_BACKEND_IDS,
+  type SandboxBackend,
+  type SandboxExecutionPlan,
+  type SandboxExecutionRequest,
+} from './sandbox-profile.js';
+
+export interface MacosSandboxBackendOptions {
+  commandExists?: (binary: string) => boolean;
+}
+
+const MACOS_SANDBOX_BINARY = 'sandbox-exec';
+
+function defaultCommandExists(binary: string): boolean {
+  const probe = spawnSync(binary, ['-h'], { stdio: 'ignore' });
+  return !probe.error;
+}
+
+function escapePolicyPath(targetPath: string): string {
+  return targetPath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+function buildNetworkRules(profile: SandboxExecutionRequest['profile']): string[] {
+  const posture = profile.networkPosture ?? 'full';
+
+  if (posture === 'off') {
+    return ['(deny network*)'];
+  }
+
+  if (posture === 'allowlist') {
+    const rules: string[] = ['(deny network*)'];
+    for (const host of profile.networkAllowlist) {
+      rules.push(`(allow network-outbound (remote ip "${host}"))`);
+    }
+    return rules;
+  }
+
+  // posture === 'full'
+  return ['(allow network*)'];
+}
+
+/** macOS system paths required for process execution (parity with bwrap --ro-bind /) */
+const MACOS_SYSTEM_READ_PATHS = [
+  '/usr',
+  '/System',
+  '/Library',
+  '/bin',
+  '/sbin',
+  '/private',
+  '/dev',
+  '/tmp',
+];
+
+/** Sensitive paths denied from read access (parity with bwrap deny overlays) */
+const SENSITIVE_DENY_PATHS = ['.ssh', '.aws', '.gnupg'];
+
+function buildReadRules(profile: SandboxExecutionRequest['profile']): string[] {
+  const readPaths = new Set<string>();
+
+  // Workspace root (covers worktree, state, WU YAML)
+  readPaths.add(profile.projectRoot);
+
+  // System paths required for process execution
+  for (const systemPath of MACOS_SYSTEM_READ_PATHS) {
+    readPaths.add(systemPath);
+  }
+
+  // Temp path from profile
+  readPaths.add(profile.tempPath);
+
+  return [...readPaths].map(
+    (readPath) => `(allow file-read* (subpath "${escapePolicyPath(readPath)}"))`,
+  );
+}
+
+function buildDenyOverlays(): string[] {
+  const homeDir = os.homedir();
+  return SENSITIVE_DENY_PATHS.map(
+    (sensitivePath) =>
+      `(deny file-read* (subpath "${escapePolicyPath(homeDir)}/${sensitivePath}"))`,
+  );
+}
+
+function buildPolicy(profile: SandboxExecutionRequest['profile']): string {
+  const writableRules = profile.allowlist.writableRoots.map(
+    (entry) => `(allow file-write* (subpath "${escapePolicyPath(entry.normalizedPath)}"))`,
+  );
+
+  return [
+    '(version 1)',
+    '(deny default)',
+    '(allow process*)',
+    ...buildReadRules(profile),
+    ...buildDenyOverlays(),
+    '(allow sysctl-read)',
+    '(allow mach-lookup)',
+    ...buildNetworkRules(profile),
+    '(allow signal)',
+    ...writableRules,
+  ].join(' ');
+}
+
+function buildUnavailablePlan(request: SandboxExecutionRequest): SandboxExecutionPlan {
+  if (request.allowUnsandboxedFallback) {
+    return {
+      backendId: SANDBOX_BACKEND_IDS.MACOS,
+      enforced: false,
+      failClosed: false,
+      warning:
+        'Running unsandboxed because sandbox-exec is unavailable and fallback was explicitly enabled.',
+    };
+  }
+
+  return {
+    backendId: SANDBOX_BACKEND_IDS.MACOS,
+    enforced: false,
+    failClosed: true,
+    reason: 'macOS sandbox backend unavailable: required binary "sandbox-exec" was not found.',
+  };
+}
+
+function buildInvocation(request: SandboxExecutionRequest) {
+  return {
+    command: MACOS_SANDBOX_BINARY,
+    args: ['-p', buildPolicy(request.profile), ...request.command],
+  };
+}
+
+export function createMacosSandboxBackend(
+  options: MacosSandboxBackendOptions = {},
+): SandboxBackend {
+  const commandExists = options.commandExists || defaultCommandExists;
+
+  return {
+    id: SANDBOX_BACKEND_IDS.MACOS,
+    resolveExecution(request: SandboxExecutionRequest): SandboxExecutionPlan {
+      if (!commandExists(MACOS_SANDBOX_BINARY)) {
+        return buildUnavailablePlan(request);
+      }
+
+      return {
+        backendId: SANDBOX_BACKEND_IDS.MACOS,
+        enforced: true,
+        failClosed: false,
+        invocation: buildInvocation(request),
+      };
+    },
+  };
+}

package/packs/software-delivery/src/sandbox/sandbox-backend-windows.ts

@@ -0,0 +1,47 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import {
+  SANDBOX_BACKEND_IDS,
+  type SandboxBackend,
+  type SandboxExecutionPlan,
+  type SandboxExecutionRequest,
+} from './sandbox-profile.js';
+
+export interface WindowsSandboxBackendOptions {
+  commandExists?: (binary: string) => boolean;
+}
+
+const WINDOWS_ENFORCEMENT_UNAVAILABLE_REASON =
+  'Windows sandbox backend unavailable: write enforcement is not yet available on Windows.';
+const WINDOWS_ENFORCEMENT_UNAVAILABLE_WARNING =
+  'Running unsandboxed because write enforcement is not yet available on Windows and fallback was explicitly enabled.';
+
+function buildNotImplementedPlan(request: SandboxExecutionRequest): SandboxExecutionPlan {
+  if (request.allowUnsandboxedFallback) {
+    return {
+      backendId: SANDBOX_BACKEND_IDS.WINDOWS,
+      enforced: false,
+      failClosed: false,
+      warning: WINDOWS_ENFORCEMENT_UNAVAILABLE_WARNING,
+    };
+  }
+
+  return {
+    backendId: SANDBOX_BACKEND_IDS.WINDOWS,
+    enforced: false,
+    failClosed: true,
+    reason: WINDOWS_ENFORCEMENT_UNAVAILABLE_REASON,
+  };
+}
+
+export function createWindowsSandboxBackend(
+  _options: WindowsSandboxBackendOptions = {},
+): SandboxBackend {
+  return {
+    id: SANDBOX_BACKEND_IDS.WINDOWS,
+    resolveExecution(request: SandboxExecutionRequest): SandboxExecutionPlan {
+      return buildNotImplementedPlan(request);
+    },
+  };
+}

package/packs/software-delivery/src/sandbox/sandbox-profile.ts

@@ -0,0 +1,153 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import os from 'node:os';
+import path from 'node:path';
+import {
+  buildSandboxAllowlist,
+  type SandboxAllowlist,
+  type BuildSandboxAllowlistInput,
+} from './sandbox-allowlist.js';
+import { LUMENFLOW_PATHS } from '../constants/wu-paths-constants.js';
+import { createWuPaths } from '../state/wu-paths.js';
+
+export const SANDBOX_BACKEND_IDS = {
+  LINUX: 'linux',
+  MACOS: 'macos',
+  WINDOWS: 'windows',
+  UNSUPPORTED: 'unsupported',
+} as const;
+
+export type SandboxBackendId = (typeof SANDBOX_BACKEND_IDS)[keyof typeof SANDBOX_BACKEND_IDS];
+
+export type SandboxNetworkPosture = 'off' | 'allowlist' | 'full';
+
+export interface SandboxProfile {
+  projectRoot: string;
+  worktreePath: string;
+  wuId: string;
+  wuYamlPath: string;
+  statePath: string;
+  tempPath: string;
+  allowlist: SandboxAllowlist;
+  networkPosture: SandboxNetworkPosture;
+  networkAllowlist: string[];
+}
+
+export interface BuildSandboxProfileInput {
+  projectRoot: string;
+  worktreePath: string;
+  wuId: string;
+  tempPath?: string;
+  extraWritableRoots?: string[];
+  networkPosture?: SandboxNetworkPosture;
+  networkAllowlist?: string[];
+}
+
+export interface SandboxBackendResolution {
+  id: SandboxBackendId;
+  platform: NodeJS.Platform | string;
+  supported: boolean;
+}
+
+export interface SandboxInvocation {
+  command: string;
+  args: string[];
+}
+
+export interface SandboxExecutionRequest {
+  profile: SandboxProfile;
+  command: string[];
+  allowUnsandboxedFallback: boolean;
+}
+
+export interface SandboxExecutionPlan {
+  backendId: SandboxBackendId;
+  enforced: boolean;
+  failClosed: boolean;
+  invocation?: SandboxInvocation;
+  reason?: string;
+  warning?: string;
+}
+
+export interface SandboxBackend {
+  id: SandboxBackendId;
+  resolveExecution: (request: SandboxExecutionRequest) => SandboxExecutionPlan;
+}
+
+function resolveWorktreePath(projectRoot: string, worktreePath: string): string {
+  if (path.isAbsolute(worktreePath)) {
+    return path.resolve(worktreePath);
+  }
+
+  return path.resolve(projectRoot, worktreePath);
+}
+
+function buildDefaultWritableRoots(profile: {
+  worktreePath: string;
+  statePath: string;
+  wuYamlPath: string;
+  tempPath: string;
+}): string[] {
+  return [profile.worktreePath, profile.statePath, profile.wuYamlPath, profile.tempPath];
+}
+
+export function buildSandboxProfile(input: BuildSandboxProfileInput): SandboxProfile {
+  const projectRoot = path.resolve(input.projectRoot);
+  const worktreePath = resolveWorktreePath(projectRoot, input.worktreePath);
+  const wuYamlPath = path.resolve(projectRoot, createWuPaths({ projectRoot }).WU(input.wuId));
+  const statePath = path.resolve(projectRoot, LUMENFLOW_PATHS.STATE_DIR);
+  const tempPath = path.resolve(input.tempPath || os.tmpdir());
+
+  const writableRoots = buildDefaultWritableRoots({
+    worktreePath,
+    statePath,
+    wuYamlPath,
+    tempPath,
+  });
+
+  if (input.extraWritableRoots && input.extraWritableRoots.length > 0) {
+    writableRoots.push(...input.extraWritableRoots);
+  }
+
+  const allowlistInput: BuildSandboxAllowlistInput = {
+    projectRoot,
+    writableRoots,
+  };
+
+  const allowlist = buildSandboxAllowlist(allowlistInput);
+
+  const networkPosture: SandboxNetworkPosture = input.networkPosture ?? 'full';
+  const networkAllowlist: string[] =
+    networkPosture === 'allowlist' && input.networkAllowlist ? [...input.networkAllowlist] : [];
+
+  return {
+    projectRoot,
+    worktreePath,
+    wuId: input.wuId,
+    wuYamlPath,
+    statePath,
+    tempPath,
+    allowlist,
+    networkPosture,
+    networkAllowlist,
+  };
+}
+
+export function resolveSandboxBackendForPlatform(
+  platform: NodeJS.Platform | string = process.platform,
+): SandboxBackendResolution {
+  if (platform === 'linux') {
+    return { id: SANDBOX_BACKEND_IDS.LINUX, platform, supported: true };
+  }
+
+  if (platform === 'darwin') {
+    return { id: SANDBOX_BACKEND_IDS.MACOS, platform, supported: true };
+  }
+
+  if (platform === 'win32') {
+    return { id: SANDBOX_BACKEND_IDS.WINDOWS, platform, supported: true };
+  }
+
+  return { id: SANDBOX_BACKEND_IDS.UNSUPPORTED, platform, supported: false };
+}

package/packs/software-delivery/src/schemas/index.ts

@@ -0,0 +1,5 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Barrel for pack-static-data schemas. Populated by Layer 2 of INIT-058.
+export {};

package/packs/software-delivery/src/state/date-utils.ts

@@ -0,0 +1,158 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * @file date-utils.ts
+ * @description Date formatting utilities using date-fns library
+ * WU-1082: Extract shared utilities (eliminate date formatting duplication)
+ *
+ * Replaces manual date formatting in:
+ * - tools/wu-block.ts (todayISO)
+ * - tools/wu-unblock.ts (todayISO)
+ * - tools/wu-done.ts (todayISO - already uses date-fns)
+ */
+
+import { format } from 'date-fns';
+
+/**
+ * Get current date in ISO format (YYYY-MM-DD)
+ * @returns {string} Current date in YYYY-MM-DD format
+ * @example
+ * todayISO(); // "2025-11-12"
+ */
+export function todayISO() {
+  return format(new Date(), 'yyyy-MM-dd');
+}
+
+/**
+ * Format a date with a custom format string
+ * @param {Date|string|number} date - Date to format
+ * @param {string} formatString - date-fns format string
+ * @returns {string} Formatted date string
+ * @example
+ * formatDate(new Date(), 'yyyy-MM-dd HH:mm:ss');
+ * formatDate('2025-11-12', 'MMMM d, yyyy'); // "November 12, 2025"
+ */
+export function formatDate(date: Date | string | number, formatString: string) {
+  return format(new Date(date), formatString);
+}
+
+/**
+ * Date format constant for YYYY-MM-DD
+ * @constant {string}
+ */
+const DATE_FORMAT_ISO = 'yyyy-MM-dd';
+
+/**
+ * Normalize a Date object or ISO timestamp string to YYYY-MM-DD format
+ *
+ * WU-1442: Fix date corruption when js-yaml parses YYYY-MM-DD as Date objects
+ * Library-First: Uses date-fns for date formatting (no manual parsing)
+ *
+ * Use case: js-yaml parses `created: 2025-12-04` (unquoted) as a Date object.
+ * When yaml.dump() serializes it back, it outputs `2025-12-04T00:00:00.000Z`.
+ * This function normalizes Date objects back to YYYY-MM-DD string format.
+ *
+ * Handles:
+ * - Date objects → YYYY-MM-DD string
+ * - ISO timestamp strings → YYYY-MM-DD string (date portion)
+ * - YYYY-MM-DD strings → preserved as-is
+ * - undefined/null → preserved as undefined
+ *
+ * @param {Date|string|undefined|null} value - Date value to normalize
+ * @returns {string|undefined} Date in YYYY-MM-DD format or undefined
+ *
+ * @example
+ * normalizeToDateString(new Date('2025-12-04')); // '2025-12-04'
+ * normalizeToDateString('2025-12-04T00:00:00.000Z'); // '2025-12-04'
+ * normalizeToDateString('2025-12-04'); // '2025-12-04'
+ * normalizeToDateString(undefined); // undefined
+ */
+export function normalizeToDateString(value: unknown) {
+  // Preserve undefined/null
+  if (value == null) {
+    return undefined;
+  }
+
+  // If already a YYYY-MM-DD string, return as-is
+  if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    return value;
+  }
+
+  // Convert Date objects or timestamp strings to YYYY-MM-DD
+  if (value instanceof Date) {
+    return format(value, DATE_FORMAT_ISO);
+  }
+
+  // Handle ISO timestamp strings (e.g., '2025-12-04T00:00:00.000Z')
+  if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(value)) {
+    return format(new Date(value), DATE_FORMAT_ISO);
+  }
+
+  // Fallback: try to parse and format (coerce to string for Date constructor)
+  try {
+    const date = new Date(String(value));
+    if (!isNaN(date.getTime())) {
+      return format(date, DATE_FORMAT_ISO);
+    }
+  } catch {
+    // Invalid date - return undefined
+  }
+
+  return undefined;
+}
+
+/**
+ * Normalize various date formats to ISO 8601 datetime (YYYY-MM-DDTHH:mm:ss.sssZ)
+ *
+ * WU-1337: Auto-repair date fields in WU YAML to consistent format
+ * Library-First: Uses date-fns for date handling (no manual parsing)
+ *
+ * Handles:
+ * - ISO date strings (YYYY-MM-DD) → midnight UTC
+ * - ISO datetime strings (already valid) → preserved
+ * - Unix timestamps (milliseconds) → converted
+ * - undefined/null → preserved as undefined
+ *
+ * @param {string|number|undefined|null} value - Date value to normalize
+ * @returns {string|undefined} ISO datetime string or undefined
+ *
+ * @example
+ * normalizeISODateTime('2025-11-29'); // '2025-11-29T00:00:00.000Z'
+ * normalizeISODateTime('2025-11-29T14:30:00.000Z'); // '2025-11-29T14:30:00.000Z'
+ * normalizeISODateTime(1732896000000); // '2024-11-29T16:00:00.000Z'
+ * normalizeISODateTime(undefined); // undefined
+ */
+export function normalizeISODateTime(value: string | number | null | undefined) {
+  // Preserve undefined/null (optional fields)
+  if (value == null) {
+    return undefined;
+  }
+
+  // If already a valid ISO datetime format, preserve it
+  // Pattern: YYYY-MM-DDTHH:mm:ss.sssZ
+  if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)) {
+    return value;
+  }
+
+  // Handle Unix timestamps as strings (convert to number first)
+  let dateInput = value;
+  if (typeof value === 'string' && /^\d+$/.test(value)) {
+    // Numeric string - treat as Unix timestamp in milliseconds
+    dateInput = Number(value);
+  }
+
+  // Parse and convert to ISO datetime
+  // date-fns/Date handles: ISO dates, ISO datetimes, Unix timestamps
+  const date = new Date(dateInput);
+
+  // Check for invalid date
+  if (isNaN(date.getTime())) {
+    // Fallback: return undefined for unparseable dates
+    // Zod schema will catch invalid dates separately
+    return undefined;
+  }
+
+  // Convert to ISO 8601 datetime format
+  return date.toISOString();
+}

package/packs/software-delivery/src/state/index.ts

@@ -0,0 +1,15 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Barrel for pack-local WU state modules. Populated by Layer 4 of INIT-058.
+// WU-2687 (narrowed): moved wu-state-schema, wu-doc-types from @lumenflow/core.
+// WU-2689 (L4 cascade): moved wu-paths, wu-yaml, wu-schema, date-utils from @lumenflow/core
+//   after WU-2690 added getDirectories/getStatePaths to the pack workspace-reader.
+export * from './wu-state-schema.js';
+export * from './wu-doc-types.js';
+export * from './date-utils.js';
+export * from './wu-paths.js';
+export * from './wu-schema.js';
+export * from './wu-yaml.js';
+// WU-2699 (L4): moved state-machine (SDLC residue) from @lumenflow/core.
+export * from './state-machine.js';