@lumenflow/cli 5.0.0 → 5.0.2

package/packs/software-delivery/src/config/delivery-review-contract.ts

@@ -1,20 +1,256 @@
 // Copyright (c) 2026 Hellmai Ltd
 // SPDX-License-Identifier: AGPL-3.0-only
 
+import { z } from 'zod';
+import { asRecord } from '@lumenflow/kernel/primitives/object-guards';
+import { LUMENFLOW_CLIENT_IDS } from '../constants/client-ids.js';
+import { WU_TYPES } from '../constants/wu-statuses.js';
+
 /**
- * Pack-side wrapper for delivery-review-contract (INIT-058 WU-2727).
- *
- * Part of the staged migration pattern: consumers migrate OFF the
- * `@lumenflow/core/delivery-review-contract` subpath and onto
- * `@lumenflow/packs-software-delivery/config/delivery-review-contract` FIRST,
- * while the canonical implementation still lives in `@lumenflow/core`. A
- * follow-up WU will move the canonical file into the pack and update this
- * wrapper to become the canonical definition.
+ * Pack-local delivery review contract surface.
  *
- * This file must re-export DIRECTLY from
- * `@lumenflow/core/delivery-review-contract` (single level). Do NOT introduce
- * a shim chain — WU-2712 hit TS2305 on type-only imports through chained
- * shims.
+ * Keeping this module in the pack avoids a package cycle with @lumenflow/core
+ * while preserving the same public API for pack consumers.
  */
 
-export * from '@lumenflow/core/delivery-review-contract';
+export const DELIVERY_REVIEW_COMMAND_CONTEXTS = {
+  GATES: 'gates',
+  WU_PREP: 'wu:prep',
+} as const;
+
+export type DeliveryReviewCommandContext =
+  (typeof DELIVERY_REVIEW_COMMAND_CONTEXTS)[keyof typeof DELIVERY_REVIEW_COMMAND_CONTEXTS];
+
+export const DEFAULT_DELIVERY_REVIEW_SKIP_TYPES = [
+  WU_TYPES.DOCUMENTATION,
+  WU_TYPES.PROCESS,
+] as const;
+
+export const DELIVERY_REVIEW_ARTIFACT_DIR = '.lumenflow/artifacts/delivery-review' as const;
+
+export const DeliveryReviewGateConfigSchema = z
+  .object({
+    enabled: z.boolean().default(false),
+    skip_types: z.array(z.string().min(1)).default([...DEFAULT_DELIVERY_REVIEW_SKIP_TYPES]),
+  })
+  .strict();
+
+export type DeliveryReviewGateConfig = z.infer<typeof DeliveryReviewGateConfigSchema>;
+
+export const DeliveryReviewClientFeatureSchema = z
+  .object({
+    enabled: z.boolean().default(false),
+    auto_run: z.boolean().default(false),
+  })
+  .strict();
+
+export type DeliveryReviewClientFeature = z.infer<typeof DeliveryReviewClientFeatureSchema>;
+
+export const DeliveryReviewVerdictSchema = z.enum(['PASS', 'FAIL', 'PARTIAL']);
+export type DeliveryReviewVerdict = z.infer<typeof DeliveryReviewVerdictSchema>;
+
+export const DeliveryReviewFindingSeveritySchema = z.enum(['critical', 'high', 'medium', 'low']);
+export type DeliveryReviewFindingSeverity = z.infer<typeof DeliveryReviewFindingSeveritySchema>;
+
+export const DeliveryReviewFindingSchema = z
+  .object({
+    severity: DeliveryReviewFindingSeveritySchema,
+    title: z.string().min(1),
+    detail: z.string().min(1),
+    acceptanceCriteriaRefs: z.array(z.string().min(1)).optional(),
+    fileRefs: z.array(z.string().min(1)).optional(),
+  })
+  .strict();
+
+export type DeliveryReviewFinding = z.infer<typeof DeliveryReviewFindingSchema>;
+
+export const DeliveryReviewAcceptanceCriterionSchema = z
+  .object({
+    criterion: z.string().min(1),
+    status: z.enum(['satisfied', 'unclear', 'not_satisfied']),
+    evidence: z.array(z.string().min(1)).optional(),
+  })
+  .strict();
+
+export type DeliveryReviewAcceptanceCriterion = z.infer<
+  typeof DeliveryReviewAcceptanceCriterionSchema
+>;
+
+export const DeliveryReviewResultSchema = z
+  .object({
+    wuId: z.string().min(1),
+    verdict: DeliveryReviewVerdictSchema,
+    summary: z.string().min(1),
+    findings: z.array(DeliveryReviewFindingSchema),
+    acceptanceCriteria: z.array(DeliveryReviewAcceptanceCriterionSchema),
+    metadata: z
+      .object({
+        runtimeClient: z.string().min(1).optional(),
+        startedAt: z.string().datetime(),
+        completedAt: z.string().datetime(),
+      })
+      .strict(),
+  })
+  .strict();
+
+export type DeliveryReviewResult = z.infer<typeof DeliveryReviewResultSchema>;
+
+export interface DeliveryReviewRuntimeConfigInput {
+  gates?: {
+    delivery_review?: unknown;
+  };
+  agents?: {
+    defaultClient?: unknown;
+    clients?: Record<string, unknown>;
+  };
+}
+
+export interface ResolvedDeliveryReviewRuntimeConfig {
+  clientName: string;
+  gate: DeliveryReviewGateConfig;
+  feature: DeliveryReviewClientFeature;
+  enabled: boolean;
+  autoRun: boolean;
+}
+
+function resolveClientNameFromOptions(options: {
+  config: DeliveryReviewRuntimeConfigInput;
+  clientName?: string;
+  env?: Readonly<Record<string, string | undefined>>;
+}): string {
+  const explicitClient = options.clientName?.trim();
+  if (explicitClient) {
+    return explicitClient;
+  }
+
+  const envClient = options.env?.LUMENFLOW_CLIENT?.trim();
+  if (envClient) {
+    return envClient;
+  }
+
+  const defaultClient =
+    typeof options.config.agents?.defaultClient === 'string'
+      ? options.config.agents.defaultClient.trim()
+      : '';
+  if (defaultClient) {
+    return defaultClient;
+  }
+
+  return LUMENFLOW_CLIENT_IDS.CLAUDE_CODE;
+}
+
+function resolveClientRecord(
+  clients: Record<string, unknown> | undefined,
+  clientName: string,
+): Record<string, unknown> | null {
+  if (!clients) {
+    return null;
+  }
+
+  const exactMatch = asRecord(clients[clientName]);
+  if (exactMatch) {
+    return exactMatch;
+  }
+
+  const matchKey = Object.keys(clients).find(
+    (key) => key.toLowerCase() === clientName.toLowerCase(),
+  );
+  return matchKey ? asRecord(clients[matchKey]) : null;
+}
+
+export function resolveDeliveryReviewRuntimeState(options: {
+  config: DeliveryReviewRuntimeConfigInput;
+  clientName?: string;
+  env?: Readonly<Record<string, string | undefined>>;
+}): ResolvedDeliveryReviewRuntimeConfig {
+  const clientName = resolveClientNameFromOptions(options);
+  const gate = DeliveryReviewGateConfigSchema.parse(options.config.gates?.delivery_review ?? {});
+  const clientConfig = resolveClientRecord(options.config.agents?.clients, clientName);
+  const features = asRecord(clientConfig?.features);
+  const feature = DeliveryReviewClientFeatureSchema.parse(features?.delivery_review ?? {});
+
+  return {
+    clientName,
+    gate,
+    feature,
+    enabled: gate.enabled && feature.enabled,
+    autoRun: gate.enabled && feature.enabled && feature.auto_run,
+  };
+}
+
+export function shouldRunDeliveryReviewForCommand(options: {
+  runtime: ResolvedDeliveryReviewRuntimeConfig;
+  commandContext: DeliveryReviewCommandContext;
+}): boolean {
+  if (!options.runtime.enabled) {
+    return false;
+  }
+
+  if (options.commandContext === DELIVERY_REVIEW_COMMAND_CONTEXTS.WU_PREP) {
+    return options.runtime.autoRun;
+  }
+
+  return true;
+}
+
+export function isDeliveryReviewSkippedForType(options: {
+  gate: DeliveryReviewGateConfig;
+  wuType?: unknown;
+}): boolean {
+  if (typeof options.wuType !== 'string' || options.wuType.trim().length === 0) {
+    return false;
+  }
+
+  return options.gate.skip_types.includes(options.wuType);
+}
+
+export function flattenDeliveryReviewAcceptanceCriteria(acceptance: unknown): string[] {
+  if (Array.isArray(acceptance)) {
+    return acceptance
+      .filter((entry): entry is string => typeof entry === 'string')
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+  }
+
+  const acceptanceRecord = asRecord(acceptance);
+  if (!acceptanceRecord) {
+    return [];
+  }
+
+  return Object.values(acceptanceRecord)
+    .flatMap((entry) =>
+      Array.isArray(entry)
+        ? entry.filter((value): value is string => typeof value === 'string')
+        : [],
+    )
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+export function calculateDeliveryReviewVerdict(input: {
+  findings: DeliveryReviewFinding[];
+  acceptanceCriteria: DeliveryReviewAcceptanceCriterion[];
+}): DeliveryReviewVerdict {
+  const hasBlockingFinding = input.findings.some(
+    (finding) => finding.severity === 'critical' || finding.severity === 'high',
+  );
+  if (hasBlockingFinding) {
+    return 'FAIL';
+  }
+
+  const hasUnsatisfiedCriterion = input.acceptanceCriteria.some(
+    (criterion) => criterion.status === 'not_satisfied',
+  );
+  if (hasUnsatisfiedCriterion) {
+    return 'FAIL';
+  }
+
+  const hasUnclearCriterion = input.acceptanceCriteria.some(
+    (criterion) => criterion.status === 'unclear',
+  );
+  if (hasUnclearCriterion || input.findings.length > 0) {
+    return 'PARTIAL';
+  }
+
+  return 'PASS';
+}

package/packs/software-delivery/src/config/env-accessors.ts

@@ -1,19 +1,66 @@
 // Copyright (c) 2026 Hellmai Ltd
 // SPDX-License-Identifier: AGPL-3.0-only
 
+import { createError, ErrorCodes } from '@lumenflow/kernel/primitives/error-handler';
+
 /**
- * Pack-side wrapper for env-accessors (INIT-058 WU-2727).
- *
- * Part of the staged migration pattern: consumers migrate OFF the
- * `@lumenflow/core/env-accessors` subpath and onto
- * `@lumenflow/packs-software-delivery/config/env-accessors` FIRST, while the
- * canonical implementation still lives in `@lumenflow/core`. A follow-up WU
- * will move the canonical file into the pack and update this wrapper to
- * become the canonical definition.
+ * Pack-local environment access helpers.
  *
- * This file must re-export DIRECTLY from `@lumenflow/core/env-accessors`
- * (single level). Do NOT introduce a shim chain — WU-2712 hit TS2305 on
- * type-only imports through chained shims.
+ * These stay local to the pack so clean workspace builds do not need to route
+ * back through @lumenflow/core, which already depends on this pack.
  */
 
-export * from '@lumenflow/core/env-accessors';
+export interface GetEnvOptions {
+  env?: NodeJS.ProcessEnv;
+  trim?: boolean;
+}
+
+export interface RequireEnvOptions extends GetEnvOptions {
+  context?: string;
+  remediation?: string;
+}
+
+const DEFAULT_REMEDIATION_SUFFIX = 'Set the environment variable and retry.';
+const CONTEXT_SEPARATOR = ': ';
+
+function getEnvSource(options: GetEnvOptions): NodeJS.ProcessEnv {
+  return options.env ?? process.env;
+}
+
+export function getEnv(envVar: string, options: GetEnvOptions = {}): string | undefined {
+  const source = getEnvSource(options);
+  const rawValue = source[envVar];
+  if (rawValue === undefined) {
+    return undefined;
+  }
+
+  const trimValue = options.trim ?? true;
+  const normalizedValue = trimValue ? rawValue.trim() : rawValue;
+  if (normalizedValue.length === 0) {
+    return undefined;
+  }
+
+  return normalizedValue;
+}
+
+function formatContextPrefix(context?: string): string {
+  if (!context) {
+    return '';
+  }
+  return `${context}${CONTEXT_SEPARATOR}`;
+}
+
+export function requireEnv(envVar: string, options: RequireEnvOptions = {}): string {
+  const value = getEnv(envVar, options);
+  if (value !== undefined) {
+    return value;
+  }
+
+  const remediation = options.remediation ?? DEFAULT_REMEDIATION_SUFFIX;
+  const contextPrefix = formatContextPrefix(options.context);
+  throw createError(
+    ErrorCodes.CONFIG_ERROR,
+    `${contextPrefix}Missing required environment variable ${envVar}. ${remediation}`,
+    { envVar, context: options.context },
+  );
+}

package/packs/software-delivery/src/config/normalize-config-keys.ts

@@ -2,18 +2,8 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 
 /**
- * Pack-side wrapper for normalize-config-keys (INIT-058 WU-2727).
- *
- * Part of the staged migration pattern: consumers migrate OFF the
- * `@lumenflow/core/normalize-config-keys` subpath and onto
- * `@lumenflow/packs-software-delivery/config/normalize-config-keys` FIRST,
- * while the canonical implementation still lives in `@lumenflow/core`. A
- * follow-up WU will move the canonical file into the pack and update this
- * wrapper to become the canonical definition.
- *
- * This file must re-export DIRECTLY from
- * `@lumenflow/core/normalize-config-keys` (single level). Do NOT introduce a
- * shim chain — WU-2712 hit TS2305 on type-only imports through chained shims.
+ * This utility already lives in kernel primitives, so the pack can depend on
+ * it directly without routing through @lumenflow/core.
  */
 
-export * from '@lumenflow/core/normalize-config-keys';
+export * from '@lumenflow/kernel/primitives/normalize-config-keys';

package/packs/agent-runtime/.turbo/turbo-build.log

@@ -1,4 +0,0 @@
-
-> @lumenflow/packs-agent-runtime@5.0.0 build /home/tom/source/hellmai/lumenflow-dev/packages/@lumenflow/packs/agent-runtime
-> tsc
-

package/packs/agent-runtime/.turbo/turbo-test.log

@@ -1,25 +0,0 @@
-
-> @lumenflow/packs-agent-runtime@4.24.0 test /home/tom/source/hellmai/lumenflow-dev/worktrees/framework-agent-wu-2733/packages/@lumenflow/packs/agent-runtime
-> vitest run
-
-
- RUN  v4.0.18 /home/tom/source/hellmai/lumenflow-dev/worktrees/framework-agent-wu-2733/packages/@lumenflow/packs/agent-runtime
-
- ✓ __tests__/turn-lifecycle-emissions.test.ts (64 tests) 31ms
- ✓ __tests__/capability-factory.test.ts (2 tests) 3ms
- ✓ __tests__/session-schema.test.ts (2 tests) 13ms
- ✓ __tests__/auto-session-integration.test.ts (3 tests) 18ms
- ✓ __tests__/remote-controls.test.ts (22 tests) 303ms
- ✓ __tests__/manifest.test.ts (3 tests) 17ms
- ✓ __tests__/workflow-state.test.ts (1 test) 53ms
- ✓ __tests__/policy-factory.test.ts (3 tests) 31ms
- ✓ __tests__/orchestration.test.ts (4 tests) 58ms
- ✓ __tests__/workflow-dag.test.ts (2 tests) 127ms
- ✓ __tests__/remote-controls-mock.test.ts (53 tests) 82ms
- ✓ __tests__/resume.test.ts (2 tests) 228ms
-
- Test Files  12 passed (12)
-      Tests  161 passed (161)
-   Start at  00:22:52
-   Duration  2.72s (transform 10.34s, setup 0ms, import 17.40s, tests 964ms, environment 3ms)
-

package/packs/agent-runtime/.turbo/turbo-typecheck.log

@@ -1,4 +0,0 @@
-
-> @lumenflow/packs-agent-runtime@4.24.0 typecheck /home/tom/source/hellmai/lumenflow-dev/worktrees/framework-agent-wu-2764/packages/@lumenflow/packs/agent-runtime
-> tsc --noEmit
-