@field/cascade 0.10.0 → 0.11.0

package/dist/cli/chunk-RUU3YWXU.js

@@ -0,0 +1,99 @@
+import {
+  ExpressionEvaluator,
+  parseBundleFieldPath
+} from "./chunk-CO22XHNG.js";
+
+// src/engine/expressions/ExpressionEngine.ts
+var ExpressionEngine = class extends ExpressionEvaluator {
+  constructor() {
+    super();
+    this.graph = null;
+    const scope = {
+      resolveParam: (from, path) => this.resolveNodePath(from, path),
+      nodeExists: (from, path) => from.node(path) !== null,
+      inputNode: (from, index) => this.resolveInput(from, index)
+    };
+    this.setScope(scope);
+  }
+  /**
+   * Set the graph reference for node lookups
+   */
+  setGraph(graph) {
+    this.graph = graph;
+  }
+  /**
+   * Resolve a path to get the parameter value
+   */
+  resolveNodePath(fromNode, path) {
+    const lastSlash = path.lastIndexOf("/");
+    if (lastSlash === -1 || path.startsWith("./")) {
+      const paramName2 = path.replace("./", "");
+      const prop2 = fromNode.props[paramName2];
+      if (prop2) return { value: prop2.value };
+      return this.resolveBundleField(fromNode, paramName2);
+    }
+    const nodePath = path.substring(0, lastSlash) || ".";
+    const paramName = path.substring(lastSlash + 1);
+    const targetNode = fromNode.node(nodePath);
+    if (!targetNode) return null;
+    const prop = targetNode.props[paramName];
+    return prop ? { value: prop.value } : null;
+  }
+  /**
+   * `format.dpi`: field `dpi` of the bundle wired into this node's `format`
+   * input. Read off the input port, so it is whatever the producer committed
+   * on its last cook, which the wire guarantees came first.
+   */
+  resolveBundleField(node, name) {
+    const reference = parseBundleFieldPath(name);
+    if (!reference) return null;
+    const port = node.inputs.find((input) => input.name === reference.port);
+    if (!port || port.dataType !== "bundle") return null;
+    const bundle = port.value;
+    if (bundle === null || typeof bundle !== "object") return null;
+    if (!Object.prototype.hasOwnProperty.call(bundle, reference.field)) return null;
+    return { value: bundle[reference.field] };
+  }
+  /**
+   * Get input node by index
+   */
+  resolveInput(node, index) {
+    if (!this.graph) return null;
+    const inputPort = node.inputs[index];
+    if (!inputPort || inputPort.connections.length === 0) return null;
+    const conn = inputPort.connections[0];
+    return this.graph.getNode(conn.from.nodeId);
+  }
+  /**
+   * Validate all expression paths in the graph
+   * Returns list of broken paths with their locations
+   */
+  validateAllPaths() {
+    if (!this.graph) return [];
+    const warnings = [];
+    for (const node of this.graph.nodes) {
+      for (const [propKey, prop] of Object.entries(node.props)) {
+        if (!prop.expression) continue;
+        const paths = this.extractDependencies(prop.expression);
+        for (const path of paths) {
+          if (!this.validatePath(node, path)) {
+            warnings.push({
+              nodeId: node.id,
+              nodePath: node.path(),
+              propName: propKey,
+              expression: prop.expression,
+              brokenPath: path
+            });
+          }
+        }
+      }
+    }
+    return warnings;
+  }
+};
+var expressionEngine = new ExpressionEngine();
+
+export {
+  expressionEngine
+};
+//# sourceMappingURL=chunk-RUU3YWXU.js.map

package/dist/cli/chunk-RXDIMXN5.js

@@ -0,0 +1,98 @@
+// packages/runtime/src/builtins/core/random.ts
+var randomDefinition = {
+  apiVersion: 1,
+  label: "Random",
+  description: "Generate a deterministic unit value from an explicit seed.",
+  icon: "Dice5",
+  runsOn: "portable",
+  inputs: {
+    seed: {
+      kind: "data",
+      type: "int",
+      default: 0,
+      description: "Integer seed. Equal seeds always produce equal values."
+    },
+    sample: {
+      kind: "data",
+      type: "int",
+      default: 0,
+      description: "Stable sample index within the seeded sequence."
+    }
+  },
+  outputs: {
+    value: {
+      kind: "data",
+      type: "float",
+      description: "Deterministic value in the half-open range [0, 1)."
+    }
+  }
+};
+function randomFromSeed(seed, sample = 0) {
+  const streamSeed = (Math.trunc(seed) ^ Math.imul(Math.trunc(sample), 2654435761)) >>> 0;
+  let value = streamSeed + 1831565813 >>> 0;
+  value = Math.imul(value ^ value >>> 15, value | 1);
+  value ^= value + Math.imul(value ^ value >>> 7, value | 61);
+  return ((value ^ value >>> 14) >>> 0) / 4294967296;
+}
+function executeRandom(context) {
+  context.outputs.value.set(randomFromSeed(context.inputs.seed, context.inputs.sample));
+}
+var randomRegistration = {
+  kind: "definition-v1",
+  moduleId: "cascade.core.Random",
+  definition: randomDefinition,
+  loadExecute: async () => executeRandom
+};
+
+// packages/runtime/src/builtins/core/remap.ts
+var remapDefinition = {
+  apiVersion: 1,
+  label: "Remap",
+  description: "Map a number from one range into another.",
+  icon: "ArrowRightLeft",
+  runsOn: "portable",
+  inputs: {
+    value: { kind: "data", type: "float", default: 0 },
+    inMin: { kind: "data", type: "float", default: 0 },
+    inMax: { kind: "data", type: "float", default: 1 },
+    outMin: { kind: "data", type: "float", default: 0 },
+    outMax: { kind: "data", type: "float", default: 1 }
+  },
+  outputs: {
+    result: { kind: "data", type: "float" }
+  },
+  props: {
+    clamp: {
+      type: "bool",
+      default: false,
+      label: "Clamp",
+      description: "Keep the normalized input between zero and one."
+    }
+  }
+};
+function remap(value, inMin, inMax, outMin, outMax, clamp) {
+  if (inMin === inMax) return outMin;
+  const normalized = (value - inMin) / (inMax - inMin);
+  const amount = clamp ? Math.min(1, Math.max(0, normalized)) : normalized;
+  return outMin + amount * (outMax - outMin);
+}
+function executeRemap(context) {
+  const { value, inMin, inMax, outMin, outMax } = context.inputs;
+  context.outputs.result.set(
+    remap(value, inMin, inMax, outMin, outMax, context.props.clamp)
+  );
+}
+var remapRegistration = {
+  kind: "definition-v1",
+  moduleId: "cascade.core.Remap",
+  definition: remapDefinition,
+  loadExecute: async () => executeRemap
+};
+
+export {
+  randomFromSeed,
+  randomRegistration,
+  remap,
+  remapRegistration
+};
+//# sourceMappingURL=chunk-RXDIMXN5.js.map

package/dist/cli/chunk-SGJAET2L.js

@@ -0,0 +1,197 @@
+import {
+  Node,
+  packagePathToType,
+  registerNodeClasses,
+  registerNodeMetadata
+} from "./chunk-FCDXJ6EK.js";
+import {
+  bundleValueProblem,
+  graphSeed,
+  isGpuHost,
+  nodeSeed,
+  seededRandom,
+  selectBundleFields
+} from "./chunk-GFS6W3C5.js";
+
+// src/nodes/definition/DefinitionNode.ts
+var silentProgress = { report: () => {
+} };
+function parameterOptions(definition) {
+  return {
+    ...definition.label ? { label: definition.label } : {},
+    ...definition.expression ? { defaultExpression: definition.expression } : {},
+    ...definition.action ? { action: definition.action } : {},
+    ...definition.min === void 0 ? {} : { min: definition.min },
+    ...definition.max === void 0 ? {} : { max: definition.max },
+    ...definition.step === void 0 ? {} : { step: definition.step },
+    ...definition.options ? {
+      // A declared label wins; a bare value is its own label, which is what
+      // every definition written before the labelled form meant. Stringifying
+      // unconditionally is what turned "Magnific — costs money" into
+      // "magnific" and threw away the only notice that it bills per call.
+      choices: definition.options.map((option) => option !== null && typeof option === "object" && "value" in option ? {
+        value: option.value,
+        label: String(option.label ?? option.value),
+        ...option.disabled ? { disabled: true } : {}
+      } : { value: option, label: String(option) })
+    } : {},
+    promotable: false
+  };
+}
+function bundlePortOptions(port) {
+  if (port.type !== "bundle") return {};
+  return {
+    ...port.schema ? { schema: port.schema } : {},
+    ...Array.isArray(port.fields) ? { fieldSelection: port.fields } : port.fields ? { bundleFields: port.fields } : {}
+  };
+}
+function attachDefinition(node, registration, capabilities) {
+  const definition = registration.definition;
+  const pendingTriggers = /* @__PURE__ */ new Map();
+  let triggerSequence = 0;
+  const container = definition.container;
+  if (container === "subnet" || container === "array") {
+    node.declaredContainer = container;
+  }
+  for (const [name, input] of Object.entries(definition.inputs ?? {})) {
+    if (input.kind === "trigger") {
+      const port = node.in(name, void 0, {
+        type: "any",
+        ...input.description ? { description: input.description } : {}
+      });
+      port.portType = "trigger";
+      port.onTrigger = async (payload) => {
+        const sequence = triggerSequence++;
+        pendingTriggers.set(name, {
+          id: `${node.id}:${sequence}`,
+          runId: `studio:${node.id}:${sequence}`,
+          sequence,
+          ...payload === void 0 ? {} : { payload },
+          source: { kind: "external" }
+        });
+        node.markDirty();
+        await node.execute();
+      };
+      continue;
+    }
+    if (input.variadic) {
+      node.setVariadic(void 0, { type: input.type });
+      continue;
+    }
+    node.in(name, input.default, {
+      type: input.type,
+      ...input.min === void 0 ? {} : { min: input.min },
+      ...input.max === void 0 ? {} : { max: input.max },
+      ...input.step === void 0 ? {} : { step: input.step },
+      ...input.options ? {
+        choices: input.options.map((value) => ({ value, label: String(value) }))
+      } : {},
+      ...input.description ? { description: input.description } : {},
+      ...bundlePortOptions(input)
+    });
+  }
+  for (const [name, output] of Object.entries(definition.outputs ?? {})) {
+    node.out(
+      name,
+      output.kind === "trigger" ? "trigger" : "param",
+      output.kind === "data" ? { type: output.type, description: output.description, ...bundlePortOptions(output) } : { description: output.description }
+    );
+  }
+  for (const [name, prop] of Object.entries(definition.props ?? {})) {
+    const parameter = node.param(name, prop.default, {
+      type: prop.type,
+      ...parameterOptions(prop)
+    });
+    parameter.documentField = "props";
+  }
+  const hasTriggerInputs = Object.values(definition.inputs ?? {}).some((input) => input.kind === "trigger");
+  let executePromise;
+  return async () => {
+    if (hasTriggerInputs && pendingTriggers.size === 0) return;
+    for (const name of definition.capabilities ?? []) {
+      if (!capabilities[name]) {
+        throw new Error(`${registration.moduleId} requires the Studio ${name} capability`);
+      }
+    }
+    const execute = await (executePromise ??= registration.loadExecute("browser"));
+    const inputValues = {};
+    for (const [name, input] of Object.entries(definition.inputs ?? {})) {
+      inputValues[name] = input.kind === "trigger" ? pendingTriggers.get(name) : input.variadic ? node.getVariadicInputs().map((port) => port.value ?? void 0) : input.type === "bundle" && input.fields ? selectBundleFields(node.inputs.find((port) => port.name === name)?.value, input.fields) : node.inputs.find((port) => port.name === name)?.value;
+    }
+    pendingTriggers.clear();
+    const outputs = Object.fromEntries(Object.entries(definition.outputs ?? {}).map(([name, output]) => {
+      const port = node.outputs.find((candidate) => candidate.name === name);
+      if (!port) throw new Error(`Missing output ${registration.moduleId}.${name}`);
+      return [name, output.kind === "trigger" ? { trigger: (payload) => port.trigger(payload) } : {
+        set: (value) => {
+          if (output.type === "bundle") {
+            const problem = bundleValueProblem(value, output.fields);
+            if (problem) throw new Error(`${node.id}.${name} ${problem}`);
+          }
+          port.setValue(value);
+        }
+      }];
+    }));
+    let nodeCapabilities = capabilities;
+    const gpuHost = (definition.capabilities ?? []).includes("gpu") && isGpuHost(capabilities.gpu) ? capabilities.gpu : null;
+    if (gpuHost) {
+      await gpuHost.ensure();
+      nodeCapabilities = { ...capabilities, gpu: gpuHost.forNode(node.id) };
+    }
+    const seed = nodeSeed(graphSeed({ seed: node.documentSeed }), node.id);
+    const context = {
+      nodeId: node.id,
+      inputs: inputValues,
+      outputs,
+      props: Object.fromEntries(node.parameters.map((parameter) => [parameter.name, parameter.value])),
+      capabilities: nodeCapabilities,
+      // The node's own cook signal, not a fresh one that nobody aborts. See
+      // `Node.cookSignal` for what that cost.
+      signal: node.cookSignal ?? new AbortController().signal,
+      progress: silentProgress,
+      // The same derivation as the headless runtime, so a seeded node draws
+      // the same thing in both hosts.
+      seed,
+      random: seededRandom(seed)
+    };
+    await execute(context);
+  };
+}
+function configureNode(node, registration, capabilities) {
+  node.setFunction(attachDefinition(node, registration, capabilities));
+}
+function registerDefinitionNodes(registrations, capabilities = {}) {
+  const libraries = /* @__PURE__ */ new Map();
+  for (const registration of registrations) {
+    const parts = registration.moduleId.split(".");
+    if (parts.length !== 3 || parts[0] !== "cascade") {
+      throw new Error(`Studio built-ins require cascade.<library>.<node>: ${registration.moduleId}`);
+    }
+    const libraryId = parts[1];
+    const nodeType = packagePathToType(registration.moduleId);
+    const classes = libraries.get(libraryId) ?? {};
+    classes[nodeType] = class extends Node {
+      constructor(id, graph) {
+        super(id, nodeType, graph);
+      }
+      setup() {
+        configureNode(this, registration, capabilities);
+      }
+    };
+    libraries.set(libraryId, classes);
+    registerNodeMetadata({
+      type: registration.moduleId,
+      name: registration.definition.label ?? nodeType,
+      icon: registration.definition.icon,
+      description: registration.definition.description,
+      category: libraryId
+    });
+  }
+  for (const [libraryId, classes] of libraries) registerNodeClasses(libraryId, classes);
+}
+
+export {
+  attachDefinition,
+  registerDefinitionNodes
+};
+//# sourceMappingURL=chunk-SGJAET2L.js.map

package/dist/cli/chunk-VVGSLVSF.js

@@ -0,0 +1,151 @@
+import {
+  declaredStagePython
+} from "./chunk-WD62JIP6.js";
+
+// server/src/stageRunner.ts
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+var TIMEOUT_MS = 10 * 60 * 1e3;
+var MAX_BUFFER = 64 * 1024 * 1024;
+function resolveProjectExecutable(project, configuredPath) {
+  if (path.isAbsolute(configuredPath)) {
+    throw new Error("cascade.json exec.stages.python must be python, python3, or a project-relative executable");
+  }
+  const executable = path.resolve(project.root, configuredPath);
+  const relative = path.relative(project.root, executable);
+  if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error("cascade.json exec.stages.python must be python, python3, or a project-relative executable");
+  }
+  return executable;
+}
+function readStageConfig(project) {
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(project.resolve("cascade.json"), "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error("Project stages are not configured; add exec.stages to cascade.json");
+    }
+    throw new Error(`Cannot read cascade.json: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const stages = raw?.exec?.stages;
+  const value = stages && typeof stages === "object" && !Array.isArray(stages) ? stages : null;
+  const entrypoint = value && typeof value.entrypoint === "string" ? value.entrypoint : "";
+  if (!entrypoint) {
+    throw new Error("Project stages are not configured; add exec.stages.entrypoint to cascade.json");
+  }
+  project.resolve(entrypoint);
+  const worker = typeof value?.worker === "string" && value.worker ? value.worker : void 0;
+  if (value?.worker !== void 0 && !worker) {
+    throw new Error("cascade.json exec.stages.worker must be a project-relative path");
+  }
+  if (worker) project.resolve(worker);
+  const configuredPython = value?.python;
+  let python = "python3";
+  let explicit = false;
+  if (configuredPython !== void 0) {
+    if (typeof configuredPython !== "string" || !configuredPython.trim()) {
+      throw new Error("cascade.json exec.stages.python must be python, python3, or a project-relative executable");
+    }
+    const executable = configuredPython.trim();
+    explicit = executable !== "python" && executable !== "python3";
+    python = explicit ? resolveProjectExecutable(project, executable) : executable;
+  }
+  if (!explicit) python = declaredStagePython(project.root) ?? python;
+  const sources = value?.sources;
+  if (sources !== void 0 && (!Array.isArray(sources) || sources.some((item) => typeof item !== "string" || !item))) {
+    throw new Error("cascade.json exec.stages.sources must be a list of project-relative paths");
+  }
+  return {
+    python,
+    entrypoint,
+    ...worker ? { worker } : {},
+    ...sources ? { sources } : {},
+    cache: readCachePolicy(value?.cache)
+  };
+}
+function readCachePolicy(value) {
+  const strings = (list, name) => {
+    if (list === void 0) return [];
+    if (!Array.isArray(list) || list.some((item) => typeof item !== "string")) {
+      throw new Error(`cascade.json exec.stages.cache.${name} must be a list of names`);
+    }
+    return list;
+  };
+  if (value === void 0) return { enabled: true, scope: "cook", exclude: [], outputs: [] };
+  if (value === false) return { enabled: false, scope: "cook", exclude: [], outputs: [] };
+  if (value === true) return { enabled: true, scope: "all", exclude: [], outputs: [] };
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const record = value;
+    if (record.scope !== void 0 && record.scope !== "cook" && record.scope !== "all") {
+      throw new Error('cascade.json exec.stages.cache.scope must be "cook" or "all"');
+    }
+    return {
+      enabled: record.enabled !== false,
+      scope: record.scope === "all" ? "all" : "cook",
+      exclude: strings(record.exclude, "exclude"),
+      outputs: strings(record.outputs, "outputs")
+    };
+  }
+  throw new Error("cascade.json exec.stages.cache must be true, false or { exclude, outputs, scope }");
+}
+async function runProjectStage(project, stage, args, options = {}) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(stage)) {
+    throw new Error("stage contains unsupported characters");
+  }
+  const { python, entrypoint } = readStageConfig(project);
+  const script = project.resolve(entrypoint);
+  const payload = JSON.stringify(args);
+  const stdout = await new Promise((resolve, reject) => {
+    const child = execFile(
+      python,
+      [script, "--stage", stage, "--args", "-"],
+      {
+        cwd: project.root,
+        timeout: options.timeout ?? TIMEOUT_MS,
+        maxBuffer: MAX_BUFFER,
+        env: {
+          ...options.env ?? process.env,
+          ...options.cascade ? { CASCADE_STAGE_ENVELOPE: JSON.stringify(options.cascade) } : {},
+          // Python checks a .pyc against the source's size and whole-second
+          // mtime, so a quick same-length edit would run the old bytecode.
+          ...options.codeHash ? { PYTHONPYCACHEPREFIX: path.join(os.tmpdir(), "cascade-pycache", options.codeHash) } : {}
+        },
+        signal: options.signal
+      },
+      (error, out, err) => {
+        if (error) {
+          const output = err?.trim() || out.trim().split("\n").pop() || error.message;
+          return reject(new Error(`stage "${stage}" failed: ${output}`));
+        }
+        if (err?.trim()) options.onOutput?.("stderr", err.trim());
+        resolve(out);
+      }
+    );
+    child.stdin?.end(payload);
+  });
+  if (options.onOutput) {
+    const lines = stdout.trim().split("\n");
+    const chatter = lines.slice(0, -1).join("\n").trim();
+    if (chatter) options.onOutput("stdout", chatter);
+  }
+  const lastLine = stdout.trim().split("\n").pop() || "{}";
+  let parsed;
+  try {
+    parsed = JSON.parse(lastLine);
+  } catch {
+    throw new Error(`stage "${stage}" returned no JSON: ${lastLine.slice(0, 200)}`);
+  }
+  if (parsed && typeof parsed === "object" && "error" in parsed) {
+    throw new Error(`stage "${stage}" failed: ${String(parsed.error)}`);
+  }
+  return parsed;
+}
+
+export {
+  readStageConfig,
+  runProjectStage
+};
+//# sourceMappingURL=chunk-VVGSLVSF.js.map

package/dist/cli/chunk-WD62JIP6.js

@@ -0,0 +1,118 @@
+// server/src/pythonEnv.ts
+import { execFile } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+var RELATIVE_DIRECTORY = path.join(".cascade-cache", "python", "venv");
+var MARKER = "cascade-env.json";
+function pythonEnvDirectory(root) {
+  return path.join(root, RELATIVE_DIRECTORY);
+}
+function pythonEnvInterpreter(root) {
+  const directory = pythonEnvDirectory(root);
+  return process.platform === "win32" ? path.join(directory, "Scripts", "python.exe") : path.join(directory, "bin", "python");
+}
+function readPythonEnv(root) {
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(path.join(root, "cascade.json"), "utf8"));
+  } catch {
+    return null;
+  }
+  const value = raw?.python;
+  if (value === void 0) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error('cascade.json python must be an object: { "requirements": ["numpy", ...] | "requirements.txt", "interpreter"?: "python3" }');
+  }
+  const { requirements, interpreter } = value;
+  const list = Array.isArray(requirements) && requirements.every((item) => typeof item === "string" && item.trim());
+  if (!list && !(typeof requirements === "string" && requirements.trim())) {
+    throw new Error("cascade.json python.requirements must be a list of pip requirements or a project-relative requirements file");
+  }
+  if (typeof requirements === "string") containedPath(root, requirements, "python.requirements");
+  if (interpreter !== void 0 && (typeof interpreter !== "string" || !/^[A-Za-z0-9._/-]+$/.test(interpreter))) {
+    throw new Error("cascade.json python.interpreter must be an executable name such as python3.12");
+  }
+  return { requirements, interpreter: interpreter ?? "python3" };
+}
+function pythonEnvKey(root, spec) {
+  const requirements = typeof spec.requirements === "string" ? `file ${spec.requirements}
+${fs.readFileSync(containedPath(root, spec.requirements, "python.requirements"), "utf8")}` : `list
+${spec.requirements.join("\n")}`;
+  return crypto.createHash("sha256").update(`${spec.interpreter}\0${requirements}`).digest("hex");
+}
+function pythonEnvStatus(root) {
+  const directory = pythonEnvDirectory(root);
+  const python = pythonEnvInterpreter(root);
+  const spec = readPythonEnv(root);
+  if (!spec) return { declared: false, directory, python, state: "none" };
+  if (!fs.existsSync(python)) return { declared: true, directory, python, state: "missing", reason: `no environment at ${path.relative(root, directory)}` };
+  let marker = {};
+  try {
+    marker = JSON.parse(fs.readFileSync(path.join(directory, MARKER), "utf8"));
+  } catch {
+  }
+  let key;
+  try {
+    key = pythonEnvKey(root, spec);
+  } catch (error) {
+    return { declared: true, directory, python, state: "stale", reason: error instanceof Error ? error.message : String(error) };
+  }
+  if (marker.key !== key) return { declared: true, directory, python, state: "stale", reason: "cascade.json python changed since the environment was built" };
+  return { declared: true, directory, python, state: "current" };
+}
+async function provisionPythonEnv(root, log = () => {
+}) {
+  const spec = readPythonEnv(root);
+  if (!spec) throw new Error('cascade.json declares no python environment ("python": { "requirements": [...] })');
+  const before = pythonEnvStatus(root);
+  if (before.state === "current") return before;
+  const directory = pythonEnvDirectory(root);
+  if (fs.existsSync(directory)) {
+    const archive = path.join(path.dirname(directory), "_archive");
+    fs.mkdirSync(archive, { recursive: true });
+    fs.renameSync(directory, path.join(archive, `venv-${Date.now()}`));
+  }
+  fs.mkdirSync(path.dirname(directory), { recursive: true });
+  const file = typeof spec.requirements === "string" ? containedPath(root, spec.requirements, "python.requirements") : void 0;
+  const fileHasRequirements = file !== void 0 && fs.readFileSync(file, "utf8").split("\n").some((line) => line.trim() && !line.trim().startsWith("#"));
+  const requirements = file !== void 0 ? fileHasRequirements ? ["-r", file] : [] : [...spec.requirements];
+  log(`Creating ${path.relative(root, directory)} with ${spec.interpreter}`);
+  await run(spec.interpreter, ["-m", "venv", ...requirements.length ? [] : ["--without-pip"], directory], root);
+  if (requirements.length) {
+    log(`Installing ${typeof spec.requirements === "string" ? spec.requirements : spec.requirements.join(", ")}`);
+    await run(pythonEnvInterpreter(root), ["-m", "pip", "install", "--disable-pip-version-check", "--quiet", ...requirements], root);
+  }
+  fs.writeFileSync(path.join(directory, MARKER), `${JSON.stringify({ key: pythonEnvKey(root, spec), requirements: spec.requirements, interpreter: spec.interpreter, builtAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2)}
+`);
+  return pythonEnvStatus(root);
+}
+function declaredStagePython(root) {
+  const status = pythonEnvStatus(root);
+  if (status.state === "none") return void 0;
+  if (status.state !== "current") {
+    throw new Error(`This project declares a Python environment (cascade.json "python") that is ${status.state}: ${status.reason}. Run \`cascade doctor --fix\` in ${root} to build it.`);
+  }
+  return status.python;
+}
+function containedPath(root, file, name) {
+  const resolved = path.resolve(root, file);
+  const relative = path.relative(root, resolved);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`cascade.json ${name} must be a project-relative path`);
+  return resolved;
+}
+function run(command, args, cwd) {
+  return new Promise((resolve, reject) => {
+    execFile(command, [...args], { cwd, maxBuffer: 16 * 1024 * 1024, timeout: 20 * 6e4 }, (error, _stdout, stderr) => {
+      if (error) reject(new Error(`${path.basename(command)} ${args.slice(0, 3).join(" ")} failed: ${(stderr || error.message).trim().slice(-2e3)}`));
+      else resolve();
+    });
+  });
+}
+
+export {
+  pythonEnvStatus,
+  provisionPythonEnv,
+  declaredStagePython
+};
+//# sourceMappingURL=chunk-WD62JIP6.js.map