@lunnoa/client 1.4.0 → 1.5.0

package/README.md

@@ -21,6 +21,14 @@ npm install @lunnoa/client
 
 **Requirements:** Node.js ≥ 20 (or any runtime with `fetch` and web streams).
 
+### Start a new app
+
+```bash
+npx @lunnoa/client init my-app --url https://lunnoa.your-company.example
+```
+
+Scaffolds the [lunnoa-starter](https://github.com/lunnoa-automate/lunnoa-starter) Next.js template (thin, Docker-deployable, both auth patterns behind `LUNNOA_AUTH_MODE`) and writes `.env`, prompting for an API key when run interactively. `--template <owner/repo[#ref]|./local-folder>` overrides the source. Then `npm install` and open the folder in Claude Code / Cursor / Codex.
+
 ## Quickstart
 
 ```typescript
@@ -98,12 +106,12 @@ const { user, status, login, logout } = useLunnoaAuth();
 const lunnoa = useLunnoaClient();
 const { progress, status: progressStatus } = useExecutionProgress(executionId);
 const { waiting, pendingInput, submitInput } = useNeedsInput(progress);
-const { messages, send, stop, taskId } = useAgentChat(agentId); // needs @ai-sdk/react
+const { messages, send, stop, taskId } = useAgentChat(agentId);
 const { items, decide } = useApprovalsInbox({ pollIntervalMs: 15_000 });
 const { data, page, setPage } = useEntityList({ objectTypeSlug: 'invoice' });
 ```
 
-Peers: `react` ≥ 18 (required for `/react`); `@ai-sdk/react` only for `useAgentChat`. Core `@lunnoa/client` stays headless.
+Peer: `react` ≥ 18 (required for `/react`). `@ai-sdk/react` (behind `useAgentChat`) ships as a dependency. Core `@lunnoa/client` stays headless.
 
 ## Resources
 
@@ -303,7 +311,7 @@ npx @lunnoa/client projects list --json
 npx @lunnoa/client features --json
 ```
 
-`tools list` is compact (`appId`, `actionId`, name, flags). `tools get` prints `inputConfig` and a `defineAction({ id, appId, input })` sketch. Auth flags and `LUNNOA_URL` / `LUNNOA_API_KEY` / `lunnoa.config` work the same as deploy.
+`tools list` is compact (`appId`, `actionId`, name, flags). `tools get` prints `inputConfig` and a `defineAction({ id, appId, input })` sketch. Auth flags and `LUNNOA_URL` / `LUNNOA_API_KEY` / `lunnoa.config` work the same as deploy. The CLI also reads `./.env` (real environment variables win).
 
 ## Regenerating the API types
 

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
-import { mkdir, writeFile } from "fs/promises";
-import { resolve as resolve3 } from "path";
+import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
+import { resolve as resolve4 } from "path";
 
 // src/core/auth.ts
 var API_KEY_PREFIX = "lna_";
@@ -1083,6 +1083,35 @@ var EntityTypesResource = class {
   }
 };
 
+// src/resources/tables.ts
+var TablesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists tables in the API key's workspace (without columns and rows). */
+  list(options = {}) {
+    return this.http.get("/api/tables", {
+      query: { projectId: options.projectId }
+    });
+  }
+  /** Returns a single table by ID, including columns and rows. */
+  get(id) {
+    return this.http.get(`/api/tables/${id}`);
+  }
+  /** Returns a single table by its workspace slug, including columns and rows. */
+  getBySlug(slug) {
+    return this.http.get(`/api/tables/slug/${slug}`);
+  }
+  /**
+   * Creates or updates a table by workspace slug. Omitted columns or rows
+   * keep their current value. Marks `managedByCode` by default.
+   */
+  upsertBySlug(input) {
+    return this.http.post("/api/tables/upsert", { body: input });
+  }
+};
+
 // src/resources/approvals.ts
 var ApprovalsResource = class {
   constructor(http) {
@@ -1422,7 +1451,7 @@ function computeDurationMs(start, end) {
   return b - a;
 }
 function defaultSleep(ms) {
-  return new Promise((resolve4) => setTimeout(resolve4, ms));
+  return new Promise((resolve5) => setTimeout(resolve5, ms));
 }
 
 // src/resources/knowledge.ts
@@ -2067,6 +2096,8 @@ var LunnoaClient = class {
   approvals;
   entities;
   entityTypes;
+  /** Small reference / lookup tables (rows stored inline; use entities for transactional data). */
+  tables;
   knowledge;
   queues;
   queueItems;
@@ -2090,6 +2121,7 @@ var LunnoaClient = class {
     this.workflows = new WorkflowsResource(this.http, this.executions);
     this.entities = new EntitiesResource(this.http);
     this.entityTypes = new EntityTypesResource(this.http);
+    this.tables = new TablesResource(this.http);
     this.knowledge = new KnowledgeResource(this.http);
     this.queues = new QueuesResource(this.http);
     this.queueItems = new QueueItemsResource(this.http);
@@ -2106,6 +2138,7 @@ var GROUPS_WITH_SUBCOMMAND = /* @__PURE__ */ new Set([
   "workflows",
   "agents",
   "entity-types",
+  "tables",
   "tools",
   "apps",
   "connections",
@@ -2118,7 +2151,8 @@ var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "--access-token",
   "--project-id",
   "--out",
-  "--app"
+  "--app",
+  "--template"
 ]);
 function requireFlagValue(flag, value) {
   if (!value || value.startsWith("--")) {
@@ -2181,6 +2215,9 @@ function parseArgs(argv) {
         case "--app":
           args.app = value;
           break;
+        case "--template":
+          args.template = value;
+          break;
         default:
           break;
       }
@@ -2196,6 +2233,7 @@ function parseArgs(argv) {
   return args;
 }
 var USAGE = `Usage:
+  npx @lunnoa/client init <dir> [--url <url>] [--api-key <lna_key>] [--template <owner/repo|path>]
   npx @lunnoa/client codegen --url <url> --api-key <lna_key> [--out <dir>]
 
   Discover (do not invent catalogue action ids):
@@ -2209,6 +2247,8 @@ var USAGE = `Usage:
   npx @lunnoa/client agents list [--json]
   npx @lunnoa/client workflows list [--json]
   npx @lunnoa/client entity-types list [--json]
+  npx @lunnoa/client tables list [--json]
+  npx @lunnoa/client tables get <slugOrId> [--json]
   npx @lunnoa/client projects list [--json]
   npx @lunnoa/client features [--json]
 
@@ -2228,10 +2268,11 @@ Options:
   --out           Output directory for lunnoa.generated.ts (codegen; default: ./src/lunnoa)
   --app           Restrict tools/connections to one workflow app id
   --for-agent     Only catalogue entries with availableForAgent
+  --template      init starter: GitHub owner/repo[#ref] or local folder (default: lunnoa-automate/lunnoa-starter)
   --json          Machine-readable JSON (preferred for coding agents)
   --help          Show this help
 
-Environment: LUNNOA_URL, LUNNOA_API_KEY, LUNNOA_PROJECT_ID
+Environment: LUNNOA_URL, LUNNOA_API_KEY, LUNNOA_PROJECT_ID (also read from ./.env)
 Optional config file: lunnoa.config.ts | .mjs | .js | .json
 
 tools get prints inputConfig and a defineAction() sketch. tools list is compact;
@@ -2708,6 +2749,39 @@ async function runEntityTypesList(client, args) {
     { key: "managedByCode", header: "CODE" }
   ]);
 }
+async function runTablesList(client, args) {
+  const tables = await client.tables.list({ projectId: args.projectId });
+  const rows = tables.map((table) => ({
+    id: table.id,
+    slug: table.slug,
+    name: table.name,
+    description: table.description ?? "",
+    managedByCode: Boolean(table.managedByCode)
+  }));
+  if (args.json) {
+    printJson(rows);
+    return;
+  }
+  printTable(rows, [
+    { key: "id", header: "ID" },
+    { key: "slug", header: "SLUG" },
+    { key: "name", header: "NAME" },
+    { key: "managedByCode", header: "CODE" }
+  ]);
+}
+async function runTablesGet(client, args) {
+  const ref = requireTarget(args, "table slug or id (example: tables get cost_centres)");
+  const table = /^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(ref) ? await client.tables.get(ref) : await client.tables.getBySlug(ref);
+  if (args.json) {
+    printJson(table);
+    return;
+  }
+  console.log(`id:      ${table.id}`);
+  console.log(`slug:    ${table.slug}`);
+  console.log(`name:    ${table.name}`);
+  console.log(`columns: ${(table.columns ?? []).map((c) => c.key).join(", ")}`);
+  console.log(`rows:    ${table.rows?.length ?? 0}`);
+}
 async function runProjectsList(client, args) {
   const projects = await client.projects.list({
     expansion: ["description", "countAgents", "countWorkflows"]
@@ -3222,8 +3296,8 @@ async function loadOptionalConfig() {
       continue;
     }
     if (name.endsWith(".json")) {
-      const { readFile } = await import("fs/promises");
-      const raw = await readFile(absolute, "utf8");
+      const { readFile: readFile2 } = await import("fs/promises");
+      const raw = await readFile2(absolute, "utf8");
       return JSON.parse(raw);
     }
     const mod = await import(pathToFileURL(absolute).href);
@@ -3237,12 +3311,102 @@ async function loadOptionalConfig() {
   return {};
 }
 
+// src/cli/init.ts
+import { spawn } from "child_process";
+import { cp, mkdir, readdir, readFile, stat, writeFile } from "fs/promises";
+import { basename, join, resolve as resolve2 } from "path";
+import { createInterface } from "readline/promises";
+var DEFAULT_TEMPLATE = "lunnoa-automate/lunnoa-starter";
+var SKIP_LOCAL = /* @__PURE__ */ new Set(["node_modules", ".next", ".git", ".env", ".claude", ".cursor"]);
+function setEnvValues(source, values) {
+  let out = source;
+  for (const [key, value] of Object.entries(values)) {
+    if (!value) continue;
+    const line = `${key}=${value}`;
+    const existing = new RegExp(`^${key}=.*$`, "m");
+    out = existing.test(out) ? out.replace(existing, () => line) : `${out}${out === "" || out.endsWith("\n") ? "" : "\n"}${line}
+`;
+  }
+  return out;
+}
+async function isDirectory(path) {
+  return (await stat(path).catch(() => void 0))?.isDirectory() ?? false;
+}
+async function downloadGithubTemplate(template, dest) {
+  const [repo, ref = "HEAD"] = template.split("#");
+  const url = `https://codeload.github.com/${repo}/tar.gz/${ref}`;
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Could not download template ${template} (${response.status} from ${url}).`);
+  }
+  const tarball = Buffer.from(await response.arrayBuffer());
+  await new Promise((done, fail) => {
+    const child = spawn("tar", ["-xzf", "-", "--strip-components=1"], {
+      cwd: dest,
+      stdio: ["pipe", "ignore", "inherit"]
+    });
+    child.on(
+      "error",
+      (error) => fail(new Error(`Could not run tar (${error.message}). Download ${url} manually.`))
+    );
+    child.on(
+      "close",
+      (code) => code === 0 ? done() : fail(new Error(`tar exited with code ${code}`))
+    );
+    child.stdin.end(tarball);
+  });
+}
+async function runInit(args) {
+  if (!args.path) {
+    throw new Error("Missing project directory. Example: init my-app --url https://lunnoa.example");
+  }
+  const dest = resolve2(process.cwd(), args.path);
+  if ((await readdir(dest).catch(() => [])).length > 0) {
+    throw new Error(`${dest} already exists and is not empty.`);
+  }
+  await mkdir(dest, { recursive: true });
+  const template = args.template ?? DEFAULT_TEMPLATE;
+  if (await isDirectory(resolve2(template))) {
+    await cp(resolve2(template), dest, {
+      recursive: true,
+      filter: (src) => !SKIP_LOCAL.has(basename(src))
+    });
+  } else {
+    console.log(`Downloading ${template} ...`);
+    await downloadGithubTemplate(template, dest);
+  }
+  let { url, apiKey } = args;
+  if (process.stdin.isTTY && (!url || !apiKey)) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    url ||= (await rl.question("Lunnoa URL (e.g. https://lunnoa.your-company.example): ")).trim();
+    apiKey ||= (await rl.question("API key lna_... (server-side only; Enter to skip and sign in as a user instead): ")).trim();
+    rl.close();
+  }
+  const example = await readFile(join(dest, ".env.example"), "utf8").catch(() => "");
+  await writeFile(
+    join(dest, ".env"),
+    setEnvValues(example, { LUNNOA_URL: url, LUNNOA_API_KEY: apiKey }),
+    "utf8"
+  );
+  console.log(`
+Created ${dest}
+
+Next steps:`);
+  console.log(`  cd ${args.path}`);
+  console.log("  npm install");
+  if (!apiKey) {
+    console.log("  Add LUNNOA_API_KEY to .env, or set LUNNOA_AUTH_MODE=user to sign in with your Lunnoa account");
+  }
+  console.log("  npm run dev");
+  console.log("  Open the folder in Claude Code / Cursor / Codex and describe your idea.");
+}
+
 // src/cli/skills.ts
-import { cp } from "fs/promises";
-import { dirname, resolve as resolve2 } from "path";
+import { cp as cp2 } from "fs/promises";
+import { dirname, resolve as resolve3 } from "path";
 import { fileURLToPath } from "url";
 var SKILL_TARGETS = [".claude/skills", ".cursor/skills"];
-var BUNDLED_SKILLS_DIR = resolve2(
+var BUNDLED_SKILLS_DIR = resolve3(
   dirname(fileURLToPath(import.meta.url)),
   "..",
   "skills"
@@ -3250,8 +3414,8 @@ var BUNDLED_SKILLS_DIR = resolve2(
 async function installSkills(projectDir, sourceDir = BUNDLED_SKILLS_DIR) {
   const written = [];
   for (const target of SKILL_TARGETS) {
-    const dest = resolve2(projectDir, target);
-    await cp(sourceDir, dest, { recursive: true, force: true });
+    const dest = resolve3(projectDir, target);
+    await cp2(sourceDir, dest, { recursive: true, force: true });
     written.push(dest);
   }
   return written;
@@ -3312,10 +3476,10 @@ async function runCodegen(args) {
     `Found ${definitions.entityTypes.length} entity type(s), ${definitions.workflows.length} workflow(s), ${definitions.agents.length} agent(s).`
   );
   const moduleSource = generateDeploymentModule(definitions);
-  const outDir = resolve3(process.cwd(), args.out);
-  await mkdir(outDir, { recursive: true });
-  const outFile = resolve3(outDir, "lunnoa.generated.ts");
-  await writeFile(outFile, moduleSource, "utf8");
+  const outDir = resolve4(process.cwd(), args.out);
+  await mkdir2(outDir, { recursive: true });
+  const outFile = resolve4(outDir, "lunnoa.generated.ts");
+  await writeFile2(outFile, moduleSource, "utf8");
   console.log(`Wrote ${outFile}`);
 }
 async function deployWorkflow(args) {
@@ -3387,6 +3551,7 @@ var DISCOVERY_SUBCOMMANDS = {
   tools: ["list", "get", "search"],
   apps: ["list", "get"],
   connections: ["list", "get"],
+  tables: ["list", "get"],
   features: void 0,
   projects: ["list"]
 };
@@ -3423,7 +3588,7 @@ ${USAGE}`
 }
 async function runDiscovery(args) {
   const { command, subcommand } = args;
-  if (command === "tools" || command === "apps" || command === "connections") {
+  if (command === "tools" || command === "apps" || command === "connections" || command === "tables") {
     assertKnownDiscoveryShape(args);
   }
   if (!isDiscoveryCommand(args)) {
@@ -3470,6 +3635,14 @@ async function runDiscovery(args) {
     await runEntityTypesList(client, args);
     return true;
   }
+  if (command === "tables" && subcommand === "list") {
+    await runTablesList(client, args);
+    return true;
+  }
+  if (command === "tables" && subcommand === "get") {
+    await runTablesGet(client, args);
+    return true;
+  }
   if (command === "projects" && (subcommand === "list" || !subcommand)) {
     await runProjectsList(client, args);
     return true;
@@ -3482,12 +3655,20 @@ async function runDiscovery(args) {
 }
 async function main() {
   const args = parseArgs(process.argv.slice(2));
+  try {
+    process.loadEnvFile();
+  } catch {
+  }
   if (!args.command || args.command === "--help" || args.command === "help" || args.help) {
     console.log(USAGE);
     return;
   }
+  if (args.command === "init") {
+    await runInit(args);
+    return;
+  }
   if (args.command === "skills" && args.subcommand === "install") {
-    const written = await installSkills(resolve3(process.cwd(), args.path ?? "."));
+    const written = await installSkills(resolve4(process.cwd(), args.path ?? "."));
     for (const dest of written) {
       console.log(`Installed Lunnoa skills into ${dest}`);
     }

package/dist/index.cjs

@@ -1125,6 +1125,35 @@ var EntityTypesResource = class {
   }
 };
 
+// src/resources/tables.ts
+var TablesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists tables in the API key's workspace (without columns and rows). */
+  list(options = {}) {
+    return this.http.get("/api/tables", {
+      query: { projectId: options.projectId }
+    });
+  }
+  /** Returns a single table by ID, including columns and rows. */
+  get(id) {
+    return this.http.get(`/api/tables/${id}`);
+  }
+  /** Returns a single table by its workspace slug, including columns and rows. */
+  getBySlug(slug) {
+    return this.http.get(`/api/tables/slug/${slug}`);
+  }
+  /**
+   * Creates or updates a table by workspace slug. Omitted columns or rows
+   * keep their current value. Marks `managedByCode` by default.
+   */
+  upsertBySlug(input) {
+    return this.http.post("/api/tables/upsert", { body: input });
+  }
+};
+
 // src/resources/approvals.ts
 var ApprovalsResource = class {
   constructor(http) {
@@ -2109,6 +2138,8 @@ var LunnoaClient = class {
   approvals;
   entities;
   entityTypes;
+  /** Small reference / lookup tables (rows stored inline; use entities for transactional data). */
+  tables;
   knowledge;
   queues;
   queueItems;
@@ -2132,6 +2163,7 @@ var LunnoaClient = class {
     this.workflows = new WorkflowsResource(this.http, this.executions);
     this.entities = new EntitiesResource(this.http);
     this.entityTypes = new EntityTypesResource(this.http);
+    this.tables = new TablesResource(this.http);
     this.knowledge = new KnowledgeResource(this.http);
     this.queues = new QueuesResource(this.http);
     this.queueItems = new QueueItemsResource(this.http);
@@ -2240,6 +2272,7 @@ exports.QueuesResource = QueuesResource;
 exports.RunsResource = RunsResource;
 exports.ScorecardsResource = ScorecardsResource;
 exports.SsoAuthResource = SsoAuthResource;
+exports.TablesResource = TablesResource;
 exports.TasksResource = TasksResource;
 exports.VariablesResource = VariablesResource;
 exports.WorkflowAppsResource = WorkflowAppsResource;