@lunnoa/client 1.3.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
 
@@ -268,7 +276,7 @@ Re-run codegen whenever entity types, workflows, or agents change on the deploym
 
 ## Define, run, and CLI deploy
 
-Author local definitions with `defineWorkflow` / `defineAgent` / `defineEntityType`, run linear chains with `lunnoa.runs.start`, and upsert with the CLI (prefer CLI over calling upsert from app code). Entity types are workspace-scoped (no `--project-id`); instance writes reject unknown attribute keys unless `allowUnknownAttributes` is true — use the reserved `extensions` object for flexible bags:
+Author local definitions with `defineWorkflow` / `defineAgent` / `defineEntityType`, run linear chains with `lunnoa.runs.start`, and upsert with the CLI (prefer CLI over calling upsert from app code). An entity type slug is unique on the deployment. Deploy grants that type to the API key's workspace when the slug is new, and will not rewrite a type already granted to other workspaces (no `--project-id`). Instance writes reject unknown attribute keys unless `allowUnknownAttributes` is true — use the reserved `extensions` object for flexible bags:
 
 ```bash
 npx @lunnoa/client entity-types deploy ./human.ts --url https://lunnoa.example --api-key lna_...
@@ -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
 
@@ -322,7 +330,9 @@ Two Cursor / Claude Code skills ship in the published package under `skills/`:
 | **lunnoa-solution-design** | [`skills/lunnoa-solution-design/SKILL.md`](./skills/lunnoa-solution-design/SKILL.md) | Interview the human, map intent to Lunnoa primitives, produce a build brief |
 | **lunnoa-client** | [`skills/lunnoa-client/SKILL.md`](./skills/lunnoa-client/SKILL.md) | Implement with auth, discovery, codegen, `define*` / `runs` / CLI deploy, React hooks |
 
-After install, copy or enable them from `node_modules/@lunnoa/client/skills/` into your app’s `.cursor/skills/` (or Claude Code skills directory). Prefer **solution-design** first when requirements are unclear, then **lunnoa-client**.
+Install them into your app with `npx @lunnoa/client skills install`. It copies the skills of the installed SDK version into `.claude/skills/` and `.cursor/skills/`. Add it as a `postinstall` script and gitignore both folders so the skills stay in step with the SDK. Prefer **solution-design** first when requirements are unclear, then **lunnoa-client**.
+
+In this repo, edit `skills/` only; `pnpm install` copies it into the local `.cursor/skills/` and `.claude/skills/`.
 
 Partner paste block:
 

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 resolve2 } 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_";
@@ -1042,7 +1042,7 @@ var EntityTypesResource = class {
   }
   http;
   /**
-   * Lists entity types in the workspace. Request
+   * Lists entity types granted to the API key's workspace. Request
    * `expansion: ['attributeSchema', 'stateSchema']` for the field and state
    * machine definitions the codegen CLI builds types from.
    */
@@ -1067,7 +1067,9 @@ var EntityTypesResource = class {
     });
   }
   /**
-   * Creates or updates an entity type by workspace-scoped slug.
+   * Creates or updates an entity type by deployment-wide slug.
+   * A new slug is granted to the API key's workspace. A slug already shared
+   * with another workspace is rejected unless the key belongs to a platform admin.
    * Prefer the CLI (`npx @lunnoa/client entity-types deploy`) for happy-path deploy.
    */
   upsertBySlug(definition) {
@@ -1081,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) {
@@ -1420,7 +1451,7 @@ function computeDurationMs(start, end) {
   return b - a;
 }
 function defaultSleep(ms) {
-  return new Promise((resolve3) => setTimeout(resolve3, ms));
+  return new Promise((resolve5) => setTimeout(resolve5, ms));
 }
 
 // src/resources/knowledge.ts
@@ -2065,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;
@@ -2088,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);
@@ -2104,10 +2138,12 @@ var GROUPS_WITH_SUBCOMMAND = /* @__PURE__ */ new Set([
   "workflows",
   "agents",
   "entity-types",
+  "tables",
   "tools",
   "apps",
   "connections",
-  "projects"
+  "projects",
+  "skills"
 ]);
 var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "--url",
@@ -2115,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("--")) {
@@ -2178,6 +2215,9 @@ function parseArgs(argv) {
         case "--app":
           args.app = value;
           break;
+        case "--template":
+          args.template = value;
+          break;
         default:
           break;
       }
@@ -2193,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):
@@ -2206,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]
 
@@ -2214,6 +2257,9 @@ var USAGE = `Usage:
   npx @lunnoa/client agents deploy <path> --url <url> --api-key <key> --project-id <uuid>
   npx @lunnoa/client entity-types deploy <path> --url <url> --api-key <key>
 
+  Agent skills (copies this version's skills into .claude/skills and .cursor/skills):
+  npx @lunnoa/client skills install [projectDir]
+
 Options:
   --url           Base URL of the Lunnoa Automate deployment
   --api-key       Machine API key (lna_...)
@@ -2222,15 +2268,17 @@ 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;
-run tools get for the schema. Entity-type deploy is workspace-scoped (no
---project-id). Unknown instance attributes are rejected unless
+run tools get for the schema. Entity-type deploy uses a deployment-wide slug
+and grants the API key's workspace when the slug is new (no --project-id).
+A slug already granted to other workspaces is not rewritten. Unknown instance attributes are rejected unless
 allowUnknownAttributes is true; use extensions.
 `;
 
@@ -2701,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"]
@@ -3215,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);
@@ -3230,6 +3311,116 @@ 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 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 = resolve3(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "skills"
+);
+async function installSkills(projectDir, sourceDir = BUNDLED_SKILLS_DIR) {
+  const written = [];
+  for (const target of SKILL_TARGETS) {
+    const dest = resolve3(projectDir, target);
+    await cp2(sourceDir, dest, { recursive: true, force: true });
+    written.push(dest);
+  }
+  return written;
+}
+
 // src/cli/index.ts
 async function bindClient(args) {
   const fileConfig = await loadOptionalConfig();
@@ -3285,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 = resolve2(process.cwd(), args.out);
-  await mkdir(outDir, { recursive: true });
-  const outFile = resolve2(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) {
@@ -3360,6 +3551,7 @@ var DISCOVERY_SUBCOMMANDS = {
   tools: ["list", "get", "search"],
   apps: ["list", "get"],
   connections: ["list", "get"],
+  tables: ["list", "get"],
   features: void 0,
   projects: ["list"]
 };
@@ -3396,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)) {
@@ -3443,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;
@@ -3455,10 +3655,25 @@ 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(resolve4(process.cwd(), args.path ?? "."));
+    for (const dest of written) {
+      console.log(`Installed Lunnoa skills into ${dest}`);
+    }
+    return;
+  }
   if (args.command === "codegen") {
     await runCodegen(args);
     return;

package/dist/index.cjs

@@ -1084,7 +1084,7 @@ var EntityTypesResource = class {
   }
   http;
   /**
-   * Lists entity types in the workspace. Request
+   * Lists entity types granted to the API key's workspace. Request
    * `expansion: ['attributeSchema', 'stateSchema']` for the field and state
    * machine definitions the codegen CLI builds types from.
    */
@@ -1109,7 +1109,9 @@ var EntityTypesResource = class {
     });
   }
   /**
-   * Creates or updates an entity type by workspace-scoped slug.
+   * Creates or updates an entity type by deployment-wide slug.
+   * A new slug is granted to the API key's workspace. A slug already shared
+   * with another workspace is rejected unless the key belongs to a platform admin.
    * Prefer the CLI (`npx @lunnoa/client entity-types deploy`) for happy-path deploy.
    */
   upsertBySlug(definition) {
@@ -1123,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) {
@@ -2107,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;
@@ -2130,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);
@@ -2238,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;