aipctl 2026.9.5 → 2026.9.6

package/build/index.cjs

@@ -89670,7 +89670,7 @@ const injectedBuildEnv = "dev".length > 0 ? "dev" : "local";
 if (!isBuildEnv(injectedBuildEnv)) {
   throw new Error(`Invalid AIPCTL_BUILD_ENV: ${injectedBuildEnv}`);
 }
-const VERSION = "2026.9.5".length > 0 ? "2026.9.5" : "0.0.0";
+const VERSION = "2026.9.6".length > 0 ? "2026.9.6" : "0.0.0";
 const BUILD_ENV = injectedBuildEnv;
 const INCLUDE_NATIVE_LOGS = BUILD_ENV !== "prod";
 
@@ -94652,12 +94652,51 @@ async function toApiError(response) {
     errorData = await response.json();
   } catch {
   }
+  const details = isCliQuotaErrorCode(errorData.code) ? parseCliQuotaErrorDetails(errorData.details) : void 0;
+  const retryAfterSeconds = details ? parseRetryAfterSeconds(response.headers.get("retry-after")) : void 0;
   return createApiError({
     message: errorData.message || `HTTP ${response.status}: ${response.statusText}`,
     statusCode: response.status,
-    code: errorData.code
+    code: errorData.code,
+    ...details ? { details } : {},
+    ...retryAfterSeconds === void 0 ? {} : { retryAfterSeconds }
   });
 }
+function isCliQuotaErrorCode(code) {
+  return code === "CLI_QUOTA_EXCEEDED" || code === "CLI_QUOTA_POLICY_UNAVAILABLE" || code === "CLI_QUOTA_LIMITER_UNAVAILABLE";
+}
+function parseCliQuotaErrorDetails(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  const details = value;
+  if (details["limitKind"] !== "request_rate") return void 0;
+  if (typeof details["quotaClass"] !== "string" || !["bootstrap", "metadata", "text-execution", "control-read"].includes(details["quotaClass"])) {
+    return void 0;
+  }
+  if (typeof details["requestId"] !== "string" || details["requestId"].length === 0) return void 0;
+  const scope = details["scope"];
+  if (scope !== void 0 && (typeof scope !== "string" || !["user", "organization", "bootstrap", "control-read"].includes(scope))) {
+    return void 0;
+  }
+  const resetAt = details["resetAt"];
+  if (resetAt !== void 0 && (typeof resetAt !== "string" || !Number.isFinite(Date.parse(resetAt)))) {
+    return void 0;
+  }
+  const dependency = details["dependency"];
+  if (dependency !== void 0 && dependency !== "policy" && dependency !== "limiter") return void 0;
+  return {
+    limitKind: "request_rate",
+    quotaClass: details["quotaClass"],
+    requestId: details["requestId"],
+    ...scope === void 0 ? {} : { scope },
+    ...resetAt === void 0 ? {} : { resetAt },
+    ...dependency === void 0 ? {} : { dependency }
+  };
+}
+function parseRetryAfterSeconds(value) {
+  if (!value || !/^\d+$/.test(value)) return void 0;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : void 0;
+}
 const makeRequest = (baseUrl, path, accessToken, options) => tryPromise({
   try: async () => {
     const resolvedBaseUrl = typeof baseUrl === "function" ? baseUrl() : baseUrl;

package/docs/api-contract-inventory.md

@@ -65,6 +65,18 @@
 | TUNNEL-01 | tunnel | `aipctl admin tunnel status`, `config`, `token` | `getTunnelStatus`, `getTunnelConfig`, `createTunnelToken` | api | `GET`, `GET`, `POST` | `/api/web/edge-tunnel/v2/organizations/slug/{organizationSlug}/status`; `/config`; `/token` | none | local `TunnelStatus`, `TunnelConfig`, `void` | `resource/oas/modules/backend/tunnel/openapi.yaml` | `frontend/packages/api/src/out/modules/tunnel-types.ts#paths[...]` | `generated-ready` | N/A | `keep` | none | N/A | existing `commands/tunnel/tunnel.test.ts`; needed v2 path snapshot |
 | P1-PRESET-01 | preset | `aipctl admin preset list`, `get`, `create`, `update`, `rename`, `delete`, `set-default`, `unset-default`, `regen-key`, `regen-static-key` | `listPresets`, `getPreset`, `createPreset`, `updatePreset`, `renamePreset`, `deletePreset`, `setPresetAsDefault`, `unsetPresetAsDefault`, `regenPresetKey`, `regenPresetStaticKey` | api | `GET`, `POST`, `PUT`, `PATCH`, `DELETE` mix | `/api/web/presets/v2`; `/api/web/presets/{presetId}`; `/key`; `/static-key`; `/default` | legacy preset API kept; delete response is contract-aligned to 204 No Content and CLI treats delete as endpoint-specific void response to tolerate deployed 200 empty drift | local preset DTOs with installation/json command fields; delete returns `void` | `resource/oas/duplo-web.yaml` | `frontend/packages/api/src/out/user-types.ts#paths["/api/web/presets/v2"]`, `#paths["/api/web/presets/{presetId}"]`, `#paths["/api/web/presets/{presetId}/default"]` | `legacy-generated` | `P1` | `keep` | owner=`backend app PresetsApiController`; rationale=`runtime returned 200 empty while generated/OAS says 204, causing JSON parse false failure`; removal condition=`204 is deployed everywhere and CLI no longer needs 200-empty tolerance`; incorporation plan=`keep endpoint-specific void mode, do not add global 200-empty fallback` | N/A | updated `src/core/api.test.ts`, `commands/admin/preset/preset.test.ts`, `../docs/how-to/aip-cli-usage.md`, `backend/api/src/test/kotlin/.../PresetsApiControllerTest.kt`; covers admin namespace docs, `/v2`, `/{id}`, `/default`, `/key`, `/static-key`, delete 200-empty tolerance, and JSON endpoint 200-empty failure |
 
+## 공통 CLI request quota 오류 계약
+
+`GA-DIRECT` 업무 호출과 `GET /api/cli/v1/capabilities`는 Gateway request-rate admission을 통과한다. Gateway-owned source 계약은 `resource/oas/modules/backend-gateway/me/components/schemas/CliQuotaErrorResponse.yaml`과 `CliQuotaErrorDetails.yaml`이다.
+
+| HTTP | code | CLI 처리 |
+| --- | --- | --- |
+| 429 | `CLI_QUOTA_EXCEEDED` | `limitKind=request_rate`, quota class, denying scope, request ID를 보존한다. 양수 refill로 계산 가능한 경우에만 `Retry-After`, `resetAt`을 보존한다. 자동 retry는 하지 않는다. |
+| 503 | `CLI_QUOTA_POLICY_UNAVAILABLE` | Backend effective-policy auth/timeout/schema/freshness 실패. stale/default policy로 대체하거나 자동 retry하지 않는다. |
+| 503 | `CLI_QUOTA_LIMITER_UNAVAILABLE` | Redis timeout/script/result 실패. 유료·mutation 요청을 자동 retry하지 않는다. |
+
+CLI `ApiError`는 위 세 code에서 allowlist된 quota detail만 보존하며 서버가 추가로 보낸 조직/사용자 ID, raw policy, Redis key는 노출하지 않는다. 회귀 테스트는 `src/core/api.test.ts`와 Gateway `test/cli/quota/**`에 있다.
+
 ## Queue IDs for follow-up
 
 ### P0 queue

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aipctl",
-  "version": "2026.9.5",
+  "version": "2026.9.6",
   "description": "QueryPie AIP and MCP CLI tool",
   "author": "QueryPie",
   "license": "UNLICENSED",
@@ -22,8 +22,8 @@
     "node": ">=24.18.0"
   },
   "metadata": {
-    "contentHash": "41009029ba4ff1bb3ad17157d8af3499f5545ddf860fb1ea4803005b6a6ca026",
-    "wrapperHash": "15330253c506008f0676946c51659e0dfc616d42e8931180f47080a03b966203",
+    "contentHash": "cbdcceeb10bb96331c9d30645354766c9172ca096bca981dd1130547ffa81d06",
+    "wrapperHash": "1f3314676a7f45c0f4672c43eb2e22c1cce93846e6215e31bb9af756c2cd89db",
     "nativeHash": "006b08c3e391f4571d9b7c0f12d684fe2448106259e7e0581b10f9be362452e9"
   },
   "optionalDependencies": {