@relayflows/sdk 2.0.31 → 2.0.32

package/src/preflight.ts

@@ -65,7 +65,7 @@ export class CliProbeError extends Error {
   }
 }
 
-type CliProbeOutcome =
+export type CliProbeOutcome =
   | { result: CliProbeResult }
   | { failure: CliProbeFailureDetail | null };
 
@@ -89,6 +89,8 @@ export interface PreflightProbes {
 }
 
 export interface PreflightOptions {
+  /** Reuse only within one run and one CLI resolution environment; failures are cached too. */
+  cliProbeCache?: Map<string, CliProbeOutcome>;
   pluginSearchStart?: string;
   /** Validated tools.mcp header and nearest flows.json connections. */
   mcpServers?: readonly string[];
@@ -99,6 +101,7 @@ export interface PreflightOptions {
   /** Exact, project-owned model allowlist from the nearest flows.json. */
   models?: readonly string[];
   modelRegistryPath?: string;
+  probeCache?: Map<string, CliProbeOutcome>;
   probes: PreflightProbes;
 }
 
@@ -194,7 +197,12 @@ async function probeMcp(result: PreflightResult, options: PreflightOptions): Pro
   return { ...result, ok: !result.diagnostics.some(d => d.severity === 'refusal'), mcpTools: Object.freeze(inventory) };
 }
 
-function preflightSync(flow: unknown, options: PreflightOptions): PreflightResult {
+type ResolutionOptions = Omit<PreflightOptions, 'probes' | 'probeCache'>;
+
+/** Resolve static declarations before any CLI, model, command or trigger probe. */
+export function resolvePreflight(flow: unknown, options: ResolutionOptions): PreflightResult & {
+  compiled?: import('./compile.js').CompiledFlowSpec;
+} {
   // Compile before touching any environment fact. `compileSpec` snapshots raw
   // input into inert data, validates it against the closed authoring schema,
   // and lowers `output` sugar into its json_schema gate — so the gate plan
@@ -235,7 +243,7 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
   const cliResolutionDiagnostics: PreflightDiagnostic[] = [];
   const resolutions: CliResolution[] = [];
   const resolutionByStep = new Map<string, CliResolution>();
-  const cliProbeResults = new Map<string, CliProbeOutcome>();
+  const cliProbeResults = options.cliProbeCache ?? new Map<string, CliProbeOutcome>();
 
   // A pure fact about the compiled snapshot, collected before anything that
   // can return early. An unresolved CLI, an unknown model or a bad scope all
@@ -289,6 +297,18 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
     return { ok: false, gates: compiled.steps.map(inspectStepGate), resolutions, diagnostics };
   }
 
+  return { ok: true, gates: compiled.steps.map(inspectStepGate), resolutions, diagnostics, compiled };
+}
+
+function preflightSync(flow: unknown, options: PreflightOptions): PreflightResult {
+  const { compiled, ...result } = resolvePreflight(flow, options);
+  if (!result.ok || compiled === undefined) return result;
+  const { diagnostics, resolutions } = result;
+  const resolutionByStep = new Map(resolutions.map(resolution => [resolution.stepId, resolution]));
+  // `cliProbeCache` is the public run-scoped name; `probeCache` is retained as
+  // a compatibility alias for the async authored-preflight path.
+  const cliProbeResults = options.cliProbeCache ?? options.probeCache ?? new Map<string, CliProbeOutcome>();
+
   for (const step of compiled.steps) {
     probeNamedGate(step, options.probes, diagnostics);
     warnOnVacuousGate(step, diagnostics);
@@ -333,7 +353,7 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
  * fact about the filesystem. Missing manifest means no known mounts — a grant
  * still parses but refuses as `mount_unknown` in that case.
  */
-function scopeDiagnostics(flow: FlowSpec, options: PreflightOptions): PreflightRefusal[] {
+function scopeDiagnostics(flow: FlowSpec, options: ResolutionOptions): PreflightRefusal[] {
   const workspace = flow.workspace;
   const toolsFs = flow.tools?.fs;
   if (workspace === undefined && toolsFs === undefined) return [];
@@ -357,7 +377,7 @@ function scopeDiagnostics(flow: FlowSpec, options: PreflightOptions): PreflightR
 /** Pure authoring validation: no executable, command, trigger, or daemon probe. */
 function unknownModelDiagnostics(
   flow: FlowSpec,
-  options: PreflightOptions,
+  options: ResolutionOptions,
   resolutionByStep: ReadonlyMap<string, CliResolution> = new Map(),
 ): PreflightRefusal[] {
   const diagnostics: PreflightRefusal[] = [];
@@ -471,7 +491,7 @@ function unknownModelMessage(
   return `Step "${stepId}" declares model "${model}"${cliContext}, but it is not listed in ${source}; add the exact model only after verifying that project is allowed to use it.`;
 }
 
-function unresolvedCliMessage(stepId: string, options: PreflightOptions): string {
+function unresolvedCliMessage(stepId: string, options: ResolutionOptions): string {
   const context = options.projectConfigPath !== undefined
     ? ` Nearest project config "${options.projectConfigPath}" declares no cli; outer configs are shadowed.`
     : options.projectSearchStart !== undefined
@@ -501,6 +521,10 @@ function resolveCli(
   return undefined;
 }
 
+export function cliProbeKey(resolution: CliResolution, managed = false): string {
+  return JSON.stringify([resolution.cli, resolution.source, resolution.model ?? null, managed]);
+}
+
 function probeResolvedCli(
   resolution: CliResolution,
   probes: PreflightProbes,
@@ -514,7 +538,7 @@ function probeResolvedCli(
   // Model is part of the key: the same CLI probed with two different models
   // is two different questions, and caching on the CLI alone would let a
   // model that the CLI cannot resolve inherit an earlier model's pass.
-  const cacheKey = JSON.stringify([resolution.cli, resolution.source, resolution.model ?? null, managed]);
+  const cacheKey = cliProbeKey(resolution, managed);
   let outcome = cache.get(cacheKey);
   if (outcome === undefined) {
     try {

package/src/relay-cli.ts

@@ -1,7 +1,6 @@
-import { readFileSync } from 'node:fs';
-
 import { runCli } from './cli.js';
 import { CLI_VERBS, CLI_VERB_NAMES, type CliCommandSpec } from './cli-commands.js';
+import { packageVersion } from './package-version.js';
 
 /**
  * The `@relayflows/sdk/relay-cli` entrypoint: a mountable CLI surface.
@@ -56,28 +55,6 @@ function toCommandSpec(verb: CliCommandSpec & { variants?: unknown }): CliComman
   return spec;
 }
 
-/**
- * Read this package's version from its own manifest.
- *
- * Resolved from `import.meta.url` rather than imported, because `package.json`
- * sits outside `rootDir` and a hardcoded literal would silently go stale at the
- * next release. `src/` and `dist/` are both one level below the manifest, so
- * the same relative path is correct before and after a build.
- */
-function packageVersion(): string {
-  try {
-    const manifest: unknown = JSON.parse(
-      readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
-    );
-    const version = (manifest as { version?: unknown }).version;
-    return typeof version === 'string' && version.length > 0 ? version : '0.0.0';
-  } catch {
-    // A surface that cannot read its own manifest is still perfectly runnable;
-    // refusing to mount over a cosmetic field would be the worse failure.
-    return '0.0.0';
-  }
-}
-
 /**
  * Build the relayflows CLI surface.
  *