@lark-apaas/miaoda-cli 0.1.3 → 0.1.4

package/dist/utils/time.js

@@ -10,45 +10,48 @@ exports.parseToSec = parseToSec;
 exports.floorMsToBucket = floorMsToBucket;
 exports.ceilMsToBucket = ceilMsToBucket;
 const error_1 = require("./error");
-exports.TIMESTAMP_HELP = "支持格式：" +
-    "相对时间 30m/1h/2d/1w；" +
-    "日期 2026-04-01（本地时区当日 00:00:00）；" +
-    "本地日期+时间 2026-04-01T10:00:00（按本地时区，T 分隔）；" +
-    "带时区 ISO 2026-04-01T10:00:00Z（UTC）或 2026-04-01T10:00:00+08:00（指定偏移）。" +
-    "禁止用空格分隔：'YYYY-MM-DD HH:mm:ss' 不带引号会被 shell 拆成两个参数。";
 /**
- * 解析时间字符串到毫秒时间戳；不匹配任一支持格式抛 ARGS_INVALID。
- *
- * 时区约定（重要）：
- *   - 不带显式时区的形式（YYYY-MM-DD、YYYY-MM-DDTHH:mm:ss）一律按
- *     **本地时区**解释，与 pretty 输出（output.ts:renderDate 用 getFullYear 等本地方法）形成
- *     输入/输出闭环：用户复制输出文本作为 --since 不会差时区。
- *   - 带显式时区（结尾 Z 或 ±HH:MM / ±HHMM）按显式时区解析，跨机器一致。
- *   - 因此跨机器同步使用时建议带显式时区；同机器复制粘贴 pretty 输出更省事。
- *
- * 拒绝 Date.parse 松散接受的形式：YYYY/MM/DD、自然语言（'April 1 2026'）、单独年份等。
+ * 时间格式简短说明，对齐 Supabase / fly.io 等主流 CLI 的「简洁但严格」风格。
  *
+ * - 不接受 YYYY/MM/DD、'April 1 2026' 这类松散 / 区域性形式（Date.parse 会误吞）
+ * - 不接受空格分隔的 'YYYY-MM-DD HH:mm:ss'：不带引号会被 shell 拆成两个参数，
+ *   宁可拒绝也不让用户踩「看起来传了 since 实际只传了一半」的坑
+ * - 不带显式时区的 (YYYY-MM-DD / YYYY-MM-DDTHH:mm:ss) 一律按**本地时区**解释，
+ *   跟 pretty 输出（renderDate 用 getFullYear 等本地方法）形成输入/输出闭环
+ *   ——用户复制 pretty 输出的时间字符串当 --since 不会差时区
+ */
+exports.TIMESTAMP_HELP = 'Accepted formats: ' +
+    'relative (30s / 5m / 2h / 3d / 1w); ' +
+    'date YYYY-MM-DD (local 00:00:00); ' +
+    'local datetime YYYY-MM-DDTHH:mm:ss (local timezone, T-separated); ' +
+    'ISO 8601 with timezone YYYY-MM-DDTHH:mm:ssZ or YYYY-MM-DDTHH:mm:ss+08:00.';
+/**
+ * 解析时间字符串到毫秒时间戳；不匹配任一支持格式抛 ARGS_INVALID。
  * 失败抛 AppError("ARGS_INVALID", ...)；CLI 层用 withHelp 自动转 exit 2 + help。
  */
 function parseTimeToMs(input, now = new Date()) {
-    // 1. 相对时间：30m / 1h / 2d / 1w
-    const relative = /^(\d+)([mhdw])$/.exec(input);
+    // 1. 相对时间：30s / 30m / 1h / 2d / 1w
+    const relative = /^(\d+)([smhdw])$/.exec(input);
     if (relative) {
         const n = Number(relative[1]);
+        if (n <= 0)
+            failInvalidTimestamp(input);
         const unit = relative[2];
-        const factor = unit === "m"
-            ? 60_000
-            : unit === "h"
-                ? 3_600_000
-                : unit === "d"
-                    ? 86_400_000
-                    : /* w */ 604_800_000;
+        const factor = unit === 's'
+            ? 1_000
+            : unit === 'm'
+                ? 60_000
+                : unit === 'h'
+                    ? 3_600_000
+                    : unit === 'd'
+                        ? 86_400_000
+                        : /* w */ 604_800_000;
         return now.getTime() - n * factor;
     }
     // 2. 纯日期：YYYY-MM-DD → 本地当日 00:00:00
     const date = /^(\d{4})-(\d{2})-(\d{2})$/.exec(input);
     if (date) {
-        return localDateMs(input, date[1], date[2], date[3], "00", "00", "00", "0");
+        return localDateMs(input, date[1], date[2], date[3], '00', '00', '00', '0');
     }
     // 3. 本地日期+时间：YYYY-MM-DDTHH:mm:ss[.SSS]（不带时区，T 分隔）。
     //    不接受空格分隔——'YYYY-MM-DD HH:mm:ss' 不带引号会被 shell 拆成两个参数，
@@ -57,14 +60,14 @@ function parseTimeToMs(input, now = new Date()) {
     if (localDt) {
         // capture 7 是可选 .SSS 组，运行时可能 undefined；TS lib 的 RegExp match 索引
         // 类型把它标成 string，所以这里显式 cast 让 ?? 在 lint 视角下也"必要"。
-        const msPart = localDt[7] ?? "0";
+        const msPart = localDt[7] ?? '0';
         return localDateMs(input, localDt[1], localDt[2], localDt[3], localDt[4], localDt[5], localDt[6], msPart);
     }
     // 4. 带显式时区的 ISO 8601：YYYY-MM-DDTHH:mm:ss[.SSS](Z|±HH:MM|±HHMM)
     const iso = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?(Z|[+-](\d{2}):?(\d{2}))$/.exec(input);
     if (iso) {
         validateDateTimeParts(input, iso[1], iso[2], iso[3], iso[4], iso[5], iso[6]);
-        if (iso[7] !== "Z")
+        if (iso[7] !== 'Z')
             validateOffset(input, iso[8], iso[9]);
         const ms = Date.parse(input);
         if (Number.isNaN(ms))
@@ -76,7 +79,7 @@ function parseTimeToMs(input, now = new Date()) {
 function localDateMs(input, y, mo, d, h, mi, s, msPart) {
     validateDateTimeParts(input, y, mo, d, h, mi, s);
     // 毫秒位补齐到 3 位再截断（"5" → 500，"12" → 120，"123" → 123）
-    const ms = Number(msPart.padEnd(3, "0").slice(0, 3));
+    const ms = Number(msPart.padEnd(3, '0').slice(0, 3));
     const date = new Date(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s), ms);
     if (date.getFullYear() !== Number(y) ||
         date.getMonth() !== Number(mo) - 1 ||
@@ -115,7 +118,9 @@ function validateOffset(input, h, mi) {
         failInvalidTimestamp(input);
 }
 function failInvalidTimestamp(input) {
-    throw new error_1.AppError("ARGS_INVALID", `无法解析时间 '${input}'。${exports.TIMESTAMP_HELP}`);
+    throw new error_1.AppError('ARGS_INVALID', `Invalid timestamp '${input}'`, {
+        next_actions: [exports.TIMESTAMP_HELP],
+    });
 }
 /** 毫秒 → 纳秒（字符串，避免 JS Number 精度丢失） */
 function msToNs(ms) {
@@ -156,21 +161,21 @@ const MS_DAY = 86_400_000;
 /** 把 ms 向下对齐到桶起点（UTC）。未识别的 bucket 原样返回。 */
 function floorMsToBucket(ms, bucket) {
     switch (bucket) {
-        case "1m":
+        case '1m':
             return Math.floor(ms / MS_MIN) * MS_MIN;
-        case "1h":
+        case '1h':
             return Math.floor(ms / MS_HOUR) * MS_HOUR;
-        case "1d":
-        case "DAY": {
+        case '1d':
+        case 'DAY': {
             const d = new Date(ms);
             return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
         }
-        case "WEEK": {
+        case 'WEEK': {
             const d = new Date(ms);
             const offsetDays = (d.getUTCDay() + 6) % 7; // 距上一个周一的天数
             return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() - offsetDays);
         }
-        case "MONTH": {
+        case 'MONTH': {
             const d = new Date(ms);
             return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1);
         }
@@ -184,16 +189,16 @@ function ceilMsToBucket(ms, bucket) {
     if (floor === ms)
         return ms;
     switch (bucket) {
-        case "1m":
+        case '1m':
             return floor + MS_MIN;
-        case "1h":
+        case '1h':
             return floor + MS_HOUR;
-        case "1d":
-        case "DAY":
+        case '1d':
+        case 'DAY':
             return floor + MS_DAY;
-        case "WEEK":
+        case 'WEEK':
             return floor + 7 * MS_DAY;
-        case "MONTH": {
+        case 'MONTH': {
             const d = new Date(floor);
             return Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {