@lexq/cli 0.1.37 → 0.1.39

package/dist/index.js

@@ -1358,13 +1358,16 @@ function registerDeployCommands(program) {
     "after",
     dedent7`
 
-        Lifecycle: Publish (DRAFT→ACTIVE) → Deploy (ACTIVE→LIVE) → Rollback / Undeploy
+        Lifecycle: Publish (DRAFT→ACTIVE) → Deploy or Schedule (ACTIVE→LIVE) → Rollback / Undeploy
 
         Commands:
           publish     Lock a DRAFT version (DRAFT → ACTIVE)
           live        Push an ACTIVE version to production traffic
           rollback    Revert to the previous deployed version
           undeploy    Remove the live version (stops all traffic)
+          schedule    Schedule an ACTIVE version to auto-deploy at its effective start
+          unschedule  Cancel the pending scheduled deployment
+          schedules   List scheduled deployments (all statuses)
           history     List deployment history with filters
           detail      Get deployment detail with integrity check
           overview    Show all groups' deployment status at a glance
@@ -1502,10 +1505,7 @@ function registerDeployCommands(program) {
       process.exit(1);
     }
   });
-  deploy.command("history").description("List deployment history").option("--group-id <groupId>", "Filter by policy group").option(
-    "--types <types>",
-    "Filter by types (comma-separated: PUBLISH,DEPLOY,ROLLBACK,UNDEPLOY)"
-  ).option("--start-date <date>", "Start date (yyyy-MM-dd)").option("--end-date <date>", "End date (yyyy-MM-dd)").option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").addHelpText(
+  deploy.command("history").description("List deployment history").option("--group-id <groupId>", "Filter by policy group").option("--types <types>", "Filter by types (comma-separated: DEPLOY,ROLLBACK,UNDEPLOY)").option("--start-date <date>", "Start date (yyyy-MM-dd)").option("--end-date <date>", "End date (yyyy-MM-dd)").option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").addHelpText(
     "after",
     dedent7`
 
@@ -1660,6 +1660,119 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
+  deploy.command("schedule").description("Schedule an ACTIVE version to auto-deploy at its effective start").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Version ID to schedule").requiredOption("--memo <memo>", "Schedule memo").addHelpText(
+    "after",
+    dedent7`
+
+        The version must be ACTIVE with a future effective start date; the system
+        deploys it automatically at that time (within one scheduler tick, ≤60s).
+        One pending schedule per group. Manual deploy/rollback/undeploy, starting
+        an A/B test, or archiving the group cancels the pending schedule.
+
+        Example:
+          $ lexq deploy schedule --group-id <gid> --version-id <vid> --memo "Q4 pricing"
+      `
+  ).action(async (opts) => {
+    try {
+      const globalOpts = program.opts();
+      const data = await apiRequest(
+        "POST",
+        `policy-groups/${opts.groupId}/schedule`,
+        {
+          apiKey: globalOpts.apiKey,
+          baseUrl: globalOpts.baseUrl,
+          dryRun: globalOpts.dryRun,
+          verbose: globalOpts.verbose,
+          body: { versionId: opts.versionId, memo: opts.memo }
+        }
+      );
+      console.log(`\u2713 Scheduled v${data.versionNo ?? "?"} for ${data.scheduledFor}.`);
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
+  deploy.command("unschedule").description("Cancel the pending scheduled deployment for a group").requiredOption("--group-id <groupId>", "Policy group ID").option("--force", "Skip confirmation prompt").addHelpText(
+    "after",
+    dedent7`
+
+        Cancels the PENDING schedule only — the version itself is not affected.
+
+        Example:
+          $ lexq deploy unschedule --group-id <gid> --force
+      `
+  ).action(async (opts) => {
+    try {
+      const globalOpts = program.opts();
+      if (!opts.force) {
+        const { createInterface: createInterface2 } = await import("readline/promises");
+        const rl = createInterface2({ input: process.stdin, output: process.stdout });
+        const answer = await rl.question(
+          `Cancel the pending scheduled deployment for group ${opts.groupId}? [y/N] `
+        );
+        rl.close();
+        if (answer.toLowerCase() !== "y") {
+          console.log("Canceled.");
+          return;
+        }
+      }
+      await apiRequest("DELETE", `policy-groups/${opts.groupId}/schedule`, {
+        apiKey: globalOpts.apiKey,
+        baseUrl: globalOpts.baseUrl,
+        dryRun: globalOpts.dryRun,
+        verbose: globalOpts.verbose
+      });
+      console.log(`\u2713 Scheduled deployment canceled for group ${opts.groupId}.`);
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
+  deploy.command("schedules").description("List scheduled deployments (all statuses, newest first)").option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").addHelpText(
+    "after",
+    dedent7`
+
+        Example:
+          $ lexq deploy schedules --format table
+      `
+  ).action(async (opts) => {
+    try {
+      const globalOpts = program.opts();
+      const format = globalOpts.format ?? "json";
+      const data = await apiRequest(
+        "GET",
+        "policy-groups/schedules",
+        {
+          apiKey: globalOpts.apiKey,
+          baseUrl: globalOpts.baseUrl,
+          dryRun: globalOpts.dryRun,
+          verbose: globalOpts.verbose,
+          params: { page: opts.page, size: opts.size }
+        }
+      );
+      if (format === "table") {
+        printTable(
+          ["Status", "Group", "Version", "Scheduled For", "By", "Result"],
+          data.content.map((s) => [
+            s.status,
+            s.policyGroupName ?? s.policyGroupId.substring(0, 8),
+            s.versionNo != null ? `v${s.versionNo}` : "\u2013",
+            s.scheduledFor.substring(0, 16),
+            s.scheduledByName,
+            s.status === "EXECUTED" ? s.executedAt?.substring(0, 16) ?? "\u2013" : s.status === "CANCELED" ? s.canceledReason ?? "\u2013" : s.status === "FAILED" ? s.failedReason ?? "\u2013" : "\u2013"
+          ]),
+          { truncate: 20 }
+        );
+        console.log(`
+${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
+      } else {
+        printJson(data);
+      }
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
 }
 async function warnUnregisteredFacts(globalOpts, groupId, versionId) {
   if (globalOpts.dryRun) return;
@@ -2206,13 +2319,16 @@ var TaskType = [
   // Internal
   "IMAGE_PROCESSING",
   "DAILY_SETTLEMENT",
-  "PLATFORM_WEBHOOK"
+  "PLATFORM_WEBHOOK",
+  "SCHEDULED_DEPLOYMENT"
 ];
 var PlatformEventType = [
   "VERSION_PUBLISHED",
   "DEPLOYED",
   "ROLLED_BACK",
-  "UNDEPLOYED"
+  "UNDEPLOYED",
+  "DEPLOY_SCHEDULED",
+  "DEPLOY_SCHEDULE_CANCELED"
 ];
 var WebhookPayloadFormat = ["GENERIC", "SLACK"];
 
@@ -2226,8 +2342,9 @@ function registerProfileCommands(program) {
 
         Slow-rule judgment is relative only: flagged = p50 ≥ 10× the median of
         per-rule p50s within the group. Absolute ms thresholds are intentionally
-        not supported. Percentiles are withheld (–) when n < 100; TOTAL is
-        recorded for every call, rule detail from a deterministic 1% sample.
+        not supported. Each percentile is withheld (–) unless n×(1−q) ≥ 3 —
+        p50 from n ≥ 6, p95 from n ≥ 60, p99 from n ≥ 300. TOTAL is recorded
+        on every call, rule detail from a deterministic 1% sample.
 
         Examples:
           $ lexq profile <groupId>
@@ -3816,7 +3933,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_live",
     {
       title: "Deploy to Live",
-      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.",
+      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.",
       inputSchema: {
         groupId: z5.string().uuid().describe("Policy group ID"),
         versionId: z5.string().uuid().describe("Version ID to deploy"),
@@ -3855,6 +3972,44 @@ function registerDeployTools(server, callApi) {
       body: { memo }
     })
   );
+  server.registerTool(
+    "lexq_deploy_schedule",
+    {
+      title: "Schedule Deployment",
+      description: "Schedule an ACTIVE version with a future effective start date to auto-deploy at that time (Scheduled Deployment). One pending schedule per group; manual deploy/rollback/undeploy, starting an A/B test, or archiving the group cancels it. The snapshot hash is sealed at scheduling and re-verified at execution (fail-closed).",
+      inputSchema: {
+        groupId: z5.string().uuid().describe("Policy group ID"),
+        versionId: z5.string().uuid().describe("ACTIVE version ID with a future effective start date"),
+        memo: z5.string().min(1).describe("Schedule memo (required)")
+      }
+    },
+    async ({ groupId, versionId, memo }) => callApi("POST", `policy-groups/${groupId}/schedule`, {
+      body: { versionId, memo }
+    })
+  );
+  server.registerTool(
+    "lexq_deploy_unschedule",
+    {
+      title: "Cancel Scheduled Deployment",
+      description: "Cancel the pending scheduled deployment for a group. The version itself is not affected. Fails with P-039 if no pending schedule exists.",
+      inputSchema: {
+        groupId: z5.string().uuid().describe("Policy group ID")
+      }
+    },
+    async ({ groupId }) => callApi("DELETE", `policy-groups/${groupId}/schedule`)
+  );
+  server.registerTool(
+    "lexq_deploy_schedules",
+    {
+      title: "List Scheduled Deployments",
+      description: "List scheduled deployments across all groups (all statuses: PENDING, EXECUTED, CANCELED, FAILED), newest first.",
+      inputSchema: {
+        page: z5.number().int().min(0).default(0).describe("Page number"),
+        size: z5.number().int().min(1).max(100).default(20).describe("Page size")
+      }
+    },
+    async ({ page, size }) => callApi("GET", "policy-groups/schedules", { params: paginationParams(page, size) })
+  );
   server.registerTool(
     "lexq_deploy_history",
     {
@@ -3864,9 +4019,7 @@ function registerDeployTools(server, callApi) {
         page: z5.number().int().min(0).default(0).describe("Page number"),
         size: z5.number().int().min(1).max(100).default(20).describe("Page size"),
         groupId: z5.string().uuid().optional().describe("Filter by group ID"),
-        types: z5.string().optional().describe(
-          "Filter by deployment types (comma-separated: PUBLISH,DEPLOY,ROLLBACK,UNDEPLOY)"
-        ),
+        types: z5.string().optional().describe("Filter by deployment types (comma-separated: DEPLOY,ROLLBACK,UNDEPLOY)"),
         startDate: z5.string().optional().describe("Start date (yyyy-MM-dd)"),
         endDate: z5.string().optional().describe("End date (yyyy-MM-dd)")
       }
@@ -4171,7 +4324,7 @@ function registerProfileTools(server, callApi) {
     "lexq_profile_overview",
     {
       title: "Group Latency Profile",
-      description: "Per-rule latency profile of a policy group over a time window: group TOTAL distribution split by cache state (HIT = compiled ruleset cache hit, MISS = deep-load + compile), a per-rule CONDITION/ACTION percentile table, and slow-rule flags. " + RELATIVE_THRESHOLD + " Every percentile is accompanied by its sample count n; percentiles are withheld (null) when n < 100, and baselines report INSUFFICIENT_COHORT when fewer than 3 rules qualify. Rule detail comes from a deterministic 1% sample of calls; TOTAL is recorded for every call. Defaults: last 24h, live version, cacheState HIT.",
+      description: "Per-rule latency profile of a policy group over a time window: group TOTAL distribution split by cache state (HIT = compiled ruleset cache hit, MISS = deep-load + compile), a per-rule CONDITION/ACTION percentile table, and slow-rule flags. " + RELATIVE_THRESHOLD + " Every percentile is accompanied by its sample count n; a percentile is withheld (null) unless n\xD7(1\u2212q) \u2265 3 (p50 needs n \u2265 6, p95 n \u2265 60, p99 n \u2265 300 \u2014 display gate, separate from the n \u2265 100 judgment gate). Baselines report INSUFFICIENT_COHORT when fewer than 3 rules qualify. Rule detail comes from a deterministic 1% sample of calls; TOTAL is recorded for every call. Defaults: last 24h, live version, cacheState HIT.",
       inputSchema: {
         groupId: z7.string().uuid().describe("Policy group ID"),
         versionId: z7.string().uuid().optional().describe("Version to inspect (default: live version)"),
@@ -4188,7 +4341,7 @@ function registerProfileTools(server, callApi) {
     "lexq_profile_rule",
     {
       title: "Rule Latency Detail",
-      description: "Single-rule latency detail: merged phase \xD7 cacheState distributions plus a per-window time series (60s windows). Missing windows are genuine gaps \u2014 never interpolated. Series points carry each window's own values; percentiles in merged distributions are withheld (null) when n < 100. " + RELATIVE_THRESHOLD,
+      description: "Single-rule latency detail: merged phase \xD7 cacheState distributions plus a per-window time series (60s windows). Missing windows are genuine gaps \u2014 never interpolated. Series points carry each window's own values; percentiles in merged distributions are withheld (null) unless n\xD7(1\u2212q) \u2265 3 (p50 n \u2265 6, p95 n \u2265 60, p99 n \u2265 300). " + RELATIVE_THRESHOLD,
       inputSchema: {
         groupId: z7.string().uuid().describe("Policy group ID"),
         ruleId: z7.string().uuid().describe("Rule ID (from lexq_profile_overview)"),

package/dist/mcp/register.d.ts

@@ -35,6 +35,12 @@ declare function paginationParams(page?: number, size?: number): Record<string,
  */
 declare function formatUnregisteredFactWarning(meta: unknown): string | null;
 
+declare class ApiError extends Error {
+    readonly statusCode: number;
+    readonly errorCode: string | null;
+    constructor(statusCode: number, errorCode: string | null, message: string);
+}
+
 /**
  * Registers all MCP tools on the given server.
  *
@@ -43,4 +49,4 @@ declare function formatUnregisteredFactWarning(meta: unknown): string | null;
  */
 declare function registerAllTools(server: McpServer, callApi: CallApi): void;
 
-export { type CallApi, type McpToolResult, formatUnregisteredFactWarning, paginationParams, registerAllTools };
+export { ApiError, type CallApi, type McpToolResult, formatUnregisteredFactWarning, paginationParams, registerAllTools };

package/dist/mcp/register.js

@@ -154,6 +154,18 @@ import { join } from "path";
 var CONFIG_DIR = join(homedir(), ".lexq");
 var CONFIG_FILE = join(CONFIG_DIR, "config.json");
 
+// src/lib/api-client.ts
+var ApiError = class extends Error {
+  constructor(statusCode, errorCode, message) {
+    super(message);
+    this.statusCode = statusCode;
+    this.errorCode = errorCode;
+    this.name = "ApiError";
+  }
+  statusCode;
+  errorCode;
+};
+
 // src/mcp/tools/_shared.ts
 function paginationParams(page, size) {
   const params = {};
@@ -532,7 +544,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_live",
     {
       title: "Deploy to Live",
-      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.",
+      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.",
       inputSchema: {
         groupId: z5.string().uuid().describe("Policy group ID"),
         versionId: z5.string().uuid().describe("Version ID to deploy"),
@@ -571,6 +583,44 @@ function registerDeployTools(server, callApi) {
       body: { memo }
     })
   );
+  server.registerTool(
+    "lexq_deploy_schedule",
+    {
+      title: "Schedule Deployment",
+      description: "Schedule an ACTIVE version with a future effective start date to auto-deploy at that time (Scheduled Deployment). One pending schedule per group; manual deploy/rollback/undeploy, starting an A/B test, or archiving the group cancels it. The snapshot hash is sealed at scheduling and re-verified at execution (fail-closed).",
+      inputSchema: {
+        groupId: z5.string().uuid().describe("Policy group ID"),
+        versionId: z5.string().uuid().describe("ACTIVE version ID with a future effective start date"),
+        memo: z5.string().min(1).describe("Schedule memo (required)")
+      }
+    },
+    async ({ groupId, versionId, memo }) => callApi("POST", `policy-groups/${groupId}/schedule`, {
+      body: { versionId, memo }
+    })
+  );
+  server.registerTool(
+    "lexq_deploy_unschedule",
+    {
+      title: "Cancel Scheduled Deployment",
+      description: "Cancel the pending scheduled deployment for a group. The version itself is not affected. Fails with P-039 if no pending schedule exists.",
+      inputSchema: {
+        groupId: z5.string().uuid().describe("Policy group ID")
+      }
+    },
+    async ({ groupId }) => callApi("DELETE", `policy-groups/${groupId}/schedule`)
+  );
+  server.registerTool(
+    "lexq_deploy_schedules",
+    {
+      title: "List Scheduled Deployments",
+      description: "List scheduled deployments across all groups (all statuses: PENDING, EXECUTED, CANCELED, FAILED), newest first.",
+      inputSchema: {
+        page: z5.number().int().min(0).default(0).describe("Page number"),
+        size: z5.number().int().min(1).max(100).default(20).describe("Page size")
+      }
+    },
+    async ({ page, size }) => callApi("GET", "policy-groups/schedules", { params: paginationParams(page, size) })
+  );
   server.registerTool(
     "lexq_deploy_history",
     {
@@ -580,9 +630,7 @@ function registerDeployTools(server, callApi) {
         page: z5.number().int().min(0).default(0).describe("Page number"),
         size: z5.number().int().min(1).max(100).default(20).describe("Page size"),
         groupId: z5.string().uuid().optional().describe("Filter by group ID"),
-        types: z5.string().optional().describe(
-          "Filter by deployment types (comma-separated: PUBLISH,DEPLOY,ROLLBACK,UNDEPLOY)"
-        ),
+        types: z5.string().optional().describe("Filter by deployment types (comma-separated: DEPLOY,ROLLBACK,UNDEPLOY)"),
         startDate: z5.string().optional().describe("Start date (yyyy-MM-dd)"),
         endDate: z5.string().optional().describe("End date (yyyy-MM-dd)")
       }
@@ -887,7 +935,7 @@ function registerProfileTools(server, callApi) {
     "lexq_profile_overview",
     {
       title: "Group Latency Profile",
-      description: "Per-rule latency profile of a policy group over a time window: group TOTAL distribution split by cache state (HIT = compiled ruleset cache hit, MISS = deep-load + compile), a per-rule CONDITION/ACTION percentile table, and slow-rule flags. " + RELATIVE_THRESHOLD + " Every percentile is accompanied by its sample count n; percentiles are withheld (null) when n < 100, and baselines report INSUFFICIENT_COHORT when fewer than 3 rules qualify. Rule detail comes from a deterministic 1% sample of calls; TOTAL is recorded for every call. Defaults: last 24h, live version, cacheState HIT.",
+      description: "Per-rule latency profile of a policy group over a time window: group TOTAL distribution split by cache state (HIT = compiled ruleset cache hit, MISS = deep-load + compile), a per-rule CONDITION/ACTION percentile table, and slow-rule flags. " + RELATIVE_THRESHOLD + " Every percentile is accompanied by its sample count n; a percentile is withheld (null) unless n\xD7(1\u2212q) \u2265 3 (p50 needs n \u2265 6, p95 n \u2265 60, p99 n \u2265 300 \u2014 display gate, separate from the n \u2265 100 judgment gate). Baselines report INSUFFICIENT_COHORT when fewer than 3 rules qualify. Rule detail comes from a deterministic 1% sample of calls; TOTAL is recorded for every call. Defaults: last 24h, live version, cacheState HIT.",
       inputSchema: {
         groupId: z7.string().uuid().describe("Policy group ID"),
         versionId: z7.string().uuid().optional().describe("Version to inspect (default: live version)"),
@@ -904,7 +952,7 @@ function registerProfileTools(server, callApi) {
     "lexq_profile_rule",
     {
       title: "Rule Latency Detail",
-      description: "Single-rule latency detail: merged phase \xD7 cacheState distributions plus a per-window time series (60s windows). Missing windows are genuine gaps \u2014 never interpolated. Series points carry each window's own values; percentiles in merged distributions are withheld (null) when n < 100. " + RELATIVE_THRESHOLD,
+      description: "Single-rule latency detail: merged phase \xD7 cacheState distributions plus a per-window time series (60s windows). Missing windows are genuine gaps \u2014 never interpolated. Series points carry each window's own values; percentiles in merged distributions are withheld (null) unless n\xD7(1\u2212q) \u2265 3 (p50 n \u2265 6, p95 n \u2265 60, p99 n \u2265 300). " + RELATIVE_THRESHOLD,
       inputSchema: {
         groupId: z7.string().uuid().describe("Policy group ID"),
         ruleId: z7.string().uuid().describe("Rule ID (from lexq_profile_overview)"),
@@ -1182,13 +1230,16 @@ var TaskType = [
   // Internal
   "IMAGE_PROCESSING",
   "DAILY_SETTLEMENT",
-  "PLATFORM_WEBHOOK"
+  "PLATFORM_WEBHOOK",
+  "SCHEDULED_DEPLOYMENT"
 ];
 var PlatformEventType = [
   "VERSION_PUBLISHED",
   "DEPLOYED",
   "ROLLED_BACK",
-  "UNDEPLOYED"
+  "UNDEPLOYED",
+  "DEPLOY_SCHEDULED",
+  "DEPLOY_SCHEDULE_CANCELED"
 ];
 var WebhookPayloadFormat = ["GENERIC", "SLACK"];
 
@@ -1396,6 +1447,7 @@ function registerAllTools(server, callApi) {
   registerWebhookSubscriptionTools(server, callApi);
 }
 export {
+  ApiError,
   formatUnregisteredFactWarning,
   paginationParams,
   registerAllTools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexq/cli",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "description": "LexQ CLI — manage policies, simulate rules, and deploy from the terminal. Built for humans and AI agents.",
   "type": "module",
   "bin": {
@@ -29,7 +29,10 @@
     "lint": "eslint src/",
     "typecheck": "tsc --noEmit",
     "start": "node dist/index.js",
-    "prepublishOnly": "pnpm build"
+    "prepublishOnly": "pnpm build",
+    "knip": "knip",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\""
   },
   "keywords": [
     "lexq",
@@ -57,15 +60,14 @@
     "cli-table3": "^0.6.5",
     "commander": "^13.1.0",
     "dedent": "^1.7.2",
-    "ora": "^8.2.0",
-    "prettier": "^3.8.1",
     "zod": "^3.25.76"
   },
   "devDependencies": {
     "@eslint/js": "^9.20.0",
-    "@types/dedent": "^0.7.2",
     "@types/node": "^22.12.0",
     "eslint": "^10.2.0",
+    "knip": "^6.29.0",
+    "prettier": "^3.9.6",
     "tsup": "^8.5.1",
     "typescript": "^5.7.0",
     "typescript-eslint": "^8.24.0"