aipctl 2026.10.4 → 2026.10.5

package/docs/api-contract-inventory.md

@@ -56,7 +56,7 @@
 | P1-AUTO-01 | automation | `aipctl automation list`, `get`, `create`, `update`, `delete`, `enable`, `disable`, `history`, `triggers` | `listAutomations`, `getAutomation`, `createAutomation`, `updateAutomation`, `deleteAutomation`, `updateAutomationStatus`, `listAutomationHistories`, `getTriggerProviderMetadata` | api | `GET`, `POST`, `PUT`, `DELETE`, `PATCH` | `/api/cli/v1/organizations/{organizationSlug}/automations`; `/{automationId}`; `/{automationId}/status`; `/{automationId}/history`; `/triggers?type=...` | one-based pageNumber/pageSize (1..100); status `{ status }`; exactly one matching trigger branch; metadata retains required accountId/folderId/serviceType input | existing list/history domain DTOs; dedicated `GetCliAutomationResponse` and ID DTO; webhook detail only serviceType/boolean secretConfigured | `resource/oas/modules/backend/cli/openapi.yaml` → `v1_automations*.yaml`; request/list/history aliases reuse Automation user schemas | `backend/api/.../cli/generated/api/CliAutomationApi.kt` | `generated-ready` | `P1` | `migrate` | owner=`CLI Automation adapter`; Schedule/Webhook/My Drive management enabled; external account provider metadata/mutations return 403 before provider side effects; stored external detail never enriches remotely or fabricates account/folder validity | `AI-6344`; external lifecycle gate `AI-6380`; large pagination gate `AI-6413` | `src/core/automation-contract.test.ts`, `src/core/api.test.ts`, Automation command tests, `redaction.test.ts`, Backend safe-read/controller/audit tests, Gateway parity; real mise servers + production CLI CRUD/ownership/pagination/quota/DB/audit |
 | P1-AUTO-02 | automation-execution | `aipctl automation run`, `cancel`, `webhook-regen` (GA-CANDIDATE, production gated) | `runAutomation`, `cancelAutomationHistory`, `regenerateWebhookUrl` | api | `POST`, `DELETE`, `POST` | legacy `/api/web/organizations/slug/{organizationSlug}/automations/{automationId}/run`; `/histories/{seq}`; `/webhook-url/regen` | existing domain input | existing execution/history/webhook URL DTO | `resource/oas/modules/backend/automation/user/openapi.yaml` | `frontend/packages/api/src/out/modules/automation-user-types.ts#paths[...]` | `generated-ready` | `P1` | `legacy-exception` | owner=`Automation execution domain`; requires execution quota, idempotency/cancel lifetime, webhook secret rotation and safe output verification before customer enablement | `AI-6380` | existing legacy path/command tests; production availability keeps all three hidden |
 | CHAT-01 | chat-readonly | `aipctl chat list`, `aipctl chat get`, `aipctl chat messages` | `listConversations`, `getConversation`, `listMessages` | chat | `GET` | `/api/cli/v1/organizations/{orgSlug}/chats`; `/chats/{conversationId}`; `/chats/{conversationId}/messages` | list sends optional cursor; server fixes bounded `updatedAt desc` page size; detail/messages preserve organization and user ownership | local `ListConversationsResponse`, `ConversationDetail`, `ChatMessage[]` | `chat/packages/chat/src/modules/cli-chat/interface/cli-chat-read-v1.interface.controller.ts` | code-first controller contract with `operationId`/quota/capability extensions; no generated backend artifact | `oas-source-only` | `P0` | `migrate` | none; `CliChatReadInterfaceService` reuses the existing conversation/message ownership services and returns CLI-safe fields only | `AI-6344` | updated `src/core/api.test.ts`, Chat read service spec, Gateway registry/contract parity; local CLI/Chat verification covers cursor and no legacy fallback |
-| P0-DRIVE-01 | drive | `aipctl drive list`, `download`, `delete`, `mkdir`, `rename`, `usage` | `listDriveEntries`, `getDriveDownloadUrl`, `deleteDriveEntries`, `createDriveFolder`, `renameDriveEntry`, `getDriveUsage`, `downloadFromUrl` | api + external | `GET`, `POST`, `POST`, `POST`, `PATCH`, `GET`, external `GET` | CLI-managed basic CRUD: `/api/cli/v1/organizations/{organizationSlug}/drive/entries?count=200`, `/drive/entries/delete`, `/drive/folders`, `/drive/entries/{entryId}`, `/drive/usage`; download/upload remain Web/presigned | official list `{ path, hasNext, nextCursor, items }`; delete body `{ entryIds[] }`; mkdir optional `parentId`; rename body `{ newName }`; download body `{ entryIds: [id] }` | official drive list/download DTOs + external file buffer | `resource/oas/modules/backend/cli/openapi.yaml` → `v1_drive_*.yaml` (DTO aliases to organization Storage OAS); download/upload remain `resource/oas/modules/backend/organization/storage/openapi.yaml` | `backend/api/.../cli/generated/api/CliDriveApi.kt`; domain DTOs remain `com.querypie.duplo.api.drive.controller.generated.model.*` | `generated-ready` | `P0` | `migrate` | none; `CliDriveApiController` delegates membership, capacity and audit owner | `AI-6344` | `src/core/api.test.ts`, `CliSkillDriveApiControllerTest`, Gateway registry/contract parity; production CRUD/usage and local 403/404 checks (401/429 remain common gates) |
+| P0-DRIVE-01 | drive | `aipctl drive list`, `download`, `delete`, `mkdir`, `rename`, `usage` | `listDriveEntries`, `getDriveDownloadUrl`, `deleteDriveEntries`, `createDriveFolder`, `renameDriveEntry`, `getDriveUsage`, `downloadFromUrl` | api + external | `GET`, `POST`, `POST`, `POST`, `PATCH`, `GET`, external `GET` | CLI-managed basic CRUD: `/api/cli/v1/organizations/{organizationSlug}/drive/entries` with optional count/cursor/parentId (default count200), `/drive/entries/delete`, `/drive/folders`, `/drive/entries/{entryId}`, `/drive/usage`; download/upload remain Web/presigned | official list `{ path, hasNext, nextCursor, items }`; delete body `{ entryIds[] }`; mkdir optional `parentId`; rename body `{ newName }`; download body `{ entryIds: [id] }` | official drive list/download DTOs + external file buffer | `resource/oas/modules/backend/cli/openapi.yaml` → `v1_drive_*.yaml` (DTO aliases to organization Storage OAS); download/upload remain `resource/oas/modules/backend/organization/storage/openapi.yaml` | `backend/api/.../cli/generated/api/CliDriveApi.kt`; domain DTOs remain `com.querypie.duplo.api.drive.controller.generated.model.*` | `generated-ready` | `P0` | `migrate` | none; `CliDriveApiController` delegates membership, capacity and audit owner | `AI-6344` | `src/core/api.test.ts`, `CliSkillDriveApiControllerTest`, Gateway registry/contract parity; production CRUD/usage and local 403/404 checks (401/429 remain common gates) |
 | P0-DRIVE-02 | drive | `aipctl drive upload` | `createDriveUploadUrl` → `uploadToS3` → `completeDriveUpload` | api + external | `POST` → `PUT` → `POST` | `/drive/entries/upload-url`; external presigned `uploadUrl`; `/drive/entries/{entryId}/complete` | official upload request `{ parentId: null, filename, fileSize, mimeType }` | official `CreateDriveUploadUrlResponse { id, filename, uploadUrl, headers }` then `void` | `resource/oas/modules/backend/organization/storage/openapi.yaml` | `frontend/packages/api/src/out/modules/organization-storage-types.ts#paths["/api/web/organizations/slug/{organizationSlug}/drive/entries/upload-url"]`, `#paths["/api/web/organizations/slug/{organizationSlug}/drive/entries/{entryId}/complete"]` | `generated-ready` | `P0` | `migrate` | none | `AIP-PUB-05` | updated `src/core/api.test.ts`, `commands/drive/drive.test.ts`; covers `parentId: null` request and response `id`/`filename` usage |
 | P1-INT-01 | integration | `aipctl integration list`, `test`; `aipctl admin integration get`, `update`, `delete`, `tools`, `available` | `listIntegrations`, `testIntegration`, `getIntegration`, `updateIntegration`, `deleteIntegration`, `listIntegrationTools`, `listConfigurableIntegrations` | api | `GET`, `POST`, `GET`, `PUT`, `DELETE`, `GET`, `GET` | read operations use `/api/cli/v1/organizations/{organizationSlug}/integrations`; `/admin/integrations/available`; `/admin/integrations/{integrationId}`; `/tools`; mutations/test remain legacy candidate paths | read responses use dedicated CLI DTOs; admin detail maps only metadata and configured boolean, never property descriptors or credential values; update/delete/test remain unchanged | local `Integration`, `IntegrationDetail`, `IntegrationToolsResponse`, `ConfigurableIntegration[]` | `resource/oas/modules/backend/cli/openapi.yaml` → `v1_integrations*.yaml` | `backend/api/.../cli/generated/api/CliIntegrationApi.kt`; generated `Cli*Integration*` models | `generated-ready` | `P1` | `migrate` | owner=`backend CLI integration adapter`; rationale=`read-only operations now have a stable v1 contract while external test and mutations retain candidate gates`; removal condition=`dedicated test/mutation contracts pass timeout, redaction and idempotency gates`; incorporation plan=`follow AI-6380 candidate work` | `AI-6344` | updated `src/core/api.test.ts`, Backend adapter/security tests, Gateway registry/contract parity; local CLI read verification and legacy mutation path regression |
 | P0-MODEL-01 | model | `aipctl model list` | `listModels` | chat | `GET` | `/api/cli/v1/organizations/{orgSlug}/models` | none | `{ models: string[], defaultModel? }` is mapped into `Model[]` and preserves active standard, custom/BYOK, and `etc` catalog IDs | code-first OAS: `chat/packages/chat/src/modules/cli-model-exec/interface/cli-model-exec-v1.interface.controller.ts` | runtime Swagger contract; the existing Web model endpoint remains an independent compatibility reference | `oas-source-only` | `P0` | `migrate` | owner=`Chat CliModelExecV1InterfaceController/ModelInternalService`; rationale=`the dedicated route reuses the existing organization-authorized model domain catalog instead of the narrowed model-exec SharedModel catalog`; removal condition=`none for the CLI route; Web migration is a separate work item`; incorporation plan=`keep the CLI path and capability/registry parity tests aligned with the code-first Chat contract` | `AIP-PUB-05` | `src/core/api.test.ts` verifies the dedicated path, production capability gate, default mapping, and preservation of custom/BYOK and `etc` IDs; Chat service/controller tests verify domain delegation and Swagger extensions |
@@ -90,6 +90,28 @@ Source OAS의 429/503은 JSON `CliQuotaErrorResponse`와 공유 `CliQuotaErrorDe
 
 ## 공통 CLI HTTP 수명과 작업량 상한
 
+Skill list/library는 `--count 1..200`/`--cursor`/`--search`, built-in/admin built-in은
+`--limit 1..100`/`--cursor`/`--search`, Drive list는 `--count 1..200`/`--cursor`/
+`--parent-id`, Chat list는 `--cursor`를 기존 OAS query로 전달한다. `--json-page`는 서버의 한
+페이지 envelope와 nullable `nextCursor`를 반환한다. Admin skill list는 기존 page/page-size query와
+`pagination` envelope를 제공한다. 기존 Skill/Chat/admin Skill `--json` 배열은 유지하며
+다음 페이지가 있으면 stderr에 안내한다. 자동 전체 수집은 없다. `src/basic-behavior.test.ts`와
+`src/core/api.test.ts`에서 root argv→API options→encoded query와 출력/오류를 검증한다.
+삭제·멤버 제거·조직 탈퇴의 확인 누락은 요청 전 `CLI_CONFIRMATION_REQUIRED`,
+`outcome=not-dispatched`, exit 1이다. 공개 범위는 `command-manifest.ts`와 availability가 결정한다.
+
+인증 state snapshot/commit·logout·환경 변경·조직 선택 저장은 동일한 짧은 credentials lock을
+사용한다. refresh 전용 lock은 network 대기 중에도 logout/config 변경을 허용한다. 새 로그인·
+logout·환경 변경은 persistent session revision을 바꾸며, refresh는 같은 session을 유지한다.
+늦은 refresh/login/org 결과는 폐기하고, HTTP admission 뒤 fetch 직전에 revision·bearer·App URL/
+first-party destination을 다시 확인한다. 재로그인 후 과거 invalid_grant가 새 credentials를
+지우지 않는다. config/credentials JSON은 atomic rename으로 저장하고 config는 매번 다시 읽는다.
+실제 filesystem을 공유하는 독립 service instance 회귀는 `src/core/auth-session.test.ts`에 있다.
+Refresh lock 획득은 metadata/token 각각 30초와 짧은 state lock을 고려해 최대 70초 기다린다.
+대기는 취소 가능하며 시간 초과는 `CLI_AUTH_REFRESH_WAIT_TIMEOUT`, `outcome=not-dispatched`다.
+취소된 대기자는 token을 재교환하지 않고, 갱신 소유자의 취소는 OAuth HTTP signal에도 전달한다.
+6초 지연된 정상 갱신에서도 독립 인스턴스가 token POST 한 번을 재사용하는 회귀를 유지한다.
+
 `src/core/http-request.ts`가 로컬 admission, fetch, 전체 body 소비를 하나의 deadline으로 묶는다.
 일반 API는 120초·decoded 8 MiB, OAuth는 30초·8 MiB, transfer/export download는 600초·128 MiB,
 external upload는 600초·응답 8 MiB, text execution은 서버 최대 600초에 응답 여유 10초를 더한다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aipctl",
-  "version": "2026.10.4",
+  "version": "2026.10.5",
   "description": "QueryPie AIP and MCP CLI tool",
   "author": "QueryPie",
   "license": "UNLICENSED",
@@ -22,8 +22,8 @@
     "node": ">=24.18.0"
   },
   "metadata": {
-    "contentHash": "4411480e1c3e2e20349fbe7f87334b5ea564727941d33906ebcab631581607e3",
-    "wrapperHash": "b4efb580c4b910212b9ba7cce836f4d6d371cfa79ab494147c7ffe2c67f1fd6e",
+    "contentHash": "b82bf4ae40e40305cc43d0cc31315cd2d21cecfeddf32f03c9df603142cba6ad",
+    "wrapperHash": "b468cab0d6f5dbb8d14c3d3958f004ab0802fd32387d93938a78f71c59aed74d",
     "nativeHash": "006b08c3e391f4571d9b7c0f12d684fe2448106259e7e0581b10f9be362452e9"
   },
   "optionalDependencies": {