@field/cascade 0.10.0 → 0.12.0

package/dist/cli/chunk-2JEU3MGB.js

@@ -0,0 +1,1125 @@
+import {
+  validateNodeDefinition
+} from "./chunk-NJFMDXHR.js";
+
+// server/src/project.ts
+import fs5 from "fs/promises";
+import fssync from "fs";
+import path5 from "path";
+
+// server/src/pathSafety.ts
+import path from "path";
+import fs from "node:fs";
+var PathSafetyError = class extends Error {
+};
+function resolveWithinRoot(root, ...segments) {
+  for (const seg of segments) {
+    if (path.isAbsolute(seg)) {
+      throw new PathSafetyError(`absolute path segment not allowed: ${seg}`);
+    }
+  }
+  const full = path.resolve(root, ...segments);
+  const rel = path.relative(root, full);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new PathSafetyError(`path escapes root: ${segments.join("/")}`);
+  }
+  const canonicalRoot = canonical(root, `project root is not accessible: ${root}`);
+  let existing = full;
+  while (!existsIncludingSymlink(existing)) {
+    const parent = path.dirname(existing);
+    if (parent === existing) {
+      throw new PathSafetyError(`path has no accessible parent: ${segments.join("/")}`);
+    }
+    existing = parent;
+  }
+  const canonicalExisting = canonical(existing, `path is not accessible: ${segments.join("/")}`);
+  const canonicalRel = path.relative(canonicalRoot, canonicalExisting);
+  if (canonicalRel.startsWith("..") || path.isAbsolute(canonicalRel)) {
+    throw new PathSafetyError(`path escapes root through a symbolic link: ${segments.join("/")}`);
+  }
+  return full;
+}
+function existsIncludingSymlink(candidate) {
+  try {
+    fs.lstatSync(candidate);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+function canonical(candidate, message) {
+  try {
+    return fs.realpathSync(candidate);
+  } catch {
+    throw new PathSafetyError(message);
+  }
+}
+
+// server/src/shell/service.ts
+import fs4 from "node:fs";
+import os2 from "node:os";
+import path4 from "node:path";
+import { execFile, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+
+// server/src/credentials.ts
+import fs2 from "node:fs";
+import os from "node:os";
+import path2 from "node:path";
+var CredentialStore = class {
+  constructor(file = process.env.CASCADE_CREDENTIALS || path2.join(os.homedir(), ".cascade", "credentials.yaml")) {
+    this.file = file;
+  }
+  has(name) {
+    const definition = this.read().get(name);
+    return !!definition && Object.keys(definition.fields).length > 0;
+  }
+  get(name) {
+    return this.read().get(name) ?? null;
+  }
+  environment(names) {
+    const definitions = this.read();
+    const env = {};
+    for (const name of names) {
+      const definition = definitions.get(name);
+      if (!definition) continue;
+      const normalizedName = envName(name);
+      for (const [field, value] of Object.entries(definition.fields)) {
+        env[`CASCADE_CREDENTIAL_${normalizedName}_${envName(field)}`] = value;
+      }
+      const secret = secretValue(definition);
+      if (secret) env[safeEnvName(definition.env) ?? `CASCADE_CREDENTIAL_${normalizedName}`] = secret;
+    }
+    return env;
+  }
+  read() {
+    let source;
+    try {
+      source = fs2.readFileSync(this.file, "utf8");
+    } catch (error) {
+      if (error.code === "ENOENT") return /* @__PURE__ */ new Map();
+      throw error;
+    }
+    return parseCredentials(source);
+  }
+};
+function secretValue(definition) {
+  const key = definition.field;
+  if (key && definition.fields[key]) return definition.fields[key];
+  for (const candidate of ["value", "api_key", "apiKey", "access_token", "token", "key"]) {
+    if (definition.fields[candidate]) return definition.fields[candidate];
+  }
+  return null;
+}
+function parseCredentials(source) {
+  const json = source.trim().startsWith("{") ? JSON.parse(source) : null;
+  const raw = json && typeof json === "object" ? json : parseSimpleYaml(source);
+  const result = /* @__PURE__ */ new Map();
+  for (const [name, value] of Object.entries(raw)) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(name) || !value || typeof value !== "object" || Array.isArray(value)) continue;
+    const record = value;
+    const fields = Object.fromEntries(Object.entries(record).filter(([key, item]) => typeof item === "string" && !["header", "scheme", "field", "env"].includes(key)));
+    const hosts = Array.isArray(record.hosts) ? record.hosts.filter((item) => typeof item === "string").map(normalizeHost).filter(Boolean) : [];
+    result.set(name, Object.freeze({
+      name,
+      fields: Object.freeze(fields),
+      hosts: Object.freeze(hosts),
+      ...typeof record.header === "string" ? { header: record.header } : {},
+      ...typeof record.scheme === "string" ? { scheme: record.scheme } : {},
+      ...typeof record.field === "string" ? { field: record.field } : {},
+      ...typeof record.env === "string" ? { env: record.env } : {}
+    }));
+  }
+  return result;
+}
+function parseSimpleYaml(source) {
+  const result = {};
+  let current = null;
+  for (const rawLine of source.split(/\r?\n/)) {
+    const line = rawLine.replace(/\s+#.*$/, "");
+    if (!line.trim()) continue;
+    const top = line.match(/^([A-Za-z0-9][A-Za-z0-9._-]*):\s*$/);
+    if (top) {
+      current = {};
+      result[top[1]] = current;
+      continue;
+    }
+    const field = line.match(/^\s{2,}([A-Za-z0-9_-]+):\s*(.*?)\s*$/);
+    if (!current || !field) throw new Error(`Unsupported credentials.yaml syntax near ${JSON.stringify(rawLine)}`);
+    const value = unquote(field[2]);
+    current[field[1]] = value.startsWith("[") && value.endsWith("]") ? value.slice(1, -1).split(",").map((item) => unquote(item.trim())).filter(Boolean) : value;
+  }
+  return result;
+}
+function unquote(value) {
+  if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1);
+  return value;
+}
+function normalizeHost(value) {
+  try {
+    return value.includes("://") ? new URL(value).hostname.toLowerCase() : value.toLowerCase();
+  } catch {
+    return "";
+  }
+}
+function envName(value) {
+  return value.replace(/[^A-Za-z0-9]/g, "_").toUpperCase();
+}
+function safeEnvName(value) {
+  return value && /^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(value) && !/^(?:PATH|NODE_OPTIONS|PYTHONPATH|LD_.*|DYLD_.*)$/i.test(value) ? value : null;
+}
+
+// server/src/projectConfig.ts
+import fs3 from "node:fs";
+import path3 from "node:path";
+var CREDENTIAL_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+var SECRET_KEY = /^(?:api[_-]?key|apiKey|secret|password|access[_-]?token|refresh[_-]?token|credential|credentials)$/i;
+function readProjectManifest(root) {
+  const raw = readRaw(root);
+  return normalizeManifest(raw);
+}
+function writeProjectManifest(root, input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("project manifest must be an object");
+  const value = input;
+  const current = readRaw(root);
+  const next = {
+    ...current,
+    name: typeof value.name === "string" ? value.name.trim() : "",
+    commands: stringRecord(value.commands, "commands"),
+    credentials: credentialNames(value.credentials),
+    settings: settingsRecord(value.settings)
+  };
+  fs3.writeFileSync(path3.join(root, "cascade.json"), `${JSON.stringify(next, null, 2)}
+`, "utf8");
+  return normalizeManifest(next);
+}
+function readRaw(root) {
+  try {
+    const value = JSON.parse(fs3.readFileSync(path3.join(root, "cascade.json"), "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("root must be an object");
+    return value;
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw new Error(`Cannot read cascade.json: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+function normalizeManifest(raw) {
+  return Object.freeze({
+    name: typeof raw.name === "string" ? raw.name : "",
+    commands: Object.freeze(stringRecord(raw.commands, "commands")),
+    credentials: Object.freeze(credentialNames(raw.credentials)),
+    settings: Object.freeze(settingsRecord(raw.settings))
+  });
+}
+function stringRecord(input, label) {
+  if (input === void 0) return {};
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error(`${label} must be an object of strings`);
+  const entries = Object.entries(input);
+  if (entries.some(([key, value]) => !CREDENTIAL_NAME.test(key) || typeof value !== "string" || value.includes("\0"))) {
+    throw new Error(`${label} must contain safe names and string values`);
+  }
+  return Object.fromEntries(entries);
+}
+function credentialNames(input) {
+  if (input === void 0) return [];
+  if (!Array.isArray(input) || input.some((name) => typeof name !== "string" || !CREDENTIAL_NAME.test(name))) {
+    throw new Error("credentials must be an array of safe names");
+  }
+  return [...new Set(input)];
+}
+function settingsRecord(input) {
+  if (input === void 0) return {};
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("settings must be an object");
+  assertSafeSettings(input, 0);
+  return structuredClone(input);
+}
+function assertSafeSettings(value, depth) {
+  if (depth > 12) throw new Error("settings nesting is too deep");
+  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) return;
+  if (Array.isArray(value)) return value.forEach((item) => assertSafeSettings(item, depth + 1));
+  if (!value || typeof value !== "object") throw new Error("settings must contain JSON values");
+  for (const [key, item] of Object.entries(value)) {
+    if (key === "__proto__" || key === "constructor" || key === "prototype" || SECRET_KEY.test(key)) {
+      throw new Error(`settings key ${JSON.stringify(key)} looks secret or unsafe; credentials belong outside the project`);
+    }
+    assertSafeSettings(item, depth + 1);
+  }
+}
+
+// server/src/shell/types.ts
+var ShellProcessError = class extends Error {
+  constructor(kind, result, message) {
+    super(message ?? `Shell process failed: ${kind}`);
+    this.kind = kind;
+    this.result = result;
+    this.name = "ShellProcessError";
+  }
+};
+var ShellRequestError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+};
+
+// server/src/shell/service.ts
+var MAX_BUFFER = 64 * 1024 * 1024;
+var MAX_ARGS = 4096;
+var MAX_ARG_BYTES = 1024 * 1024;
+var MAX_STDIN_BYTES = 16 * 1024 * 1024;
+var MAX_ENV_BYTES = 1024 * 1024;
+var MAX_ENV_KEYS = 128;
+var ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+var ALIAS = /^[A-Za-z0-9._-]+$/;
+var BLOCKED_ENV = /^(?:PATH|NODE_OPTIONS|PYTHONPATH|RUBYOPT|PERL5OPT|BASH_ENV|ENV|SHELLOPTS|IFS|CDPATH|GLOBIGNORE|LD_.*|DYLD_.*)$/i;
+var ShellService = class {
+  constructor(project) {
+    this.project = project;
+    this.executables = /* @__PURE__ */ new Map();
+    this.auditSink = (record) => console.info("[cascade-shell]", JSON.stringify(record));
+    this.config = loadConfig(project.root);
+    this.configRevision = readConfigRevision(project.root);
+    for (const [alias, target] of Object.entries(this.config.commands)) {
+      if (!ALIAS.test(alias)) {
+        console.warn(`[cascade-shell] ignoring invalid command alias ${JSON.stringify(alias)}`);
+        continue;
+      }
+      const executable = resolveExecutable(project.root, target);
+      this.executables.set(alias, executable);
+      if (!executable) console.warn(`[cascade-shell] command ${JSON.stringify(alias)} could not be resolved`);
+    }
+  }
+  setAuditSink(sink) {
+    this.auditSink = sink;
+  }
+  async run(command, args = [], options = {}) {
+    const started = Date.now();
+    const id = randomUUID();
+    let cwd = ".";
+    let result = emptyResult();
+    let errorKind;
+    try {
+      this.reloadConfig();
+      const executable = this.resolveCommand(command);
+      const validated = this.validate(args, options);
+      cwd = validated.relativeCwd;
+      result = await execute(executable, validated.args, {
+        cwd: validated.cwd,
+        timeout: validated.timeout,
+        stdin: validated.stdin,
+        env: validated.env,
+        signal: options.signal
+      });
+      return result;
+    } catch (error) {
+      if (error instanceof ShellProcessError) {
+        result = error.result;
+        errorKind = error.kind;
+      } else if (error instanceof ShellRequestError) {
+        errorKind = error.code;
+      }
+      throw error;
+    } finally {
+      this.auditSink({
+        id,
+        command,
+        cwd,
+        durationMs: Date.now() - started,
+        code: result.code,
+        errorKind,
+        timedOut: result.timedOut,
+        cancelled: result.cancelled,
+        outputLimited: result.outputLimited
+      });
+    }
+  }
+  reloadConfig() {
+    const revision = readConfigRevision(this.project.root);
+    if (revision === this.configRevision) return;
+    this.config = loadConfig(this.project.root);
+    this.configRevision = revision;
+    this.executables.clear();
+    for (const [alias, target] of Object.entries(this.config.commands)) {
+      if (!ALIAS.test(alias)) continue;
+      this.executables.set(alias, resolveExecutable(this.project.root, target));
+    }
+  }
+  async runJson(command, args = [], options = {}) {
+    const result = await this.run(command, args, options);
+    if (result.code !== 0) throw new ShellProcessError("nonzero", result, result.stderr || `Command exited with code ${result.code}`);
+    const lines = result.stdout.split(/\r?\n/).filter((value) => value.trim());
+    const line = lines[lines.length - 1] ?? "";
+    try {
+      return JSON.parse(line);
+    } catch {
+      throw new ShellProcessError("invalid-json", result, "Command output was not valid JSON");
+    }
+  }
+  resolveCommand(command) {
+    if (!ALIAS.test(command)) throw new ShellRequestError("INVALID_REQUEST", "command must be an allowlist alias");
+    if (!this.executables.has(command)) {
+      throw new ShellRequestError(
+        "COMMAND_NOT_ALLOWED",
+        `Command "${command}" is not allowed. Add this under "commands" in ${this.project.root}/cascade.json: "${command}": "<path>"`
+      );
+    }
+    const executable = this.executables.get(command);
+    if (!executable) throw new ShellRequestError("MISSING_EXECUTABLE", `Configured command "${command}" is not available`);
+    return executable;
+  }
+  validate(args, options) {
+    if (!Array.isArray(args) || args.length > MAX_ARGS || args.some((arg) => typeof arg !== "string" || Buffer.byteLength(arg) > MAX_ARG_BYTES || arg.includes("\0"))) {
+      throw new ShellRequestError("INVALID_REQUEST", "args must be an array of bounded strings");
+    }
+    if (options.stdin !== void 0 && (typeof options.stdin !== "string" || Buffer.byteLength(options.stdin) > MAX_STDIN_BYTES || options.stdin.includes("\0"))) {
+      throw new ShellRequestError("INVALID_REQUEST", "stdin exceeds the 16 MiB limit or is invalid");
+    }
+    const { cwd, relativeCwd } = resolveCwd(this.project.root, options.cwd ?? ".");
+    const requestEnv = options.env ?? {};
+    const entries = Object.entries(requestEnv);
+    if (entries.length > MAX_ENV_KEYS || entries.reduce((sum, [key, value]) => sum + Buffer.byteLength(key) + Buffer.byteLength(String(value)), 0) > MAX_ENV_BYTES) {
+      throw new ShellRequestError("INVALID_REQUEST", "request environment exceeds its limit");
+    }
+    for (const [key, value] of entries) {
+      if (!ENV_NAME.test(key) || typeof value !== "string" || value.length > 65536 || value.includes("\0") || BLOCKED_ENV.test(key) || !this.config.shell.allowedRequestEnv.has(key)) {
+        throw new ShellRequestError("INVALID_REQUEST", `request environment variable ${JSON.stringify(key)} is not allowed`);
+      }
+    }
+    if (options.timeout !== void 0 && (typeof options.timeout !== "number" || !Number.isFinite(options.timeout))) {
+      throw new ShellRequestError("INVALID_REQUEST", "timeout must be a finite number");
+    }
+    const timeout = Math.min(6e5, Math.max(1, Math.trunc(options.timeout ?? this.config.shell.timeout)));
+    const credentialEnv = new CredentialStore().environment(readProjectManifest(this.project.root).credentials);
+    return {
+      args: [...args],
+      cwd,
+      relativeCwd,
+      timeout,
+      stdin: options.stdin,
+      env: { ...process.env, ...this.config.shell.env, ...requestEnv, ...credentialEnv }
+    };
+  }
+};
+function readConfigRevision(root) {
+  try {
+    return fs4.readFileSync(path4.join(root, "cascade.json"), "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return "";
+    throw error;
+  }
+}
+function loadConfig(root) {
+  let raw = {};
+  try {
+    raw = JSON.parse(fs4.readFileSync(path4.join(root, "cascade.json"), "utf8"));
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  return {
+    commands: raw?.commands && typeof raw.commands === "object" ? raw.commands : {},
+    shell: {
+      timeout: Number.isFinite(raw?.shell?.timeout) ? Math.min(6e5, Math.max(1, Math.trunc(raw.shell.timeout))) : 12e4,
+      env: stringRecord2(raw?.shell?.env),
+      allowedRequestEnv: new Set(Array.isArray(raw?.shell?.allowedRequestEnv) ? raw.shell.allowedRequestEnv.filter((v) => typeof v === "string") : [])
+    }
+  };
+}
+function stringRecord2(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  return Object.fromEntries(Object.entries(value).filter(([key, item]) => ENV_NAME.test(key) && !BLOCKED_ENV.test(key) && typeof item === "string" && item.length <= 65536 && !item.includes("\0")));
+}
+function resolveExecutable(root, target) {
+  if (typeof target !== "string" || !target || target.includes("\0")) return null;
+  const expanded = target.replace(/^~(?=\/|$)/, os2.homedir());
+  if (!path4.isAbsolute(expanded) && !/[\\/]/.test(expanded)) {
+    for (const dir of (process.env.PATH ?? "").split(path4.delimiter)) {
+      const found = executableFile(path4.join(dir, expanded));
+      if (found) return found;
+    }
+    return null;
+  }
+  const candidate = path4.isAbsolute(expanded) ? expanded : path4.resolve(root, expanded);
+  if (!path4.isAbsolute(expanded) && !within(fs4.realpathSync(root), safeRealpath(candidate))) return null;
+  return executableFile(candidate);
+}
+function executableFile(candidate) {
+  try {
+    fs4.accessSync(candidate, fs4.constants.X_OK);
+    return fs4.statSync(candidate).isFile() ? fs4.realpathSync(candidate) : null;
+  } catch {
+    return null;
+  }
+}
+function safeRealpath(candidate) {
+  try {
+    return fs4.realpathSync(candidate);
+  } catch {
+    return candidate;
+  }
+}
+function resolveCwd(root, requested) {
+  if (typeof requested !== "string" || path4.isAbsolute(requested) || requested.includes("\0")) throw new ShellRequestError("INVALID_REQUEST", "cwd must be project-relative");
+  const lexical = path4.resolve(root, requested);
+  if (!within(root, lexical)) throw new ShellRequestError("INVALID_REQUEST", "cwd escapes project root");
+  let real;
+  try {
+    real = fs4.realpathSync(lexical);
+  } catch {
+    throw new ShellRequestError("INVALID_REQUEST", "cwd does not exist");
+  }
+  const realRoot = fs4.realpathSync(root);
+  if (!within(realRoot, real)) throw new ShellRequestError("INVALID_REQUEST", "cwd escapes project root through a symlink");
+  return { cwd: real, relativeCwd: path4.relative(realRoot, real) || "." };
+}
+function within(root, candidate) {
+  const relative = path4.relative(root, candidate);
+  return relative === "" || !relative.startsWith("..") && !path4.isAbsolute(relative);
+}
+function emptyResult() {
+  return { stdout: "", stderr: "", code: null, timedOut: false, cancelled: false, outputLimited: false };
+}
+function execute(executable, args, options) {
+  return new Promise((resolve, reject) => {
+    let terminal = null;
+    let spawnError;
+    let termination;
+    const stdout = [];
+    const stderr = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    const child = spawn(executable, args, {
+      cwd: options.cwd,
+      env: options.env,
+      detached: process.platform !== "win32",
+      shell: false,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    const finishCause = (cause) => {
+      if (terminal) return;
+      terminal = cause;
+      if (cause === "timeout" || cause === "cancelled" || cause === "output-limit") termination = terminateTree(child);
+    };
+    const timer = setTimeout(() => finishCause("timeout"), options.timeout);
+    const abort = () => finishCause("cancelled");
+    options.signal?.addEventListener("abort", abort, { once: true });
+    child.stdout.on("data", (chunk) => {
+      stdoutBytes += chunk.length;
+      if (stdoutBytes <= MAX_BUFFER) stdout.push(chunk);
+      else finishCause("output-limit");
+    });
+    child.stderr.on("data", (chunk) => {
+      stderrBytes += chunk.length;
+      if (stderrBytes <= MAX_BUFFER) stderr.push(chunk);
+      else finishCause("output-limit");
+    });
+    child.once("error", (error) => {
+      spawnError = error;
+      finishCause("spawn");
+    });
+    child.once("exit", (code, signal) => finishCause(code === null || signal ? "signal" : "exit"));
+    child.once("close", async (code, signal) => {
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", abort);
+      await termination?.beforeSettle();
+      const output = { stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8") };
+      if (terminal === "timeout" || terminal === "cancelled" || terminal === "output-limit") {
+        const result = { ...output, code: null, timedOut: terminal === "timeout", cancelled: terminal === "cancelled", outputLimited: terminal === "output-limit" };
+        reject(new ShellProcessError(terminal, result));
+      } else if (terminal === "spawn" || terminal === "signal" || spawnError || code === null || signal) {
+        const reason = spawnError ? "Unable to spawn configured command" : `Command terminated by signal ${signal ?? "unknown"}`;
+        reject(new ShellProcessError("spawn", { ...emptyResult(), ...output }, reason));
+      } else {
+        resolve({ ...output, code, timedOut: false, cancelled: false, outputLimited: false });
+      }
+    });
+    if (options.stdin !== void 0) child.stdin.end(options.stdin);
+    else child.stdin.end();
+    if (options.signal?.aborted) abort();
+  });
+}
+function terminateTree(child) {
+  if (!child.pid) return { beforeSettle: async () => void 0 };
+  if (process.platform === "win32") {
+    const taskkill = new Promise((resolve) => {
+      execFile("taskkill.exe", ["/PID", String(child.pid), "/T", "/F"], () => resolve());
+    });
+    return { beforeSettle: () => taskkill };
+  }
+  try {
+    process.kill(-child.pid, "SIGTERM");
+  } catch {
+    child.kill("SIGTERM");
+  }
+  const killTimer = setTimeout(() => {
+    forceKillTree(child);
+  }, 2e3);
+  killTimer.unref();
+  return {
+    beforeSettle: async () => {
+      clearTimeout(killTimer);
+      forceKillTree(child);
+    }
+  };
+}
+function forceKillTree(child) {
+  if (!child.pid) return;
+  if (process.platform === "win32") return;
+  try {
+    process.kill(-child.pid, "SIGKILL");
+  } catch {
+    child.kill("SIGKILL");
+  }
+}
+
+// server/src/project.ts
+import * as ts from "typescript";
+
+// packages/runtime/src/definition/extract.ts
+var MAX_DEPTH = 32;
+var MAX_NODES = 1e4;
+function extractNodeDefinition(source, fileName, ts2) {
+  const file = ts2.createSourceFile(
+    fileName,
+    source,
+    ts2.ScriptTarget.Latest,
+    true,
+    ts2.ScriptKind.TS
+  );
+  const syntaxDiagnostics = file.parseDiagnostics;
+  if (syntaxDiagnostics?.length) {
+    const syntax = syntaxDiagnostics[0];
+    const start = syntax.start ?? 0;
+    const point = file.getLineAndCharacterOfPosition(start);
+    return {
+      ok: false,
+      diagnostics: [
+        {
+          phase: "definition",
+          code: "definition/syntax",
+          message: ts2.flattenDiagnosticMessageText(syntax.messageText, "\n"),
+          file: fileName,
+          line: point.line + 1,
+          column: point.character + 1
+        }
+      ]
+    };
+  }
+  const declarations = [];
+  for (const statement of file.statements) {
+    if (!ts2.isVariableStatement(statement) || !statement.modifiers?.some(
+      (modifier) => modifier.kind === ts2.SyntaxKind.ExportKeyword
+    ))
+      continue;
+    if (!(statement.declarationList.flags & ts2.NodeFlags.Const)) continue;
+    for (const declaration2 of statement.declarationList.declarations) {
+      if (ts2.isIdentifier(declaration2.name) && declaration2.name.text === "definition")
+        declarations.push(declaration2);
+    }
+  }
+  if (declarations.length !== 1)
+    return failure(
+      declarations[1] ?? declarations[0] ?? file,
+      declarations.length ? "definition/duplicate-export" : "definition/missing-export",
+      declarations.length ? "Exactly one definition export is allowed" : "Missing exported const definition"
+    );
+  const declaration = declarations[0];
+  const initializer = declaration.initializer;
+  if (!initializer)
+    return failure(
+      declaration,
+      "definition/non-literal",
+      "definition requires a literal initializer"
+    );
+  let visited = 0;
+  try {
+    const definition = read(initializer, "$", 0);
+    const diagnostics = validateNodeDefinition(definition).map((item) => ({
+      ...item,
+      file: fileName,
+      ...location(initializer)
+    }));
+    return diagnostics.length ? { ok: false, diagnostics } : { ok: true, definition, diagnostics: [] };
+  } catch (error) {
+    return {
+      ok: false,
+      diagnostics: [error.diagnostic]
+    };
+  }
+  function read(node, path6, depth) {
+    if (++visited > MAX_NODES)
+      throw extraction(
+        node,
+        "definition/size-limit",
+        "Definition exceeds 10,000 syntax nodes",
+        path6
+      );
+    if (depth > MAX_DEPTH)
+      throw extraction(
+        node,
+        "definition/depth-limit",
+        "Definition exceeds 32 levels",
+        path6
+      );
+    if (ts2.isParenthesizedExpression(node) || ts2.isSatisfiesExpression(node))
+      return read(node.expression, path6, depth + 1);
+    if (ts2.isAsExpression(node)) {
+      if (node.type.getText(file) !== "const")
+        throw extraction(
+          node.type,
+          "definition/non-literal",
+          "Only 'as const' assertions are allowed",
+          path6
+        );
+      return read(node.expression, path6, depth + 1);
+    }
+    if (ts2.isStringLiteral(node) || ts2.isNoSubstitutionTemplateLiteral(node))
+      return node.text;
+    if (ts2.isNumericLiteral(node)) return Number(node.text);
+    if (node.kind === ts2.SyntaxKind.TrueKeyword) return true;
+    if (node.kind === ts2.SyntaxKind.FalseKeyword) return false;
+    if (node.kind === ts2.SyntaxKind.NullKeyword) return null;
+    if (ts2.isPrefixUnaryExpression(node) && node.operator === ts2.SyntaxKind.MinusToken && ts2.isNumericLiteral(node.operand))
+      return -Number(node.operand.text);
+    if (ts2.isArrayLiteralExpression(node))
+      return node.elements.map((element, index) => {
+        if (ts2.isSpreadElement(element))
+          throw extraction(
+            element,
+            "definition/spread",
+            "Spreads are not allowed",
+            `${path6}.${index}`
+          );
+        return read(element, `${path6}.${index}`, depth + 1);
+      });
+    if (ts2.isObjectLiteralExpression(node)) {
+      const object = /* @__PURE__ */ Object.create(null);
+      const keys = /* @__PURE__ */ new Set();
+      for (const property of node.properties) {
+        if (ts2.isSpreadAssignment(property))
+          throw extraction(
+            property,
+            "definition/spread",
+            "Spreads are not allowed",
+            path6
+          );
+        if (!ts2.isPropertyAssignment(property) || property.name && ts2.isComputedPropertyName(property.name))
+          throw extraction(
+            property,
+            "definition/non-literal",
+            "Only explicit properties are allowed",
+            path6
+          );
+        const key = ts2.isIdentifier(property.name) || ts2.isStringLiteral(property.name) || ts2.isNumericLiteral(property.name) ? property.name.text : void 0;
+        if (key === void 0)
+          throw extraction(
+            property,
+            "definition/non-literal",
+            "Property name must be literal",
+            path6
+          );
+        if (keys.has(key))
+          throw extraction(
+            property.name,
+            "definition/duplicate-key",
+            `Duplicate key ${key}`,
+            `${path6}.${key}`
+          );
+        keys.add(key);
+        object[key] = read(property.initializer, `${path6}.${key}`, depth + 1);
+      }
+      return object;
+    }
+    throw extraction(
+      node,
+      "definition/non-literal",
+      `Unsupported ${ts2.SyntaxKind[node.kind]}`,
+      path6
+    );
+  }
+  function location(node) {
+    const point = file.getLineAndCharacterOfPosition(node.getStart(file));
+    return { line: point.line + 1, column: point.character + 1 };
+  }
+  function extraction(node, code, message, path6) {
+    return new ExtractionFailure({
+      phase: "definition",
+      code,
+      message,
+      path: path6,
+      file: fileName,
+      ...location(node)
+    });
+  }
+  function failure(node, code, message) {
+    return {
+      ok: false,
+      diagnostics: [extraction(node, code, message).diagnostic]
+    };
+  }
+}
+var ExtractionFailure = class extends Error {
+  constructor(diagnostic) {
+    super(diagnostic.message);
+    this.diagnostic = diagnostic;
+  }
+};
+
+// server/src/project.ts
+var BROWSER_ONLY_IDENTIFIERS = /* @__PURE__ */ new Set([
+  "document",
+  "window",
+  "navigator",
+  "localStorage",
+  "sessionStorage",
+  "HTMLCanvasElement",
+  "HTMLImageElement",
+  "HTMLElement",
+  "WebGLRenderingContext",
+  "WebGL2RenderingContext",
+  "requestAnimationFrame"
+]);
+function usesBrowserOnlyApi(source, fileName) {
+  const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  let found = false;
+  const visit = (node) => {
+    if (found) return;
+    if (ts.isIdentifier(node) && BROWSER_ONLY_IDENTIFIERS.has(node.text)) {
+      const parent = node.parent;
+      const isPropertyName = ts.isPropertyAccessExpression(parent) && parent.name === node || ts.isPropertyAssignment(parent) && parent.name === node || ts.isPropertyDeclaration(parent) && parent.name === node || ts.isMethodDeclaration(parent) && parent.name === node;
+      if (!isPropertyName) {
+        found = true;
+        return;
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(file);
+  return found;
+}
+var ProjectRoot = class _ProjectRoot {
+  constructor(root, explicitGraph = null) {
+    this.root = path5.resolve(root);
+    if (!fssync.existsSync(this.root) || !fssync.statSync(this.root).isDirectory()) {
+      throw new Error(`Project root does not exist or is not a directory: ${this.root}`);
+    }
+    this.explicitGraph = explicitGraph;
+    this.shell = new ShellService(this);
+  }
+  /** The graph the client should open on startup, or null when there is
+   * nothing obvious to open. Order: the file named on the command line,
+   * then `index.cascade` by convention, then the sole `.cascade` file if
+   * there is exactly one. With several files and no `index.cascade` this
+   * returns null rather than guessing — the app opens empty and File >
+   * Open picks. */
+  async resolveDefaultGraph() {
+    if (this.explicitGraph) return this.explicitGraph;
+    const graphs = await this.listGraphFiles();
+    if (graphs.includes("index.cascade")) return "index.cascade";
+    if (graphs.length === 1) return graphs[0];
+    return null;
+  }
+  /** Split a `cascade <arg>` argument into a root directory and, when the
+   * argument named a `.cascade` file, the graph inside it. */
+  static fromArg(arg) {
+    const resolved = path5.resolve(arg);
+    const isFile = fssync.existsSync(resolved) && fssync.statSync(resolved).isFile();
+    if (isFile || resolved.endsWith(".cascade")) {
+      if (!resolved.endsWith(".cascade")) {
+        throw new Error(`Not a .cascade file: ${resolved}`);
+      }
+      if (!isFile) {
+        throw new Error(`Graph file does not exist: ${resolved}`);
+      }
+      return new _ProjectRoot(path5.dirname(resolved), path5.basename(resolved));
+    }
+    return new _ProjectRoot(resolved);
+  }
+  resolve(relativePath = "") {
+    return resolveWithinRoot(this.root, relativePath);
+  }
+  /** Resolve browser-readable project media. `shared/` is the one intentional
+   * external root: projects use it for reusable nodes, panels, and cached source
+   * assets. Its canonical target remains independently confined, while every
+   * other symlink escape is rejected by resolve(). */
+  resolveMedia(relativePath) {
+    const normalized = relativePath.split("\\").join("/");
+    if (normalized === "shared" || normalized.startsWith("shared/")) {
+      return this.resolveShared(...normalized.split("/").slice(1));
+    }
+    return this.resolve(relativePath);
+  }
+  /**
+   * Whether this project is under version control, walking **up** rather than
+   * looking only at the root.
+   *
+   * It checked `<root>/.git` alone, which is right for a sketch that is its own
+   * repository and wrong for one inside a repository of sketches — every
+   * example in `cascade-sketches` reported *"not a git repo yet"* while sitting
+   * in a perfectly good repo. Found 2026-09-09 by an agent that mentioned it in
+   * passing while launching a server, which is the sort of aside worth reading.
+   *
+   * A worktree's `.git` is a file rather than a directory, so the test is
+   * existence and not `isDirectory()`. And the walk stops at the filesystem
+   * root, where `dirname` stops changing — a `while (true)` on `dirname` is an
+   * infinite loop on any path that never contains one.
+   */
+  get isGitRepo() {
+    let directory = this.root;
+    for (; ; ) {
+      if (fssync.existsSync(path5.join(directory, ".git"))) return true;
+      const parent = path5.dirname(directory);
+      if (parent === directory) return false;
+      directory = parent;
+    }
+  }
+  /** Sorted graph filenames directly in the project root. The caller chooses
+   * the active document when a project contains several graphs. */
+  async listGraphFiles() {
+    const entries = await fs5.readdir(this.root, { withFileTypes: true });
+    return entries.filter((e) => e.isFile() && e.name.endsWith(".cascade")).map((e) => e.name).sort();
+  }
+  async readGraph(filename) {
+    const full = this.resolve(filename);
+    if (!filename.endsWith(".cascade")) {
+      throw new PathSafetyError(`not a .cascade file: ${filename}`);
+    }
+    return fs5.readFile(full, "utf-8");
+  }
+  async writeGraph(filename, content) {
+    const full = this.resolve(filename);
+    if (!filename.endsWith(".cascade")) {
+      throw new PathSafetyError(`not a .cascade file: ${filename}`);
+    }
+    await fs5.writeFile(full, content, "utf-8");
+  }
+  /** `nodes/<moduleName>/` folders — one per custom node type. */
+  async listNodeModules() {
+    const nodesDir = this.resolve("nodes");
+    if (!fssync.existsSync(nodesDir)) return [];
+    const entries = await fs5.readdir(nodesDir, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name).sort();
+  }
+  /** Project-owned browser panels. A project-local panel overrides a panel
+   * with the same name provided by `shared/panels`. */
+  async listPanels() {
+    const [local, shared] = await Promise.all([
+      this.listPanelDirectory(this.resolve("panels")),
+      this.listPanelDirectory(this.resolveShared("panels"))
+    ]);
+    return [.../* @__PURE__ */ new Set([...local, ...shared])].sort();
+  }
+  /** Statically declared panel metadata. Reading this never imports or
+   * executes project code. */
+  async panelMeta(name) {
+    const source = await this.readPanelModuleFile(name);
+    const rendererTypes = exportedStringArray(source, "rendererTypes");
+    return {
+      name,
+      title: exportedString(source, "title") ?? name,
+      icon: exportedString(source, "icon"),
+      ...rendererTypes === null ? {} : { rendererTypes }
+    };
+  }
+  /** Resolve the selected panel entry, preferring the project-local version.
+   * Kept public for the compiler; callers must not use it for arbitrary files. */
+  async resolvePanelEntry(name) {
+    this.assertExtensionName(name, "panel");
+    const entries = [
+      this.resolve(path5.join("panels", name, "index.ts")),
+      this.resolveShared("panels", name, "index.ts")
+    ];
+    for (const entry of entries) {
+      try {
+        const stat = await fs5.stat(entry);
+        if (stat.isFile()) return entry;
+      } catch (err) {
+        if (err.code !== "ENOENT") throw err;
+      }
+    }
+    await fs5.access(entries[0]);
+    return entries[0];
+  }
+  /**
+   * Where a node module's work actually happens.
+   *
+   * A declaration normally wins. `cascade/shell` is the exception: it is a
+   * server-only effect, so declaring that import as browser code is rejected
+   * before compilation or loading. Otherwise the environment is inferred,
+   * distinction is already legible in the code — a node whose work happens
+   * server-side is exactly one that calls the exec bridge, since a module
+   * compiled into the browser cannot spawn a subprocess itself. That fallback
+   * is what makes every existing Python-backed node report correctly without
+   * being edited.
+   *
+   * Both kinds are peers: they exchange images as project-relative paths, which
+   * the browser reads back through /api/media.
+   * Undeclared legacy modules infer a host only from explicit host APIs;
+   * otherwise they remain portable. A literal runsOn declaration always wins.
+   */
+  async moduleRunsOn(moduleName) {
+    let source;
+    try {
+      source = await this.readNodeModuleFile(moduleName);
+    } catch {
+      return "browser";
+    }
+    const fromDefinition = this.definitionOf(moduleName, source);
+    if (fromDefinition?.runsOn) return fromDefinition.runsOn;
+    const declared = source.match(/export\s+const\s+runsOn\s*[:=][^'"`]*['"`](portable|server|browser)['"`]/);
+    const importsShell = /(?:from\s+|import\s*(?:\(\s*)?|require\s*\(\s*)['"`]cascade\/shell['"`]/.test(source);
+    if (importsShell && declared && declared[1] !== "server") {
+      throw new Error(`Node module "${moduleName}" imports cascade/shell but declares runsOn = '${declared?.[1]}'; shell nodes must run on the server`);
+    }
+    if (declared) return declared[1];
+    if (/\/api\/exec|runStage\s*(?:<[^>]*>)?\s*\(/.test(source) || importsShell) return "server";
+    return usesBrowserOnlyApi(source, `nodes/${moduleName}/index.ts`) ? "browser" : "portable";
+  }
+  /**
+   * A node module's declared icon, if it names one: `export const icon = 'Cloud'`.
+   *
+   * A project's nodes all fell back to the same cog, because the icon table is a
+   * hardcoded list of Cascade's own built-ins and knows nothing about a project.
+   * Letting a module say what it is turns a wall of identical boxes into
+   * something you can read at a glance.
+   */
+  async moduleIcon(moduleName) {
+    try {
+      const source = await this.readNodeModuleFile(moduleName);
+      return this.definitionOf(moduleName, source)?.icon ?? source.match(/export\s+const\s+icon\s*[:=][^'"`]*['"`]([A-Za-z0-9]+)['"`]/)?.[1] ?? null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * A node module's definition-v1 `definition`, read statically.
+   *
+   * Static on purpose: classification happens before compilation, so the module
+   * cannot be imported to be asked. `extractNodeDefinition` walks the AST, which
+   * is the same thing `cascade check` does, so Studio and the CLI agree.
+   * Returns null for a legacy dynamic module, which has no definition to find.
+   */
+  definitionOf(moduleName, source) {
+    try {
+      const result = extractNodeDefinition(source, `nodes/${moduleName}/index.ts`, ts);
+      return result.ok ? result.definition : null;
+    } catch {
+      return null;
+    }
+  }
+  async readPanelModuleFile(name) {
+    return fs5.readFile(await this.resolvePanelEntry(name), "utf-8");
+  }
+  async listPanelDirectory(directory) {
+    let entries;
+    try {
+      entries = await fs5.readdir(directory, { withFileTypes: true });
+    } catch (err) {
+      if (err.code === "ENOENT") return [];
+      throw err;
+    }
+    const panels = await Promise.all(entries.filter((entry) => !entry.name.startsWith(".") && (entry.isDirectory() || entry.isSymbolicLink())).map(async (entry) => {
+      try {
+        return (await fs5.stat(path5.join(directory, entry.name, "index.ts"))).isFile() ? entry.name : null;
+      } catch (err) {
+        if (err.code === "ENOENT") return null;
+        throw err;
+      }
+    }));
+    return panels.filter((name) => name !== null);
+  }
+  /** `shared/` may intentionally link to a sibling library. Its canonical
+   * target is a second confined root for shared project extensions only. */
+  resolveShared(...segments) {
+    const sharedLink = path5.join(this.root, "shared");
+    let sharedRoot = sharedLink;
+    try {
+      sharedRoot = fssync.realpathSync(sharedLink);
+    } catch (error) {
+      if (error.code === "ENOENT") return path5.join(sharedLink, ...segments);
+      throw error;
+    }
+    return resolveWithinRoot(sharedRoot, ...segments);
+  }
+  assertExtensionName(name, kind) {
+    if (!name || name === "." || name === ".." || name.startsWith(".") || name !== path5.basename(name)) {
+      throw new PathSafetyError(`invalid ${kind} name: ${name}`);
+    }
+  }
+  async readNodeModuleFile(moduleName, relativeFile = "index.ts") {
+    const full = this.resolve(path5.join("nodes", moduleName, relativeFile));
+    return fs5.readFile(full, "utf-8");
+  }
+  async writeNodeModuleFile(moduleName, relativeFile, content) {
+    const full = this.resolve(path5.join("nodes", moduleName, relativeFile));
+    await fs5.mkdir(path5.dirname(full), { recursive: true });
+    await fs5.writeFile(full, content, "utf-8");
+  }
+  async ensureNodeModuleScaffold(moduleName) {
+    const dir = this.resolve(path5.join("nodes", moduleName));
+    await fs5.mkdir(dir, { recursive: true });
+    const indexPath = path5.join(dir, "index.ts");
+    if (!fssync.existsSync(indexPath)) {
+      await fs5.writeFile(
+        indexPath,
+        `// ${moduleName} \u2014 scaffolded by Cascade. Replace with real node logic.
+// Every node module exports execute(node, graph); real imports work here \u2014
+// relative files in this project, npm deps, whatever the code needs.
+
+export function execute(node, graph) {
+  // node.in('name', defaultValue) / node.out('name').setValue(value)
+}
+`,
+        "utf-8"
+      );
+    }
+  }
+};
+function exportedString(source, exportName) {
+  const match = source.match(new RegExp(
+    `export\\s+const\\s+${exportName}\\s*(?::[^=]+)?=\\s*([\\'"\`])((?:\\\\.|(?!\\1)[^\\\\])*)\\1`
+  ));
+  if (!match || match[1] === "`" && match[2].includes("${")) return null;
+  if (match[1] === '"') {
+    try {
+      return JSON.parse(`"${match[2]}"`);
+    } catch {
+      return null;
+    }
+  }
+  return match[2].replace(/\\([\\'"`])/g, "$1");
+}
+function exportedStringArray(source, exportName) {
+  const declaration = new RegExp(`export\\s+const\\s+${exportName}\\s*(?::[^=]+)?=\\s*\\[`).exec(source);
+  if (!declaration) return null;
+  const values = [];
+  const start = declaration.index + declaration[0].length;
+  const end = source.indexOf("]", start);
+  if (end < 0) return null;
+  const contents = source.slice(start, end);
+  const literal = /(['"`])([^'"`]*)\1/g;
+  let cursor = 0;
+  for (const match of contents.matchAll(literal)) {
+    if (!/^[\s,]*$/.test(contents.slice(cursor, match.index))) return null;
+    if (match[1] === "`" && match[2].includes("${")) return null;
+    const decoded = exportedString(`export const value = ${match[0]}`, "value");
+    if (decoded === null) return null;
+    values.push(decoded);
+    cursor = (match.index ?? 0) + match[0].length;
+  }
+  return /^[\s,]*$/.test(contents.slice(cursor)) ? values : null;
+}
+
+export {
+  PathSafetyError,
+  resolveWithinRoot,
+  readProjectManifest,
+  writeProjectManifest,
+  CredentialStore,
+  secretValue,
+  ShellProcessError,
+  ShellRequestError,
+  extractNodeDefinition,
+  ProjectRoot
+};
+//# sourceMappingURL=chunk-2JEU3MGB.js.map