@lumenflow/cli 3.1.2 → 3.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "3.1.2",
+  "version": "3.1.3",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -142,11 +142,13 @@
     "workspace-init": "./dist/workspace-init.js",
     "config-set": "./dist/config-set.js",
     "config-get": "./dist/config-get.js",
+    "cloud-connect": "./dist/init.js",
     "lumenflow-onboard": "./dist/onboard.js",
     "onboard": "./dist/onboard.js"
   },
   "files": [
     "dist",
+    "packs",
     "templates",
     "LICENSE",
     "README.md"
@@ -176,12 +178,12 @@
     "xstate": "^5.28.0",
     "yaml": "^2.8.2",
     "zod": "^4.3.6",
-    "@lumenflow/agent": "3.1.2",
-    "@lumenflow/kernel": "3.1.2",
-    "@lumenflow/memory": "3.1.2",
-    "@lumenflow/initiatives": "3.1.2",
-    "@lumenflow/core": "3.1.2",
-    "@lumenflow/metrics": "3.1.2"
+    "@lumenflow/agent": "3.1.3",
+    "@lumenflow/core": "3.1.3",
+    "@lumenflow/initiatives": "3.1.3",
+    "@lumenflow/metrics": "3.1.3",
+    "@lumenflow/memory": "3.1.3",
+    "@lumenflow/kernel": "3.1.3"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.18",
@@ -197,8 +199,10 @@
     "access": "public"
   },
   "scripts": {
+    "sync:bundled-packs": "node scripts/sync-bundled-packs.mjs",
     "build": "tsc && node scripts/check-shebangs.mjs",
-    "build:dist": "tsup && node scripts/fix-entry-points.mjs && node scripts/check-shebangs.mjs",
+    "build:dist:deps": "pnpm --filter @lumenflow/metrics build && pnpm --filter @lumenflow/kernel build && pnpm --filter @lumenflow/core build && pnpm --filter @lumenflow/memory build && pnpm --filter @lumenflow/agent build && pnpm --filter @lumenflow/initiatives build",
+    "build:dist": "pnpm run clean && pnpm run build:dist:deps && tsup && node scripts/fix-entry-points.mjs && node scripts/check-shebangs.mjs",
     "pack:dist": "pnpm pack",
     "clean": "rm -rf dist *.tgz",
     "test": "vitest run",

package/packs/software-delivery/constants.ts

@@ -0,0 +1,10 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+export const SOFTWARE_DELIVERY_PACK_ID = 'software-delivery' as const;
+export const SOFTWARE_DELIVERY_PACK_VERSION = '0.1.0' as const;
+export const SOFTWARE_DELIVERY_DOMAIN = SOFTWARE_DELIVERY_PACK_ID;
+export const SOFTWARE_DELIVERY_POLICY_ID_PREFIX = `${SOFTWARE_DELIVERY_PACK_ID}.gate` as const;
+export const SOFTWARE_DELIVERY_MANIFEST_FILE_NAME = 'manifest.yaml' as const;
+export const SHA256_ALGORITHM = 'sha256' as const;
+export const UTF8_ENCODING = 'utf8' as const;

package/packs/software-delivery/extensions.ts

@@ -0,0 +1,140 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { SOFTWARE_DELIVERY_DOMAIN } from './constants.js';
+
+export const SOFTWARE_DELIVERY_EXTENSION_KEY = 'software_delivery';
+export const SOFTWARE_DELIVERY_EXPOSURES = ['ui', 'api', 'backend-only', 'documentation'] as const;
+
+interface Parser<T> {
+  parse(input: unknown): T;
+}
+
+export interface SoftwareDeliveryTests {
+  unit: string[];
+  e2e: string[];
+  manual: string[];
+}
+
+export interface SoftwareDeliveryTaskExtensions {
+  code_paths: string[];
+  tests: SoftwareDeliveryTests;
+  exposure: (typeof SOFTWARE_DELIVERY_EXPOSURES)[number];
+  worktree: string;
+  branch: string;
+}
+
+export interface SoftwareDeliveryTask {
+  domain: typeof SOFTWARE_DELIVERY_DOMAIN;
+  extensions: Record<string, unknown> & {
+    [SOFTWARE_DELIVERY_EXTENSION_KEY]: SoftwareDeliveryTaskExtensions;
+  };
+}
+
+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 assertOnlyKeys(
+  record: Record<string, unknown>,
+  allowedKeys: readonly string[],
+  label: string,
+): void {
+  const allowed = new Set(allowedKeys);
+  for (const key of Object.keys(record)) {
+    if (!allowed.has(key)) {
+      throw new Error(`${label} has unrecognized key "${key}".`);
+    }
+  }
+}
+
+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 parseTests(input: unknown): SoftwareDeliveryTests {
+  const tests = asRecord(input, 'tests');
+  assertOnlyKeys(tests, ['unit', 'e2e', 'manual'], 'tests');
+  return {
+    unit: parseStringArray(tests.unit ?? [], 'tests.unit'),
+    e2e: parseStringArray(tests.e2e ?? [], 'tests.e2e'),
+    manual: parseStringArray(tests.manual ?? [], 'tests.manual'),
+  };
+}
+
+const ExposureSet = new Set<string>(SOFTWARE_DELIVERY_EXPOSURES);
+
+export const SoftwareDeliveryTaskExtensionsSchema: Parser<SoftwareDeliveryTaskExtensions> = {
+  parse(input: unknown): SoftwareDeliveryTaskExtensions {
+    const extension = asRecord(input, 'software delivery extension');
+    assertOnlyKeys(
+      extension,
+      ['code_paths', 'tests', 'exposure', 'worktree', 'branch'],
+      'software delivery extension',
+    );
+
+    const exposure = parseNonEmptyString(extension.exposure, 'exposure');
+    if (!ExposureSet.has(exposure)) {
+      throw new Error(`exposure must be one of: ${SOFTWARE_DELIVERY_EXPOSURES.join(', ')}`);
+    }
+
+    return {
+      code_paths: parseStringArray(extension.code_paths, 'code_paths'),
+      tests: parseTests(extension.tests),
+      exposure: exposure as (typeof SOFTWARE_DELIVERY_EXPOSURES)[number],
+      worktree: parseNonEmptyString(extension.worktree, 'worktree'),
+      branch: parseNonEmptyString(extension.branch, 'branch'),
+    };
+  },
+};
+
+export const TaskExtensionsOpaqueRecordSchema: Parser<Record<string, unknown>> = {
+  parse(input: unknown): Record<string, unknown> {
+    return asRecord(input, 'extensions');
+  },
+};
+
+export function extractSoftwareDeliveryExtensions(
+  extensions: Record<string, unknown> | undefined,
+): SoftwareDeliveryTaskExtensions {
+  const parsedExtensions = TaskExtensionsOpaqueRecordSchema.parse(extensions ?? {});
+  return SoftwareDeliveryTaskExtensionsSchema.parse(
+    parsedExtensions[SOFTWARE_DELIVERY_EXTENSION_KEY],
+  );
+}
+
+export const SoftwareDeliveryTaskSchema: Parser<SoftwareDeliveryTask> = {
+  parse(input: unknown): SoftwareDeliveryTask {
+    const task = asRecord(input, 'task');
+
+    if (task.domain !== SOFTWARE_DELIVERY_DOMAIN) {
+      throw new Error(`task.domain must be "${SOFTWARE_DELIVERY_DOMAIN}".`);
+    }
+
+    const parsedExtensions = TaskExtensionsOpaqueRecordSchema.parse(task.extensions);
+    const parsedSoftwareDeliveryExtensions = SoftwareDeliveryTaskExtensionsSchema.parse(
+      parsedExtensions[SOFTWARE_DELIVERY_EXTENSION_KEY],
+    );
+
+    return {
+      domain: SOFTWARE_DELIVERY_DOMAIN,
+      extensions: {
+        ...parsedExtensions,
+        [SOFTWARE_DELIVERY_EXTENSION_KEY]: parsedSoftwareDeliveryExtensions,
+      },
+    };
+  },
+};

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`) };
+      }),
+    };
+  },
+};