@mainsoft/agent-cms 0.7.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (111) hide show
  1. package/CHANGELOG.md +60 -0
  2. package/README.md +291 -32
  3. package/TODO.md +72 -26
  4. package/UPGRADE-0.10.md +36 -0
  5. package/UPGRADE-0.8.md +117 -0
  6. package/dist/agent.cjs +39 -17
  7. package/dist/agent.d.cts +2 -2
  8. package/dist/agent.d.ts +2 -2
  9. package/dist/agent.js +9 -7
  10. package/dist/bin.js +4528 -355
  11. package/dist/{chunk-OQ55GEF3.js → chunk-3OPKTBEI.js} +1 -1
  12. package/dist/chunk-6PB4ZCHH.js +328 -0
  13. package/dist/chunk-7SCYDG2G.js +2943 -0
  14. package/dist/chunk-7WJIIJCI.js +544 -0
  15. package/dist/chunk-7Y6TU2UA.js +150 -0
  16. package/dist/{chunk-EXV6JNLY.js → chunk-AKCXMT3X.js} +15 -22
  17. package/dist/{chunk-QC2M4NZY.js → chunk-BFVBHIHV.js} +72 -1
  18. package/dist/chunk-DSJETZT4.js +493 -0
  19. package/dist/{chunk-IW3D4I7Q.js → chunk-IU2SMWAM.js} +246 -4
  20. package/dist/{chunk-VICZ76TR.js → chunk-KAO3Z3CF.js} +43 -2
  21. package/dist/{chunk-CRDW6Q72.js → chunk-MA6VKJ3F.js} +87 -25
  22. package/dist/{chunk-6K5ZTGHQ.js → chunk-PEQY4N73.js} +16 -0
  23. package/dist/{chunk-DOADAH4L.js → chunk-PGV2QPIL.js} +40 -0
  24. package/dist/{chunk-Y63XQS2J.js → chunk-TOZQYJFG.js} +1 -1
  25. package/dist/cli.cjs +4528 -355
  26. package/dist/cli.d.cts +19 -3
  27. package/dist/cli.d.ts +19 -3
  28. package/dist/cli.js +206 -16
  29. package/dist/client.cjs +72 -1
  30. package/dist/client.d.cts +308 -6
  31. package/dist/client.d.ts +308 -6
  32. package/dist/client.js +1 -1
  33. package/dist/cms-C_vkAxYV.d.cts +1537 -0
  34. package/dist/cms-pqJyowu1.d.ts +1537 -0
  35. package/dist/config.d.cts +7 -1
  36. package/dist/config.d.ts +7 -1
  37. package/dist/drizzle-repo-CviH3EX7.d.cts +146 -0
  38. package/dist/drizzle-repo-DWLD0rWe.d.ts +146 -0
  39. package/dist/errors.cjs +82 -1
  40. package/dist/errors.d.cts +43 -3
  41. package/dist/errors.d.ts +43 -3
  42. package/dist/errors.js +2 -2
  43. package/dist/frontmatter.d.cts +5 -4
  44. package/dist/frontmatter.d.ts +5 -4
  45. package/dist/http.cjs +640 -94
  46. package/dist/http.d.cts +51 -2
  47. package/dist/http.d.ts +51 -2
  48. package/dist/http.js +203 -13
  49. package/dist/index.cjs +3759 -575
  50. package/dist/index.d.cts +8 -8
  51. package/dist/index.d.ts +8 -8
  52. package/dist/index.js +226 -30
  53. package/dist/markdown.cjs +89 -25
  54. package/dist/markdown.d.cts +57 -3
  55. package/dist/markdown.d.ts +57 -3
  56. package/dist/markdown.js +5 -1
  57. package/dist/mcp.cjs +314 -37
  58. package/dist/mcp.d.cts +3 -2
  59. package/dist/mcp.d.ts +3 -2
  60. package/dist/mcp.js +12 -9
  61. package/dist/messages/en.cjs +40 -0
  62. package/dist/messages/en.js +1 -1
  63. package/dist/messages/ko.cjs +40 -0
  64. package/dist/messages/ko.js +40 -0
  65. package/dist/registry/cms-audit.json +1 -1
  66. package/dist/registry/cms-doc-editor.json +15 -4
  67. package/dist/registry/cms-doc-list.json +2 -1
  68. package/dist/registry/cms-files.json +29 -0
  69. package/dist/registry/cms-lib.json +3 -3
  70. package/dist/registry/cms-media-picker.json +29 -0
  71. package/dist/registry/cms-media.json +28 -0
  72. package/dist/registry/cms-preview-comments.json +24 -0
  73. package/dist/registry/cms-releases.json +28 -0
  74. package/dist/registry/cms-shell.json +2 -2
  75. package/dist/registry/cms-trash.json +24 -0
  76. package/dist/registry/cms-versions.json +2 -1
  77. package/dist/registry/registry.json +163 -3
  78. package/dist/storage-s3.cjs +168 -0
  79. package/dist/storage-s3.d.cts +53 -0
  80. package/dist/storage-s3.d.ts +53 -0
  81. package/dist/storage-s3.js +143 -0
  82. package/dist/storage.cjs +373 -0
  83. package/dist/storage.d.cts +183 -0
  84. package/dist/storage.d.ts +183 -0
  85. package/dist/storage.js +49 -0
  86. package/dist/tables.cjs +251 -3
  87. package/dist/tables.d.cts +4965 -681
  88. package/dist/tables.d.ts +4965 -681
  89. package/dist/tables.js +14 -2
  90. package/dist/tools.cjs +331 -20
  91. package/dist/tools.d.cts +54 -7
  92. package/dist/tools.d.ts +54 -7
  93. package/dist/tools.js +16 -7
  94. package/dist/types.cjs +99 -1
  95. package/dist/types.d.cts +205 -5
  96. package/dist/types.d.ts +205 -5
  97. package/dist/types.js +5 -3
  98. package/package.json +32 -22
  99. package/dist/ai.cjs +0 -555
  100. package/dist/ai.d.cts +0 -48
  101. package/dist/ai.d.ts +0 -48
  102. package/dist/ai.js +0 -73
  103. package/dist/chunk-52NUUZC7.js +0 -1446
  104. package/dist/chunk-IGL2V6US.js +0 -324
  105. package/dist/chunk-QQV6VLYJ.js +0 -204
  106. package/dist/cms-BPp01z-8.d.ts +0 -411
  107. package/dist/cms-D6D89-qZ.d.cts +0 -411
  108. package/dist/drizzle-repo-B1rt7r4j.d.ts +0 -90
  109. package/dist/drizzle-repo-Cn-kL2FK.d.cts +0 -90
  110. package/dist/repo-BWI2Pkrv.d.ts +0 -162
  111. package/dist/repo-CeDxUxO6.d.cts +0 -162
package/TODO.md CHANGED
@@ -1,9 +1,10 @@
1
1
  # agent-cms TODO
2
2
 
3
- 일반 웹 앱(Next.js 등)에 얹어서 함께 돌아가는 **애드온 CMS**. 사람(어드민 화면)과 에이전트(REST, MCP, AI SDK 도구)가 같은 문서를 같이 고친다.
4
- 블로그, 사내 문서, 개발 문서, 공지, 게시판처럼 CMS가 쓰이는 곳이면 어디든 쓸 수 있어야 한다. 특정 앱의 개발 흐름(PR, CI, 배포)에 묶인 기능은 라이브러리에 넣지 않는다. 그런 흐름은 앱이 이 라이브러리의 도구(`./ai`, CLI)를 써서 직접 짠다.
3
+ 일반 웹 앱(Next.js 등)에 얹어서 함께 돌아가는 **애드온 CMS**. 사람(어드민 화면)과 에이전트(REST, MCP, CLI)가 같은 문서를 같이 고친다.
4
+ 블로그, 사내 문서, 개발 문서, 공지, 게시판처럼 CMS가 쓰이는 곳이면 어디든 쓸 수 있어야 한다. 특정 앱의 개발 흐름(PR, CI, 배포)에 묶인 기능은 라이브러리에 넣지 않는다. 그런 흐름은 앱이 이 라이브러리의 도구(`./tools`, CLI)를 써서 직접 짠다.
5
5
  이 목록은 라이브러리를 키울 때의 백로그다. 서비서(첫 사용처)는 새 버전을 받아 올려 쓴다.
6
6
  사용자 질문(검색어, 못 찾은 질문, 질의 로그)은 앱의 데이터다. 라이브러리는 이를 저장하지 않고 `onSearchMiss` 같은 이벤트 훅만 낸다. 저장과 운영 화면은 앱이 맡는다(0.6.0부터). 삭제한 항목도 번호는 그대로 둔다.
7
+ 자세한 설계와 정해 둔 기본값은 `docs/roadmap/` 아래 묶음별 문서에 있다. 이 파일은 번호와 한 문단만 둔다. 순서는 맨 아래 9절.
7
8
 
8
9
  표기: **[P0]** 떼어 내기 전에 필요, **[P1]** 첫 공개 버전, **[P2]** 그 뒤.
9
10
  출처: (lead) 리드 에이전트, (A)~(D) 검토 에이전트 4개.
@@ -16,14 +17,14 @@
16
17
  - 한글 2-gram 메모리 검색 (섹션 단위, 조사 제거, 불용어, 영문 오타 1글자 허용)
17
18
  - API 키: sha256 해시만 저장, read / write / publish / admin 범위와 컬렉션 제한
18
19
  - REST 하나와 stateless MCP(JSON-RPC)
19
- - 도구 목록 하나(`tools.ts`)를 MCP, AI SDK 도구(`./ai`: `cmsTools`, `remoteCmsTools`, slash-agent-sdk에서도 그대로), CLI가 함께 쓴다
20
+ - 도구 목록 하나(`tools.ts`)를 MCP와 CLI가 함께 쓰고, `./tools`의 `toolsFor`와 `callTool`로 어떤 에이전트 틀에든 붙일 수 있다. 이 패키지는 모델을 부르지 않는다
20
21
  - CLI: `tools`, `collections`, `list`, `get`, `search`, `put <file.md>`(frontmatter), `publish`, `call`
21
22
  - 저장소 인터페이스: `MemoryRepo`(테스트), `DrizzleRepo`(Postgres)
22
23
 
23
24
  ## 1. 리드 아이디어 (lead)
24
25
 
25
26
  ### 콘텐츠 모델
26
- 1. **[P1] 필드 스키마로 어드민 폼 자동 생성.** zod `fields`를 읽어 입력 컴포넌트(텍스트, 숫자, 선택, 날짜, 불리언, 배열, 관계)를 고르고, 필드마다 `admin: { label, help, widget }` 메타를 붙인다. 지금은 `fields`가 JSON으로만 다뤄진다.
27
+ 1. **[P1] 필드 스키마로 어드민 폼 자동 생성.** zod `fields`를 읽어 입력 컴포넌트(텍스트, 숫자, 선택, 날짜, 불리언, 배열, 관계)를 고르고, 필드마다 `admin: { label, help, widget }` 메타를 붙인다. 지금은 `fields`가 JSON으로만 다뤄진다. [완료 0.6.0, 관계 위젯만 2번에 남음]
27
28
  2. **[P1] 관계 필드.** `relation('guide')`처럼 다른 문서를 가리키고, 삭제와 보관 때 참조하는 쪽을 경고한다. 공개 화면에서는 "관련 문서"로 그린다.
28
29
  3. **[P2] 블록(섹션) 기반 본문.** 마크다운 외에 callout, 단계, 이미지, 표, 영상, 링크 카드 블록 배열을 쓰는 모드. 에이전트에게는 블록 단위로 패치하게 한다.
29
30
  4. **[P1] 문서 트리와 순서.** `parent`와 `order`로 사이드바 목차를 정하고, 어드민에서 끌어서 순서를 바꾼다. 지금은 분류 안에서 갱신 시각순이다.
@@ -31,14 +32,14 @@
31
32
 
32
33
  ### 편집과 검토
33
34
  6. **[P0] 버전 diff 화면.** 두 버전의 필드별 차이와 본문 줄 단위 diff를 보여 준다. 되돌리기 전에 꼭 필요하다. [완료 0.6.0]
34
- 7. **[P1] 예약 게시와 예약 숨김.** `publishAt`, `unpublishAt`. 앱의 크론(Inngest 등)에 붙일 `runScheduled()`를 제공한다.
35
- 8. **[P1] 검토 요청 흐름.** 에이전트가 쓴 버전은 "검토 대기"로 두고, 승인한 사람과 시각을 기록한다. 컬렉션마다 "에이전트 글은 사람 승인 필수"를 켤 수 있다.
36
- 9. **[P1] 편집 잠금 표시.** 누가 이 문서를 열고 있는지 보여 준다(하트비트, 오래되면 자동 해제). 409보다 앞서 충돌을 막는다.
35
+ 7. **[P1] 예약 게시와 예약 숨김.** `publishAt`, `unpublishAt`. 앱의 크론(Inngest 등)에 붙일 `runScheduled()`를 제공한다. **상태:** 0.10.0에서 완료 (실행은 앱의 cron이 `/_cron`을 부른다).
36
+ 8. **[P1] 검토 요청 흐름.** 에이전트가 쓴 버전은 "검토 대기"로 두고, 승인한 사람과 시각을 기록한다. 컬렉션마다 "에이전트 글은 사람 승인 필수"를 켤 수 있다. **상태:** 0.10.0에서 완료.
37
+ 9. **[P1] 편집 잠금 표시.** 누가 이 문서를 열고 있는지 보여 준다(하트비트, 오래되면 자동 해제). 409보다 앞서 충돌을 막는다. **상태:** 0.10.0에서 완료 (잠금이 아니라 함께 보는 사람 표시).
37
38
  10. **[P2] 버전 간 3-way 병합.** 409가 났을 때 내 변경과 남의 변경이 겹치지 않으면 자동으로 합친다. [완료 0.6.0]
38
39
  11. **[P1] 미리보기 링크.** 서명된 토큰으로 초안을 공개 화면 모양 그대로 보는 URL(만료 시간 포함). 로그인 없이 리뷰어에게 보낼 수 있다. [완료 0.6.0]
39
40
 
40
41
  ### 검색과 에이전트
41
- 12. **[P1] 선택형 임베딩 검색.** 키워드 점수와 벡터 점수를 섞고(pgvector 어댑터), 키워드만으로도 돌아가게 둔다. 임베딩은 게시 때만 다시 계산한다.
42
+ 12. **[P1] 선택형 임베딩 검색.** 키워드 점수와 벡터 점수를 섞고(pgvector 어댑터), 키워드만으로도 돌아가게 둔다. 임베딩은 게시 때만 다시 계산한다. [이 패키지에서는 하지 않음: 모델을 부르는 기능. 135번의 연결구로 확장 패키지가 붙인다]
42
43
  13. **[P1] 동의어 사전.** 컬렉션 설정이나 어드민에서 "슬랙 = slack", "ppt = 발표 자료 = 슬라이드"를 관리한다. 지금은 문서마다 keywords에 반복해 넣어야 한다.
43
44
  14. ~~**[P1] 못 찾은 질문에서 바로 초안 만들기.** 같은 의도의 질문을 묶고, "이 질문들로 초안 쓰기"를 에이전트에게 맡긴다(MCP 도구 `draft_from_gaps`).~~ [삭제] 사용자 질문은 앱 데이터. 앱이 `onSearchMiss`로 모은 질문으로 직접 에이전트를 부른다.
44
45
  15. **[P1] 검색 품질 평가 세트.** `queries.eval.json`(질문 → 기대 문서)과 CLI `agent-cms eval`로 순위 회귀를 CI에서 잡는다.
@@ -47,15 +48,15 @@
47
48
  ### 운영과 보안
48
49
  17. **[P0] 감사 로그.** 키 생성과 폐기, 게시, 삭제, 권한 실패를 누가 언제 했는지 남긴다. 지금은 버전 기록만 있다. [완료 0.6.0]
49
50
  18. **[P1] 키 사용량 제한(rate limit)과 만료일.** 키마다 분당 요청 수와 만료일, IP 허용 목록을 둔다. [0.6.0에서 만료일만]
50
- 19. **[P1] 소프트 삭제와 휴지통.** 삭제는 30일 보관 뒤 영구 삭제한다. 지금은 바로 지운다.
51
+ 19. **[P1] 소프트 삭제와 휴지통.** 삭제는 30일 보관 뒤 영구 삭제한다. 지금은 바로 지운다. **상태:** 0.10.0에서 완료.
51
52
  20. **[P1] 웹훅.** 게시, 수정, 삭제 때 서명된 POST를 보낸다(재시도, 실패 기록). ISR 재검증이나 Slack 알림에 쓴다.
52
53
  21. **[P2] 멀티 테넌트.** `tenant` 열을 두고, 한 앱 안의 워크스페이스마다 별도 문서 세트를 둔다.
53
54
 
54
55
  ### 패키징과 개발 경험
55
- 22. **[P0] 다른 저장소로 분리.** `@mainsoft/agent-cms`로 만들고 엔트리를 나눈다(server, http, mcp, ai, react, markdown, cli). peer deps는 drizzle-orm, zod, ai(선택), react(선택).
56
+ 22. **[P0] 다른 저장소로 분리.** `@mainsoft/agent-cms`로 만들고 엔트리를 나눈다(server, http, mcp, ai, react, markdown, cli). peer deps는 drizzle-orm, zod, ai(선택), react(선택). [완료: 이 저장소. `ai` 엔트리와 peer dep은 0.8.0에서 뺌]
56
57
  23. **[P0] 공식 MCP SDK로 교체.** 지금은 손으로 짠 JSON-RPC다. `@modelcontextprotocol/sdk`로 바꾸고 resources(문서를 리소스로)와 prompts도 노출한다. [완료 0.6.0]
57
58
  24. **[P1] `agent-cms add <component>` 레지스트리.** shadcn처럼 어드민 UI 컴포넌트를 앱으로 복사해 넣는다(문서 목록, 편집기, 버전 기록, 키 관리). [완료 0.6.0]
58
- 25. **[P1] 마이그레이션 생성기.** `agent-cms ddl`이 버전별 증분 SQL을 내보내고, 앱의 마이그레이션 체계(drizzle-kit, 직접 작성한 guarded step)에 붙인다.
59
+ 25. **[P1] 마이그레이션 생성기.** `agent-cms ddl`이 버전별 증분 SQL을 내보내고, 앱의 마이그레이션 체계(drizzle-kit, 직접 작성한 guarded step)에 붙인다. [완료 0.6.0: migrate print, check, apply]
59
60
  26. **[P1] 가져오기와 내보내기.** 폴더의 md(frontmatter)와 DB를 서로 옮기는 CLI(`agent-cms export ./content`, `import`). 백업과 초기 시드, 로컬 편집에 쓴다.
60
61
  27. **[P2] Next 이외 어댑터.** Hono, Express, Remix용 핸들러(지금 핸들러는 fetch `Request`/`Response`라 얇게 감쌀 수 있다).
61
62
  28. **[P1] 예제 앱과 문서 사이트.** 문서 사이트 자체를 agent-cms로 만든다.
@@ -65,32 +66,32 @@
65
66
  29. **[P0] 전체 진단 `diagnose()`와 필드별 오류.** 지금 `validate()`는 첫 오류에서 throw한다. `Diagnostic[]`(`{ path, code, message, params }`)을 한 번에 돌려주고 `POST /collections/:c/_diagnose`로 저장 없이 검사한다. 폼은 입력마다 `aria-invalid`를 붙이고, 에이전트는 한 번에 모든 문제를 받는다. (Payload, Sanity) [완료 0.6.0]
66
67
  30. **[P0] 오류 코드 계약과 문구 카탈로그.** `CmsError`의 한국어 산문을 `invalid_slug`, `unknown_link`, `conflict_version` 같은 세분 코드와 `params`로 바꾸고 `createCms({ messages })`로 문구를 주입한다. 공개 패키지가 한국어 전용이 되지 않게 한다. (Directus, Strapi) [완료 0.6.0]
67
68
  31. **[P0] 버전을 만들지 않는 자동 저장.** `autosave jsonb`, `autosave_at`, `autosave_by`에 저장하고 버전은 사람이 저장할 때만 만든다. 다시 열면 "저장하지 않은 내용을 복구할까요?"를 띄운다. 자동 저장이 `versions.max`를 채워 실제 이력을 밀어내는 것을 막는다. (Payload autosave) [완료 0.6.0]
68
- 32. **[P0] 복사형 어드민의 접근성 계약.** `role="status"` 저장 알림, `label`과 `aria-describedby`, 포커스 트랩과 복귀, 키보드만으로 생성부터 게시와 되돌리기까지. jsdom과 axe 검사로 고정한다. (Sanity Studio)
69
+ 32. **[P0] 복사형 어드민의 접근성 계약.** `role="status"` 저장 알림, `label`과 `aria-describedby`, 포커스 트랩과 복귀, 키보드만으로 생성부터 게시와 되돌리기까지. jsdom과 axe 검사로 고정한다. (Sanity Studio) [완료 0.6.0]
69
70
  33. **[P1] "에이전트가 바꾼 곳" 표시와 부분 되돌리기.** `commit()`이 필드 단위 diff를 `cms_versions.changed`에 남기고, 편집 화면 상단에 "에이전트가 v12에서 제목, 본문 2곳을 바꿨어요"를 띄운다. hunk마다 "이 부분만 되돌리기"는 새 버전을 만든다. (Sanity AI Assist, Directus) [완료 0.6.0]
70
- 34. **[P1] 섹션에 붙는 댓글.** `cms_comments`(anchor, quote, thread, resolvedAt). 앵커는 `splitSections()`의 것을 쓴다. 서명된 미리보기 링크로 온 외부 리뷰어도 댓글만 남길 수 있다. 에이전트는 댓글을 읽고 수정안을 새 버전으로 만든다. (Directus, Sanity)
71
- 35. **[P1] 분할 라이브 미리보기와 스크롤 동기화.** 저장 전 로컬 상태로 200ms 디바운스 렌더, 커서 섹션과 미리보기 앵커를 양방향으로 맞추고, 375/768/전체 폭 전환을 둔다. `renderBlocks(blocks, components)`로 앱 컴포넌트를 주입한다. (Payload live preview, TinaCMS)
72
- 36. **[P1] 미리보기에서 소스로 점프.** 블록에 `line`, `endLine`을 남겨 제목을 누르면 편집기의 해당 줄을 선택한다. 댓글 인용과 섹션 diff에도 같은 좌표를 쓴다. (TinaCMS click-to-edit)
73
- 37. **[P1] 저장 없는 미리보기 API.** `cms.preview(actor, col, input)`가 `{ blocks, toc, diagnostics, diff, publicUrl }`를 돌려준다. 어드민 미리보기와 에이전트의 저장 전 자기 점검이 같은 코드를 쓴다.
71
+ 34. **[P1] 섹션에 붙는 댓글.** `cms_comments`(anchor, quote, thread, resolvedAt). 앵커는 `splitSections()`의 것을 쓴다. 서명된 미리보기 링크로 온 외부 리뷰어도 댓글만 남길 수 있다. 에이전트는 댓글을 읽고 수정안을 새 버전으로 만든다. (Directus, Sanity) **상태:** 0.10.0에서 완료.
72
+ 35. **[P1] 분할 라이브 미리보기와 스크롤 동기화.** 저장 전 로컬 상태로 200ms 디바운스 렌더, 커서 섹션과 미리보기 앵커를 양방향으로 맞추고, 375/768/전체 폭 전환을 둔다. `renderBlocks(blocks, components)`로 앱 컴포넌트를 주입한다. (Payload live preview, TinaCMS) [0.6.0에서 일부: 미리보기와 폭 전환. 스크롤 맞춤과 컴포넌트 주입은 남음]
73
+ 36. **[P1] 미리보기에서 소스로 점프.** 블록에 `line`, `endLine`을 남겨 제목을 누르면 편집기의 해당 줄을 선택한다. 댓글 인용과 섹션 diff에도 같은 좌표를 쓴다. (TinaCMS click-to-edit) **상태:** 0.10.0에서 `line`, `endLine`까지 완료. 미리보기를 눌러 줄을 찾는 동작은 아직.
74
+ 37. **[P1] 저장 없는 미리보기 API.** `cms.preview(actor, col, input)`가 `{ blocks, toc, diagnostics, diff, publicUrl }`를 돌려준다. 어드민 미리보기와 에이전트의 저장 전 자기 점검이 같은 코드를 쓴다. **상태:** 0.10.0에서 완료.
74
75
  38. **[P1] 앵커 고정과 별칭.** `## 제목 {#id}`로 명시 앵커를 허용하고, 제목을 바꾸면 옛 앵커를 `cms_anchor_aliases`에 남겨 공개 화면과 에이전트가 준 링크가 끊기지 않게 한다. (Mintlify, Fumadocs)
75
76
  39. **[P1] 슬러그 도우미와 게시 후 주소 변경.** 한글 제목에서 `suggestSlug()`(로마자 표기 + 중복 검사)를 만들고, 게시 뒤 주소를 바꾸면 `cms_redirects`에 자동 기록한다. 지금은 게시 후 변경이 아예 금지돼 있다.
76
77
  40. **[P1] 문서 구조 린트와 게시 전 품질 게이트.** `structure: { requiredSections, maxSectionChars, requireIntro, requireLink }`. 목록에 품질 배지, 게시 다이얼로그에 체크리스트. 검색이 `##` 단위라 구조가 곧 검색 품질이다. (Fumadocs, Mintlify)
77
78
  41. **[P1] 컬렉션별 문서 템플릿.** `templates: [{ key, label, body, fields }]`, `cms.create({ template })`, MCP `list_templates`. 사람과 에이전트가 같은 골격에서 시작한다. (Sanity initial value templates)
78
79
  42. **[P1] 재사용 스니펫.** `[[snippet:key]]`로 다른 문서를 끼워 넣고, 순환 감지와 "이 스니펫을 쓰는 문서 5개" 역색인을 둔다. (Mintlify snippets)
79
80
  43. **[P1] 내부 링크와 고아 문서 리포트.** `cms.linkReport()`가 `{ broken, orphans, unreachable }`를 돌려주고 어드민 "링크" 탭과 MCP 도구로 노출한다.
80
- 44. **[P1] 외부 URL 미디어와 figure 블록.** `{ url, alt, caption, width, height }`, alt 필수, https만, CLS 방지 상자, lazy 로딩. 업로드 저장소는 그 뒤. (Strapi)
81
- 45. **[P1] 붙여넣기 정규화.** HTML을 지원 부분집합 마크다운으로 바꾸고(turndown), 제로폭 문자와 스마트 따옴표를 정리하며, 사라질 문법은 편집기에서 경고한다. (Payload Lexical)
82
- 46. **[P2] 버전 이름표와 고정.** `cms_versions.label`, `pinned`; prune이 고정 버전을 보호한다. (Directus)
83
- 47. **[P1] 어드민 ⌘K 빠른 열기.** 초안 포함 문서 퍼지 검색, 최근 편집, 게시와 버전 기록 같은 액션. (Sanity)
81
+ 44. **[P1] 외부 URL 미디어와 figure 블록.** `{ url, alt, caption, width, height }`, alt 필수, https만, CLS 방지 상자, lazy 로딩. 업로드 저장소는 그 뒤. (Strapi) [0.8.0에서 107번에 흡수]
82
+ 45. **[P1] 붙여넣기 정규화.** HTML을 지원 부분집합 마크다운으로 바꾸고(turndown), 제로폭 문자와 스마트 따옴표를 정리하며, 사라질 문법은 편집기에서 경고한다. (Payload Lexical) **상태:** 0.10.0에서 완료 (turndown 없이 직접 변환).
83
+ 46. **[P2] 버전 이름표와 고정.** `cms_versions.label`, `pinned`; prune이 고정 버전을 보호한다. (Directus) **상태:** 0.10.0에서 완료.
84
+ 47. **[P1] 어드민 ⌘K 빠른 열기.** 초안 포함 문서 퍼지 검색, 최근 편집, 게시와 버전 기록 같은 액션. (Sanity) [완료 0.6.0]
84
85
  48. **[P2] 섹션 단위 편집기.** 섹션 카드로 편집, 순서 변경, 삽입. 댓글, 점프, 린트의 위치 기준이 된다. (Sanity Portable Text)
85
86
 
86
87
  ## 3. 에이전트와 검색 (B)
87
88
 
88
- 49. **[완료 0.5.0] 도구 스펙 단일 레지스트리와 `/ai` 진입점.** MCP와 AI SDK 도구가 같은 `ToolDef[]`(이름, 설명, zod 입력, 권한)를 쓰게 `tools.ts`로 옮기고, `createAgentTools(cms, { collections })`가 `search_docs`, `get_doc`, `report_gap`을 만든다. 지금 서비서는 앱 쪽에서 직접 감싼다.
89
+ 49. **[완료 0.5.0] 도구 스펙 단일 레지스트리와 `/ai` 진입점.** MCP와 AI SDK 도구가 같은 `ToolDef[]`(이름, 설명, zod 입력, 권한)를 쓰게 `tools.ts`로 옮기고, `createAgentTools(cms, { collections })`가 `search_docs`, `get_doc`, `report_gap`을 만든다. 지금 서비서는 앱 쪽에서 직접 감싼다. [0.8.0에서 `./ai` 입구를 뺌 (132번). 도구 목록은 그대로]
89
90
  50. **[P0] 토크나이저 기반 컨텍스트 패커.** 지금은 섹션을 1,400자로 자른다. 호출자가 넘긴 프로바이더 `countTokens`로만 예산을 계산하고(문자 수 추정 금지), 문장 경계 절단, 중복 억제, `{ sections, usedTokens, dropped }`를 돌려준다. (Context7 `tokens` 파라미터) [완료 0.6.0]
90
91
  51. **[P0] 섹션 패치 API.** `patch(actor, col, slug, ops)`; op는 `replace | insert_after | insert_before | delete | append` + `anchor`. 틀린 앵커는 유효 앵커 목록과 함께 422, `dryRun`은 unified diff. 60k 본문을 통째로 다시 쓰는 비용과 불필요한 409를 없앤다. MCP `patch_document`. [완료 0.6.0]
91
92
  52. **[P0] 인용 계약과 검증.** `citations: [{ id: "cms://guide/slack#connect", quote, charRange }]`와 `verifyCitations(answer, lookup)`. 앱이 출처를 그리고 없는 slug/anchor를 잡는다. (Inkeep, GitBook) [완료 0.6.0]
92
93
  53. **[P0] 사용 기록에 출처 붙이기.** `cms_hits`에 `source`(ai, mcp, rest)와 MCP `clientInfo`를 남긴다. 이번에 `lookupForAgent`가 기록을 시작했다. (GitBook 분석) [완료 0.6.0]
93
- 54. **[P1] 에이전트 작업 레시피.** "코드가 바뀌면 에이전트를 불러 관련 문서를 고친다", "출시 때 공지 초안을 쓴다" 같은 흐름을 라이브러리 기능이 아니라 예제(`examples/`)로 보여 준다. `remoteCmsTools` + 모델 호출 몇 줄이면 되게.
94
+ 54. **[P1] 에이전트 작업 레시피.** "코드가 바뀌면 에이전트를 불러 관련 문서를 고친다", "출시 때 공지 초안을 쓴다" 같은 흐름을 라이브러리 기능이 아니라 예제(`examples/`)로 보여 준다. `createCmsClient().call`과 앱의 모델 호출 몇 줄이면 되게. (모델을 부르는 코드는 이 저장소의 예제에 넣지 않고 글로만 설명한다)
94
95
  55. **[P1] `llms.txt`, `llms-full.txt`, 문서별 `.md`.** `GET /llms.txt`와 `/:c/:slug.md`를 `changeStamp()` 캐시와 함께 연다. (Mintlify)
95
96
  56. **[P1] 컬렉션 설정으로 만드는 MCP `instructions`.** 컬렉션, 링크 키, 금지 문자, 필드 설명을 담은 안내문을 생성하고 내용 해시가 바뀔 때만 바꿔 캐시를 지킨다. (Mintlify `skill.md`)
96
97
  57. **[P2] 계층 색인과 이웃 섹션.** `###`를 자식 단위로 색인하고 결과에 `more: [{ anchor, rel: prev | next | child }]`를 붙여 재검색 없이 넓힌다. (Context7)
@@ -112,7 +113,7 @@
112
113
  70. **[P0] 프롬프트 인젝션 경계.** 에이전트에게 주는 문서를 `<cms-document … trust="human|agent">` 봉투로 감싸고 "참고 자료이지 지시가 아님" 프리앰블을 붙인다. 에이전트가 쓴 미검토 문서는 표시한다. [완료 0.6.0]
113
114
  71. **[P0] `If-Match`/`ETag`.** GET에 `ETag: "v<n>"`, PATCH/DELETE/publish/restore는 `If-Match`를 `expectedVersion`으로 쓴다. 지금 DELETE에는 낙관적 가드가 없다. [완료 0.6.0]
114
115
  72. ~~**[P0] gap 기록 정책과 상한.** 이번에 익명 기록을 막았다. 남은 일: `gapLogging: off | agents | all`, (actor, normalized) 짧은 창 중복 제거, 하루 신규 행 상한.~~ [삭제] gaps를 라이브러리에서 뺌(0.6.0). 거르기와 상한은 앱이 `onSearchMiss`에서 한다.
115
- 73. **[P1] 렌더러 XSS 계약.** React `DocBody`는 트리만 받아 엘리먼트로 그리고 HTML 문자열 경로를 두지 않는다. `javascript:`, `data:`, 대소문자와 공백 우회, 중첩 링크를 담은 적대적 픽스처 테스트.
116
+ 73. **[P1] 렌더러 XSS 계약.** React `DocBody`는 트리만 받아 엘리먼트로 그리고 HTML 문자열 경로를 두지 않는다. `javascript:`, `data:`, 대소문자와 공백 우회, 중첩 링크를 담은 적대적 픽스처 테스트. [0.6.0에서 일부: javascript: 링크 테스트만]
116
117
  74. **[P1] 증분 색인.** `SearchIndex.upsertDoc / removeDoc`로 바뀐 문서만 갈아끼우고, 영문 어휘 스캔을 접두 맵으로. 수천 문서에서 p95 5ms를 지킨다.
117
118
  75. **[P1] 프로세스 간 무효화를 `pg_notify` + 시퀀스로.** `cms_change_log(seq bigserial)`와 `LISTEN`으로 즉시 무효화하고 폴링은 안전망으로. 지금 `changeStamp()`는 30~60초마다 `count(*)`를 돌린다.
118
119
  76. **[P1] 게시본 읽기 캐시 어댑터.** `CacheAdapter`(메모리, Redis, Next `unstable_cache`), 키에 `publishedVersion`, 무효화는 `onChange`와 75번.
@@ -132,7 +133,7 @@
132
133
  87. **[P0] 분리 게이트.** `npm pack` 결과를 임시 Next 14 앱에 설치해 subpath `exports`가 실제로 resolve되는지, `publint`와 `attw` 검사. (지금 앱 import 금지 규칙은 `parts.test.ts`가 지킨다.) [완료 0.6.0]
133
134
  88. **[P0] `cmsTables({ prefix, schema })` 팩토리.** `DrizzleRepo`가 테이블 세트를 생성자로 받고 `cmsDdl(tables)`도 접두사와 스키마를 따른다. (Payload `schemaName`) [완료 0.6.0]
134
135
  89. **[P0] 스키마 버전 핸드셰이크와 `migrate check`.** 패키지가 기대하는 `SCHEMA_VERSION`과 DB를 비교해 빠진 컬럼만 guarded `ALTER`로 출력한다. 서비서의 `migrate-prod.ts` step 형식 그대로. [완료 0.6.0]
135
- 90. **[P1] 드라이버 독립 어댑터.** `PgDatabase` 계열로 넓히고 neon-http(트랜잭션 없음)는 `db.batch`로 폴백. postgres.js, pglite 팩토리.
136
+ 90. **[P1] 드라이버 독립 어댑터.** `PgDatabase` 계열로 넓히고 neon-http(트랜잭션 없음)는 `db.batch`로 폴백. postgres.js, pglite 팩토리. [0.6.0에서 일부: 트랜잭션이 있는 드라이버와 pglite. neon-http 폴백은 남음]
136
137
  91. **[P1] `createTestCms()`와 fetch 하네스.** `agent-cms/testing`에서 `seedDoc`, `asAdmin`, `asKey(scopes)`, `createFetchMock(cms)`. (Better Auth)
137
138
  92. **[P1] 플러그인 시스템.** `definePlugin({ name, setup(ctx) })`로 훅, 컬렉션 확장, 라우트, 테이블 추가. 감사 로그, 웹훅, rate limit이 코어 수정 없이 붙는다. (Better Auth registry, Payload plugins)
138
139
  93. **[P1] 전체 라이프사이클 훅.** `beforeValidate`, `beforeChange`(변형 가능), `afterChange`, `before/afterPublish`, `afterDelete`, `afterRead`와 `{ actor, previous, operation, abort }` 컨텍스트. (Payload hooks)
@@ -144,7 +145,7 @@
144
145
  99. **[P1] 공개 렌더링 킷.** `agent-cms/next`: `generateDocParams`, 태그 캐시(`cms:guide:slug`), `revalidateDoc`, sitemap, RSS, OG 이미지.
145
146
  100. **[P1] `agent-cms lint` 콘텐츠 린터.** 저장 검증과 같은 함수로 전체 문서를 검사하고 `--fix`, `--staged`(pre-commit).
146
147
  101. **[P1] `agent-cms dev` 단독 하네스.** 호스트 앱 없이 pglite나 메모리 저장소로 어드민, REST, MCP를 띄운다. (Keystone dev)
147
- 102. **[P1] 호환성 매트릭스 CI.** Next 14/15/16, React 18/19, zod 3/4, ai SDK 버전 조합에 tarball을 설치해 스모크 테스트하고 지원표를 자동 갱신한다.
148
+ 102. **[P1] 호환성 매트릭스 CI.** Next 14/15/16, React 18/19, zod 3/4 조합에 tarball을 설치해 스모크 테스트하고 지원표를 자동 갱신한다.
148
149
  103. **[P1] 에이전트용 라이브러리 문서.** 문서 사이트의 `llms.txt`, MCP 리소스 `cms://docs/*`, subpath별 TypeDoc. 코딩 에이전트에게 "agent-cms로 어드민 붙여 줘"가 첫 사용 경로가 된다.
149
150
  104. **[P2] Edge 런타임.** `node:crypto` 대신 `crypto.subtle`, `doctor --runtime=edge`.
150
151
  105. **[P2] `import --dry-run --diff`.** 폴더 md와 DB의 차이를 문서별로 보여 주고 `db-wins | file-wins | newest`를 고른다.
@@ -174,5 +175,50 @@
174
175
  - `toJsonSchema`가 `.min/.max/.default`를 버려 모델이 제한을 모른다. [완료 0.5.3]
175
176
  - 키 생성의 `% 62` 모듈로 편향(거부 샘플링으로), 쓰이지 않는 `sameHash`. [완료 0.5.3]
176
177
  - 문서 삭제 시 `cms_gaps.document_slug` 참조가 남는다. [해당 없음: 0.6.0에서 gaps 제거]
177
- - `remoteCmsTools`는 키 권한과 상관없이 모든 도구를 노출한다(`only`로 직접 줄여야 함). 시작할 때 `tools/list`로 맞추는 비동기 버전 `await remoteCmsToolsFor(...)`. [완료 0.5.3]
178
+ - `remoteCmsTools`는 키 권한과 상관없이 모든 도구를 노출한다(`only`로 직접 줄여야 함). 시작할 때 `tools/list`로 맞추는 비동기 버전 `await remoteCmsToolsFor(...)`. [완료 0.5.3, 0.8.0에서 `./ai`와 함께 뺌: `createCmsClient().listTools()`가 같은 일을 한다]
178
179
  - `cms_documents`에 0.4.0까지 쓰던 `covers`, `needs_review`, `review_reason`, `pending_pr`, `cms_versions.pr` 열이 기존 DB에 남아 있다. 쓰지 않으니 해는 없지만 `doctor`가 알려 주고 지울 SQL을 내야 한다. [완료 0.6.0]
180
+
181
+ ## 8. 미디어, 그리고 2026-11 조사에서 나온 항목
182
+
183
+ 다른 CMS(Payload, Directus, Strapi, Sanity)와 비교해서 나온 빈자리다. 자세한 내용은 `docs/roadmap/`.
184
+
185
+ 107. **[P1] 미디어 라이브러리.** S3 호환 저장소 연결(`./storage-s3`), 브라우저 직접 올리기(조각, 재시도, 기본 5GB), 공개와 비공개 저장소, 폴더와 태그, 허용 형식과 최대 크기를 앱 전체와 저장소별과 필드별로 설정, 본문 `![alt](asset:id/name)` 문법, 이미지와 파일 필드, 사용처와 삭제 확인, 브라우저 썸네일과 변환 주소 연결구, 에이전트 도구 6개. (Payload, Directus, Strapi) [0.8.0] → 0.8.0에서 완료. 화면에서 파일을 옮기거나 이름을 바꾸는 일은 108번(파일 관리자)에서 한다.
186
+ 108. **[P1] 버킷 파일 관리자.** 버킷 전체를 폴더로 탐색하고 CMS가 모르는 파일도 등록, 여러 파일 이동과 삭제, 기한이 있는 공유 링크. [0.9.0] → 화면, REST, 도구 3개, `storage sync`까지 만듦(0.9.0에 나감). 일부만 다르게 만든 점은 `docs/roadmap/1-media-and-files.md`의 구현 결과에 적었다.
187
+ 109. **[P1] Vercel Blob 어댑터.** `./storage-vercel-blob`. [0.9.0]
188
+ 110. **[P2] 선택형 서버 이미지 변환 모듈.** sharp를 쓰는 앱만 켠다. 미리 정한 크기 목록, 크기 상한, 결과 캐시, 자르기와 초점 지정. (Payload, Directus, Sanity) [0.9.0]
189
+ 111. **[P1] 릴리스.** 여러 문서의 게시와 게시 취소를 묶어 한 번에, 또는 예약해서 실행한다. 하나라도 문제가 있으면 전부 하지 않는다. (Strapi, Sanity) **상태:** 0.10.0에서 완료 (되돌리기 없음).
190
+ 112. **[P1] 단일 문서.** 사이트 설정이나 메뉴처럼 하나만 있는 문서(`defineSingle`).
191
+ 113. **[P1] 역할 관리 화면.** 역할마다 컬렉션과 미디어와 폼의 읽기, 쓰기, 게시, 삭제를 정하고 사람을 넣는다. 지금은 권한을 코드 함수로만 정한다. (Strapi, Directus)
192
+ 114. **[이 패키지에서는 하지 않음] AI 보조.** 편집기에서 요약, 검색어, 대체 텍스트, 번역 초안을 만드는 기능 (Sanity AI Assist). 모델을 부르는 기능이라 이 패키지에 넣지 않는다. 확장 패키지가 134번의 자리에 붙인다.
193
+ 115. **[P1] 단독 서버.** `agent-cms serve`로 호스트 앱 없이 어드민, REST, MCP를 띄워 다른 언어의 앱이 REST와 OpenAPI로 쓴다(101번 확장). Docker 이미지 포함.
194
+ 116. **[P2] 다른 화면 프레임워크의 어드민.** Vue, Svelte용 복사형 부품.
195
+ 117. **[P1] 공개 npm 배포와 커뮤니티 문서.** CONTRIBUTING, 행동 강령, 보안 신고 안내, 이슈 템플릿, 영어 로드맵. [npm 공개 배포는 0.6.1에서 완료. 커뮤니티 문서가 남음]
196
+ 118. **[P1] 갤러리 필드.** 이미지 여러 장과 순서(`assetIds()`).
197
+ 119. **[P1] 실시간 공동 편집.** 같은 문서를 연 사람과 에이전트의 표시와 커서, 겹치지 않는 변경의 자동 병합. 1단계는 서버리스에서도 도는 방식, 2단계는 WebSocket 선택 모듈. (Sanity, Directus) **상태:** 0.10.0에서 1단계 완료 (표시, 커서, 겹치지 않는 저장의 자동 병합. 글자 단위 실시간 모듈은 아직).
198
+ 120. **[P1] 자동화 흐름.** "문서가 게시되면, 분류가 News이면, 태그를 붙이고 웹훅을 보낸다" 같은 규칙을 화면에서 만든다. 실행 기록과 시험 실행. 플러그인이 동작을 더할 수 있다. (Directus Flows)
199
+ 121. **[P1] 대시보드.** 문서 수와 상태, 사람과 에이전트의 변경 추이, 많이 본 문서, 최근 활동. (Directus Insights)
200
+ 122. **[P1] 단독 서버용 로그인.** 이메일과 비밀번호, OIDC 방식의 SSO, 세션, 사용자 관리. 호스트 앱에 얹을 때는 지금처럼 앱의 로그인을 쓴다.
201
+ 123. **[P1] 폼 빌더.** 문의 같은 폼을 화면에서 만들고 제출을 모은다. 스팸 방지, 파일 첨부, CSV 내보내기, 웹훅. (Payload form-builder)
202
+ 124. **[P1] SEO 도구.** 문서마다 검색 제목, 설명, 공유 이미지, 대표 주소, 노출 여부. 검색 결과 미리보기와 길이 경고, 사이트맵. (Payload seo)
203
+ 125. **[P1] 리다이렉트 관리.** 주소를 바꾸면 자동으로 생기는 것과 직접 만든 것을 한 화면에서 관리(39번의 `cms_redirects`를 쓴다). (Payload redirects)
204
+ 126. **[P1] 백그라운드 작업 실행기.** 예약 게시, 웹훅 재시도, 휴지통 비우기, 자동화가 함께 쓰는 작업 표와 `/_cron` 진입점. (Payload jobs)
205
+ 127. **[P2] 앱용 실시간 변경 알림.** 앱이 문서 변경을 SSE로 구독한다(75번 위에). (Directus realtime)
206
+ 128. **[P2] 저장된 필터.** 문서 목록의 검색과 필터 조합에 이름을 붙여 다시 쓴다. (Payload query presets) **상태:** 0.10.0에서 완료.
207
+ 129. **[P1] 목록 필드.** 메뉴 항목처럼 여러 값을 한 묶음으로 반복해 넣고 순서를 바꾸는 입력(`z.array(z.object())`의 위젯).
208
+ 130. **[P2] 미디어 후속.** 어드민에서 URL로 가져오기, 새로 고친 뒤 올리기 이어 하기, 사진 위치 정보 지우기, 같은 주소로 파일 교체, 바이러스 검사 연결구.
209
+ 131. **[P2] 다른 CMS에서 가져오기.** WordPress 내보내기 파일, CSV, JSON.
210
+ 132. **[P0] `./ai` 입구 제거.** 이 패키지는 모델을 부르지 않는다. `./ai`(`cmsTools`, `remoteCmsTools`)와 `ai` 의존성을 빼고, `./tools`에 `callTool`을 넣어 어떤 에이전트 틀에서든 `toolsFor`와 `callTool`로 도구를 붙이게 한다. 모델 호출 라이브러리를 불러오지 않는다는 것을 테스트로 지킨다. [0.8.0]
211
+ 133. **[P0] 사람을 대신한 에이전트 표시.** 로그인한 사람의 권한으로 움직이는 에이전트가 고친 버전을 구분해 기록한다(`actor.agent`). 권한은 그 사람과 같고, "에이전트 변경" 표시와 감사 로그에 에이전트의 이름이 남는다. [0.8.0]
212
+ 134. **[P1] 어드민 확장 자리.** 편집기 머리글, 편집기 옆 패널, 필드 이름 옆, 미디어 정보 패널에 앱이나 플러그인이 버튼과 패널을 꽂는다(`CmsProvider`의 `slots`). 비어 있으면 아무것도 보이지 않는다. [미디어 자리는 0.8.0, 나머지는 92번과 함께]
213
+ 135. **[P1] 검색 확장 연결구.** 플러그인이 "추가 순위"를 돌려주면 낱말 검색의 순위와 합친다(reciprocal rank fusion). 뜻으로 찾는 검색 같은 것을 이 패키지 밖에서 붙일 수 있게 한다.
214
+
215
+ ## 9. 순서
216
+
217
+ 묶음 순서대로 구현한다. 묶음 안에서는 적힌 순서대로. 괄호는 임시 버전. 12번과 114번은 하지 않는다.
218
+
219
+ 1. 미디어와 파일 저장소 (0.8.0, 0.9.0): 132, 133, 107, 108, 109, 110, 130
220
+ 2. 편집과 게시 흐름 (0.10.0): 7, 19, 8, 9, 119, 34, 111, 46, 35, 36, 37, 45, 48, 128
221
+ 3. 연동과 운영 (0.11.0): 126, 20, 120, 95, 26, 105, 131, 79, 27, 113, 101, 115, 122, 121, 93, 92, 134, 80, 18, 81, 83, 73, 21, 75, 76, 77, 78, 82, 90, 104, 106, 127
222
+ 4. 콘텐츠 모델 (0.12.0): 2, 118, 129, 4, 5, 112, 41, 42, 3, 38, 39, 125, 124, 123
223
+ 5. 검색과 AI (0.13.0): 74, 58, 59, 60, 57, 63, 13, 61, 135, 62, 15, 64, 16, 67, 68, 55, 56, 54, 40, 65, 100, 43, 66
224
+ 6. 오픈소스 공개 준비 (1.0.0): 117, 28, 103, 102, 91, 94, 96, 98, 99, 116
@@ -0,0 +1,36 @@
1
+ # Upgrading to 0.10
2
+
3
+ 0.10 is not released yet. This file grows as its parts land.
4
+
5
+ ## 1. Schema version 4
6
+
7
+ ```sh
8
+ npx agent-cms migrate check
9
+ npx agent-cms migrate apply # or `migrate print` and run the SQL yourself
10
+ ```
11
+
12
+ The step only adds things and is safe to run twice: columns on `cms_documents` (`deleted_at`, `deleted_by`, `schedule`, `due_at`, `review`), `cms_versions` (`label`, `pinned`, `approved_by`, `approved_at`) and `cms_assets` (`deleted_at`, `deleted_by`), and the tables `cms_comments`, `cms_releases`, `cms_saved_filters` and `cms_presence`. Re-export `cmsComments`, `cmsReleases`, `cmsSavedFilters` and `cmsPresence` from your Drizzle schema next to the other tables.
13
+
14
+ ## 2. Deleting now means the trash
15
+
16
+ `cms.remove`, `DELETE /collections/:c/:slug`, the `delete_document` tool and deleting a file used to be final. They now put the document or file in the trash for 30 days.
17
+
18
+ - A trashed document is not found by `get`, `list`, search or agents. Its address stays taken: creating a document with the same slug fails with `slug_in_trash` until it is restored or purged.
19
+ - A trashed file's object stays in the bucket until it is purged, so a public address keeps answering until then.
20
+ - `createCms({ trash: { days: 0 } })` keeps the old behaviour. Tests that count rows after a delete want this, or `cms.trash.purge(admin, "all")`.
21
+ - Something has to call `cms.runScheduled()` for old trash to be emptied (next section).
22
+
23
+ ## 3. A cron for schedules and the trash
24
+
25
+ Scheduled publishing and emptying the trash happen when `cms.runScheduled()` runs. Set `createCms({ cronSecret })` and call the route every few minutes:
26
+
27
+ ```
28
+ POST /api/cms/_cron
29
+ Authorization: Bearer <cronSecret>
30
+ ```
31
+
32
+ Without `cronSecret` the route answers 404. On Vercel, a cron job with `CRON_SECRET` sends exactly this header. Calling it from two places at once is safe.
33
+
34
+ ## 4. Type changes
35
+
36
+ `CmsDoc` has `deletedAt`, `deletedBy`, `schedule`, `dueAt`, `review`; `CmsVersion` has `label`, `pinned`, `approvedBy`, `approvedAt`; `DocSummary` has `schedule` and `review`; `DocCounts` has `scheduled` and `review`; `CmsAsset` has `deletedAt`, `deletedBy`. A custom `CmsRepo` has new methods (`updateVersion`, comments, releases, filters, presence) and `findDoc`, `findDocById`, `findAsset` take `{ trashed }`. `MemoryRepo` and `DrizzleRepo` implement them.
package/UPGRADE-0.8.md ADDED
@@ -0,0 +1,117 @@
1
+ # Upgrading to agent-cms 0.8
2
+
3
+ 0.8 is not released yet. This file grows as its parts land; what is here is
4
+ already on `main`.
5
+
6
+ ## 1. `./ai` is gone: the package no longer calls into a model library
7
+
8
+ agent-cms hands agents tools. It never calls a model, and from 0.8 it does
9
+ not depend on any library that does. The `./ai` entry (`cmsTools`,
10
+ `remoteCmsTools`, `remoteCmsToolsFor`) and the optional `ai` peer dependency
11
+ are removed. MCP, REST, the CLI and `./tools` are unchanged.
12
+
13
+ If you used `cmsTools`, wrap the same tool list yourself. It is about ten
14
+ lines with whatever your agent framework calls a tool:
15
+
16
+ ```ts
17
+ import { toolsFor, callTool } from "@mainsoft/agent-cms/tools";
18
+
19
+ const actor = { kind: "system", label: "assistant" } as const;
20
+
21
+ const tools = Object.fromEntries(
22
+ toolsFor(cms, actor).map((t) => [
23
+ `cms_${t.name}`, // the old `prefix` option
24
+ {
25
+ description: t.description,
26
+ inputSchema: t.input, // a zod object
27
+ execute: (args: unknown) => callTool(cms, actor, t.name, args),
28
+ },
29
+ ])
30
+ );
31
+ ```
32
+
33
+ `callTool` does what the old wrapper did: it checks the input, runs the tool
34
+ with the actor's permissions, records the call as made by an agent
35
+ (`via: "ai"`), and returns a CMS error (`{ error, kind, message, params }`)
36
+ as a result instead of throwing. `toolsFor(cms, actor, only)` replaces the
37
+ `only` option.
38
+
39
+ If you used `remoteCmsTools` or `remoteCmsToolsFor`:
40
+
41
+ ```ts
42
+ import { createCmsClient } from "@mainsoft/agent-cms/client";
43
+ import { toolErrorResult } from "@mainsoft/agent-cms/tools";
44
+
45
+ const api = createCmsClient({ url, key });
46
+ const tools = await api.listTools(); // only what the key may use; each has a JSON Schema
47
+ const run = (name: string, args: Record<string, unknown>) =>
48
+ api.call(name, args).catch((e) => toolErrorResult(e) ?? Promise.reject(e));
49
+ ```
50
+
51
+ ## 2. Schema version 3
52
+
53
+ ```sh
54
+ npx agent-cms migrate check # what is missing
55
+ npx agent-cms migrate apply # or `migrate print` and run the SQL yourself
56
+ ```
57
+
58
+ The step only adds things, and is safe to run twice:
59
+
60
+ - `cms_documents.updated_by_agent`, `cms_versions.author_agent`,
61
+ `cms_audit.actor_agent` (text, nullable).
62
+ - Tables `cms_assets` and `cms_asset_refs` for the media library that ships
63
+ with 0.8. They stay empty until you configure a file store.
64
+
65
+ Until it has run, the CMS answers `schema_outdated`, as with every schema
66
+ change.
67
+
68
+ ## 3. An agent acting for a person
69
+
70
+ When an agent in your app works with a signed-in person's permissions, say
71
+ so on the actor:
72
+
73
+ ```ts
74
+ await callTool(cms, { ...user, agent: { label: "assistant" } }, "patch_document", args);
75
+ ```
76
+
77
+ Permissions are exactly the person's. The version, the document and the audit
78
+ log also record the agent's name, the edit shows up under "Agent changes" for
79
+ review, and the admin shows it as "assistant, Kim". Only code that calls the
80
+ CMS in-process can set this; REST and MCP never accept it (the handler drops
81
+ it even if `resolveUser` returns it).
82
+
83
+ Type changes that follow: `CmsDoc.updatedByAgent`, `CmsVersion.authorAgent`,
84
+ `AuditEntry.actorAgent` and `DocSummary.updatedByAgent` are new (`string |
85
+ null`). `AgentChange.authorKind` can now be `"user"`, and `AgentChange.behalf`
86
+ names the person the agent acted for. A custom `CmsRepo` has new methods for
87
+ files (`insertAsset` … `listAssetRefs`); `MemoryRepo` and `DrizzleRepo`
88
+ implement them.
89
+
90
+ ## 4. The media library is opt-in
91
+
92
+ Nothing changes until you pass `media` to `createCms` (README, "Media
93
+ library"). Two things to know even if you never do:
94
+
95
+ - `parseMarkdown` has a new block (`media`) and two new inlines (`image`,
96
+ `file`). A renderer with an exhaustive `switch` needs cases for them; one
97
+ that ignores unknown blocks shows nothing for a media line.
98
+ - A line that is only `![alt](https://…)` used to render as text and is now
99
+ an image block. `![alt](asset:…)` in a body is checked on save: without a
100
+ media library it fails with `asset_missing`.
101
+
102
+ When you turn it on: re-export `cmsAssets` and `cmsAssetRefs` from your
103
+ Drizzle schema next to the other tables, add the same `media` object to
104
+ `agent-cms.config.ts`, and run `npx agent-cms storage check --origin
105
+ https://your-site` once per environment.
106
+
107
+ ## 5. Admin screens
108
+
109
+ Run `npx agent-cms add --update` (or `--diff` first) to get this version of
110
+ the screens you copied. What changed in them:
111
+
112
+ - `cms-doc-editor` now imports `./cms-media-picker` (and `cms-upload.ts`
113
+ with it), also in apps without a media library; `add` brings both.
114
+ - `cms-shell`'s `hrefFor` may be asked for `{ kind: "media" }`. The default
115
+ is `<basePath>/media`; add that page with `cms-media` when you turn the
116
+ library on.
117
+ - New strings start with `media_` in `cms-messages.ts` (English and Korean).
package/dist/agent.cjs CHANGED
@@ -29,34 +29,50 @@ __export(agent_exports, {
29
29
  });
30
30
  module.exports = __toCommonJS(agent_exports);
31
31
 
32
- // src/cms.ts
33
- var import_node_crypto = require("crypto");
34
-
35
- // src/errors.ts
36
- function isCmsError(e) {
37
- return !!e && typeof e === "object" && e.isCmsError === true;
38
- }
39
-
40
32
  // src/markdown.ts
41
33
  var APP_LINK_RE = /\[\[link:([a-z0-9][a-z0-9._-]*)\|([^\]]+)\]\]/gi;
42
34
  function anchorOf(text) {
43
35
  const base = text.trim().toLowerCase().replace(/[`*_[\]()<>!?.,:;'"“”‘’/\\|]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
44
36
  return base || "section";
45
37
  }
38
+ var ASSET_TARGET = /^asset:([a-z0-9]{12})(?:\/([^\s)]*))?$/;
39
+ var IMAGE = String.raw`!\[([^\]]*)\]\(\s*((?:[^()\s]|\([^()\s]*\))+)(?:\s+"([^"]*)")?\s*\)`;
40
+ var IMAGE_LINE = new RegExp(`^\\s*${IMAGE}\\s*$`);
41
+ var IMAGE_ANY = new RegExp(IMAGE, "g");
42
+ var safeDecode = (s) => {
43
+ try {
44
+ return decodeURIComponent(s);
45
+ } catch {
46
+ return s;
47
+ }
48
+ };
49
+ function mediaTarget(target) {
50
+ const a = ASSET_TARGET.exec(target);
51
+ if (a) return { asset: a[1], name: safeDecode(a[2] ?? ""), src: null };
52
+ if (/^https:\/\//i.test(target)) return { asset: null, name: "", src: target };
53
+ return null;
54
+ }
46
55
  function parseInline(src) {
47
56
  const out = [];
48
- const re = /(\[\[link:([a-z0-9][a-z0-9._-]*)\|([^\]]+)\]\]|\*\*([^*]+)\*\*|`([^`]+)`|\[([^\]]+)\]\(((?:[^()\s]|\([^()\s]*\))+)\))/gi;
57
+ const re = new RegExp(String.raw`(\[\[link:(?<key>[a-z0-9][a-z0-9._-]*)\|(?<keyLabel>[^\]]+)\]\]|\*\*(?<strong>[^*]+)\*\*|` + "`(?<code>[^`]+)`" + String.raw`|!\[(?<alt>[^\]]*)\]\(\s*(?<img>(?:[^()\s]|\([^()\s]*\))+)(?:\s+"(?<cap>[^"]*)")?\s*\)|\[(?<label>[^\]]+)\]\((?<href>(?:[^()\s]|\([^()\s]*\))+)\))`, "gi");
49
58
  let last = 0;
50
59
  let m;
51
60
  while (m = re.exec(src)) {
61
+ const g = m.groups;
52
62
  if (m.index > last) out.push({ t: "text", v: src.slice(last, m.index) });
53
- if (m[2]) out.push({ t: "applink", key: m[2], v: m[3] });
54
- else if (m[4] !== void 0) out.push({ t: "strong", v: m[4] });
55
- else if (m[5] !== void 0) out.push({ t: "code", v: m[5] });
56
- else if (m[6] !== void 0) {
57
- const href = m[7];
58
- if (/^(https?:\/\/|mailto:|\/(?!\/)|#)/i.test(href)) out.push({ t: "link", href, v: m[6] });
59
- else out.push({ t: "text", v: m[6] });
63
+ if (g.key) out.push({ t: "applink", key: g.key, v: g.keyLabel });
64
+ else if (g.strong !== void 0) out.push({ t: "strong", v: g.strong });
65
+ else if (g.code !== void 0) out.push({ t: "code", v: g.code });
66
+ else if (g.img !== void 0) {
67
+ const target = mediaTarget(g.img);
68
+ if (target) out.push({ t: "image", ...target, alt: g.alt, v: g.alt });
69
+ else out.push({ t: "text", v: g.alt });
70
+ } else if (g.label !== void 0) {
71
+ const href = g.href;
72
+ const file = ASSET_TARGET.exec(href);
73
+ if (file) out.push({ t: "file", asset: file[1], name: safeDecode(file[2] ?? ""), v: g.label });
74
+ else if (/^(https?:\/\/|mailto:|\/(?!\/)|#)/i.test(href)) out.push({ t: "link", href, v: g.label });
75
+ else out.push({ t: "text", v: g.label });
60
76
  }
61
77
  last = m.index + m[0].length;
62
78
  }
@@ -104,7 +120,13 @@ function splitSections(body) {
104
120
  return out;
105
121
  }
106
122
 
123
+ // src/errors.ts
124
+ function isCmsError(e) {
125
+ return !!e && typeof e === "object" && e.isCmsError === true;
126
+ }
127
+
107
128
  // src/cms.ts
129
+ var import_node_crypto = require("crypto");
108
130
  var PREVIEW_TTLS = { "1h": 36e5, "24h": 864e5, "7d": 7 * 864e5 };
109
131
  var coreOf = (c) => "core" in c && c.core ? c.core : c;
110
132
 
@@ -156,7 +178,7 @@ async function lookupForAgent(cms, actor, collections, query, o = {}) {
156
178
  for (const id of new Set(hits.map((h) => h.docId))) {
157
179
  const doc = await core.repo.findDocById(id);
158
180
  const v = doc?.publishedVersion ? await core.repo.getVersion(id, doc.publishedVersion) : null;
159
- trustOf.set(id, v && v.authorKind !== "user" ? "agent" : "human");
181
+ trustOf.set(id, v && (v.authorKind !== "user" || v.authorAgent) ? "agent" : "human");
160
182
  }
161
183
  const links = [];
162
184
  const seen = /* @__PURE__ */ new Set();
package/dist/agent.d.cts CHANGED
@@ -1,10 +1,10 @@
1
- import { C as CmsLike } from './cms-D6D89-qZ.cjs';
1
+ import { C as CmsLike } from './cms-C_vkAxYV.cjs';
2
2
  export { appLinkKeys } from './markdown.cjs';
3
3
  import { Actor } from './types.cjs';
4
+ import './storage.cjs';
4
5
  import 'zod';
5
6
  import './diff.cjs';
6
7
  import './errors.cjs';
7
- import './repo-CeDxUxO6.cjs';
8
8
 
9
9
  /**
10
10
  * What an agent gets back from a lookup: a few sections (not whole documents)
package/dist/agent.d.ts CHANGED
@@ -1,10 +1,10 @@
1
- import { C as CmsLike } from './cms-BPp01z-8.js';
1
+ import { C as CmsLike } from './cms-pqJyowu1.js';
2
2
  export { appLinkKeys } from './markdown.js';
3
3
  import { Actor } from './types.js';
4
+ import './storage.js';
4
5
  import 'zod';
5
6
  import './diff.js';
6
7
  import './errors.js';
7
- import './repo-BWI2Pkrv.js';
8
8
 
9
9
  /**
10
10
  * What an agent gets back from a lookup: a few sections (not whole documents)
package/dist/agent.js CHANGED
@@ -4,15 +4,17 @@ import {
4
4
  envelope,
5
5
  lookupForAgent,
6
6
  verifyCitations
7
- } from "./chunk-52NUUZC7.js";
8
- import "./chunk-6K5ZTGHQ.js";
9
- import "./chunk-OQ55GEF3.js";
10
- import "./chunk-AKN7SUXU.js";
11
- import "./chunk-VICZ76TR.js";
12
- import "./chunk-DOADAH4L.js";
7
+ } from "./chunk-7Y6TU2UA.js";
8
+ import "./chunk-7SCYDG2G.js";
13
9
  import {
14
10
  appLinkKeys
15
- } from "./chunk-CRDW6Q72.js";
11
+ } from "./chunk-MA6VKJ3F.js";
12
+ import "./chunk-PEQY4N73.js";
13
+ import "./chunk-3OPKTBEI.js";
14
+ import "./chunk-AKN7SUXU.js";
15
+ import "./chunk-KAO3Z3CF.js";
16
+ import "./chunk-PGV2QPIL.js";
17
+ import "./chunk-6PB4ZCHH.js";
16
18
  import "./chunk-2NTK7H4W.js";
17
19
  export {
18
20
  ENVELOPE_PREAMBLE,