@lumerahq/cli 0.24.7 → 0.26.0

package/README.md

@@ -33,10 +33,22 @@ lumera destroy             # Delete remote resources
 
 lumera run <target>        # Run script, automation, or invoke agent
 
+lumera functions list     # List locally configured Functions
+lumera functions inspect invoices:approve
+lumera functions invoke invoices:approve --input input.json --local
+lumera functions test     # Validate contracts and run Function tests
+
 lumera flags list          # List this sandbox's feature flags
 lumera flags get <key>     # Print one flag's value (--default <v> if unset)
 ```
 
+Function commands are local-only in this release. Each command starts a fresh
+SDK runner through `uv` and supplies the compatible Functions SDK as an
+isolated overlay, so an older project lock cannot select a pre-Functions SDK.
+`invoke` requires `--local` so it cannot be mistaken for a deployed invocation.
+Function modules and test locations are configured under
+`[tool.lumera.functions]` in `pyproject.toml`.
+
 ## Scaffolding Projects
 
 ### Interactive Mode
@@ -54,7 +66,7 @@ For CI/CD or scripted environments, use `-y` (or `--yes`) flag:
 lumera init my-app -y                 # Creates ./my-app
 lumera init my-app -y --dir ./apps    # Creates ./apps
 lumera init my-app -y --force         # Overwrites if directory exists
-lumera init my-app -y --no-install    # Skip pnpm install
+lumera init my-app -y --no-install    # Defer Python and pnpm dependencies
 ```
 
 ### Init Options

package/dist/functions-PVOVWMON.js

@@ -0,0 +1,212 @@
+import "./chunk-PNKVD2UK.js";
+
+// src/commands/functions.ts
+import { spawn } from "child_process";
+import { existsSync } from "fs";
+import { join, resolve } from "path";
+import pc from "picocolors";
+var SUPPORTED_SUBCOMMANDS = /* @__PURE__ */ new Set(["list", "inspect", "invoke", "test"]);
+var FUNCTIONS_SDK_REQUIREMENT = "lumera[functions]>=0.30.0,<0.31.0";
+var FUNCTIONS_RUNNER_PROTOCOL_VERSION = 1;
+function errorMessage(error, fallback) {
+  return error instanceof Error && error.message ? error.message : fallback;
+}
+function isFunctionProtocolEnvelope(output) {
+  try {
+    const payload = JSON.parse(output);
+    return typeof payload === "object" && payload !== null && !Array.isArray(payload) && "protocol_version" in payload && payload.protocol_version === FUNCTIONS_RUNNER_PROTOCOL_VERSION && "ok" in payload && typeof payload.ok === "boolean";
+  } catch {
+    return false;
+  }
+}
+function emitFunctionCliFailure(code, message, write = (value) => {
+  process.stdout.write(value);
+}) {
+  write(
+    `${JSON.stringify({
+      protocol_version: FUNCTIONS_RUNNER_PROTOCOL_VERSION,
+      ok: false,
+      error: { code, message, retryable: false }
+    })}
+`
+  );
+  process.exitCode = 1;
+}
+function findFunctionsProjectRoot(startDir = process.cwd()) {
+  let directory = resolve(startDir);
+  while (true) {
+    if (existsSync(join(directory, "pyproject.toml"))) {
+      return directory;
+    }
+    const parent = resolve(directory, "..");
+    if (parent === directory) break;
+    directory = parent;
+  }
+  throw new Error(
+    "Could not find Functions project root (no pyproject.toml found)"
+  );
+}
+function showHelp() {
+  console.log(`
+${pc.dim("Usage:")}
+  lumera functions list
+  lumera functions inspect <function-id>
+  lumera functions invoke <function-id> --input <path|-> --local
+  lumera functions test [-- <pytest-options>]
+
+${pc.dim("Description:")}
+  Discover, inspect, invoke, and test configured Functions in a fresh local
+  Python process. Phase 1 does not deploy or invoke Functions remotely.
+
+${pc.dim("Options:")}
+  --local                Required for invoke; remote invocation is unavailable
+  --input <path|->       Read a JSON object from a project file or stdin (-)
+  --help, -h             Show this help
+
+${pc.dim("Examples:")}
+  lumera functions list
+  lumera functions inspect invoices:approve
+  lumera functions invoke invoices:approve --input input.json --local
+  cat input.json | lumera functions invoke invoices:approve --input - --local
+  lumera functions test
+  lumera functions test -- -k approve
+`);
+}
+function buildFunctionRunnerArgs(subcommand, args, projectRoot) {
+  if (!SUPPORTED_SUBCOMMANDS.has(subcommand)) {
+    throw new Error(`Unknown functions subcommand: ${subcommand}`);
+  }
+  if (subcommand === "invoke" && !args.includes("--local")) {
+    throw new Error(
+      "Function invocation is local-only in Phase 1; pass --local explicitly."
+    );
+  }
+  const runnerPrefix = ["run"];
+  if (existsSync(join(projectRoot, "uv.lock"))) {
+    runnerPrefix.push("--locked");
+  }
+  runnerPrefix.push("--with", FUNCTIONS_SDK_REQUIREMENT);
+  if (subcommand === "test") {
+    runnerPrefix.push("--with", "pytest>=8.0,<10.0");
+  }
+  return [
+    ...runnerPrefix,
+    "python",
+    "-m",
+    "lumera.functions",
+    "--project-root",
+    projectRoot,
+    subcommand,
+    ...args
+  ];
+}
+async function runFunctionRunner(runnerArgs, projectRoot, spawnRunner = (command, args, options) => spawn(command, args, options), writeOutput = (value) => {
+  process.stdout.write(value);
+}, writeDiagnostic = (value) => {
+  process.stderr.write(value);
+}) {
+  return await new Promise((resolve2, reject) => {
+    const child = spawnRunner("uv", runnerArgs, {
+      cwd: projectRoot,
+      env: process.env,
+      shell: false,
+      // Buffer the single protocol value so a uv failure before Python starts
+      // cannot leave machine callers with stderr and no JSON response.
+      stdio: ["inherit", "pipe", "inherit"]
+    });
+    let protocolOutput = "";
+    child.stdout?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => {
+      protocolOutput += chunk;
+    });
+    let settled = false;
+    const forwardSigint = () => child.kill("SIGINT");
+    const forwardSigterm = () => child.kill("SIGTERM");
+    const cleanup = () => {
+      process.off("SIGINT", forwardSigint);
+      process.off("SIGTERM", forwardSigterm);
+    };
+    process.once("SIGINT", forwardSigint);
+    process.once("SIGTERM", forwardSigterm);
+    child.once("error", (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (error.code === "ENOENT") {
+        reject(
+          new Error(
+            "uv is not installed. Install it from https://docs.astral.sh/uv/"
+          )
+        );
+        return;
+      }
+      reject(new Error(`Failed to start the Function runner: ${error.message}`));
+    });
+    child.once("close", (code) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (!isFunctionProtocolEnvelope(protocolOutput)) {
+        if (protocolOutput) writeDiagnostic(protocolOutput);
+        reject(
+          new Error(
+            `Function runner exited with status ${code ?? 1} before emitting a valid protocol envelope`
+          )
+        );
+        return;
+      }
+      writeOutput(protocolOutput);
+      resolve2(code ?? 1);
+    });
+  });
+}
+async function functions(subcommand, args, dependencies = {}) {
+  if (subcommand === void 0 || subcommand === "help" || subcommand === "--help" || subcommand === "-h" || args.includes("--help") || args.includes("-h")) {
+    showHelp();
+    return;
+  }
+  const findProjectRoot = dependencies.findProjectRoot ?? (() => findFunctionsProjectRoot());
+  const buildRunnerArgs = dependencies.buildRunnerArgs ?? buildFunctionRunnerArgs;
+  const runRunner = dependencies.runRunner ?? runFunctionRunner;
+  const emitFailure = dependencies.emitFailure ?? emitFunctionCliFailure;
+  let projectRoot;
+  try {
+    projectRoot = findProjectRoot();
+  } catch (error) {
+    emitFailure(
+      "function_discovery_error",
+      errorMessage(error, "Could not locate the Functions project")
+    );
+    return;
+  }
+  let runnerArgs;
+  try {
+    runnerArgs = buildRunnerArgs(subcommand, args, projectRoot);
+  } catch (error) {
+    emitFailure(
+      "invalid_arguments",
+      errorMessage(error, "Invalid Functions command arguments")
+    );
+    return;
+  }
+  let exitCode;
+  try {
+    exitCode = await runRunner(runnerArgs, projectRoot);
+  } catch (error) {
+    emitFailure(
+      "function_runner_unavailable",
+      errorMessage(error, "The local Function runner is unavailable")
+    );
+    return;
+  }
+  if (exitCode !== 0) {
+    process.exitCode = exitCode;
+  }
+}
+export {
+  buildFunctionRunnerArgs,
+  emitFunctionCliFailure,
+  findFunctionsProjectRoot,
+  functions,
+  runFunctionRunner
+};

package/dist/index.js

@@ -10,6 +10,11 @@ import { dirname as dirname2, join as join2 } from "path";
 import { fileURLToPath } from "url";
 import pc from "picocolors";
 
+// src/lib/command-output.ts
+function commandOwnsStdout(command2) {
+  return command2 === "functions";
+}
+
 // src/lib/update-check.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
@@ -79,6 +84,7 @@ if (jsonMode) process.env.LUMERA_JSON = "1";
 var args = rawArgs.filter((a) => a !== "--json");
 var command = args[0];
 var subcommand = args[1];
+var ownsStdout = commandOwnsStdout(command);
 var COMMANDS = [
   "plan",
   "apply",
@@ -89,6 +95,7 @@ var COMMANDS = [
   "diff",
   "dev",
   "run",
+  "functions",
   "init",
   "register",
   "templates",
@@ -150,6 +157,7 @@ ${pc.dim("Resource Commands:")}
 ${pc.dim("Development:")}
   ${pc.cyan("dev")}                      Start dev server
   ${pc.cyan("run")} <target>             Run script, trigger automation, or invoke agent
+  ${pc.cyan("functions")} <command>       Develop and test Functions locally
 
 ${pc.dim("Project:")}
   ${pc.cyan("init")} [name]              Scaffold a new project
@@ -194,6 +202,9 @@ ${pc.dim("Examples:")}
   lumera run scripts/seed.py          # Run a script
   lumera run automations/sync         # Trigger automation
   lumera run agents/support "Hello"   # Invoke an agent
+  lumera functions list                # List locally configured Functions
+  lumera functions invoke invoices:approve --input input.json --local
+  lumera functions test                # Validate Function contracts and tests
   lumera dev                          # Start dev server
   lumera flags list                   # List this sandbox's feature flags
   lumera flags get studio_browser --default false   # one flag (fallback if unset)
@@ -222,7 +233,7 @@ async function main() {
     }
   }
   const startTime = performance.now();
-  const updateCheck = checkForUpdate(VERSION);
+  const updateCheck = ownsStdout ? Promise.resolve(null) : checkForUpdate(VERSION);
   try {
     switch (command) {
       // Resource commands
@@ -254,9 +265,14 @@ async function main() {
       case "run":
         await import("./run-WHVUVIYB.js").then((m) => m.run(args.slice(1)));
         break;
+      case "functions":
+        await import("./functions-PVOVWMON.js").then(
+          (m) => m.functions(subcommand, args.slice(2))
+        );
+        break;
       // Project
       case "init":
-        await import("./init-B4DXTC7L.js").then((m) => m.init(args.slice(1)));
+        await import("./init-CUB3KH6M.js").then((m) => m.init(args.slice(1)));
         break;
       case "register":
         await import("./register-HRLBT4FI.js").then((m) => m.register(args.slice(1)));
@@ -309,14 +325,14 @@ async function main() {
         process.exit(1);
       }
     }
-    if (!jsonMode) {
+    if (!jsonMode && !ownsStdout) {
       const elapsed = performance.now() - startTime;
       if (elapsed >= 500) {
         console.log(pc.dim(`
 Done in ${formatElapsed(elapsed)}`));
       }
     }
-    if (!jsonMode) {
+    if (!jsonMode && !ownsStdout) {
       try {
         const update = await Promise.race([
           updateCheck,

package/dist/{init-B4DXTC7L.js → init-CUB3KH6M.js}

@@ -1,3 +1,7 @@
+import {
+  listAllTemplates,
+  resolveTemplate
+} from "./chunk-H357NP7T.js";
 import {
   installAllSkills,
   syncClaudeMd
@@ -15,10 +19,6 @@ import {
   setProjectId
 } from "./chunk-JLVVHTBY.js";
 import "./chunk-FJFIWC7G.js";
-import {
-  listAllTemplates,
-  resolveTemplate
-} from "./chunk-H357NP7T.js";
 import "./chunk-PNKVD2UK.js";
 
 // src/commands/init.ts
@@ -130,14 +130,11 @@ function installUv() {
     return false;
   }
 }
-function createPythonVenv(targetDir) {
-  try {
-    execSync("uv venv", { cwd: targetDir, stdio: "ignore" });
-    execSync("uv pip install lumera", { cwd: targetDir, stdio: "ignore" });
-    return true;
-  } catch {
-    return false;
-  }
+function createPythonVenv(targetDir, runCommand = execSync) {
+  runCommand("uv sync --extra dev --no-install-project", {
+    cwd: targetDir,
+    stdio: "ignore"
+  });
 }
 function detectEditor() {
   const envEditor = process.env.VISUAL || process.env.EDITOR;
@@ -377,6 +374,7 @@ async function init(args) {
   copyDir(templateDir, targetDir, replacements);
   ensureClaudeInstructionsLink(targetDir);
   const installCommand = existsSync(join(targetDir, "pnpm-lock.yaml")) ? "pnpm install --frozen-lockfile" : "pnpm install";
+  const hasPythonProject = existsSync(join(targetDir, "pyproject.toml"));
   function listFiles(dir, prefix = "") {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
       const relativePath = prefix + entry.name;
@@ -388,6 +386,31 @@ async function init(args) {
     }
   }
   listFiles(targetDir);
+  if (opts.install && hasPythonProject) {
+    if (!isUvInstalled()) {
+      const stopUv = spinner("Installing uv (Python package manager)...");
+      if (installUv()) {
+        stopUv(pc.green("\u2713") + pc.dim(" uv installed successfully"));
+      } else {
+        stopUv(pc.red("\u2717") + pc.dim(" Failed to install uv"));
+        rmSync(targetDir, { recursive: true, force: true });
+        throw new Error(
+          "uv is required to resolve this Python project, so the incomplete generated directory was removed. Install uv from https://docs.astral.sh/uv/ and retry initialization, or pass --no-install to defer Python and JavaScript dependencies."
+        );
+      }
+    }
+    const stopVenv = spinner("Creating Python venv with Lumera SDK...");
+    try {
+      createPythonVenv(targetDir);
+      stopVenv(pc.green("\u2713") + pc.dim(" Python venv created (.venv/) with lumera SDK"));
+    } catch {
+      stopVenv(pc.red("\u2717") + pc.dim(" Failed to resolve the Python environment"));
+      rmSync(targetDir, { recursive: true, force: true });
+      throw new Error(
+        "Python dependency resolution failed, so the incomplete generated directory was removed. Verify the declared Lumera SDK is available and retry initialization, or pass --no-install to defer Python and JavaScript dependencies."
+      );
+    }
+  }
   if (isGitInstalled()) {
     const stopGit = spinner("Initializing git repository...");
     if (initGitRepo(targetDir, finalProjectName)) {
@@ -398,24 +421,6 @@ async function init(args) {
   } else {
     console.log(pc.yellow("  \u26A0"), pc.dim("Git not found \u2014 skipping repository initialization"));
   }
-  let uvAvailable = isUvInstalled();
-  if (!uvAvailable) {
-    const stopUv = spinner("Installing uv (Python package manager)...");
-    if (installUv()) {
-      stopUv(pc.green("\u2713") + pc.dim(" uv installed successfully"));
-      uvAvailable = true;
-    } else {
-      stopUv(pc.yellow("\u26A0") + pc.dim(" Failed to install uv \u2014 install manually: https://docs.astral.sh/uv/"));
-    }
-  }
-  if (uvAvailable) {
-    const stopVenv = spinner("Creating Python venv with Lumera SDK...");
-    if (createPythonVenv(targetDir)) {
-      stopVenv(pc.green("\u2713") + pc.dim(" Python venv created (.venv/) with lumera SDK"));
-    } else {
-      stopVenv(pc.yellow("\u26A0") + pc.dim(" Failed to create Python venv"));
-    }
-  }
   if (opts.install) {
     const stopInstall = spinner("Installing dependencies...");
     try {
@@ -467,6 +472,9 @@ async function init(args) {
   console.log();
   console.log(pc.cyan(`  cd ${finalDirectory}`));
   if (!opts.install) {
+    if (hasPythonProject) {
+      console.log(pc.cyan("  uv sync --extra dev --no-install-project"));
+    }
     console.log(pc.cyan(`  ${installCommand}`));
   }
   if (!registered) {
@@ -481,5 +489,6 @@ async function init(args) {
   }
 }
 export {
+  createPythonVenv,
   init
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumerahq/cli",
-  "version": "0.24.7",
+  "version": "0.26.0",
   "description": "CLI for building and deploying Lumera apps",
   "type": "module",
   "engines": {

package/templates/default/README.md

@@ -13,6 +13,16 @@ lumera apply   # Deploy resources
 
 - `platform/collections/` — Collection schemas (JSON)
 - `platform/automations/` — Python automations
+- `platform/functions/` — Typed Python Functions configured in `pyproject.toml`
 - `platform/hooks/` — JavaScript hooks
 - `src/` — React frontend (TanStack Router + Query)
 - `scripts/` — Utility scripts
+
+Add each Function module to `[tool.lumera.functions].modules`, then use
+`lumera functions list`, `lumera functions invoke <id> --local`, and
+`lumera functions test` for the local development loop. With dependency
+installation enabled, scaffolding runs `uv sync` and includes `uv.lock` in the
+initial commit. `--no-install` (used by Studio bootstrap) defers this until the
+first Functions command or an explicit `uv sync`. Refresh and commit the lock
+after changing Python dependencies so every developer and later release build
+resolves the same SDK and dependency graph.

package/templates/default/_gitignore

@@ -7,7 +7,6 @@ __pycache__
 *.pyc
 .venv/
 .lumera/
-uv.lock
 src/routeTree.gen.ts
 .tanstack/
 output/

package/templates/default/platform/functions/__init__.py

@@ -0,0 +1 @@
+"""Project Function modules."""

package/templates/default/pyproject.toml

@@ -4,11 +4,16 @@ version = "0.1.0"
 description = "{{projectTitle}} - Lumera custom app"
 requires-python = ">=3.11"
 dependencies = [
-    "lumera",
+    "lumera[functions]>=0.30.0,<0.31.0",
 ]
 
 [project.optional-dependencies]
 dev = [
     "ruff",
-    "pytest",
+    "pytest>=8.0,<10.0",
 ]
+
+[tool.lumera.functions]
+source-root = "platform"
+modules = []
+test-paths = ["tests/functions"]

package/templates/default/template.json

@@ -3,5 +3,5 @@
   "title": "Blank Starter",
   "description": "A minimal blank canvas with React frontend and Lumera platform scaffolding. No pre-built collections or agents — start from scratch.",
   "category": "General",
-  "version": "1.3.0"
+  "version": "1.4.0"
 }

package/templates/default/tests/functions/.gitkeep

@@ -0,0 +1 @@
+