@lumerahq/cli 0.19.25 → 0.20.0-dev.0

package/README.md

@@ -32,6 +32,9 @@ lumera show <resource>     # Show resource details
 lumera destroy             # Delete remote resources
 
 lumera run <target>        # Run script, automation, or invoke agent
+
+lumera flags list          # List this sandbox's feature flags
+lumera flags get <key>     # Print one flag's value (--default <v> if unset)
 ```
 
 ## Scaffolding Projects

package/dist/flags-AVQEXEDT.js

@@ -0,0 +1,89 @@
+import "./chunk-PNKVD2UK.js";
+
+// src/commands/flags.ts
+import pc from "picocolors";
+
+// src/lib/flags.ts
+import { readFileSync, statSync } from "fs";
+var ENV_PATH = "LUMERA_FEATURE_FLAGS_PATH";
+var DEFAULT_PATH = "/opt/lumera/feature-flags/flags.json";
+function flagsPath() {
+  return process.env[ENV_PATH] || DEFAULT_PATH;
+}
+var cache = null;
+function featureFlags() {
+  const path = flagsPath();
+  let key;
+  try {
+    key = `${path}:${statSync(path).mtimeMs}`;
+  } catch {
+    return {};
+  }
+  if (cache && cache.key === key) return cache.flags;
+  let flags2 = {};
+  try {
+    const data = JSON.parse(readFileSync(path, "utf-8"));
+    if (data && typeof data === "object" && data.flags && typeof data.flags === "object") {
+      flags2 = data.flags;
+    }
+  } catch {
+    flags2 = {};
+  }
+  cache = { key, flags: flags2 };
+  return flags2;
+}
+
+// src/commands/flags.ts
+async function flags(subcommand, args) {
+  switch (subcommand) {
+    case "get": {
+      const key = args[0];
+      if (!key) {
+        console.error(pc.red("Usage: lumera flags get <key> [--default <value>]"));
+        process.exit(1);
+      }
+      const defIdx = args.indexOf("--default");
+      const fallback = defIdx !== -1 ? args[defIdx + 1] : void 0;
+      const all = featureFlags();
+      if (!(key in all)) {
+        if (fallback !== void 0) {
+          console.log(fallback);
+          return;
+        }
+        process.exit(1);
+      }
+      printValue(all[key]);
+      break;
+    }
+    case void 0:
+    case "list": {
+      const all = featureFlags();
+      if (process.env.LUMERA_JSON === "1") {
+        console.log(JSON.stringify(all, null, 2));
+        break;
+      }
+      const keys = Object.keys(all).sort();
+      if (keys.length === 0) {
+        console.log(pc.dim("No feature flags available."));
+        break;
+      }
+      for (const k of keys) {
+        console.log(`${pc.cyan(k)} = ${formatValue(all[k])}`);
+      }
+      break;
+    }
+    default:
+      console.error(pc.red(`Unknown flags subcommand: ${subcommand}`));
+      console.error("Usage: lumera flags [list | get <key> [--default <value>]]");
+      process.exit(1);
+  }
+}
+function formatValue(v) {
+  return typeof v === "string" ? v : JSON.stringify(v);
+}
+function printValue(v) {
+  console.log(formatValue(v));
+}
+export {
+  flags
+};

package/dist/index.js

@@ -95,6 +95,7 @@ var COMMANDS = [
   "migrate",
   "skills",
   "deps",
+  "flags",
   "login",
   "logout",
   "whoami"
@@ -162,6 +163,10 @@ ${pc.dim("Skills:")}
   ${pc.cyan("skills install")}           Install skills
   ${pc.cyan("skills update")}            Update skills
 
+${pc.dim("Feature Flags:")}
+  ${pc.cyan("flags list")}               List feature flags in this sandbox
+  ${pc.cyan("flags get")} <key>          Print one flag's value (--default <v> if unset)
+
 ${pc.dim("Auth:")}
   ${pc.cyan("login")}                    Login to Lumera
   ${pc.cyan("logout")}                   Clear credentials
@@ -189,6 +194,8 @@ ${pc.dim("Examples:")}
   lumera run automations/sync         # Trigger automation
   lumera run agents/support "Hello"   # Invoke an agent
   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)
 
 ${pc.dim("Documentation:")}
   https://docs.lumerahq.com/cli
@@ -270,6 +277,10 @@ async function main() {
       case "deps":
         await import("./deps-HWO6X5WM.js").then((m) => m.deps(args.slice(1)));
         break;
+      // Feature flags (read the in-sandbox snapshot)
+      case "flags":
+        await import("./flags-AVQEXEDT.js").then((m) => m.flags(subcommand, args.slice(2)));
+        break;
       // Auth
       case "login":
         await import("./auth-NI7JTMJM.js").then((m) => m.login(args.slice(1)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumerahq/cli",
-  "version": "0.19.25",
+  "version": "0.20.0-dev.0",
   "description": "CLI for building and deploying Lumera apps",
   "type": "module",
   "engines": {
@@ -16,6 +16,7 @@
   "scripts": {
     "build": "tsup src/index.ts --format esm --clean",
     "dev": "tsup src/index.ts --format esm --watch",
+    "test": "rm -rf dist-test && tsc -p tsconfig.test.json && node --test 'dist-test/**/*.test.js'",
     "prepublishOnly": "pnpm build"
   },
   "dependencies": {

package/templates/default/AGENTS.md

@@ -1,6 +1,6 @@
 # {{projectTitle}}
 
-A Lumera app built with collections, automations, hooks, and a React frontend.
+A Lumera app built with collections, automations, hooks, custom agents, and a React frontend.
 
 ## Project Structure
 
@@ -8,6 +8,7 @@ A Lumera app built with collections, automations, hooks, and a React frontend.
 platform/
 ├── collections/       # Collection schemas (JSON) — deployed via lumera apply
 ├── automations/       # Python automations (config.json + run.py per automation)
+├── agents/            # Custom AI agents (config.json + system_prompt.md + optional policy.js)
 ├── hooks/             # JavaScript hooks on collection lifecycle events
 src/
 ├── routes/index.tsx   # Home page
@@ -29,6 +30,7 @@ A Lumera app is built from these primitives — all defined as code in `platform
 
 - **Collections** (`platform/collections/*.json`) — Data tables with typed fields. Deployed via `lumera apply`.
 - **Automations** (`platform/automations/*/`) — Python scripts that run on Lumera's servers. Each has a `config.json` and `run.py`.
+- **Custom agents** (`platform/agents/*/`) — AI-powered agents with prompts, skills, optional policies, and reusable sessions. Use them for classification, extraction, enrichment, drafting, guided review, and tool-heavy workflows. When creating or changing agents, read the Building Agents skill first.
 - **Hooks** (`platform/hooks/*.js`) — JavaScript on collection lifecycle events (`before_create`, `after_update`, etc.).
 - **Webhooks** — Receive events from external services (Stripe, GitHub, etc.). Events land in `lm_event_log`; process them with hooks or automations.
 - **Mailbox** — Each tenant gets an email address. Inbound emails are persisted to `lm_mailbox_messages` — use hooks to trigger automations on new mail.
@@ -151,22 +153,26 @@ changes, tell them to open the **Preview tab**.
 
 ## Workflow
 
-Follow the user's lead. If they tell you exactly what to build, build it. The workflow below is the default when they describe a goal and leave the approach to you.
+Follow the user's lead. If they tell you exactly what to build and no critical unknowns block correctness, build it. If critical unknowns exist, ask before encoding assumptions. The workflow below is the default when they describe a goal and leave the approach to you.
 
-### Step 1: Plan
+### Step 1: Understand and Plan
 1. **Read skills first** — Read the matching skill files for API details and patterns.
-2. **Discuss the plan** — Start from the **simplest thing that works** — one collection, one screen, one feature. Propose incremental steps that layer on complexity but if the decisions are obvious, you can execute multiple steps in one go. Each step should be a complete horizontal slice (collection + backend logic + UI).
-3. **Stop and ask the user to approve.** Iterate until they're happy with the plan. They may reorder steps, drop features, or add ones you didn't think of.
+2. **Decide one-off vs repeatable** — Determine whether the user needs a one-off answer/artifact or a repeatable workflow. For one-off tasks, answer the question, analyze the data, or produce the requested artifact directly; do not build an app unless the user asks. Propose an app, automation, agent, or durable workflow only when the process will be reused.
+3. **Inspect uploaded files** — If the user uploaded files, inspect them before planning. Identify what each file represents: one-time input data, recurring source data, configuration data, mapping/lookup tables, business rules or domain knowledge, templates, expected input/output examples, exports from another system, or debugging evidence. Decide whether each file should be used only for this turn, stored as durable configuration/reference data, imported into collections, converted into an automation input, or preserved as documentation/examples.
+4. **Identify critical unknowns** — Before proposing or building, list unknowns that affect correctness in real use. Pay special attention to source-of-truth data, ownership/assignment/approval rules, escalation or routing rules, permissions/roles/access control, integrations and required scopes, identifiers and mappings between systems, and what should happen when required data is missing.
+5. **Ask blockers, state assumptions** — Ask concise clarifying questions for blockers. Do not silently create manual lookup tables, fallback rules, durable apps, or business assumptions unless the user explicitly accepts them. For non-blocking details, state your assumption and proceed.
+6. **Discuss the plan** — Propose the **smallest validated useful slice**: a complete horizontal slice that proves the workflow with real data and realistic edge cases. Propose incremental steps that layer on complexity; if decisions are obvious, you can execute multiple steps in one go.
+7. **Stop and ask the user to approve.** Iterate until they're happy with the plan. They may reorder steps, drop features, or add ones you didn't think of.
 
 ### Step 2: Build (one slice at a time)
-4. **Build horizontally** — Pick the first step. Build the full slice: collection schema → `lumera apply` → seed data → UI route/components → commit. Each slice should be deployable and usable on its own.
-5. **Stop and ask for feedback** — Tell the user to open the **Preview tab** to see the app. Do not mention local dev-server commands or localhost URLs. Iterate on the slice until they're happy.
-6. **Repeat** — Move to the next step. Build, deploy, get feedback.
+1. **Build horizontally** — Pick the first step. Build the full slice: collection schema and/or agent definition → `lumera apply` → seed data → UI route/components → commit. Each slice should be deployable and usable on its own.
+2. **Stop and ask for feedback** — Tell the user to open the **Preview tab** to see the app. Do not mention local dev-server commands or localhost URLs. Iterate on the slice until they're happy.
+3. **Repeat** — Move to the next step. Build, deploy, get feedback.
 
 ### Rules
-7. **Code is source of truth** — Edit files in `platform/`, then deploy with `lumera apply`. Don't edit in the Lumera UI.
-8. **Keep docs current** — After each slice, update `architecture.md` with what was built (data models, relationships, hook logic, design decisions). Also update the project description at the top of this file (`AGENTS.md`) so it reflects what the project actually does now — not the original template description.
-9. **Commit and push** — After each slice or significant change, stage your changes, create a meaningful commit with both a title and description, then push. The sandbox is ephemeral — uncommitted work is lost if recycled.
+1. **Code is source of truth** — Edit files in `platform/`, then deploy with `lumera apply`. Don't edit in the Lumera UI.
+2. **Keep docs current** — After each slice, update `architecture.md` with what was built (data models, relationships, hook logic, design decisions). Also update the project description at the top of this file (`AGENTS.md`) so it reflects what the project actually does now — not the original template description.
+3. **Commit and push** — After each slice or significant change, stage your changes, create a meaningful commit with both a title and description, then push. The sandbox is ephemeral — uncommitted work is lost if recycled.
    - Use a conventional subject (`feat:`, `fix:`, `chore:`, `docs:`, `test:`) that explains the user-visible change, not just the filenames.
    - Include a body that describes why the change was needed, what you changed, and the main areas covered.
    - Avoid generic messages like `update files`, `changes`, `WIP`, or filename-only summaries.
@@ -187,7 +193,7 @@ Follow the user's lead. If they tell you exactly what to build, build it. The wo
      )"
      git push
      ```
-10. **Deploy marker** — When your changes need `lumera apply`, include at the end of your response: `<!-- DEPLOY: short commit message -->`. Skip for frontend-only changes.
+4. **Deploy marker** — When your changes need `lumera apply`, include at the end of your response: `<!-- DEPLOY: short commit message -->`. Skip for frontend-only changes.
 
 ## File Artifacts