@lexq/cli 0.1.54 → 0.1.56

package/AGENTS.md

@@ -61,7 +61,7 @@ lexq groups list|get|create|update|delete|reorder
 lexq groups ab-test start|stop|adjust
 lexq versions list|get|create|update|delete|clone
 lexq rules list|get|create|update|delete|reorder|toggle
-lexq facts list|create|update|delete|action-metadata|unregistered
+lexq facts list|create|update|delete|export|action-metadata|unregistered
 lexq domain-templates list|preview|apply
 lexq deploy publish|live|rollback|undeploy|history|detail|overview|deployable|diff|schedule|unschedule|schedules
 lexq analytics dry-run|dry-run-compare|requirements
@@ -69,7 +69,7 @@ lexq analytics simulation start|status|list|cancel|export
 lexq analytics dataset upload|template
 lexq profile <groupId>
 lexq history list|get|stats
-lexq replay decision|start|list|get|cancel
+lexq replay decision|start|list|get|cancel|export
 lexq provenance get|reveal-audits
 lexq logs list|get|action|bulk-action
 lexq webhook-subscriptions list|get|save|delete|test

package/dist/index.js

@@ -111,6 +111,12 @@ async function doFetch(method, path, options) {
   }
   return response;
 }
+function isFileResponse(response) {
+  const disposition = response.headers.get("content-disposition") ?? "";
+  if (disposition.toLowerCase().includes("attachment")) return true;
+  const contentType = response.headers.get("content-type") ?? "";
+  return contentType.includes("text/csv") || contentType.includes("application/octet-stream");
+}
 function assertOk(response, json) {
   if (!response.ok || json.result !== "SUCCESS") {
     throw new ApiError(
@@ -126,10 +132,10 @@ async function apiRequest(method, path, options = {}) {
 }
 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 (isFileResponse(response)) {
+    return { data: await response.text(), meta: null };
   }
+  const contentType = response.headers.get("content-type") ?? "";
   if (response.status === 204 || contentType === "") {
     return { data: void 0, meta: null };
   }
@@ -1164,6 +1170,59 @@ ${data.length} total`);
 // src/commands/facts.ts
 import "commander";
 import dedent6 from "dedent";
+
+// src/lib/export.ts
+import { writeFileSync as writeFileSync2 } from "fs";
+
+// src/types/enums.ts
+var ValueType = ["STRING", "NUMBER", "BOOLEAN", "LIST_STRING", "LIST_NUMBER"];
+var ConflictResolutionMode = ["NONE", "EXCLUSIVE", "MAX_N"];
+var ConflictResolutionStrategy = ["HIGHEST_PRIORITY"];
+var ProfileCacheState = ["HIT", "MISS"];
+var ExportFormat = ["CSV", "JSON"];
+var FailureStatus = ["PENDING", "RESOLVED", "IGNORED"];
+var FailureAction = ["IGNORE", "RESOLVE"];
+var TaskType = ["PLATFORM_WEBHOOK", "SCHEDULED_DEPLOYMENT"];
+var PlatformEventType = [
+  "VERSION_PUBLISHED",
+  "DEPLOYED",
+  "ROLLED_BACK",
+  "UNDEPLOYED",
+  "DEPLOY_SCHEDULED",
+  "DEPLOY_SCHEDULE_CANCELED"
+];
+var WebhookPayloadFormat = ["GENERIC", "SLACK"];
+
+// src/lib/export.ts
+var EXPORT_FORMATS = ExportFormat.map((name) => name.toLowerCase()).sort();
+function parseFormat(value) {
+  if (typeof value === "string" && EXPORT_FORMATS.includes(value)) {
+    return value;
+  }
+  throw new Error(
+    `Unsupported export format: ${String(value)}. Use ${EXPORT_FORMATS.join(" or ")}.`
+  );
+}
+async function runExport(path, format, options) {
+  const { output, params, ...clientOptions } = options;
+  const body = await apiRequest("GET", path, {
+    ...clientOptions,
+    params: { ...params, format }
+  });
+  if (typeof body !== "string") {
+    throw new Error(
+      `Export did not return a file (${path}). Re-run with --verbose to see the response headers.`
+    );
+  }
+  if (output) {
+    writeFileSync2(output, body, "utf-8");
+    console.log(`\u2713 Exported to ${output}`);
+    return;
+  }
+  process.stdout.write(body.endsWith("\n") ? body : body + "\n");
+}
+
+// src/commands/facts.ts
 function registerFactCommands(program) {
   const facts = program.command("facts").description("Manage fact definitions (schema)").addHelpText(
     "after",
@@ -1360,6 +1419,36 @@ ${data.length} unregistered`);
       process.exit(1);
     }
   });
+  facts.command("export").description("Export the fact catalog").option("--as <fmt>", `Exported file format: ${EXPORT_FORMATS.join(" or ")}`, "csv").option("--keyword <keyword>", "Filter by key or name").option("--output <path>", "Output file path").addHelpText(
+    "after",
+    dedent6`
+
+        The two formats carry different things. CSV is the catalog as it stands, system
+        facts included, for reading in a spreadsheet. JSON matches the shape that
+        batch create accepts, so it can be fed straight back in — which is why it leaves
+        out the fields that endpoint does not take.
+
+        Examples:
+          $ lexq facts export --output facts.csv
+          $ lexq facts export --as json --output facts.json
+          $ lexq facts export --keyword user --as json
+      `
+  ).action(async (opts) => {
+    try {
+      const globalOpts = program.opts();
+      await runExport("schema/facts/export", parseFormat(opts.as), {
+        apiKey: globalOpts.apiKey,
+        baseUrl: globalOpts.baseUrl,
+        dryRun: globalOpts.dryRun,
+        verbose: globalOpts.verbose,
+        output: opts.output,
+        params: opts.keyword ? { keyword: opts.keyword } : void 0
+      });
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
   facts.command("action-metadata").description("Get action runtime fact metadata").addHelpText(
     "after",
     dedent6`
@@ -1843,7 +1932,7 @@ async function warnUnregisteredFacts(globalOpts, groupId, versionId) {
 }
 
 // src/commands/analytics.ts
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "fs";
 import "commander";
 import dedent8 from "dedent";
 function registerAnalyticsCommands(program) {
@@ -2191,38 +2280,30 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  sim.command("export").description("Export simulation results").requiredOption("--id <simulationId>", "Simulation ID").option("--format <fmt>", "Export format: csv or json", "json").option("--output <path>", "Output file path").addHelpText(
+  sim.command("export").description("Export simulation results").requiredOption("--id <simulationId>", "Simulation ID").option("--as <fmt>", `Exported file format: ${EXPORT_FORMATS.join(" or ")}`, "json").option("--output <path>", "Output file path").addHelpText(
     "after",
     dedent8`
 
         Only COMPLETED simulations can be exported.
 
         Examples:
-          $ lexq analytics simulation export --id <simId> --format csv --output results.csv
-          $ lexq analytics simulation export --id <simId> --format json
+          $ lexq analytics simulation export --id <simId> --as csv --output results.csv
+          $ lexq analytics simulation export --id <simId> --as json
       `
   ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
-      const exportFormat = opts.format === "csv" ? "csv" : "json";
-      const response = await apiRequest(
-        "GET",
+      await runExport(
         `analytics/simulations/${opts.id}/export`,
+        parseFormat(opts.as),
         {
           apiKey: globalOpts.apiKey,
           baseUrl: globalOpts.baseUrl,
           dryRun: globalOpts.dryRun,
           verbose: globalOpts.verbose,
-          params: { format: exportFormat }
+          output: opts.output
         }
       );
-      if (opts.output) {
-        const text = typeof response === "string" ? response : stringifyJson(response, 2) ?? "";
-        writeFileSync2(opts.output, text, "utf-8");
-        console.log(`\u2713 Exported to ${opts.output}`);
-      } else {
-        printJson(response);
-      }
     } catch (error) {
       printError(error);
       process.exit(1);
@@ -2293,7 +2374,7 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  dataset.command("template").description("Download a dataset template based on version requirements").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Policy version ID").option("--format <fmt>", "Template format: csv or json", "csv").option("--output <path>", "Output file path").addHelpText(
+  dataset.command("template").description("Download a dataset template based on version requirements").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Policy version ID").option("--as <fmt>", `Template file format: ${EXPORT_FORMATS.join(" or ")}`, "csv").option("--output <path>", "Output file path").addHelpText(
     "after",
     dedent8`
 
@@ -2301,7 +2382,7 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
 
         Examples:
           $ lexq analytics dataset template --group-id <gid> --version-id <vid> --output template.csv
-          $ lexq analytics dataset template --group-id <gid> --version-id <vid> --format json
+          $ lexq analytics dataset template --group-id <gid> --version-id <vid> --as json
       `
   ).action(async (opts) => {
     try {
@@ -2312,7 +2393,7 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       if (!apiKey) {
         throw new Error('Not authenticated. Run "lexq auth login" first.');
       }
-      const fmt = opts.format === "json" ? "json" : "csv";
+      const fmt = parseFormat(opts.as);
       const url = new URL(
         `analytics/groups/${opts.groupId}/versions/${opts.versionId}/dataset-template`,
         baseUrl.endsWith("/") ? baseUrl : baseUrl + "/"
@@ -2326,7 +2407,7 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       }
       const text = await response.text();
       if (opts.output) {
-        writeFileSync2(opts.output, text, "utf-8");
+        writeFileSync3(opts.output, text, "utf-8");
         console.log(`\u2713 Template saved to ${opts.output}`);
       } else {
         console.log(text);
@@ -2357,26 +2438,6 @@ function resolveBody(opts) {
 // src/commands/profile.ts
 import "commander";
 import dedent9 from "dedent";
-
-// src/types/enums.ts
-var ValueType = ["STRING", "NUMBER", "BOOLEAN", "LIST_STRING", "LIST_NUMBER"];
-var ConflictResolutionMode = ["NONE", "EXCLUSIVE", "MAX_N"];
-var ConflictResolutionStrategy = ["HIGHEST_PRIORITY"];
-var ProfileCacheState = ["HIT", "MISS"];
-var FailureStatus = ["PENDING", "RESOLVED", "IGNORED"];
-var FailureAction = ["IGNORE", "RESOLVE"];
-var TaskType = ["PLATFORM_WEBHOOK", "SCHEDULED_DEPLOYMENT"];
-var PlatformEventType = [
-  "VERSION_PUBLISHED",
-  "DEPLOYED",
-  "ROLLED_BACK",
-  "UNDEPLOYED",
-  "DEPLOY_SCHEDULED",
-  "DEPLOY_SCHEDULE_CANCELED"
-];
-var WebhookPayloadFormat = ["GENERIC", "SLACK"];
-
-// src/commands/profile.ts
 var ms = (nanos) => nanos == null ? "\u2013" : (nanos / 1e6).toFixed(2);
 var msWithUnit = (nanos) => nanos == null ? "\u2013" : `${(nanos / 1e6).toFixed(2)}ms`;
 function registerProfileCommands(program) {
@@ -2766,6 +2827,36 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
+  replay.command("export").description("Export the result of a completed replay job").requiredOption("--id <jobId>", "Replay job ID").option("--as <fmt>", `Exported file format: ${EXPORT_FORMATS.join(" or ")}`, "json").option("--output <path>", "Output file path").addHelpText(
+    "after",
+    dedent11`
+
+        Only COMPLETED jobs can be exported. A running job has no full result yet, and a
+        partial one reads as the whole thing on the receiving end.
+
+        The two formats carry different things. CSV holds the effect blast radius, whose
+        columns are fixed. JSON holds the changed samples and action parameters, which
+        nest and whose keys differ per tenant. JSON is not a superset of CSV.
+
+        Examples:
+          $ lexq replay export --id <jobId> --as csv --output blast-radius.csv
+          $ lexq replay export --id <jobId> --as json
+      `
+  ).action(async (opts) => {
+    try {
+      const globalOpts = program.opts();
+      await runExport(`replay/jobs/${opts.id}/export`, parseFormat(opts.as), {
+        apiKey: globalOpts.apiKey,
+        baseUrl: globalOpts.baseUrl,
+        dryRun: globalOpts.dryRun,
+        verbose: globalOpts.verbose,
+        output: opts.output
+      });
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
 }
 
 // src/commands/provenance.ts
@@ -3810,6 +3901,20 @@ function registerFactTools(server, callApi) {
     },
     async ({ groupId, versionId }) => callApi("GET", `policy-groups/${groupId}/versions/${versionId}/unregistered-facts`)
   );
+  server.registerTool(
+    "lexq_facts_export",
+    {
+      title: "Export Fact Catalog",
+      description: "Export the fact catalog. The two formats carry different things: CSV is the catalog as it stands, system facts included, for reading in a spreadsheet; JSON matches the shape that batch create accepts, so it can be fed straight back in, which is why it leaves out the fields that endpoint does not take. Returns the file contents as text.",
+      inputSchema: {
+        format: z4.enum(EXPORT_FORMATS).default("csv").describe("Export format"),
+        keyword: z4.string().optional().describe("Filter by key or name")
+      }
+    },
+    async ({ format, keyword }) => callApi("GET", "schema/facts/export", {
+      params: keyword ? { format, keyword } : { format }
+    })
+  );
 }
 
 // src/mcp/tools/deploy.ts
@@ -4139,7 +4244,7 @@ function registerAnalyticsTools(server, callApi) {
       description: "Export simulation results as JSON or CSV. Returns the raw data.",
       inputSchema: {
         simulationId: z6.string().uuid().describe("Simulation ID"),
-        format: z6.enum(["json", "csv"]).default("json").describe("Export format")
+        format: z6.enum(EXPORT_FORMATS).default("json").describe("Export format")
       }
     },
     async ({ simulationId, format }) => callApi("GET", `analytics/simulations/${simulationId}/export`, {
@@ -4197,7 +4302,7 @@ function registerAnalyticsTools(server, callApi) {
       inputSchema: {
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("Version ID"),
-        format: z6.enum(["csv", "json"]).default("csv").describe("Template format")
+        format: z6.enum(EXPORT_FORMATS).default("csv").describe("Template format")
       }
     },
     async ({ groupId, versionId, format }) => callApi("GET", `analytics/groups/${groupId}/versions/${versionId}/dataset-template`, {
@@ -4323,6 +4428,18 @@ function registerReplayTools(server, callApi) {
     },
     async ({ jobId }) => callApi("POST", `replay/jobs/${jobId}/cancel`)
   );
+  server.registerTool(
+    "lexq_replay_export",
+    {
+      title: "Export Replay Result",
+      description: "Export a COMPLETED window replay job. A running job is rejected \u2014 a partial result reads as the whole thing on the receiving end. The two formats carry different things: CSV holds the effect blast radius, whose columns are fixed; JSON holds the changed samples and action parameters, which nest and whose keys differ per tenant. JSON is not a superset of CSV. Returns the file contents as text.",
+      inputSchema: {
+        jobId: z8.string().describe("Replay job ID"),
+        format: z8.enum(EXPORT_FORMATS).default("json").describe("Export format")
+      }
+    },
+    async ({ jobId, format }) => callApi("GET", `replay/jobs/${jobId}/export`, { params: { format } })
+  );
 }
 
 // src/mcp/tools/history.ts

package/dist/mcp/register.js

@@ -18,6 +18,7 @@ import { z } from "zod";
 var ValueType = ["STRING", "NUMBER", "BOOLEAN", "LIST_STRING", "LIST_NUMBER"];
 var ConflictResolutionMode = ["NONE", "EXCLUSIVE", "MAX_N"];
 var ConflictResolutionStrategy = ["HIGHEST_PRIORITY"];
+var ExportFormat = ["CSV", "JSON"];
 var FailureStatus = ["PENDING", "RESOLVED", "IGNORED"];
 var FailureAction = ["IGNORE", "RESOLVE"];
 var TaskType = ["PLATFORM_WEBHOOK", "SCHEDULED_DEPLOYMENT"];
@@ -514,6 +515,10 @@ import { z as z4 } from "zod";
 // src/types/facts.ts
 var FACT_KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]*$/;
 
+// src/lib/export.ts
+import { writeFileSync as writeFileSync2 } from "fs";
+var EXPORT_FORMATS = ExportFormat.map((name) => name.toLowerCase()).sort();
+
 // src/mcp/tools/facts.ts
 var VALUE_TYPES = ValueType;
 function registerFactTools(server, callApi) {
@@ -602,6 +607,20 @@ function registerFactTools(server, callApi) {
     },
     async ({ groupId, versionId }) => callApi("GET", `policy-groups/${groupId}/versions/${versionId}/unregistered-facts`)
   );
+  server.registerTool(
+    "lexq_facts_export",
+    {
+      title: "Export Fact Catalog",
+      description: "Export the fact catalog. The two formats carry different things: CSV is the catalog as it stands, system facts included, for reading in a spreadsheet; JSON matches the shape that batch create accepts, so it can be fed straight back in, which is why it leaves out the fields that endpoint does not take. Returns the file contents as text.",
+      inputSchema: {
+        format: z4.enum(EXPORT_FORMATS).default("csv").describe("Export format"),
+        keyword: z4.string().optional().describe("Filter by key or name")
+      }
+    },
+    async ({ format, keyword }) => callApi("GET", "schema/facts/export", {
+      params: keyword ? { format, keyword } : { format }
+    })
+  );
 }
 
 // src/mcp/tools/deploy.ts
@@ -931,7 +950,7 @@ function registerAnalyticsTools(server, callApi) {
       description: "Export simulation results as JSON or CSV. Returns the raw data.",
       inputSchema: {
         simulationId: z6.string().uuid().describe("Simulation ID"),
-        format: z6.enum(["json", "csv"]).default("json").describe("Export format")
+        format: z6.enum(EXPORT_FORMATS).default("json").describe("Export format")
       }
     },
     async ({ simulationId, format }) => callApi("GET", `analytics/simulations/${simulationId}/export`, {
@@ -989,7 +1008,7 @@ function registerAnalyticsTools(server, callApi) {
       inputSchema: {
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("Version ID"),
-        format: z6.enum(["csv", "json"]).default("csv").describe("Template format")
+        format: z6.enum(EXPORT_FORMATS).default("csv").describe("Template format")
       }
     },
     async ({ groupId, versionId, format }) => callApi("GET", `analytics/groups/${groupId}/versions/${versionId}/dataset-template`, {
@@ -1115,6 +1134,18 @@ function registerReplayTools(server, callApi) {
     },
     async ({ jobId }) => callApi("POST", `replay/jobs/${jobId}/cancel`)
   );
+  server.registerTool(
+    "lexq_replay_export",
+    {
+      title: "Export Replay Result",
+      description: "Export a COMPLETED window replay job. A running job is rejected \u2014 a partial result reads as the whole thing on the receiving end. The two formats carry different things: CSV holds the effect blast radius, whose columns are fixed; JSON holds the changed samples and action parameters, which nest and whose keys differ per tenant. JSON is not a superset of CSV. Returns the file contents as text.",
+      inputSchema: {
+        jobId: z8.string().describe("Replay job ID"),
+        format: z8.enum(EXPORT_FORMATS).default("json").describe("Export format")
+      }
+    },
+    async ({ jobId, format }) => callApi("GET", `replay/jobs/${jobId}/export`, { params: { format } })
+  );
 }
 
 // src/mcp/tools/history.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexq/cli",
-  "version": "0.1.54",
+  "version": "0.1.56",
   "description": "LexQ CLI — manage policies, simulate rules, and deploy from the terminal. Built for humans and AI agents.",
   "type": "module",
   "bin": {
@@ -35,6 +35,7 @@
     "start": "node dist/index.js",
     "test:decimals": "pnpm build && node tests/exact-decimals.mjs",
     "test:fact-key": "node tests/fact-key.mjs",
+    "test:export-format": "node tests/export-format.mjs",
     "prepublishOnly": "pnpm build",
     "knip": "knip",
     "format": "prettier --write \"src/**/*.ts\"",

package/skills/lexq-execution/SKILL.md

@@ -218,11 +218,19 @@ lexq replay start --version-id <candidateVid> --from 2025-01-01 --to 2025-01-31
 lexq replay get --id <jobId>
 lexq replay list
 lexq replay cancel --id <jobId>
+
+# Export a finished job
+lexq replay export --id <jobId> --as csv --output blast-radius.csv
 ```
 
 Replay reports whether the outcome is `DETERMINISTIC` or `REPLAY_MAY_DIFFER` — the latter when the
 original execution depended on values the replay cannot reproduce.
 
+Only a `COMPLETED` job can be exported; a running one has no full result yet, and a partial one reads
+as the whole thing on the receiving end. The two formats answer different questions — CSV carries the
+effect blast radius, whose columns are fixed, and JSON carries the changed samples and action
+parameters, which nest and whose keys differ per tenant.
+
 ## 6. Latency Profile
 
 Per-rule latency distribution for a policy group.

package/skills/lexq-simulation/SKILL.md

@@ -250,7 +250,7 @@ lexq analytics simulation start --json '{
 ```bash
 # 1. Download template (optional)
 lexq analytics dataset template \
-  --group-id <gid> --version-id <vid> --format csv --output template.csv
+  --group-id <gid> --version-id <vid> --as csv --output template.csv
 
 # 2. Upload dataset
 lexq analytics dataset upload --file ./my-data.csv
@@ -304,8 +304,8 @@ lexq analytics simulation cancel --id <simulationId> --force
 ### Export Results
 
 ```bash
-lexq analytics simulation export --id <simulationId> --format json
-lexq analytics simulation export --id <simulationId> --format csv --output results.csv
+lexq analytics simulation export --id <simulationId> --as json
+lexq analytics simulation export --id <simulationId> --as csv --output results.csv
 ```
 
 ## Simulation Response (COMPLETED)