@lexq/cli 1.0.2 → 1.1.0

package/AGENTS.md

@@ -180,8 +180,12 @@ The MCP toolset mirrors the CLI command inventory one-to-one.
 - Releasing is two steps, in this order. Raise `version` in package.json inside the pull request, so a reviewer
   sees the number beside the change that justifies it. After it merges, push the matching `v<version>` tag — that
   tag is what publishes. A tag that disagrees with package.json is rejected before anything reaches npm.
-- Pick the number by what breaks. On 0.x a breaking change is a minor bump (0.1 → 0.2), not a patch. Raising the
-  Node floor, a peer dependency major, or any change to what `tools/list` returns is breaking.
+- Pick the number by what breaks. A change is breaking when a call that used to work now fails or does something
+  else. That includes removing or renaming a tool, command, option or parameter, changing a parameter's type,
+  adding a required parameter or making an optional one required, and narrowing the values a parameter accepts.
+  Raising the Node floor or moving a peer dependency to a new major version is breaking too. A breaking change
+  raises the major number. A new tool, command, option or optional parameter raises the minor, and anything else,
+  including a changed description, raises the patch.
 - Gates before commit: `pnpm typecheck` (zero errors), `pnpm lint` (zero warnings), `pnpm test:fact-key`,
   `pnpm test:decimals`.
 - Multi-line CLI help and MCP tool descriptions use `dedent` — template-literal indentation leaks into LLM context.

package/dist/index.js

@@ -804,18 +804,18 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  versions.command("update").description("Update a draft version metadata").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--id <versionId>", "Policy version ID").option("--commit-message <message>", "Commit message").option("--effective-from <instant>", `Effective start, ${INSTANT}`).option("--effective-to <instant>", `Effective end, ${INSTANT}`).option("--json <body>", "Full request body as JSON (overrides other options)").addHelpText(
+  versions.command("update").description("Update a draft version metadata").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--id <versionId>", "Policy version ID").option("--commit-message <message>", "Commit message").option("--effective-from <instant>", `Effective start, ${INSTANT}`).option("--effective-to <instant>", `Effective end, ${INSTANT}`).option("--clear-effective-from", "Remove the effective start").option("--clear-effective-to", "Remove the effective end").option("--json <body>", "Full request body as JSON (overrides other options)").addHelpText(
     "after",
     dedent4`
 
         Only DRAFT versions can be updated. Published (ACTIVE) versions are immutable.
 
-        An omitted --commit-message keeps its value, but --effective-from and --effective-to
-        are replaced together: one you omit is cleared. To keep the effective window, pass
-        both current values (read them with lexq versions get).
+        Omitted options keep their current values. To remove an end of the effective
+        window, pass --clear-effective-from or --clear-effective-to instead of a value.
 
-        Example:
+        Examples:
           $ lexq versions update --group-id <gid> --id <vid> --commit-message "Updated rules"
+          $ lexq versions update --group-id <gid> --id <vid> --clear-effective-to
       `
   ).action(async (opts) => {
     try {
@@ -911,6 +911,8 @@ function buildUpdateBody(opts) {
   if (opts.commitMessage) body.commitMessage = opts.commitMessage;
   if (opts.effectiveFrom) body.effectiveFrom = opts.effectiveFrom;
   if (opts.effectiveTo) body.effectiveTo = opts.effectiveTo;
+  if (opts.clearEffectiveFrom) body.clearEffectiveFrom = true;
+  if (opts.clearEffectiveTo) body.clearEffectiveTo = true;
   return body;
 }
 
@@ -1642,6 +1644,7 @@ function registerDeployCommands(program) {
 
         Locks the version permanently. Rules cannot be modified after publishing.
         A snapshot hash is generated for integrity verification.
+        A version whose effective end has already passed cannot be published (P-058).
 
         Example:
           $ lexq deploy publish --group-id <gid> --version-id <vid> --memo "Validated via dry-run"
@@ -1672,6 +1675,8 @@ function registerDeployCommands(program) {
     dedent7`
 
         Takes effect immediately. The version starts receiving production traffic.
+        A version whose effective start has not arrived (P-037) or whose effective end
+        has passed (P-058) is rejected.
 
         Example:
           $ lexq deploy live --group-id <gid> --version-id <vid> --memo "Go live — v3"
@@ -1698,7 +1703,8 @@ function registerDeployCommands(program) {
     dedent7`
 
         Reverts to the version that was live before the current one.
-        Only available if the previous version is still ACTIVE.
+        Only available if the previous version is still ACTIVE and its effective end
+        has not passed (P-058).
 
         Example:
           $ lexq deploy rollback --group-id <gid> --memo "High error rate" --force
@@ -2201,7 +2207,7 @@ function registerAnalyticsCommands(program) {
         Use --format table for summary view.
       `
   );
-  sim.command("start").description("Start a new batch simulation").requiredOption("--json <body>", "Simulation request body as JSON").option("--file <path>", "Read request body from a JSON file").addHelpText(
+  sim.command("start").description("Start a new batch simulation").option("--json <body>", "Simulation request body as JSON").option("--file <path>", "Read request body from a JSON file").addHelpText(
     "after",
     dedent8`
 
@@ -2220,7 +2226,9 @@ function registerAnalyticsCommands(program) {
                 "maxRecords": 1000
               }
             }'
-            
+
+          $ lexq analytics simulation start --file simulation.json
+
         Dataset types: HISTORICAL, UPLOADED, MANUAL
         Dataset sources: EXECUTION_LOGS, S3_BUCKET, REQUEST_BODY
         HISTORICAL from / to are yyyy-MM-dd, whole days in the organization time zone, both inclusive.
@@ -2228,6 +2236,9 @@ function registerAnalyticsCommands(program) {
   ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
+      if (!opts.json && !opts.file) {
+        throw new Error("Request body is required. Use --json or --file.");
+      }
       const body = resolveBody(opts);
       const data = await apiRequest("POST", "analytics/simulations", {
         apiKey: globalOpts.apiKey,
@@ -2578,7 +2589,7 @@ function registerProfileCommands(program) {
   program.command("profile <groupId>").description("Per-rule latency profile with relative slow-rule flags").option(
     "--rule <ruleId>",
     `Single-rule detail (distributions + ${LATENCY_WINDOW_MILLIS / 1e3}s window series)`
-  ).option("--version <versionId>", "Version to inspect (default: live version)").option(
+  ).option("--version-id <versionId>", "Version to inspect (default: live version)").option(
     "--from <instant>",
     `Window start, ISO-8601 instant (default: ${PROFILE_DEFAULT_WINDOW_HOURS}h ago)`
   ).option("--to <instant>", "Window end, ISO-8601 instant (default: now)").option("--cache <state>", "Cache dimension for the rule table: HIT | MISS (default: HIT)").addHelpText(
@@ -2594,7 +2605,7 @@ function registerProfileCommands(program) {
         Examples:
           $ lexq profile <groupId>
           $ lexq profile <groupId> --cache MISS --from 2026-07-01T00:00:00Z
-          $ lexq profile <groupId> --rule <ruleId> --version <versionId>
+          $ lexq profile <groupId> --rule <ruleId> --version-id <versionId>
       `
   ).action(async (groupId, opts) => {
     try {
@@ -2604,7 +2615,7 @@ function registerProfileCommands(program) {
         throw new Error(`--cache must be one of: ${ProfileCacheState.join(" | ")}`);
       }
       const params = {};
-      if (opts.version) params.versionId = opts.version;
+      if (opts.versionId) params.versionId = opts.versionId;
       if (opts.from) params.from = opts.from;
       if (opts.to) params.to = opts.to;
       if (opts.cache) params.cacheState = opts.cache;
@@ -3743,13 +3754,15 @@ function registerVersionTools(server, callApi) {
     {
       title: "Update Policy Version",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Update a DRAFT version. Only DRAFT versions can be modified. An omitted commitMessage keeps its value, but effectiveFrom and effectiveTo are replaced together: one you omit is cleared. To keep the effective window, send both current values (read them with lexq_versions_get).",
+      description: "Update a DRAFT version. Only DRAFT versions can be modified. Omitted fields keep their current values. To remove an end of the effective window, set clearEffectiveFrom or clearEffectiveTo to true instead of sending a value.",
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
         versionId: z3.string().uuid().describe("Version ID"),
         commitMessage: z3.string().optional().describe("New commit message"),
-        effectiveFrom: z3.string().optional().describe(`Effective start, ${INSTANT} Omit it and the start is cleared.`),
-        effectiveTo: z3.string().optional().describe(`Effective end, ${INSTANT} Omit it and the end is cleared.`)
+        effectiveFrom: z3.string().optional().describe(`Effective start, ${INSTANT} Omit it to keep the current start.`),
+        effectiveTo: z3.string().optional().describe(`Effective end, ${INSTANT} Omit it to keep the current end.`),
+        clearEffectiveFrom: z3.boolean().optional().describe("Set to true to remove the effective start. Do not send effectiveFrom with it."),
+        clearEffectiveTo: z3.boolean().optional().describe("Set to true to remove the effective end. Do not send effectiveTo with it.")
       })
     },
     async ({ groupId, versionId, ...body }) => callApi("PUT", `policy-groups/${groupId}/versions/${versionId}`, { body })
@@ -4092,7 +4105,7 @@ function registerFactTools(server, callApi) {
     {
       title: "List Unregistered Facts",
       annotations: { readOnlyHint: true },
-      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.",
+      description: "List facts referenced by a version's rules but not yet defined (read-only \u2014 does not block publish/deploy). 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: z5.object({
         groupId: z5.string().uuid().describe("Policy group ID"),
         versionId: z5.string().uuid().describe("Version ID")
@@ -4125,7 +4138,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Publish Version",
       annotations: { readOnlyHint: false, destructiveHint: false },
-      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. Publishing fails if the version's compiled rules exceed ${MAX_SNAPSHOT_BYTES / 1024} KB.`,
+      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; call lexq_facts_unregistered first to review them. Publishing fails if the version's compiled rules exceed ${MAX_SNAPSHOT_BYTES / 1024} KB, or if its effective end has already passed (P-058); move the end into the future with lexq_versions_update first.`,
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("Version ID to publish"),
@@ -4139,7 +4152,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Deploy to Live",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Deploy an ACTIVE (published) version to live traffic. Takes effect immediately. Versions whose effective start date has not arrived are rejected (P-037) \u2014 use lexq_deploy_schedule for those. Undefined facts do not block deployment (INV-4); use lexq_facts_unregistered to review what the version references but has not defined.",
+      description: "Deploy an ACTIVE (published) version to live traffic. Takes effect immediately. Versions whose effective start date has not arrived are rejected (P-037) \u2014 use lexq_deploy_schedule for those. Versions whose effective end has passed are rejected (P-058). Undefined facts do not block deployment; use lexq_facts_unregistered to review what the version references but has not defined.",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("Version ID to deploy"),
@@ -4155,7 +4168,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Rollback Deployment",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Rollback to the previous deployed version. Only available if there is a previous version.",
+      description: "Rollback to the previous deployed version. Only available if there is a previous version that is still ACTIVE and whose effective end has not passed (P-058).",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         memo: z6.string().min(1).describe("Rollback reason (required)")

package/dist/mcp/register.js

@@ -321,13 +321,15 @@ function registerVersionTools(server, callApi) {
     {
       title: "Update Policy Version",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Update a DRAFT version. Only DRAFT versions can be modified. An omitted commitMessage keeps its value, but effectiveFrom and effectiveTo are replaced together: one you omit is cleared. To keep the effective window, send both current values (read them with lexq_versions_get).",
+      description: "Update a DRAFT version. Only DRAFT versions can be modified. Omitted fields keep their current values. To remove an end of the effective window, set clearEffectiveFrom or clearEffectiveTo to true instead of sending a value.",
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
         versionId: z3.string().uuid().describe("Version ID"),
         commitMessage: z3.string().optional().describe("New commit message"),
-        effectiveFrom: z3.string().optional().describe(`Effective start, ${INSTANT} Omit it and the start is cleared.`),
-        effectiveTo: z3.string().optional().describe(`Effective end, ${INSTANT} Omit it and the end is cleared.`)
+        effectiveFrom: z3.string().optional().describe(`Effective start, ${INSTANT} Omit it to keep the current start.`),
+        effectiveTo: z3.string().optional().describe(`Effective end, ${INSTANT} Omit it to keep the current end.`),
+        clearEffectiveFrom: z3.boolean().optional().describe("Set to true to remove the effective start. Do not send effectiveFrom with it."),
+        clearEffectiveTo: z3.boolean().optional().describe("Set to true to remove the effective end. Do not send effectiveTo with it.")
       })
     },
     async ({ groupId, versionId, ...body }) => callApi("PUT", `policy-groups/${groupId}/versions/${versionId}`, { body })
@@ -674,7 +676,7 @@ function registerFactTools(server, callApi) {
     {
       title: "List Unregistered Facts",
       annotations: { readOnlyHint: true },
-      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.",
+      description: "List facts referenced by a version's rules but not yet defined (read-only \u2014 does not block publish/deploy). 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: z5.object({
         groupId: z5.string().uuid().describe("Policy group ID"),
         versionId: z5.string().uuid().describe("Version ID")
@@ -707,7 +709,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Publish Version",
       annotations: { readOnlyHint: false, destructiveHint: false },
-      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. Publishing fails if the version's compiled rules exceed ${MAX_SNAPSHOT_BYTES / 1024} KB.`,
+      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; call lexq_facts_unregistered first to review them. Publishing fails if the version's compiled rules exceed ${MAX_SNAPSHOT_BYTES / 1024} KB, or if its effective end has already passed (P-058); move the end into the future with lexq_versions_update first.`,
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("Version ID to publish"),
@@ -721,7 +723,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Deploy to Live",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Deploy an ACTIVE (published) version to live traffic. Takes effect immediately. Versions whose effective start date has not arrived are rejected (P-037) \u2014 use lexq_deploy_schedule for those. Undefined facts do not block deployment (INV-4); use lexq_facts_unregistered to review what the version references but has not defined.",
+      description: "Deploy an ACTIVE (published) version to live traffic. Takes effect immediately. Versions whose effective start date has not arrived are rejected (P-037) \u2014 use lexq_deploy_schedule for those. Versions whose effective end has passed are rejected (P-058). Undefined facts do not block deployment; use lexq_facts_unregistered to review what the version references but has not defined.",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("Version ID to deploy"),
@@ -737,7 +739,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Rollback Deployment",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Rollback to the previous deployed version. Only available if there is a previous version.",
+      description: "Rollback to the previous deployed version. Only available if there is a previous version that is still ACTIVE and whose effective end has not passed (P-058).",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         memo: z6.string().min(1).describe("Rollback reason (required)")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexq/cli",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "mcpName": "io.lexq/lexq",
   "description": "LexQ CLI — manage policies, simulate rules, and deploy from the terminal. Built for humans and AI agents.",
   "type": "module",
@@ -41,6 +41,7 @@
     "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",
+    "test:command-options": "node tests/command-options.mjs",
     "test:value-domain": "pnpm build && node tests/value-domain.mjs",
     "prepublishOnly": "pnpm build",
     "knip": "knip",

package/skills/lexq-execution/SKILL.md

@@ -253,7 +253,7 @@ lexq profile <groupId>
 lexq profile <groupId> --rule <ruleId>
 
 # Defaults: live version, last 24h, cache HIT
-lexq profile <groupId> --version <vid> --cache MISS \
+lexq profile <groupId> --version-id <vid> --cache MISS \
   --from 2026-07-01T00:00:00Z --to 2026-08-01T00:00:00Z
 ```