@lexq/cli 0.1.32 → 0.1.33

package/dist/index.js

@@ -59,7 +59,7 @@ var ApiError = class extends Error {
   statusCode;
   errorCode;
 };
-async function apiRequest(method, path, options = {}) {
+async function doFetch(method, path, options) {
   const config = loadConfig();
   const baseUrl = options.baseUrl ?? config.baseUrl;
   const apiKey = options.apiKey ?? config.apiKey;
@@ -69,18 +69,11 @@ async function apiRequest(method, path, options = {}) {
   const url = new URL(path, baseUrl.endsWith("/") ? baseUrl : baseUrl + "/");
   if (options.params) {
     for (const [key, value] of Object.entries(options.params)) {
-      if (value !== void 0 && value !== "") {
-        url.searchParams.set(key, value);
-      }
+      if (value !== void 0 && value !== "") url.searchParams.set(key, value);
     }
   }
-  const headers = {
-    "X-API-KEY": apiKey,
-    Accept: "application/json"
-  };
-  if (options.body) {
-    headers["Content-Type"] = "application/json";
-  }
+  const headers = { "X-API-KEY": apiKey, Accept: "application/json" };
+  if (options.body) headers["Content-Type"] = "application/json";
   if (options.dryRun) {
     const masked = apiKey.length > 8 ? apiKey.substring(0, 4) + "****" + apiKey.substring(apiKey.length - 4) : "****";
     console.log(`${method} ${url.toString()}`);
@@ -94,9 +87,7 @@ async function apiRequest(method, path, options = {}) {
     console.log("\n(Use without --dry-run to execute)");
     process.exit(0);
   }
-  if (options.verbose) {
-    console.error(`\u2192 ${method} ${url.toString()}`);
-  }
+  if (options.verbose) console.error(`\u2192 ${method} ${url.toString()}`);
   const startTime = Date.now();
   const response = await fetch(url.toString(), {
     method,
@@ -106,14 +97,9 @@ async function apiRequest(method, path, options = {}) {
   if (options.verbose) {
     console.error(`\u2190 ${response.status} ${response.statusText} (${Date.now() - startTime}ms)`);
   }
-  const contentType = response.headers.get("content-type") ?? "";
-  if (contentType.includes("text/csv") || contentType.includes("application/octet-stream")) {
-    return response;
-  }
-  if (response.status === 204 || contentType === "") {
-    return void 0;
-  }
-  const json = await response.json();
+  return response;
+}
+function assertOk(response, json) {
   if (!response.ok || json.result !== "SUCCESS") {
     throw new ApiError(
       response.status,
@@ -121,7 +107,23 @@ async function apiRequest(method, path, options = {}) {
       json.message ?? `Request failed with status ${response.status}`
     );
   }
-  return json.data;
+}
+async function apiRequest(method, path, options = {}) {
+  const { data } = await apiRequestWithMeta(method, path, options);
+  return data;
+}
+async function apiRequestWithMeta(method, path, options = {}) {
+  const response = await doFetch(method, path, options);
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.includes("text/csv") || contentType.includes("application/octet-stream")) {
+    return { data: response, meta: null };
+  }
+  if (response.status === 204 || contentType === "") {
+    return { data: void 0, meta: null };
+  }
+  const json = await response.json();
+  assertOk(response, json);
+  return { data: json.data, meta: json.meta ?? null };
 }
 
 // src/lib/output.ts
@@ -163,6 +165,23 @@ function printError(error) {
     console.error(JSON.stringify({ error: "UNKNOWN", message: String(error) }, null, 2));
   }
 }
+function printUnregisteredFactsWarning(facts) {
+  if (facts.length === 0) return;
+  const s = facts.length === 1 ? "" : "s";
+  console.error(
+    `
+\u26A0 ${facts.length} undefined fact${s} referenced \u2014 register to enable validation:`
+  );
+  for (const f of facts) {
+    const type = f.inferredType ?? f.candidateTypes?.[0] ?? "STRING";
+    const note = f.conflict ? ` (ambiguous: ${f.candidateTypes?.join(" | ") ?? "?"})` : "";
+    console.error(`  \u2022 ${f.key} \u2192 ${type}${note}`);
+    console.error(
+      `      lexq facts create --key ${f.key} --name "${f.suggestedName}" --type ${type}`
+    );
+  }
+  console.error("");
+}
 
 // src/commands/auth.ts
 function registerAuthCommands(program) {
@@ -935,7 +954,7 @@ ${data.length} total`);
     try {
       const globalOpts = program.opts();
       const body = JSON.parse(opts.json);
-      const data = await apiRequest(
+      const { data, meta } = await apiRequestWithMeta(
         "POST",
         `policy-groups/${opts.groupId}/versions/${opts.versionId}/rules`,
         {
@@ -947,6 +966,7 @@ ${data.length} total`);
         }
       );
       printJson(data);
+      printUnregisteredFactsWarning(meta?.unregisteredFacts ?? []);
     } catch (error) {
       printError(error);
       process.exit(1);
@@ -970,7 +990,7 @@ ${data.length} total`);
     try {
       const globalOpts = program.opts();
       const body = JSON.parse(opts.json);
-      const data = await apiRequest(
+      const { data, meta } = await apiRequestWithMeta(
         "PUT",
         `policy-groups/${opts.groupId}/versions/${opts.versionId}/rules/${opts.id}`,
         {
@@ -982,6 +1002,7 @@ ${data.length} total`);
         }
       );
       printJson(data);
+      printUnregisteredFactsWarning(meta?.unregisteredFacts ?? []);
     } catch (error) {
       printError(error);
       process.exit(1);
@@ -1099,6 +1120,7 @@ function registerFactCommands(program) {
 
         Commands:
           list             List all fact definitions
+          unregistered     List facts referenced by a version but not yet defined
           create           Register a new fact
           update           Update fact metadata
           delete           Remove a fact definition
@@ -1143,6 +1165,52 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
+  facts.command("unregistered").description("List facts referenced by a version but not yet defined").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Policy version ID").addHelpText(
+    "after",
+    dedent6`
+
+        Facts used in a version's rules that have no definition yet (read-only).
+        Does not block publish/deploy — register them to enable validation.
+
+        Example:
+          $ lexq facts unregistered --group-id <gid> --version-id <vid> --format table
+      `
+  ).action(async (opts) => {
+    try {
+      const globalOpts = program.opts();
+      const format = globalOpts.format ?? "json";
+      const data = await apiRequest(
+        "GET",
+        `policy-groups/${opts.groupId}/versions/${opts.versionId}/unregistered-facts`,
+        {
+          apiKey: globalOpts.apiKey,
+          baseUrl: globalOpts.baseUrl,
+          dryRun: globalOpts.dryRun,
+          verbose: globalOpts.verbose
+        }
+      );
+      if (format === "table") {
+        printTable(
+          ["Key", "Type", "Suggested Name", "Conflict", "Sources"],
+          data.map((f) => [
+            f.key,
+            f.inferredType ?? f.candidateTypes?.join("|") ?? "?",
+            f.suggestedName,
+            f.conflict ? "\u2713" : "\u2013",
+            f.sources.map((s) => `${s.kind}:${s.field}`).join(", ")
+          ]),
+          { truncate: 28 }
+        );
+        console.log(`
+${data.length} unregistered`);
+      } else {
+        printJson(data);
+      }
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
   facts.command("create").description("Create a new fact definition").option("--key <key>", "Fact key (lowercase, underscores)").option("--name <n>", "Display name").option("--type <type>", "Value type: STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER").option("--description <desc>", "Description").option("--required", "Mark as required", false).option("--json <body>", "Full request body as JSON (overrides other options)").addHelpText(
     "after",
     dedent6`
@@ -1316,6 +1384,7 @@ function registerDeployCommands(program) {
   ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
+      await warnUnregisteredFacts(globalOpts, opts.groupId, opts.versionId);
       await apiRequest(
         "POST",
         `policy-groups/${opts.groupId}/versions/${opts.versionId}/publish`,
@@ -1345,6 +1414,7 @@ function registerDeployCommands(program) {
   ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
+      await warnUnregisteredFacts(globalOpts, opts.groupId, opts.versionId);
       await apiRequest("POST", `policy-groups/${opts.groupId}/deploy`, {
         apiKey: globalOpts.apiKey,
         baseUrl: globalOpts.baseUrl,
@@ -1588,6 +1658,18 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
     }
   });
 }
+async function warnUnregisteredFacts(globalOpts, groupId, versionId) {
+  if (globalOpts.dryRun) return;
+  try {
+    const facts = await apiRequest(
+      "GET",
+      `policy-groups/${groupId}/versions/${versionId}/unregistered-facts`,
+      { apiKey: globalOpts.apiKey, baseUrl: globalOpts.baseUrl, verbose: globalOpts.verbose }
+    );
+    printUnregisteredFactsWarning(facts);
+  } catch {
+  }
+}
 
 // src/commands/analytics.ts
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
@@ -2858,14 +2940,17 @@ function createCallApiFromConfig() {
         apiKey: config.apiKey,
         baseUrl: config.baseUrl
       };
-      const data = await apiRequest(method, path, {
+      const { data, meta } = await apiRequestWithMeta(method, path, {
         ...clientOpts,
         body: opts?.body,
         params: opts?.params
       });
-      return {
-        content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
-      };
+      const content = [
+        { type: "text", text: JSON.stringify(data, null, 2) }
+      ];
+      const warning = formatUnregisteredFactWarning(meta);
+      if (warning) content.push({ type: "text", text: warning });
+      return { content };
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       return {
@@ -2881,6 +2966,22 @@ function paginationParams(page, size) {
   if (size !== void 0) params.size = String(size);
   return params;
 }
+function formatUnregisteredFactWarning(meta) {
+  const facts = meta?.unregisteredFacts ?? [];
+  if (facts.length === 0) return null;
+  const lines = facts.map((f) => {
+    if (f.inferredType) {
+      return `  \u2022 ${f.key} (${f.inferredType}) \u2014 register: lexq_facts_create({ key: "${f.key}", name: "${f.suggestedName}", type: "${f.inferredType}" })`;
+    }
+    const choices = f.candidateTypes?.join(" | ") ?? "STRING | NUMBER | BOOLEAN";
+    return `  \u2022 ${f.key} (ambiguous) \u2014 pick a type (${choices}), then lexq_facts_create({ key: "${f.key}", name: "${f.suggestedName}", type: <chosen> })`;
+  });
+  return [
+    `\u26A0 The saved rule references ${facts.length} fact(s) not defined in the schema. The rule was saved \u2014 this does not block \u2014 but undefined facts skip type validation and the dry-run requirements analyzer.`,
+    ...lines,
+    `Register them now so the rule validates as intended, or call lexq_facts_unregistered to review the version's full list.`
+  ].join("\n");
+}
 
 // src/mcp/tools/status.ts
 function registerStatusTools(server, callApi) {
@@ -3157,6 +3258,9 @@ function registerRuleTools(server, callApi) {
         If a required key is missing, ask the user to confirm the type, isRequired, and description
         before calling lexq_facts_create — registering facts enables type validation, Console UI
         autocomplete, and the dry-run requirements analyzer.
+        
+        After saving, lexq_facts_unregistered lists any keys this version references but has not
+        defined (non-blocking, version-wide) — use it to decide what to register.
 
         Condition: { type: "SINGLE", field, operator, value, valueType } or { type: "GROUP", operator: "AND"|"OR", children: [...] }
         Operators: EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, CONTAINS, IN, NOT_IN
@@ -3342,6 +3446,18 @@ function registerFactTools(server, callApi) {
     },
     async () => callApi("GET", "schema/action-metadata")
   );
+  server.registerTool(
+    "lexq_facts_unregistered",
+    {
+      title: "List Unregistered Facts",
+      description: "List facts referenced by a version's rules but not yet defined (read-only \u2014 does not block publish/deploy, INV-4). Version-wide: covers every rule in the version. Each entry carries the inferred type, suggested name, and where it is referenced (condition/action). Register them with lexq_facts_create to enable type validation and the dry-run requirements analyzer.",
+      inputSchema: {
+        groupId: z4.string().uuid().describe("Policy group ID"),
+        versionId: z4.string().uuid().describe("Version ID")
+      }
+    },
+    async ({ groupId, versionId }) => callApi("GET", `policy-groups/${groupId}/versions/${versionId}/unregistered-facts`)
+  );
 }
 
 // src/mcp/tools/deploy.ts
@@ -3351,7 +3467,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_publish",
     {
       title: "Publish Version",
-      description: "Publish a DRAFT version (DRAFT \u2192 ACTIVE). Locks the version from further edits. Must have at least one rule.",
+      description: "Publish a DRAFT version (DRAFT \u2192 ACTIVE). Locks the version from further edits. Must have at least one rule. Undefined facts referenced by rules do not block publishing (INV-4); call lexq_facts_unregistered first to review them.",
       inputSchema: {
         groupId: z5.string().uuid().describe("Policy group ID"),
         versionId: z5.string().uuid().describe("Version ID to publish"),
@@ -3364,7 +3480,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_live",
     {
       title: "Deploy to Live",
-      description: "Deploy an ACTIVE (published) version to live traffic. Takes effect immediately.",
+      description: "Deploy an ACTIVE (published) version to live traffic. Takes effect immediately. Undefined facts do not block deployment (INV-4); use lexq_facts_unregistered to review what the version references but has not defined.",
       inputSchema: {
         groupId: z5.string().uuid().describe("Policy group ID"),
         versionId: z5.string().uuid().describe("Version ID to deploy"),

package/dist/mcp/register.d.ts

@@ -1,5 +1,30 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
+declare const ValueType: readonly ["STRING", "NUMBER", "BOOLEAN", "LIST_STRING", "LIST_NUMBER"];
+type ValueType = (typeof ValueType)[number];
+declare const Confidence: readonly ["EXACT", "AMBIGUOUS"];
+type Confidence = (typeof Confidence)[number];
+declare const SourceKind: readonly ["CONDITION", "ACTION"];
+type SourceKind = (typeof SourceKind)[number];
+
+interface ResponseMeta {
+    unregisteredFacts?: UnregisteredFact[];
+}
+interface UnregisteredFact {
+    key: string;
+    inferredType: ValueType | null;
+    confidence: Confidence;
+    conflict: boolean;
+    candidateTypes: ValueType[] | null;
+    suggestedName: string;
+    sources: UnregisteredFactSource[];
+}
+interface UnregisteredFactSource {
+    kind: SourceKind;
+    field: string;
+    operator?: string;
+}
+
 interface McpToolResult {
     [key: string]: unknown;
     content: Array<{
@@ -25,13 +50,22 @@ type CallApi = (method: string, path: string, opts?: {
     };
 }) => Promise<McpToolResult>;
 declare function paginationParams(page?: number, size?: number): Record<string, string>;
+/**
+ * Builds a salient, actionable warning from a response's meta when it reports facts that
+ * rules reference but the schema does not define. Returns null when there is nothing to warn.
+ *
+ * Shared by both CallApi implementations (CLI stdio here, lexq-mcp HTTP via @lexq/cli/mcp)
+ * so the agent-facing text is identical on every surface. The backend only populates
+ * meta.unregisteredFacts on rule create/update, so this only ever fires there.
+ */
+declare function formatUnregisteredFactWarning(meta: ResponseMeta | null | undefined): string | null;
 
 /**
- * Registers all 66 MCP tools on the given server.
+ * Registers all MCP tools on the given server.
  *
  * @param server - McpServer instance
  * @param callApi - API caller function (config-based for CLI, Bearer-based for HTTP)
  */
 declare function registerAllTools(server: McpServer, callApi: CallApi): void;
 
-export { type CallApi, type McpToolResult, paginationParams, registerAllTools };
+export { type CallApi, type McpToolResult, formatUnregisteredFactWarning, paginationParams, registerAllTools };

package/dist/mcp/register.js

@@ -161,6 +161,22 @@ function paginationParams(page, size) {
   if (size !== void 0) params.size = String(size);
   return params;
 }
+function formatUnregisteredFactWarning(meta) {
+  const facts = meta?.unregisteredFacts ?? [];
+  if (facts.length === 0) return null;
+  const lines = facts.map((f) => {
+    if (f.inferredType) {
+      return `  \u2022 ${f.key} (${f.inferredType}) \u2014 register: lexq_facts_create({ key: "${f.key}", name: "${f.suggestedName}", type: "${f.inferredType}" })`;
+    }
+    const choices = f.candidateTypes?.join(" | ") ?? "STRING | NUMBER | BOOLEAN";
+    return `  \u2022 ${f.key} (ambiguous) \u2014 pick a type (${choices}), then lexq_facts_create({ key: "${f.key}", name: "${f.suggestedName}", type: <chosen> })`;
+  });
+  return [
+    `\u26A0 The saved rule references ${facts.length} fact(s) not defined in the schema. The rule was saved \u2014 this does not block \u2014 but undefined facts skip type validation and the dry-run requirements analyzer.`,
+    ...lines,
+    `Register them now so the rule validates as intended, or call lexq_facts_unregistered to review the version's full list.`
+  ].join("\n");
+}
 
 // src/mcp/tools/versions.ts
 function registerVersionTools(server, callApi) {
@@ -290,6 +306,9 @@ function registerRuleTools(server, callApi) {
         If a required key is missing, ask the user to confirm the type, isRequired, and description
         before calling lexq_facts_create — registering facts enables type validation, Console UI
         autocomplete, and the dry-run requirements analyzer.
+        
+        After saving, lexq_facts_unregistered lists any keys this version references but has not
+        defined (non-blocking, version-wide) — use it to decide what to register.
 
         Condition: { type: "SINGLE", field, operator, value, valueType } or { type: "GROUP", operator: "AND"|"OR", children: [...] }
         Operators: EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, CONTAINS, IN, NOT_IN
@@ -475,6 +494,18 @@ function registerFactTools(server, callApi) {
     },
     async () => callApi("GET", "schema/action-metadata")
   );
+  server.registerTool(
+    "lexq_facts_unregistered",
+    {
+      title: "List Unregistered Facts",
+      description: "List facts referenced by a version's rules but not yet defined (read-only \u2014 does not block publish/deploy, INV-4). Version-wide: covers every rule in the version. Each entry carries the inferred type, suggested name, and where it is referenced (condition/action). Register them with lexq_facts_create to enable type validation and the dry-run requirements analyzer.",
+      inputSchema: {
+        groupId: z4.string().uuid().describe("Policy group ID"),
+        versionId: z4.string().uuid().describe("Version ID")
+      }
+    },
+    async ({ groupId, versionId }) => callApi("GET", `policy-groups/${groupId}/versions/${versionId}/unregistered-facts`)
+  );
 }
 
 // src/mcp/tools/deploy.ts
@@ -484,7 +515,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_publish",
     {
       title: "Publish Version",
-      description: "Publish a DRAFT version (DRAFT \u2192 ACTIVE). Locks the version from further edits. Must have at least one rule.",
+      description: "Publish a DRAFT version (DRAFT \u2192 ACTIVE). Locks the version from further edits. Must have at least one rule. Undefined facts referenced by rules do not block publishing (INV-4); call lexq_facts_unregistered first to review them.",
       inputSchema: {
         groupId: z5.string().uuid().describe("Policy group ID"),
         versionId: z5.string().uuid().describe("Version ID to publish"),
@@ -497,7 +528,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_live",
     {
       title: "Deploy to Live",
-      description: "Deploy an ACTIVE (published) version to live traffic. Takes effect immediately.",
+      description: "Deploy an ACTIVE (published) version to live traffic. Takes effect immediately. Undefined facts do not block deployment (INV-4); use lexq_facts_unregistered to review what the version references but has not defined.",
       inputSchema: {
         groupId: z5.string().uuid().describe("Policy group ID"),
         versionId: z5.string().uuid().describe("Version ID to deploy"),
@@ -1175,6 +1206,7 @@ function registerAllTools(server, callApi) {
   registerWebhookSubscriptionTools(server, callApi);
 }
 export {
+  formatUnregisteredFactWarning,
   paginationParams,
   registerAllTools
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexq/cli",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "description": "LexQ CLI — manage policies, simulate rules, and deploy from the terminal. Built for humans and AI agents.",
   "type": "module",
   "bin": {