aipctl 2026.9.4 → 2026.9.6

package/build/index.cjs

@@ -778,7 +778,7 @@ const isIterable = input => typeof input === "string" || hasProperty(input, Symb
  * @since 2.0.0
  * @see isObject
  */
-const isRecord$2 = input => isRecordOrArray(input) && !Array.isArray(input);
+const isRecord$3 = input => isRecordOrArray(input) && !Array.isArray(input);
 /**
  * A refinement that checks if a value is `PromiseLike`. It performs a duck-typing
  * check for a `.then` method.
@@ -25158,7 +25158,7 @@ const go = (ast, isDecoding) => {
         const concurrency = getConcurrency(ast);
         const batching = getBatching(ast);
         return (input, options) => {
-          if (!isRecord$2(input)) {
+          if (!isRecord$3(input)) {
             return left(new Type(ast, input));
           }
           const allErrors = options?.errors === "all";
@@ -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.4".length > 0 ? "2026.9.4" : "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";
 
@@ -89812,10 +89812,18 @@ const implementedCommandOperationIds = /* @__PURE__ */ new Set([
   "listCliModelExecModels",
   "createCliModelChatExecution"
 ]);
+const releaseEnabledCommandOperationIds = /* @__PURE__ */ new Set([
+  "getCliMe",
+  "getCliUserSettings",
+  "listCliOrganizations",
+  "getCliOrganizationCapabilities",
+  "listCliOrganizationMembers",
+  "listCliModelExecModels"
+]);
 const direct = (commands, operation) => commands.map((command) => ({
   command,
   tier: "GA_DIRECT",
-  availability: implementedCommandOperationIds.has(operation.operationId ?? "") ? "IMPLEMENTED" : "PLANNED",
+  availability: !implementedCommandOperationIds.has(operation.operationId ?? "") ? "PLANNED" : releaseEnabledCommandOperationIds.has(operation.operationId ?? "") ? "IMPLEMENTED" : "GATED",
   ...operation
 }));
 const candidate = (commands, owner, authBoundary, requiredGates) => commands.map((command) => ({
@@ -90554,6 +90562,7 @@ const CUSTOMER_AVAILABILITIES = /* @__PURE__ */ new Set([
   "AVAILABLE"
 ]);
 const isCustomerAvailable = (entry) => CUSTOMER_AVAILABILITIES.has(entry.availability);
+const normalizeCliArgCase = (arg) => arg.toLowerCase();
 const commandSegments = (command) => command.split(" ");
 const PROD_DISABLED_BUILT_INS = /* @__PURE__ */ new Set(["--completions", "--wizard"]);
 const isCommandPrefix = (entry, args) => {
@@ -90579,11 +90588,12 @@ const getUnavailableCommandMessage = (args, buildEnv) => {
   if (buildEnv !== "prod" || args.length === 0) {
     return null;
   }
-  const disabledBuiltIn = args.find((arg) => PROD_DISABLED_BUILT_INS.has(arg));
+  const normalizedArgs = args.map(normalizeCliArgCase);
+  const disabledBuiltIn = normalizedArgs.find((arg) => PROD_DISABLED_BUILT_INS.has(arg));
   if (disabledBuiltIn) {
     return formatUnavailableOptionMessage(disabledBuiltIn);
   }
-  const commandArgs = commandArgsForAvailability(args);
+  const commandArgs = commandArgsForAvailability(normalizedArgs);
   const entry = commandManifest.filter((candidate) => isCommandPrefix(candidate, commandArgs)).sort((left, right) => commandSegments(right.command).length - commandSegments(left.command).length).at(0);
   if (entry) {
     return isCustomerAvailable(entry) ? null : formatUnavailableMessage(entry.command);
@@ -90622,14 +90632,14 @@ class InvalidAppUrlError extends Error {
     this.rawValue = rawValue;
   }
 }
-function isRecord$1(value) {
+function isRecord$2(value) {
   return typeof value === "object" && value !== null;
 }
 function optionalString$1(value) {
   return typeof value === "string" ? value : void 0;
 }
 function parseCurrentOrganization(value) {
-  if (!isRecord$1(value)) {
+  if (!isRecord$2(value)) {
     return void 0;
   }
   const id = optionalString$1(value["id"]);
@@ -90641,7 +90651,7 @@ function parseCurrentOrganization(value) {
   return { id, slug, name };
 }
 function normalizeLoadedConfig(value) {
-  if (!isRecord$1(value)) {
+  if (!isRecord$2(value)) {
     return {};
   }
   return {
@@ -92875,11 +92885,11 @@ const CREDENTIALS_FILE = path__namespace.join(CONFIG_DIR$1, "credentials.json");
 const CREDENTIALS_LOCK_FILE = path__namespace.join(CONFIG_DIR$1, "credentials.lock");
 class CredentialServiceTag extends Tag$1("CredentialService")() {
 }
-function isNonEmptyString(value) {
+function isNonEmptyString$1(value) {
   return typeof value === "string" && value.length > 0;
 }
 function hasOAuthClient(credentials) {
-  return isNonEmptyString(credentials?.clientId);
+  return isNonEmptyString$1(credentials?.clientId);
 }
 function isAccessTokenExpired(credentials, bufferMs = 0, now = Date.now()) {
   if (!credentials?.expiresAt) {
@@ -92888,13 +92898,13 @@ function isAccessTokenExpired(credentials, bufferMs = 0, now = Date.now()) {
   return credentials.expiresAt - bufferMs <= now;
 }
 function hasValidRefreshToken(credentials, now) {
-  return isNonEmptyString(credentials.refreshToken) && (credentials.refreshExpiresAt === void 0 || credentials.refreshExpiresAt > now);
+  return isNonEmptyString$1(credentials.refreshToken) && (credentials.refreshExpiresAt === void 0 || credentials.refreshExpiresAt > now);
 }
 function getCredentialAuthStatus(credentials, now = Date.now(), options = {}) {
   if (!hasOAuthClient(credentials)) {
     return "missing";
   }
-  const needsAccessRefresh = options.forceRefresh || !isNonEmptyString(credentials.accessToken) || isAccessTokenExpired(credentials, options.accessExpiryBufferMs ?? 0, now);
+  const needsAccessRefresh = options.forceRefresh || !isNonEmptyString$1(credentials.accessToken) || isAccessTokenExpired(credentials, options.accessExpiryBufferMs ?? 0, now);
   if (!needsAccessRefresh) {
     return "authenticated";
   }
@@ -93890,7 +93900,7 @@ function trimTrailingSlash(value) {
 function toError$1(error, fallbackMessage) {
   return error instanceof Error ? new Error(maskSensitiveText(error.message)) : new Error(maskSensitiveText(fallbackMessage));
 }
-function isRecord(value) {
+function isRecord$1(value) {
   return typeof value === "object" && value !== null;
 }
 function optionalString(value) {
@@ -93900,7 +93910,7 @@ function optionalNumber(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
 function parseOAuthTokenResponse(value) {
-  if (!isRecord(value)) {
+  if (!isRecord$1(value)) {
     throw new OAuthRequestError("OAuth token response was not a JSON object", void 0, "invalid_token_response");
   }
   const accessToken = optionalString(value["access_token"]);
@@ -94429,6 +94439,55 @@ async function acquire() {
   }
 }
 
+const SERVER_CAPABILITY_SCHEMA_VERSION = 1;
+class ServerCapabilityError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "ServerCapabilityError";
+    this.code = code;
+  }
+}
+function parseEnabledServerOperations(value) {
+  if (!isRecord(value) || value["schemaVersion"] !== SERVER_CAPABILITY_SCHEMA_VERSION) {
+    throw new ServerCapabilityError(
+      "CLI_CAPABILITIES_INCOMPATIBLE",
+      "The server returned an unsupported CLI capability schema."
+    );
+  }
+  const enabledOperations = value["enabledOperations"];
+  if (!Array.isArray(enabledOperations)) {
+    throw new ServerCapabilityError(
+      "CLI_CAPABILITIES_INCOMPATIBLE",
+      "The server returned an invalid CLI capability operation list."
+    );
+  }
+  const operationIds = /* @__PURE__ */ new Set();
+  for (const operation of enabledOperations) {
+    if (!isRecord(operation) || !isNonEmptyString(operation["operationId"]) || !isNonEmptyString(operation["capability"]) || operationIds.has(operation["operationId"])) {
+      throw new ServerCapabilityError(
+        "CLI_CAPABILITIES_INCOMPATIBLE",
+        "The server returned an invalid CLI capability operation."
+      );
+    }
+    operationIds.add(operation["operationId"]);
+  }
+  return operationIds;
+}
+function requireEnabledServerOperation(enabledOperations, operationId) {
+  if (enabledOperations.has(operationId)) return;
+  throw new ServerCapabilityError(
+    "CLI_OPERATION_NOT_ENABLED",
+    `CLI operation "${operationId}" is not enabled by the server.`
+  );
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+
 class ApiError extends TaggedError$1("ApiError") {
 }
 class NotLoggedInError extends TaggedError$1("NotLoggedInError") {
@@ -94593,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;
@@ -94735,7 +94833,7 @@ const parseSseStream = async (body) => {
   }
   throw new AgentChatStreamIncompleteError(hasDataEvent && sawOnlyTerminalEnvelope);
 };
-const ApiServiceLive = effect$1(
+const makeApiServiceLive = (buildEnv) => effect$1(
   ApiServiceTag,
   gen(function* () {
     const configService = yield* ConfigService;
@@ -94852,6 +94950,34 @@ const ApiServiceLive = effect$1(
     });
     const baseUrl = () => loadConfiguredApiBaseUrl();
     const chatBaseUrl = () => loadConfiguredChatBaseUrl();
+    const requireServerOperation = (operationId, token) => {
+      if (buildEnv !== "prod") return _void;
+      if (!releaseEnabledCommandOperationIds.has(operationId)) {
+        return fail$3(createApiError({
+          message: `CLI operation "${operationId}" is not enabled in this aipctl release.`,
+          statusCode: 404,
+          code: "CLI_OPERATION_NOT_ENABLED"
+        }));
+      }
+      return gen(function* () {
+        const response = yield* makeRequest(
+          baseUrl,
+          "/api/cli/v1/capabilities",
+          token
+        );
+        yield* try_({
+          try: () => {
+            const enabledOperations = parseEnabledServerOperations(response);
+            requireEnabledServerOperation(enabledOperations, operationId);
+          },
+          catch: (error) => createApiError({
+            message: error instanceof Error ? error.message : "CLI server capability validation failed",
+            statusCode: error instanceof ServerCapabilityError && error.code === "CLI_OPERATION_NOT_ENABLED" ? 404 : 503,
+            code: error instanceof ServerCapabilityError ? error.code : "CLI_CAPABILITIES_INCOMPATIBLE"
+          })
+        });
+      });
+    };
     const subscribeAgentChatStream = (orgSlug, conversationId, token) => gen(function* () {
       const resolvedChatBaseUrl = yield* requireChatBaseUrlEffect();
       const path = `/api/${encodeURIComponent(orgSlug)}/conversations/${encodeURIComponent(conversationId)}/stream`;
@@ -94918,10 +95044,12 @@ const ApiServiceLive = effect$1(
     return {
       listOrganizations: () => gen(function* () {
         const token = yield* getAccessToken();
+        yield* requireServerOperation("listCliOrganizations", token);
         return yield* makeRequest(baseUrl, "/api/cli/v1/organizations", token);
       }),
       getOrganization: (slug) => gen(function* () {
         const token = yield* getAccessToken();
+        yield* requireServerOperation("listCliOrganizations", token);
         const orgs = yield* makeRequest(baseUrl, "/api/cli/v1/organizations", token);
         const org = orgs.find((o) => o.slug === slug);
         if (!org) {
@@ -95261,6 +95389,7 @@ const ApiServiceLive = effect$1(
       // Phase 4: Monitoring
       listOrgMembers: (orgSlug) => gen(function* () {
         const token = yield* getAccessToken();
+        yield* requireServerOperation("listCliOrganizationMembers", token);
         const path = `/api/cli/v1/organizations/${encodeURIComponent(orgSlug)}/members`;
         const raw = yield* makeRequest(baseUrl, path, token);
         return {
@@ -95286,12 +95415,14 @@ const ApiServiceLive = effect$1(
       listModelExecModels: (orgSlug) => gen(function* () {
         yield* requireChatBaseUrlEffect();
         const token = yield* getAccessToken();
+        yield* requireServerOperation("listCliModelExecModels", token);
         const path = `/api/cli/v1/organizations/${encodeURIComponent(orgSlug)}/model-exec/models`;
         return yield* makeRequest(chatBaseUrl, path, token);
       }),
       executeModelExecChat: (orgSlug, body) => gen(function* () {
         yield* requireChatBaseUrlEffect();
         const token = yield* getAccessToken();
+        yield* requireServerOperation("createCliModelChatExecution", token);
         const path = `/api/cli/v1/organizations/${encodeURIComponent(orgSlug)}/model-exec/chat`;
         return yield* makeRequest(chatBaseUrl, path, token, {
           method: "POST",
@@ -95433,6 +95564,7 @@ const ApiServiceLive = effect$1(
       // Phase 6: Auth enhancements
       getMe: () => gen(function* () {
         const token = yield* getAccessToken();
+        yield* requireServerOperation("getCliMe", token);
         return yield* makeRequest(baseUrl, "/api/cli/v1/me", token);
       }),
       refreshToken: () => refreshAccessToken({ force: true }),
@@ -95614,11 +95746,13 @@ const ApiServiceLive = effect$1(
       // Org capabilities & user settings
       getOrgCapabilities: (orgSlug) => gen(function* () {
         const token = yield* getAccessToken();
+        yield* requireServerOperation("getCliOrganizationCapabilities", token);
         const path = `/api/cli/v1/organizations/${encodeURIComponent(orgSlug)}/capabilities`;
         return yield* makeRequest(baseUrl, path, token);
       }),
       getUserSettings: () => gen(function* () {
         const token = yield* getAccessToken();
+        yield* requireServerOperation("getCliUserSettings", token);
         return yield* makeRequest(baseUrl, "/api/cli/v1/me/settings", token);
       }),
       // Tunnel management
@@ -95736,6 +95870,7 @@ const ApiServiceLive = effect$1(
     };
   })
 );
+const ApiServiceLive = makeApiServiceLive(BUILD_ENV);
 const ApiService = ApiServiceTag;
 
 const orgOption = text("org").pipe(
@@ -101402,10 +101537,10 @@ const hasCustomerAvailableCommand = (path) => {
 const formatCommandList = (path, subcommands, options) => subcommands.map((command) => [...path, getCommandName(command)]).filter((commandPath) => !options.customerOnly || hasCustomerAvailableCommand(commandPath)).map((commandPath) => `  - ${formatCanonicalPath(commandPath)}`).join("\n");
 const getHelpPath = (args) => {
   const lastArg = args.at(-1);
-  if (!lastArg || !HELP_FLAGS$1.has(lastArg)) {
+  if (!lastArg || !HELP_FLAGS$1.has(normalizeCliArgCase(lastArg))) {
     return null;
   }
-  const path = args.slice(0, -1);
+  const path = args.slice(0, -1).map(normalizeCliArgCase);
   return path.every((segment) => !segment.startsWith("-")) ? path : null;
 };
 const renderGroupHelp = ({ path, description, subcommands }, options) => {

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.4",
+  "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": "324de7cea8dc3fde3a838c4aadd5029fb56b526a8139e7be35b08a3e7de824e4",
-    "wrapperHash": "bc687edf26af6780466e1818b26030068995fd234be8ebd80e960121df783158",
+    "contentHash": "cbdcceeb10bb96331c9d30645354766c9172ca096bca981dd1130547ffa81d06",
+    "wrapperHash": "1f3314676a7f45c0f4672c43eb2e22c1cce93846e6215e31bb9af756c2cd89db",
     "nativeHash": "006b08c3e391f4571d9b7c0f12d684fe2448106259e7e0581b10f9be362452e9"
   },
   "optionalDependencies": {