@lumenflow/cli 3.1.1 → 3.1.3

package/packs/software-delivery/gate-policies.ts

@@ -0,0 +1,134 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { SOFTWARE_DELIVERY_PACK_ID, SOFTWARE_DELIVERY_POLICY_ID_PREFIX } from './constants.js';
+
+export const SOFTWARE_DELIVERY_GATE_NAMES = [
+  'format',
+  'lint',
+  'typecheck',
+  'test',
+  'coverage',
+] as const;
+
+export type SoftwareDeliveryGateName = (typeof SOFTWARE_DELIVERY_GATE_NAMES)[number];
+
+export interface PolicyProvider {
+  id: string;
+  gate: SoftwareDeliveryGateName;
+  trigger: 'on_completion';
+  command: string;
+}
+
+export interface CompletionPolicyContext {
+  trigger: 'on_completion';
+  run_id: string;
+  task_id: string;
+  gate: SoftwareDeliveryGateName;
+  pack_id: typeof SOFTWARE_DELIVERY_PACK_ID;
+}
+
+export interface CompletionPolicyEvaluation {
+  decision: 'allow' | 'deny';
+  decisions: Array<{
+    policy_id: string;
+    decision: 'allow' | 'deny';
+    reason?: string;
+  }>;
+  warnings: string[];
+}
+
+export interface CompletionPolicyEngine {
+  evaluate(context: CompletionPolicyContext): Promise<CompletionPolicyEvaluation>;
+}
+
+export interface CompletionPolicyExecution {
+  ok: boolean;
+}
+
+export interface CompletionPolicyRunResult {
+  gate: SoftwareDeliveryGateName;
+  policy_id: string;
+  decision: 'allow' | 'deny';
+  command: string;
+  executed: boolean;
+  ok: boolean;
+}
+
+const SOFTWARE_DELIVERY_GATE_COMMANDS: Record<SoftwareDeliveryGateName, string> = {
+  format: 'pnpm format:check',
+  lint: 'pnpm lint',
+  typecheck: 'pnpm typecheck',
+  test: 'pnpm turbo run test',
+  coverage: 'pnpm vitest run --coverage',
+};
+
+export const SOFTWARE_DELIVERY_GATE_POLICIES: readonly PolicyProvider[] =
+  SOFTWARE_DELIVERY_GATE_NAMES.map((gate) => ({
+    id: `${SOFTWARE_DELIVERY_POLICY_ID_PREFIX}.${gate}`,
+    gate,
+    trigger: 'on_completion',
+    command: SOFTWARE_DELIVERY_GATE_COMMANDS[gate],
+  }));
+
+export const SOFTWARE_DELIVERY_STATE_ALIASES = {
+  active: 'in_progress',
+} as const;
+
+export function resolveSoftwareDeliveryStateAlias(
+  state: string,
+  aliases: Record<string, string> = SOFTWARE_DELIVERY_STATE_ALIASES,
+): string {
+  return aliases[state] ?? state;
+}
+
+export async function runCompletionGatePolicies(options: {
+  engine: CompletionPolicyEngine;
+  runId: string;
+  taskId: string;
+  providers?: readonly PolicyProvider[];
+  executePolicy?: (provider: PolicyProvider) => Promise<CompletionPolicyExecution>;
+}): Promise<CompletionPolicyRunResult[]> {
+  const providers = options.providers ?? SOFTWARE_DELIVERY_GATE_POLICIES;
+  const executePolicy =
+    options.executePolicy ??
+    (async () => ({
+      ok: true,
+    }));
+
+  const results: CompletionPolicyRunResult[] = [];
+
+  for (const provider of providers) {
+    const evaluation = await options.engine.evaluate({
+      trigger: provider.trigger,
+      run_id: options.runId,
+      task_id: options.taskId,
+      gate: provider.gate,
+      pack_id: SOFTWARE_DELIVERY_PACK_ID,
+    });
+
+    if (evaluation.decision === 'deny') {
+      results.push({
+        gate: provider.gate,
+        policy_id: provider.id,
+        decision: 'deny',
+        command: provider.command,
+        executed: false,
+        ok: false,
+      });
+      continue;
+    }
+
+    const execution = await executePolicy(provider);
+    results.push({
+      gate: provider.gate,
+      policy_id: provider.id,
+      decision: 'allow',
+      command: provider.command,
+      executed: true,
+      ok: execution.ok,
+    });
+  }
+
+  return results;
+}

package/packs/software-delivery/index.ts

@@ -0,0 +1,8 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+export * from './constants.js';
+export * from './extensions.js';
+export * from './gate-policies.js';
+export * from './manifest.js';
+export * from './pack-registration.js';

package/packs/software-delivery/manifest-schema.ts

@@ -0,0 +1,236 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import {
+  TOOL_PERMISSIONS,
+  TOOL_SCOPE_ACCESS,
+  TOOL_SCOPE_TYPES,
+  type PathScope,
+  type ToolPermission,
+} from './tools/types.js';
+
+interface Parser<T> {
+  parse(input: unknown): T;
+}
+
+export const MANIFEST_POLICY_TRIGGERS = {
+  ON_TOOL_REQUEST: 'on_tool_request',
+  ON_CLAIM: 'on_claim',
+  ON_COMPLETION: 'on_completion',
+  ON_EVIDENCE_ADDED: 'on_evidence_added',
+} as const;
+
+export type ManifestPolicyTrigger =
+  (typeof MANIFEST_POLICY_TRIGGERS)[keyof typeof MANIFEST_POLICY_TRIGGERS];
+
+export const MANIFEST_POLICY_DECISIONS = {
+  ALLOW: 'allow',
+  DENY: 'deny',
+} as const;
+
+export type ManifestPolicyDecision =
+  (typeof MANIFEST_POLICY_DECISIONS)[keyof typeof MANIFEST_POLICY_DECISIONS];
+
+export interface SoftwareDeliveryManifestTool {
+  name: string;
+  entry: string;
+  permission: ToolPermission;
+  required_scopes: PathScope[];
+  internal_only?: boolean;
+}
+
+export interface SoftwareDeliveryManifestPolicy {
+  id: string;
+  trigger: ManifestPolicyTrigger;
+  decision: ManifestPolicyDecision;
+  reason?: string;
+}
+
+export interface SoftwareDeliveryPackManifest {
+  id: string;
+  version: string;
+  task_types: string[];
+  tools: SoftwareDeliveryManifestTool[];
+  policies: SoftwareDeliveryManifestPolicy[];
+  evidence_types: string[];
+  state_aliases: Record<string, string>;
+  lane_templates: Array<{ id: string }>;
+}
+
+function asRecord(input: unknown, label: string): Record<string, unknown> {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error(`${label} must be an object.`);
+  }
+  return input as Record<string, unknown>;
+}
+
+function parseNonEmptyString(value: unknown, label: string): string {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function parseStringArray(value: unknown, label: string): string[] {
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array.`);
+  }
+  return value.map((entry, index) => parseNonEmptyString(entry, `${label}[${index}]`));
+}
+
+function isSemver(value: string): boolean {
+  let core = value;
+  const prereleaseIndex = core.indexOf('-');
+  if (prereleaseIndex >= 0) {
+    core = core.slice(0, prereleaseIndex);
+  }
+  const metadataIndex = core.indexOf('+');
+  if (metadataIndex >= 0) {
+    core = core.slice(0, metadataIndex);
+  }
+  const parts = core.split('.');
+  if (parts.length !== 3) {
+    return false;
+  }
+  return parts.every(
+    (part) => part.length > 0 && [...part].every((char) => char >= '0' && char <= '9'),
+  );
+}
+
+const ALLOWED_POLICY_TRIGGERS = new Set<string>(Object.values(MANIFEST_POLICY_TRIGGERS));
+const ALLOWED_POLICY_DECISIONS = new Set<string>(Object.values(MANIFEST_POLICY_DECISIONS));
+const ALLOWED_TOOL_PERMISSIONS = new Set<string>(Object.values(TOOL_PERMISSIONS));
+
+function parsePathScope(input: unknown, label: string): PathScope {
+  const scope = asRecord(input, label);
+  const type = parseNonEmptyString(scope.type, `${label}.type`);
+  const pattern = parseNonEmptyString(scope.pattern, `${label}.pattern`);
+  const access = parseNonEmptyString(scope.access, `${label}.access`);
+
+  if (type !== TOOL_SCOPE_TYPES.PATH) {
+    throw new Error(`${label}.type must be "${TOOL_SCOPE_TYPES.PATH}".`);
+  }
+  if (access !== TOOL_SCOPE_ACCESS.READ && access !== TOOL_SCOPE_ACCESS.WRITE) {
+    throw new Error(
+      `${label}.access must be "${TOOL_SCOPE_ACCESS.READ}" or "${TOOL_SCOPE_ACCESS.WRITE}".`,
+    );
+  }
+
+  return {
+    type: TOOL_SCOPE_TYPES.PATH,
+    pattern,
+    access,
+  };
+}
+
+function parseRequiredScopes(value: unknown, label: string): PathScope[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error(`${label} must be a non-empty array.`);
+  }
+  return value.map((entry, index) => parsePathScope(entry, `${label}[${index}]`));
+}
+
+function parsePolicy(input: unknown, index: number): SoftwareDeliveryManifestPolicy {
+  const policy = asRecord(input, `policies[${index}]`);
+  const trigger = parseNonEmptyString(policy.trigger, `policies[${index}].trigger`);
+  const decision = parseNonEmptyString(policy.decision, `policies[${index}].decision`);
+
+  if (!ALLOWED_POLICY_TRIGGERS.has(trigger)) {
+    throw new Error(`policies[${index}].trigger is invalid.`);
+  }
+  if (!ALLOWED_POLICY_DECISIONS.has(decision)) {
+    throw new Error(`policies[${index}].decision is invalid.`);
+  }
+
+  return {
+    id: parseNonEmptyString(policy.id, `policies[${index}].id`),
+    trigger: trigger as ManifestPolicyTrigger,
+    decision: decision as ManifestPolicyDecision,
+    reason:
+      policy.reason === undefined
+        ? undefined
+        : parseNonEmptyString(policy.reason, `policies[${index}].reason`),
+  };
+}
+
+function parseTool(input: unknown, index: number): SoftwareDeliveryManifestTool {
+  const tool = asRecord(input, `tools[${index}]`);
+  const permission =
+    tool.permission === undefined
+      ? TOOL_PERMISSIONS.READ
+      : parseNonEmptyString(tool.permission, `tools[${index}].permission`);
+
+  if (!ALLOWED_TOOL_PERMISSIONS.has(permission)) {
+    throw new Error(`tools[${index}].permission is invalid.`);
+  }
+
+  return {
+    name: parseNonEmptyString(tool.name, `tools[${index}].name`),
+    entry: parseNonEmptyString(tool.entry, `tools[${index}].entry`),
+    permission: permission as ToolPermission,
+    required_scopes: parseRequiredScopes(tool.required_scopes, `tools[${index}].required_scopes`),
+    internal_only:
+      tool.internal_only === undefined
+        ? undefined
+        : (() => {
+            if (typeof tool.internal_only !== 'boolean') {
+              throw new Error(`tools[${index}].internal_only must be boolean.`);
+            }
+            return tool.internal_only;
+          })(),
+  };
+}
+
+function parseStateAliases(input: unknown): Record<string, string> {
+  const aliases = asRecord(input ?? {}, 'state_aliases');
+  const parsed: Record<string, string> = {};
+  for (const [key, value] of Object.entries(aliases)) {
+    parsed[parseNonEmptyString(key, 'state_aliases key')] = parseNonEmptyString(
+      value,
+      `state_aliases.${key}`,
+    );
+  }
+  return parsed;
+}
+
+export const SoftwareDeliveryManifestSchema: Parser<SoftwareDeliveryPackManifest> = {
+  parse(input: unknown): SoftwareDeliveryPackManifest {
+    const manifest = asRecord(input, 'manifest');
+    const version = parseNonEmptyString(manifest.version, 'version');
+    if (!isSemver(version)) {
+      throw new Error('version must be semver.');
+    }
+
+    const taskTypes = parseStringArray(manifest.task_types, 'task_types');
+    if (taskTypes.length === 0) {
+      throw new Error('task_types must include at least one item.');
+    }
+
+    const toolsValue = manifest.tools ?? [];
+    if (!Array.isArray(toolsValue)) {
+      throw new Error('tools must be an array.');
+    }
+    const policiesValue = manifest.policies ?? [];
+    if (!Array.isArray(policiesValue)) {
+      throw new Error('policies must be an array.');
+    }
+    const laneTemplatesValue = manifest.lane_templates ?? [];
+    if (!Array.isArray(laneTemplatesValue)) {
+      throw new Error('lane_templates must be an array.');
+    }
+
+    return {
+      id: parseNonEmptyString(manifest.id, 'id'),
+      version,
+      task_types: taskTypes,
+      tools: toolsValue.map((tool, index) => parseTool(tool, index)),
+      policies: policiesValue.map((policy, index) => parsePolicy(policy, index)),
+      evidence_types: parseStringArray(manifest.evidence_types ?? [], 'evidence_types'),
+      state_aliases: parseStateAliases(manifest.state_aliases),
+      lane_templates: laneTemplatesValue.map((laneTemplate, index) => {
+        const entry = asRecord(laneTemplate, `lane_templates[${index}]`);
+        return { id: parseNonEmptyString(entry.id, `lane_templates[${index}].id`) };
+      }),
+    };
+  },
+};