@lunnoa/client 1.1.0 → 1.2.0

package/README.md

@@ -283,6 +283,26 @@ npx @lunnoa/client agents deploy ./agents/triage.ts \
 
 `defineAction` binds catalogue actions only; toolkit `createAction` is for in-platform apps. See Lunnoa Docs under `guides/develop/client/define`, `runs`, and `cli-deploy`.
 
+### CLI discovery
+
+Coding agents (and humans) should list the catalogue for a given key instead of guessing action ids. `--json` is the machine-readable form.
+
+```bash
+npx @lunnoa/client tools list --url … --api-key lna_… --for-agent --json
+npx @lunnoa/client tools search email --for-agent --json
+npx @lunnoa/client tools get http_action_send-request --json
+npx @lunnoa/client apps list --json
+npx @lunnoa/client apps get http --json
+npx @lunnoa/client connections list --app gmail --json
+npx @lunnoa/client agents list --json
+npx @lunnoa/client workflows list --json
+npx @lunnoa/client entity-types list --json
+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.
+
 ## Regenerating the API types
 
 The generic types are generated from the deployment's public OpenAPI spec (`spec/openapi.public.json`, produced by the platform's `export-openapi --public`):

package/dist/cli.js

@@ -2049,6 +2049,646 @@ var LunnoaClient = class {
   }
 };
 
+// src/cli/args.ts
+var GROUPS_WITH_SUBCOMMAND = /* @__PURE__ */ new Set([
+  "workflows",
+  "agents",
+  "entity-types",
+  "tools",
+  "apps",
+  "connections",
+  "projects"
+]);
+var VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "--url",
+  "--api-key",
+  "--access-token",
+  "--project-id",
+  "--out",
+  "--app"
+]);
+function requireFlagValue(flag, value) {
+  if (!value || value.startsWith("--")) {
+    throw new Error(`Missing value for ${flag}`);
+  }
+  return value;
+}
+function parseArgs(argv) {
+  const args = {
+    command: argv[0],
+    out: "./src/lunnoa",
+    json: false,
+    forAgent: false,
+    help: false
+  };
+  let i = 1;
+  if (args.command && GROUPS_WITH_SUBCOMMAND.has(args.command)) {
+    const next = argv[1];
+    if (next && !next.startsWith("--")) {
+      args.subcommand = next;
+      i = 2;
+      if (argv[2] && !argv[2].startsWith("--")) {
+        args.path = argv[2];
+        i = 3;
+      }
+    }
+  }
+  for (; i < argv.length; i += 1) {
+    const flag = argv[i];
+    if (flag === "--help" || flag === "-h") {
+      args.help = true;
+      continue;
+    }
+    if (flag === "--json") {
+      args.json = true;
+      continue;
+    }
+    if (flag === "--for-agent") {
+      args.forAgent = true;
+      continue;
+    }
+    if (flag && VALUE_FLAGS.has(flag)) {
+      const value = requireFlagValue(flag, argv[i + 1]);
+      switch (flag) {
+        case "--url":
+          args.url = value;
+          break;
+        case "--api-key":
+          args.apiKey = value;
+          break;
+        case "--access-token":
+          args.accessToken = value;
+          break;
+        case "--project-id":
+          args.projectId = value;
+          break;
+        case "--out":
+          args.out = value;
+          break;
+        case "--app":
+          args.app = value;
+          break;
+        default:
+          break;
+      }
+      i += 1;
+      continue;
+    }
+    if (flag && !flag.startsWith("--") && !args.path) {
+      args.path = flag;
+      continue;
+    }
+    throw new Error(`Unknown option: ${flag}`);
+  }
+  return args;
+}
+var USAGE = `Usage:
+  npx @lunnoa/client codegen --url <url> --api-key <lna_key> [--out <dir>]
+
+  Discover (do not invent catalogue action ids):
+  npx @lunnoa/client tools list [--app <appId>] [--for-agent] [--json]
+  npx @lunnoa/client tools get <actionId> [--app <appId>] [--json]
+  npx @lunnoa/client tools search <query> [--app <appId>] [--for-agent] [--json]
+  npx @lunnoa/client apps list [--for-agent] [--json]
+  npx @lunnoa/client apps get <appId> [--json]
+  npx @lunnoa/client connections list [--app <appId>] [--json]
+  npx @lunnoa/client connections get <connectionId> [--json]
+  npx @lunnoa/client agents list [--json]
+  npx @lunnoa/client workflows list [--json]
+  npx @lunnoa/client entity-types list [--json]
+  npx @lunnoa/client projects list [--json]
+  npx @lunnoa/client features [--json]
+
+  Deploy (upsert by slug):
+  npx @lunnoa/client workflows deploy <path> --url <url> --api-key <key> --project-id <uuid>
+  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>
+
+Options:
+  --url           Base URL of the Lunnoa Automate deployment
+  --api-key       Machine API key (lna_...)
+  --access-token  User JWT as an alternative to --api-key
+  --project-id    Project UUID (required for workflow/agent deploy)
+  --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
+  --json          Machine-readable JSON (preferred for coding agents)
+  --help          Show this help
+
+Environment: LUNNOA_URL, LUNNOA_API_KEY, LUNNOA_PROJECT_ID
+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
+allowUnknownAttributes is true; use extensions.
+`;
+
+// src/cli/catalog.ts
+function asRecord(value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value;
+  }
+  return void 0;
+}
+function flattenActions(apps) {
+  const out = [];
+  for (const app of apps) {
+    const appId = typeof app.id === "string" ? app.id : "";
+    if (!appId) {
+      continue;
+    }
+    const actions = Array.isArray(app.actions) ? app.actions : [];
+    for (const raw of actions) {
+      const action = asRecord(raw);
+      if (!action || typeof action.id !== "string" || !action.id) {
+        continue;
+      }
+      const actionId = action.id;
+      out.push({
+        appId,
+        appName: typeof app.name === "string" ? app.name : appId,
+        actionId,
+        name: typeof action.name === "string" ? action.name : actionId,
+        description: typeof action.description === "string" ? action.description : "",
+        availableForAgent: typeof action.availableForAgent === "boolean" ? action.availableForAgent : Boolean(app.availableForAgent),
+        needsConnection: typeof action.needsConnection === "boolean" ? action.needsConnection : Boolean(app.needsConnection),
+        inputConfig: action.inputConfig
+      });
+    }
+  }
+  return out;
+}
+function filterActions(actions, filter = {}) {
+  const appId = filter.appId?.trim();
+  const query = filter.query?.trim().toLowerCase();
+  return actions.filter((action) => {
+    if (appId && action.appId !== appId) {
+      return false;
+    }
+    if (filter.forAgent && !action.availableForAgent) {
+      return false;
+    }
+    if (query) {
+      const haystack = [
+        action.appId,
+        action.appName,
+        action.actionId,
+        action.name,
+        action.description
+      ].join(" ").toLowerCase();
+      if (!haystack.includes(query)) {
+        return false;
+      }
+    }
+    return true;
+  });
+}
+function parseActionRef(raw) {
+  const trimmed = raw.trim();
+  const dot = trimmed.indexOf(".");
+  if (dot > 0) {
+    const maybeApp = trimmed.slice(0, dot);
+    const maybeAction = trimmed.slice(dot + 1);
+    if (maybeApp && maybeAction && !maybeApp.includes("_action_")) {
+      return { appId: maybeApp, actionId: maybeAction };
+    }
+  }
+  return { actionId: trimmed };
+}
+function resolveAction(actions, rawRef, appId) {
+  const parsed = parseActionRef(rawRef);
+  const scope = appId?.trim() || parsed.appId;
+  const matches = actions.filter((action) => {
+    if (action.actionId !== parsed.actionId) {
+      return false;
+    }
+    return scope ? action.appId === scope : true;
+  });
+  if (matches.length === 1) {
+    return matches[0];
+  }
+  if (matches.length === 0) {
+    const hint = scope ? `No action "${parsed.actionId}" on app "${scope}". Try: tools search ${parsed.actionId}` : `Unknown action "${parsed.actionId}". Try: tools search ${parsed.actionId}`;
+    throw new Error(hint);
+  }
+  const apps = matches.map((m) => m.appId).join(", ");
+  throw new Error(
+    `Action "${parsed.actionId}" exists on multiple apps (${apps}). Pass --app <appId>.`
+  );
+}
+function extractInputFields(inputConfig) {
+  if (!inputConfig) {
+    return [];
+  }
+  if (Array.isArray(inputConfig)) {
+    return inputConfig.map((item) => fieldFromUnknown(item)).filter((field) => Boolean(field));
+  }
+  const record = asRecord(inputConfig);
+  if (!record) {
+    return [];
+  }
+  if (Array.isArray(record.fields)) {
+    return extractInputFields(record.fields);
+  }
+  if (Array.isArray(record.sections)) {
+    return record.sections.flatMap((section) => {
+      const sectionRecord = asRecord(section);
+      return extractInputFields(sectionRecord?.fields ?? section);
+    });
+  }
+  return Object.entries(record).filter(([, value]) => value === null || typeof value !== "object" || !Array.isArray(value)).map(([id, value]) => {
+    const field = asRecord(value);
+    if (!field) {
+      return { id };
+    }
+    return {
+      id: typeof field.id === "string" ? field.id : id,
+      label: typeof field.label === "string" ? field.label : void 0,
+      type: typeof field.type === "string" ? field.type : typeof field.inputType === "string" ? field.inputType : void 0,
+      required: typeof field.required === "boolean" ? field.required : void 0
+    };
+  });
+}
+function fieldFromUnknown(value) {
+  const field = asRecord(value);
+  if (!field || typeof field.id !== "string" || !field.id) {
+    return void 0;
+  }
+  return {
+    id: field.id,
+    label: typeof field.label === "string" ? field.label : void 0,
+    type: typeof field.type === "string" ? field.type : typeof field.inputType === "string" ? field.inputType : void 0,
+    required: typeof field.required === "boolean" ? field.required : void 0
+  };
+}
+function summarizeAction(action) {
+  return {
+    appId: action.appId,
+    actionId: action.actionId,
+    name: action.name,
+    description: action.description,
+    availableForAgent: action.availableForAgent,
+    needsConnection: action.needsConnection
+  };
+}
+function formatDefineActionSnippet(action) {
+  const fields = extractInputFields(action.inputConfig);
+  const inputBlock = fields.length === 0 ? "    // no inputConfig fields advertised" : fields.map((field) => {
+    const notes = [
+      field.label && field.label !== field.id ? field.label : void 0,
+      field.type,
+      field.required ? "required" : void 0
+    ].filter(Boolean).join(", ");
+    return notes ? `    // ${field.id}${notes ? ` \u2014 ${notes}` : ""}` : `    // ${field.id}`;
+  }).join("\n");
+  return [
+    "defineAction({",
+    `  id: '${action.actionId}',`,
+    `  appId: '${action.appId}',`,
+    "  input: {",
+    inputBlock,
+    "  },",
+    "})"
+  ].join("\n");
+}
+function actionDetail(action) {
+  return {
+    ...summarizeAction(action),
+    inputFields: extractInputFields(action.inputConfig),
+    inputConfig: action.inputConfig ?? null,
+    defineAction: formatDefineActionSnippet(action)
+  };
+}
+
+// src/cli/print.ts
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+function formatTable(rows, columns) {
+  if (rows.length === 0) {
+    return "No results.";
+  }
+  const widths = columns.map((col) => {
+    let width = col.header.length;
+    for (const row of rows) {
+      width = Math.max(width, stringifyCell(row[col.key]).length);
+    }
+    return width;
+  });
+  const header = columns.map((col, i) => pad(col.header, widths[i])).join("  ");
+  const divider = widths.map((w) => "-".repeat(w)).join("  ");
+  const body = rows.map(
+    (row) => columns.map((col, i) => pad(stringifyCell(row[col.key]), widths[i])).join("  ")
+  );
+  return [header, divider, ...body].join("\n");
+}
+function printTable(rows, columns) {
+  console.log(formatTable(rows, columns));
+}
+function stringifyCell(value) {
+  if (value === null || value === void 0) {
+    return "";
+  }
+  if (typeof value === "boolean") {
+    return value ? "yes" : "no";
+  }
+  return String(value);
+}
+function pad(value, width) {
+  return value.length >= width ? value : `${value}${" ".repeat(width - value.length)}`;
+}
+
+// src/cli/discover.ts
+function requireTarget(args, label) {
+  const value = args.path?.trim();
+  if (!value) {
+    throw new Error(`Missing ${label}.`);
+  }
+  return value;
+}
+async function loadCatalog(client) {
+  return flattenActions(await client.workflowApps.list());
+}
+async function runToolsList(client, args) {
+  const actions = filterActions(await loadCatalog(client), {
+    appId: args.app,
+    forAgent: args.forAgent
+  });
+  const rows = actions.map(summarizeAction);
+  if (args.json) {
+    printJson(rows);
+    return;
+  }
+  printTable(rows, [
+    { key: "appId", header: "APP" },
+    { key: "actionId", header: "ACTION" },
+    { key: "name", header: "NAME" },
+    { key: "availableForAgent", header: "FOR_AGENT" },
+    { key: "needsConnection", header: "NEEDS_CONN" }
+  ]);
+}
+async function runToolsGet(client, args) {
+  const ref = requireTarget(args, "action id (example: tools get http_action_send-request)");
+  const action = resolveAction(await loadCatalog(client), ref, args.app);
+  const detail = actionDetail(action);
+  if (args.json) {
+    printJson(detail);
+    return;
+  }
+  console.log(`appId:             ${detail.appId}`);
+  console.log(`actionId:          ${detail.actionId}`);
+  console.log(`name:              ${detail.name}`);
+  if (detail.description) {
+    console.log(`description:       ${detail.description}`);
+  }
+  console.log(`availableForAgent: ${detail.availableForAgent ? "yes" : "no"}`);
+  console.log(`needsConnection:   ${detail.needsConnection ? "yes" : "no"}`);
+  console.log("");
+  console.log("inputFields:");
+  if (detail.inputFields.length === 0) {
+    console.log("  (none advertised)");
+  } else {
+    for (const field of detail.inputFields) {
+      const bits = [
+        field.label && field.label !== field.id ? field.label : void 0,
+        field.type,
+        field.required ? "required" : void 0
+      ].filter(Boolean);
+      console.log(`  ${field.id}${bits.length ? `  (${bits.join(", ")})` : ""}`);
+    }
+  }
+  console.log("");
+  console.log("defineAction:");
+  console.log(detail.defineAction);
+}
+async function runToolsSearch(client, args) {
+  const query = requireTarget(args, "search query (example: tools search email)");
+  const actions = filterActions(await loadCatalog(client), {
+    appId: args.app,
+    forAgent: args.forAgent,
+    query
+  });
+  const rows = actions.map(summarizeAction);
+  if (args.json) {
+    printJson(rows);
+    return;
+  }
+  printTable(rows, [
+    { key: "appId", header: "APP" },
+    { key: "actionId", header: "ACTION" },
+    { key: "name", header: "NAME" },
+    { key: "availableForAgent", header: "FOR_AGENT" },
+    { key: "needsConnection", header: "NEEDS_CONN" }
+  ]);
+}
+async function runAppsList(client, args) {
+  const apps = await client.workflowApps.list();
+  const rows = apps.filter((app) => args.forAgent ? Boolean(app.availableForAgent) : true).filter((app) => args.app ? app.id === args.app : true).map((app) => ({
+    id: app.id ?? "",
+    name: app.name ?? app.id ?? "",
+    availableForAgent: Boolean(app.availableForAgent),
+    needsConnection: Boolean(app.needsConnection),
+    actions: Array.isArray(app.actions) ? app.actions.length : 0
+  }));
+  if (args.json) {
+    printJson(rows);
+    return;
+  }
+  printTable(rows, [
+    { key: "id", header: "APP" },
+    { key: "name", header: "NAME" },
+    { key: "availableForAgent", header: "FOR_AGENT" },
+    { key: "needsConnection", header: "NEEDS_CONN" },
+    { key: "actions", header: "ACTIONS" }
+  ]);
+}
+async function runAppsGet(client, args) {
+  const appId = requireTarget(args, "app id (example: apps get http)");
+  const apps = await client.workflowApps.list();
+  const app = apps.find((item) => item.id === appId);
+  if (!app) {
+    throw new Error(`Unknown app "${appId}". Try: apps list`);
+  }
+  const actions = flattenActions([app]).map(summarizeAction);
+  const payload = {
+    id: app.id,
+    name: app.name,
+    description: app.description ?? "",
+    availableForAgent: Boolean(app.availableForAgent),
+    needsConnection: Boolean(app.needsConnection),
+    isPublished: Boolean(app.isPublished),
+    actions,
+    connectionTypes: Array.isArray(app.connections) ? app.connections : []
+  };
+  if (args.json) {
+    printJson(payload);
+    return;
+  }
+  console.log(`id:                ${payload.id}`);
+  console.log(`name:              ${payload.name}`);
+  if (payload.description) {
+    console.log(`description:       ${payload.description}`);
+  }
+  console.log(`availableForAgent: ${payload.availableForAgent ? "yes" : "no"}`);
+  console.log(`needsConnection:   ${payload.needsConnection ? "yes" : "no"}`);
+  console.log("");
+  printTable(actions, [
+    { key: "actionId", header: "ACTION" },
+    { key: "name", header: "NAME" },
+    { key: "availableForAgent", header: "FOR_AGENT" },
+    { key: "needsConnection", header: "NEEDS_CONN" }
+  ]);
+}
+async function runConnectionsList(client, args) {
+  const connections = await client.connections.list({
+    expansion: ["workflowAppId", "connectionId", "createdAt"]
+  });
+  const rows = connections.filter(
+    (connection) => args.app ? connection.workflowAppId === args.app : true
+  ).map((connection) => ({
+    id: connection.id,
+    name: connection.name,
+    workflowAppId: connection.workflowAppId ?? "",
+    connectionId: connection.connectionId ?? ""
+  }));
+  if (args.json) {
+    printJson(rows);
+    return;
+  }
+  printTable(rows, [
+    { key: "id", header: "ID" },
+    { key: "name", header: "NAME" },
+    { key: "workflowAppId", header: "APP" },
+    { key: "connectionId", header: "TYPE" }
+  ]);
+}
+async function runConnectionsGet(client, args) {
+  const id = requireTarget(args, "connection id (example: connections get <uuid>)");
+  const connection = await client.connections.get(id, {
+    expansion: ["workflowAppId", "connectionId", "createdAt", "updatedAt"]
+  });
+  const payload = {
+    id: connection.id,
+    name: connection.name,
+    workflowAppId: connection.workflowAppId ?? null,
+    connectionId: connection.connectionId ?? null,
+    createdAt: connection.createdAt ?? null,
+    updatedAt: connection.updatedAt ?? null
+  };
+  if (args.json) {
+    printJson(payload);
+    return;
+  }
+  console.log(`id:            ${payload.id}`);
+  console.log(`name:          ${payload.name}`);
+  console.log(`workflowAppId: ${payload.workflowAppId ?? ""}`);
+  console.log(`connectionId:  ${payload.connectionId ?? ""}`);
+}
+async function runAgentsList(client, args) {
+  const agents = await client.agents.list({
+    expansion: ["description", "slug", "managedByCode"]
+  });
+  const rows = agents.map((agent) => ({
+    id: agent.id,
+    name: agent.name,
+    slug: agent.slug ?? "",
+    managedByCode: Boolean(agent.managedByCode),
+    description: agent.description ?? ""
+  }));
+  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 runWorkflowsList(client, args) {
+  const workflows = await client.workflows.list({
+    expansion: ["description", "isActive", "slug", "managedByCode"]
+  });
+  const rows = workflows.map((workflow) => ({
+    id: workflow.id,
+    name: workflow.name,
+    slug: workflow.slug ?? "",
+    isActive: Boolean(workflow.isActive),
+    managedByCode: Boolean(workflow.managedByCode)
+  }));
+  if (args.json) {
+    printJson(rows);
+    return;
+  }
+  printTable(rows, [
+    { key: "id", header: "ID" },
+    { key: "slug", header: "SLUG" },
+    { key: "name", header: "NAME" },
+    { key: "isActive", header: "ACTIVE" },
+    { key: "managedByCode", header: "CODE" }
+  ]);
+}
+async function runEntityTypesList(client, args) {
+  const types = await client.entityTypes.list({
+    expansion: ["description"]
+  });
+  const rows = types.map((type) => ({
+    id: type.id,
+    slug: type.slug,
+    name: type.name,
+    managedByCode: Boolean(type.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 runProjectsList(client, args) {
+  const projects = await client.projects.list({
+    expansion: ["description", "countAgents", "countWorkflows"]
+  });
+  const rows = projects.map((project) => ({
+    id: project.id,
+    name: project.name,
+    description: project.description ?? "",
+    agents: project._count?.agents ?? "",
+    workflows: project._count?.workflows ?? ""
+  }));
+  if (args.json) {
+    printJson(rows);
+    return;
+  }
+  printTable(rows, [
+    { key: "id", header: "ID" },
+    { key: "name", header: "NAME" },
+    { key: "agents", header: "AGENTS" },
+    { key: "workflows", header: "WORKFLOWS" }
+  ]);
+}
+async function runFeatures(client, args) {
+  const features = await client.discovery.enabledFeatures();
+  if (args.json) {
+    printJson(features);
+    return;
+  }
+  const rows = Object.entries(features).filter(([, value]) => typeof value === "boolean").map(([key, value]) => ({
+    feature: key,
+    enabled: value
+  }));
+  printTable(rows, [
+    { key: "feature", header: "FEATURE" },
+    { key: "enabled", header: "ENABLED" }
+  ]);
+}
+
 // src/cli/generate.ts
 function computeDeploymentSchemaFingerprint(entityTypes) {
   const parts = [...entityTypes].map((type) => {
@@ -2537,70 +3177,6 @@ async function loadOptionalConfig() {
 }
 
 // src/cli/index.ts
-function parseArgs(argv) {
-  const args = { command: argv[0], out: "./src/lunnoa" };
-  let i = 1;
-  if (args.command === "workflows" || args.command === "agents" || args.command === "entity-types") {
-    args.subcommand = argv[1];
-    i = 2;
-    if (argv[2] && !argv[2].startsWith("--")) {
-      args.path = argv[2];
-      i = 3;
-    }
-  }
-  for (; i < argv.length; i += 1) {
-    const flag = argv[i];
-    const value = argv[i + 1];
-    switch (flag) {
-      case "--url":
-        args.url = value;
-        i += 1;
-        break;
-      case "--api-key":
-        args.apiKey = value;
-        i += 1;
-        break;
-      case "--access-token":
-        args.accessToken = value;
-        i += 1;
-        break;
-      case "--project-id":
-        args.projectId = value;
-        i += 1;
-        break;
-      case "--out":
-        args.out = value;
-        i += 1;
-        break;
-      default:
-        if (!args.path && !flag.startsWith("--")) {
-          args.path = flag;
-          break;
-        }
-        throw new Error(`Unknown option: ${flag}`);
-    }
-  }
-  return args;
-}
-var USAGE = `Usage:
-  npx @lunnoa/client codegen --url <deployment-url> --api-key <lna_key> [--out <dir>]
-  npx @lunnoa/client workflows deploy <path> --url <url> --api-key <key> --project-id <uuid>
-  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>
-
-Options:
-  --url           Base URL of the Lunnoa Automate deployment
-  --api-key       Machine API key (lna_...)
-  --access-token  User JWT as an alternative to --api-key
-  --project-id    Project UUID (required for workflow/agent deploy)
-  --out           Output directory for lunnoa.generated.ts (codegen; default: ./src/lunnoa)
-
-Environment: LUNNOA_URL, LUNNOA_API_KEY, LUNNOA_PROJECT_ID
-Optional config file: lunnoa.config.ts | .mjs | .js | .json
-
-Entity-type deploy is workspace-scoped (no --project-id). Unknown instance
-attributes are rejected unless allowUnknownAttributes is true; use extensions.
-`;
 async function bindClient(args) {
   const fileConfig = await loadOptionalConfig();
   const url = args.url ?? process.env.LUNNOA_URL ?? fileConfig.url;
@@ -2726,9 +3302,106 @@ async function deployEntityType(args) {
     `Upserted entity type ${result.id} (${payload.slug})` + (typeof result.schemaRevision === "number" ? ` schemaRevision=${result.schemaRevision}` : "")
   );
 }
+var DISCOVERY_SUBCOMMANDS = {
+  tools: ["list", "get", "search"],
+  apps: ["list", "get"],
+  connections: ["list", "get"],
+  features: void 0,
+  projects: ["list"]
+};
+function isDiscoveryCommand(args) {
+  const { command, subcommand } = args;
+  if (!command) {
+    return false;
+  }
+  if (command === "features") {
+    return true;
+  }
+  if (command === "projects" && (subcommand === "list" || !subcommand)) {
+    return true;
+  }
+  if ((command === "agents" || command === "workflows" || command === "entity-types") && subcommand === "list") {
+    return true;
+  }
+  const allowed = DISCOVERY_SUBCOMMANDS[command];
+  return Array.isArray(allowed) && Boolean(subcommand && allowed.includes(subcommand));
+}
+function assertKnownDiscoveryShape(args) {
+  const { command, subcommand } = args;
+  const allowed = command ? DISCOVERY_SUBCOMMANDS[command] : void 0;
+  if (!command || allowed === void 0) {
+    return;
+  }
+  if (!subcommand || !allowed.includes(subcommand)) {
+    throw new Error(
+      `Unknown command: ${command} ${subcommand ?? ""}
+
+${USAGE}`
+    );
+  }
+}
+async function runDiscovery(args) {
+  const { command, subcommand } = args;
+  if (command === "tools" || command === "apps" || command === "connections") {
+    assertKnownDiscoveryShape(args);
+  }
+  if (!isDiscoveryCommand(args)) {
+    return false;
+  }
+  const { client } = await bindClient(args);
+  if (command === "tools" && subcommand === "list") {
+    await runToolsList(client, args);
+    return true;
+  }
+  if (command === "tools" && subcommand === "get") {
+    await runToolsGet(client, args);
+    return true;
+  }
+  if (command === "tools" && subcommand === "search") {
+    await runToolsSearch(client, args);
+    return true;
+  }
+  if (command === "apps" && subcommand === "list") {
+    await runAppsList(client, args);
+    return true;
+  }
+  if (command === "apps" && subcommand === "get") {
+    await runAppsGet(client, args);
+    return true;
+  }
+  if (command === "connections" && subcommand === "list") {
+    await runConnectionsList(client, args);
+    return true;
+  }
+  if (command === "connections" && subcommand === "get") {
+    await runConnectionsGet(client, args);
+    return true;
+  }
+  if (command === "agents" && subcommand === "list") {
+    await runAgentsList(client, args);
+    return true;
+  }
+  if (command === "workflows" && subcommand === "list") {
+    await runWorkflowsList(client, args);
+    return true;
+  }
+  if (command === "entity-types" && subcommand === "list") {
+    await runEntityTypesList(client, args);
+    return true;
+  }
+  if (command === "projects" && (subcommand === "list" || !subcommand)) {
+    await runProjectsList(client, args);
+    return true;
+  }
+  if (command === "features") {
+    await runFeatures(client, args);
+    return true;
+  }
+  return false;
+}
 async function main() {
   const args = parseArgs(process.argv.slice(2));
-  if (!args.command || args.command === "--help" || args.command === "help") {
+  if (!args.command || args.command === "--help" || args.command === "help" || args.help) {
     console.log(USAGE);
     return;
   }
@@ -2736,6 +3409,9 @@ async function main() {
     await runCodegen(args);
     return;
   }
+  if (await runDiscovery(args)) {
+    return;
+  }
   if (args.command === "workflows" && args.subcommand === "deploy") {
     await deployWorkflow(args);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunnoa/client",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "TypeScript SDK for building applications on top of Lunnoa Automate — typed client for the Public API (agents, workflows, executions, entities, knowledge, queues), SSE agent chat streaming, and deployment-specific codegen",
   "type": "module",
   "main": "./dist/index.cjs",

package/skills/lunnoa-client/SKILL.md

@@ -54,8 +54,12 @@ Run these before inventing resources or shipping UI code:
    browser (SDK throws when `window` exists).
 2. **Codegen** — When building typed UIs, run
    `npx @lunnoa/client codegen` against the deployment first.
-3. **Discover before inventing** — `workflowApps.list()`, `agents.list`,
-   `workflows.list`, `entityTypes.list` (and `discovery.enabledFeatures()`).
+3. **Discover before inventing** — prefer the CLI (JSON for agents), then
+   the SDK: `npx @lunnoa/client tools list --json --for-agent`,
+   `tools get <actionId> --json`, `apps list`, `connections list`,
+   `agents|workflows|entity-types|projects list`, `features`.
+   SDK equivalents: `workflowApps.list()`, `agents.list`, `workflows.list`,
+   `entityTypes.list`, `discovery.enabledFeatures()`.
    Do not invent catalogue action ids.
 4. **Run vs deploy** — Ad-hoc: `actions.run` / `runs.start` /
    `workflows.execute`. Durable shared automation: CLI
@@ -361,6 +365,18 @@ const result = await lunnoa.runs.start(ping);
 // or lunnoa.runs.startAndWait(ping)
 ```
 
+Discover the catalogue **before** writing `defineAction` (do not guess ids):
+
+```bash
+npx @lunnoa/client tools list --json --for-agent
+npx @lunnoa/client tools search email --json --for-agent
+npx @lunnoa/client tools get http_action_send-request --json
+npx @lunnoa/client connections list --app gmail --json
+```
+
+`tools get` returns `inputConfig` / `inputFields` and a `defineAction` sketch.
+`tools list` is compact; use `get` for the schema. `--json` is for coding agents.
+
 Deploy to Automate UI (upsert by slug; prefer CLI):
 
 ```bash
@@ -510,7 +526,7 @@ emails (capped; not Azure object IDs).
 3. Call `discovery.enabledFeatures()` and hide unsupported areas.
 4. Build forms/tables from `attributeSchema` / `customInputConfig` (or the generated types).
 5. Render workflow progress from `executionPath`; handle `NEEDS_INPUT` with `submitInput`.
-6. For single-action calls, use `actions.run`; for linear multi-step, use `runs.start` / `defineWorkflow`. Deploy with `npx @lunnoa/client workflows|agents deploy`. Discover catalogue via `workflowApps.list()`.
+6. For single-action calls, use `actions.run`; for linear multi-step, use `runs.start` / `defineWorkflow`. Deploy with `npx @lunnoa/client workflows|agents deploy`. Discover catalogue via `npx @lunnoa/client tools list|get|search` (or `workflowApps.list()`).
 7. For Request Approval nodes, use `approvals.inbox` / `approvals.decide` (or `executions.submitApproval`).
 8. Chat: stream via SSE, handle resume (reconnects) and stop, load history from the task.
 9. Handle `LunnoaApiError`: 401 → re-auth; 403 → hide the capability; 429 → back off.

package/skills/lunnoa-solution-design/SKILL.md

@@ -63,8 +63,9 @@ interrogation.
 ### Integrations
 
 - Which external systems? Prefer existing catalogue apps (Slack, HTTP, CRM…).
-- Do not invent action ids. Implementation must call `workflowApps.list()`
-  (or codegen) to see what this API key can use.
+- Do not invent action ids. Implementation must discover the catalogue for
+  this API key (`npx @lunnoa/client tools list --json --for-agent`, then
+  `tools get <actionId> --json`, or `workflowApps.list()` / codegen).
 
 ### Auth for any custom UI
 
@@ -96,8 +97,9 @@ interrogation.
 2. **Connections stay on Lunnoa.** Definitions only reference connection ids
    (or omit for sole/default resolution). Never ask the partner to put OAuth
    secrets in their app.
-3. **Do not invent catalogue actions.** Discover with `workflowApps.list()` /
-   codegen. Client `defineAction` binds existing catalogue actions; toolkit
+3. **Do not invent catalogue actions.** Discover with
+   `npx @lunnoa/client tools list|get|search --json` (or `workflowApps.list()`
+   / codegen). Client `defineAction` binds existing catalogue actions; toolkit
    `createAction` is a different product (in-platform apps).
 4. **Durable vs ephemeral:** experiments → `runs.start`; shared production
    automation → CLI `workflows deploy` / `agents deploy` by slug.
@@ -131,8 +133,8 @@ can execute. Use this shape:
 - Notes: <CORS, BFF, project id, env vars>
 
 ### Discovery (run first)
-- [ ] workflowApps.list() — catalogue actions for tools/steps
-- [ ] agents.list / workflows.list / entityTypes.list — reuse before create
+- [ ] `npx @lunnoa/client tools list --json --for-agent` then `tools get <id>`
+- [ ] agents / workflows / entity-types / projects list — reuse before create
 - [ ] codegen — if building typed entity/workflow accessors
 
 ### Resources
@@ -175,7 +177,7 @@ continue in a coding turn with that skill loaded.
 action)? Need approvals? Existing HTTP/CRM connections?
 
 **You conclude (example):** Pattern A BFF; Agent `order-status` with tools
-`defineAction` for ERP lookup (after `workflowApps.list`) + optional
+`defineAction` for ERP lookup (after `tools list` / `tools get`) + optional
 workflow for staff notifications; UI = chat only; no agent schedule.
 
 **You produce** the build brief, then hand off.