@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.
- package/CHANGELOG.md +60 -0
- package/README.md +291 -32
- package/TODO.md +72 -26
- package/UPGRADE-0.10.md +36 -0
- package/UPGRADE-0.8.md +117 -0
- package/dist/agent.cjs +39 -17
- package/dist/agent.d.cts +2 -2
- package/dist/agent.d.ts +2 -2
- package/dist/agent.js +9 -7
- package/dist/bin.js +4528 -355
- package/dist/{chunk-OQ55GEF3.js → chunk-3OPKTBEI.js} +1 -1
- package/dist/chunk-6PB4ZCHH.js +328 -0
- package/dist/chunk-7SCYDG2G.js +2943 -0
- package/dist/chunk-7WJIIJCI.js +544 -0
- package/dist/chunk-7Y6TU2UA.js +150 -0
- package/dist/{chunk-EXV6JNLY.js → chunk-AKCXMT3X.js} +15 -22
- package/dist/{chunk-QC2M4NZY.js → chunk-BFVBHIHV.js} +72 -1
- package/dist/chunk-DSJETZT4.js +493 -0
- package/dist/{chunk-IW3D4I7Q.js → chunk-IU2SMWAM.js} +246 -4
- package/dist/{chunk-VICZ76TR.js → chunk-KAO3Z3CF.js} +43 -2
- package/dist/{chunk-CRDW6Q72.js → chunk-MA6VKJ3F.js} +87 -25
- package/dist/{chunk-6K5ZTGHQ.js → chunk-PEQY4N73.js} +16 -0
- package/dist/{chunk-DOADAH4L.js → chunk-PGV2QPIL.js} +40 -0
- package/dist/{chunk-Y63XQS2J.js → chunk-TOZQYJFG.js} +1 -1
- package/dist/cli.cjs +4528 -355
- package/dist/cli.d.cts +19 -3
- package/dist/cli.d.ts +19 -3
- package/dist/cli.js +206 -16
- package/dist/client.cjs +72 -1
- package/dist/client.d.cts +308 -6
- package/dist/client.d.ts +308 -6
- package/dist/client.js +1 -1
- package/dist/cms-C_vkAxYV.d.cts +1537 -0
- package/dist/cms-pqJyowu1.d.ts +1537 -0
- package/dist/config.d.cts +7 -1
- package/dist/config.d.ts +7 -1
- package/dist/drizzle-repo-CviH3EX7.d.cts +146 -0
- package/dist/drizzle-repo-DWLD0rWe.d.ts +146 -0
- package/dist/errors.cjs +82 -1
- package/dist/errors.d.cts +43 -3
- package/dist/errors.d.ts +43 -3
- package/dist/errors.js +2 -2
- package/dist/frontmatter.d.cts +5 -4
- package/dist/frontmatter.d.ts +5 -4
- package/dist/http.cjs +640 -94
- package/dist/http.d.cts +51 -2
- package/dist/http.d.ts +51 -2
- package/dist/http.js +203 -13
- package/dist/index.cjs +3759 -575
- package/dist/index.d.cts +8 -8
- package/dist/index.d.ts +8 -8
- package/dist/index.js +226 -30
- package/dist/markdown.cjs +89 -25
- package/dist/markdown.d.cts +57 -3
- package/dist/markdown.d.ts +57 -3
- package/dist/markdown.js +5 -1
- package/dist/mcp.cjs +314 -37
- package/dist/mcp.d.cts +3 -2
- package/dist/mcp.d.ts +3 -2
- package/dist/mcp.js +12 -9
- package/dist/messages/en.cjs +40 -0
- package/dist/messages/en.js +1 -1
- package/dist/messages/ko.cjs +40 -0
- package/dist/messages/ko.js +40 -0
- package/dist/registry/cms-audit.json +1 -1
- package/dist/registry/cms-doc-editor.json +15 -4
- package/dist/registry/cms-doc-list.json +2 -1
- package/dist/registry/cms-files.json +29 -0
- package/dist/registry/cms-lib.json +3 -3
- package/dist/registry/cms-media-picker.json +29 -0
- package/dist/registry/cms-media.json +28 -0
- package/dist/registry/cms-preview-comments.json +24 -0
- package/dist/registry/cms-releases.json +28 -0
- package/dist/registry/cms-shell.json +2 -2
- package/dist/registry/cms-trash.json +24 -0
- package/dist/registry/cms-versions.json +2 -1
- package/dist/registry/registry.json +163 -3
- package/dist/storage-s3.cjs +168 -0
- package/dist/storage-s3.d.cts +53 -0
- package/dist/storage-s3.d.ts +53 -0
- package/dist/storage-s3.js +143 -0
- package/dist/storage.cjs +373 -0
- package/dist/storage.d.cts +183 -0
- package/dist/storage.d.ts +183 -0
- package/dist/storage.js +49 -0
- package/dist/tables.cjs +251 -3
- package/dist/tables.d.cts +4965 -681
- package/dist/tables.d.ts +4965 -681
- package/dist/tables.js +14 -2
- package/dist/tools.cjs +331 -20
- package/dist/tools.d.cts +54 -7
- package/dist/tools.d.ts +54 -7
- package/dist/tools.js +16 -7
- package/dist/types.cjs +99 -1
- package/dist/types.d.cts +205 -5
- package/dist/types.d.ts +205 -5
- package/dist/types.js +5 -3
- package/package.json +32 -22
- package/dist/ai.cjs +0 -555
- package/dist/ai.d.cts +0 -48
- package/dist/ai.d.ts +0 -48
- package/dist/ai.js +0 -73
- package/dist/chunk-52NUUZC7.js +0 -1446
- package/dist/chunk-IGL2V6US.js +0 -324
- package/dist/chunk-QQV6VLYJ.js +0 -204
- package/dist/cms-BPp01z-8.d.ts +0 -411
- package/dist/cms-D6D89-qZ.d.cts +0 -411
- package/dist/drizzle-repo-B1rt7r4j.d.ts +0 -90
- package/dist/drizzle-repo-Cn-kL2FK.d.cts +0 -90
- package/dist/repo-BWI2Pkrv.d.ts +0 -162
- package/dist/repo-CeDxUxO6.d.cts +0 -162
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,65 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.10.0
|
|
4
|
+
|
|
5
|
+
The first npm release since 0.7.0. It contains 0.8.0 and 0.9.0 below, which were not published on their own: coming from 0.7.0, read [UPGRADE-0.8.md](./UPGRADE-0.8.md) first, then [UPGRADE-0.10.md](./UPGRADE-0.10.md).
|
|
6
|
+
|
|
7
|
+
The editing and publishing flow: its rules, REST routes, admin client, agent tools and screens. Read [UPGRADE-0.10.md](./UPGRADE-0.10.md): deletes now go to a trash, and the schema is version 4.
|
|
8
|
+
|
|
9
|
+
- **Scheduled publishing:** `cms.schedule(actor, col, slug, { publishAt, unpublishAt })`. What goes public is the version that was current when it was scheduled, not what the draft holds later. `cms.runScheduled()` does what is due; the `/_cron` route calls it and has its own secret (`createCms({ cronSecret })`, `Authorization: Bearer`). A version that no longer passes its checks is not published and the failure is in the audit log.
|
|
10
|
+
- **Trash:** a deleted document or file goes to the trash for 30 days (`createCms({ trash: { days } })`, `0` deletes at once). It is gone for readers, search and agents, keeps its address, and comes back as it was. `cms.trash.list / restore / purge`; purging is for admins; `runScheduled` empties what is older.
|
|
11
|
+
- **Review:** `defineCollection({ review: { agents: "required" } })` stops API keys and agents acting for a person from publishing a version nobody approved (`review_required`); `everyone: "required"` also stops people from approving their own request. `requestReview`, `approveReview` (publishes exactly the requested version), `rejectReview` (with a note), `reviewRequests`.
|
|
12
|
+
- **Comments:** threads on a section and a quoted piece of text, answers one level deep, resolve and reopen. Each thread says whether its text is still there. A preview link made with `comments: true` lets its holder read and write them without an account.
|
|
13
|
+
- **Releases:** documents that go out together, each pinned at a version. `cms.releases.publish` is one transaction: any blocked document stops all of it and the error lists what blocked. A release can be scheduled.
|
|
14
|
+
- **Versions:** a name and a pin (`labelVersion`); pinned versions are never pruned.
|
|
15
|
+
- **Saved filters**, **presence** (who has a document open, also agents while they save) and **`cms.preview`** (blocks with source lines, table of contents, problems and diff of unsaved text; `parseMarkdown(src, { lines: true })`).
|
|
16
|
+
- List states `scheduled` and `review`; `counts` has both.
|
|
17
|
+
- Agent tools (16 → 31, plus the file tools): `schedule_document`, `unschedule_document`, `request_review`, `list_review_requests`, `list_comments`, `add_comment`, `resolve_comment`, `list_trash`, `restore_from_trash`, `list_releases`, `create_release`, `add_to_release`, `publish_release`, `label_version`, `preview_document`. Approving a review is a person's job and has no tool.
|
|
18
|
+
- Schema version 4 (run `npx agent-cms migrate apply`).
|
|
19
|
+
|
|
20
|
+
Screens (`npx agent-cms add --update`, then `add cms-trash cms-releases`):
|
|
21
|
+
|
|
22
|
+
- **`cms-doc-editor`:** the publish button has a schedule panel (times on the clock of `createCms({ timeZone })`, which `GET /_me` now returns); strips under the header show a schedule, a review request ("Send back", "Approve and publish") and the release the document is in; a comments panel (a tab on phones) with marks on the commented text; who else has the document open, their cursors, and their saves merged into unsaved edits that do not overlap (`presenceMs`); "Add to a release"; "Allow comments" on preview links. The item has a second file, `cms-flow.tsx`.
|
|
23
|
+
- **`cms-doc-list`:** "Scheduled" and "In review" tabs and badges, who has a document open, saved filters. It needs the shadcn `label` part now.
|
|
24
|
+
- **`cms-trash`** (new) and **`cms-releases`** (new: `<CmsReleases>` and `<CmsRelease id>`); `cms-shell` links to both for people who can edit (`CmsShellTarget` has `releases` and `trash`).
|
|
25
|
+
- **`cms-versions`:** name a version, pin it, see who approved it. It needs the shadcn `dialog` and `input` parts now.
|
|
26
|
+
- Fix: on a phone the state tabs of `cms-doc-list` pushed the page sideways once there were seven of them. They now scroll inside their own row, and a tab you press comes fully into view.
|
|
27
|
+
- Korean copy picks the particle that fits a name ("김지수가", "docs-bot이"): `format()` reads `{who|이|가}`.
|
|
28
|
+
- **Paste clean-up** in the body: HTML from a web page, Google Docs or Word becomes markdown (headings, lists, bold, italic, links, tables, code, quotes, https images); zero-width characters, non-breaking spaces and curly quotes are tidied; a paste from a code editor stays plain text. No new dependency. Third file of the item: `cms-paste.ts`.
|
|
29
|
+
- **`cms-preview-comments`** (new): the comment box for guests on your public preview page.
|
|
30
|
+
- Not in this release: a CodeMirror editor (the body stays a text box, with a layer behind it for marks and cursors), section reordering, preview scroll sync, and a click in the preview that finds the line in the body.
|
|
31
|
+
|
|
32
|
+
## 0.9.0 (released as part of 0.10.0)
|
|
33
|
+
|
|
34
|
+
- **File manager:** `cms-files` shows a storage bucket as it is, folder by folder, also files nobody uploaded through the CMS. Move, download, share links and delete for several files and whole folders at once; opening a file shows the media library's panel. `cms-shell` shows "Files" to whoever may look around a store (`access.browse`, default: whoever may read it).
|
|
35
|
+
- A file the CMS did not know gets a row when it is opened, shared or registered (`cms.assets.register`), and then works in documents. `agent-cms storage sync` registers a whole bucket and lists rows whose file is gone.
|
|
36
|
+
- Share links: `cms.assets.share(actor, id, { ttl: "1h" | "24h" | "7d" })`. A private file's link is a signed address that cannot be taken back; a public file gives its public address. Needs the permission to delete in the store; audited as `asset.share`.
|
|
37
|
+
- REST: `GET /stores/:store/files`, `…/_open`, `POST …/_register`, `…/_move`, `…/_delete` (`check: true` only counts), `POST /assets/:id/share`. Agent tools (22 → 25 with a media library): `list_store_files`, `register_asset`, `create_share_link`.
|
|
38
|
+
- **Media library:** "Import from URL" in the header fetches a public https address into the open folder (the same guarded path as `import_asset`), and a file can be renamed in its panel (the extension is kept; documents keep working).
|
|
39
|
+
- `media.scan`: the app's own check of every file that arrives (a virus scanner, a content policy). A refused file is deleted and the caller gets `asset_rejected`; a check that throws refuses too.
|
|
40
|
+
- Fix: `cms-media` no longer uses `asChild` on a button, which exists only in the Radix flavour of shadcn/ui. Apps on the Base UI flavour failed to typecheck after `add cms-media`. Found by moving this project's own docs site to 0.8.
|
|
41
|
+
- The docs site (`apps/docs`) runs on this version: its copied screens are updated, it documents the media library, the file manager and the tools without `./ai`, and its gallery has a read-only media demo.
|
|
42
|
+
- No schema change.
|
|
43
|
+
|
|
44
|
+
## 0.8.0 (released as part of 0.10.0)
|
|
45
|
+
|
|
46
|
+
Read [UPGRADE-0.8.md](./UPGRADE-0.8.md). What comes next is in [docs/roadmap](./docs/roadmap/README.md).
|
|
47
|
+
|
|
48
|
+
- **Breaking: the `./ai` entry and the optional `ai` peer dependency are removed.** This package hands agents tools and never calls a model, and it no longer depends on a library that does. MCP, REST, the CLI and `./tools` are unchanged. A test keeps model libraries out of the sources and the dependencies.
|
|
49
|
+
- **`callTool`, `runTool`, `toolErrorResult`** in `./tools`: run a tool by name as an actor, with CMS errors returned as results. Together with `toolsFor` this is the way to give the tools to an agent in your app, whatever framework runs it. MCP runs tools through the same path.
|
|
50
|
+
- **An agent acting for a person:** `{ kind: "user", …, agent: { label } }`. Same permissions as the person; versions, the document and the audit log record the agent's name, and its edits are listed under "Agent changes". Requests cannot set it. The admin shows such authors as "agent, person".
|
|
51
|
+
- **Schema version 3** (`agent-cms migrate apply`): three nullable columns for the above, and the tables `cms_assets` and `cms_asset_refs` for the media library, with the matching `CmsRepo` methods.
|
|
52
|
+
- **Media library screens:** `cms-media` (stores and folders, grid and list, search, type tabs, a panel with a file's alt text, tags and the documents that use it, delete with a look at its uses, a phone layout) and `cms-media-picker` (the "choose media" dialog). The editor gets "Insert media", image and file fields, and media in the preview. `cms-shell` shows "Media" when the app has a library. Uploads go from the browser straight to the storage with progress, parts for large files, automatic retry of a failed part and "Try again" for what is missing; the browser makes the thumbnail.
|
|
53
|
+
- `<CmsProvider slots={{ assetAlt }}>`: a place for an extension package next to a file's alt text.
|
|
54
|
+
- The example app has a media library when it is given a storage (`npm run s3:dev`), and its public page renders media blocks.
|
|
55
|
+
- **Media library (server side):** `createCms({ media: { stores } })` with `s3Storage` from `./storage-s3` (AWS S3, Cloudflare R2, MinIO; signed with `aws4fetch`, no AWS SDK). Files go from the browser straight to the storage with signed addresses; files over 16MB go up in parts and a broken upload resumes with the missing parts. Public and private stores; private files open through `GET /files/:id/:name` after a permission check, with a link that works for 5 minutes.
|
|
56
|
+
- **What may be uploaded is the developer's choice** at three levels (`media.accept`, `stores.<name>.accept`, `admin.fields.<field>.accept`; the same for `maxFileSize`, default 5GB). The default list has no web pages or programs. The server checks the first bytes of what arrived and deletes a file that is not what its name says.
|
|
57
|
+
- **Files in documents:** ``, `[label](asset:ID/name)` and `` in markdown (`media` blocks, `image` and `file` inlines in `parseMarkdown`); field widgets `image` and `file` with `assetId()`; `cms.assetsFor(doc)` and `cms.imageUrl(asset, { width })` for rendering. Saving checks the files a document names (`asset_missing`, `asset_wrong_kind`, `asset_alt_missing`, `asset_private_in_public`), and the CMS records which documents use which file, so deleting a file in use asks first (`asset_in_use`).
|
|
58
|
+
- **REST:** `/assets` (list, folders, uploads, import, edit, move, delete) and `/files`; `_me.media`; `createRestClient` methods. **Agent tools (16 → 22):** `list_assets`, `get_asset`, `import_asset` (https only; addresses inside the network are refused, also after redirects), `update_asset`, `move_asset`, `delete_asset`. **CLI:** `agent-cms upload`, `agent-cms storage check | cleanup`; `doctor` reports unfinished uploads.
|
|
59
|
+
- New entries `./storage` (`StorageAdapter`, `MemoryStorage`, `DEFAULT_ACCEPT`) and `./storage-s3`. New dependency: `aws4fetch` (no dependencies of its own). `scripts/s3-dev.sh` starts a local S3-compatible server for tests and the example.
|
|
60
|
+
- The audit log's route label "AI SDK" is now "Agent".
|
|
61
|
+
- Roadmap: `docs/roadmap/` holds one document per bundle of planned work (design, defaults, done criteria) and the approved screen mockups; `TODO.md` gained items 107 to 135.
|
|
62
|
+
|
|
3
63
|
## 0.7.0
|
|
4
64
|
|
|
5
65
|
- **Anonymous MCP read:** `createCmsHandler({ mcp: { anonymous: "read" } })` lets agents use `/mcp` without a key. They get the read tools only (`ANONYMOUS_READ_TOOLS`) and see published documents of collections anyone may read. Off by default.
|
package/README.md
CHANGED
|
@@ -12,15 +12,16 @@ notes, a help center, internal docs, a notice board.
|
|
|
12
12
|
archive, restore. Two writers never overwrite each other: a stale save is a
|
|
13
13
|
conflict (409) that carries the other person's copy, and the admin screen
|
|
14
14
|
merges the two line by line.
|
|
15
|
-
- **Agents are first-class editors.** One tool list,
|
|
16
|
-
- **AI SDK tools** (`./ai`) for your own agent: `cmsTools(cms, actor)`
|
|
17
|
-
in-process, or `remoteCmsTools({ url, key })` against another app. They
|
|
18
|
-
are plain AI SDK `Tool`s, so they also work unchanged with anything built
|
|
19
|
-
on the AI SDK, such as slash-agent-sdk.
|
|
15
|
+
- **Agents are first-class editors.** One tool list, three ways in:
|
|
20
16
|
- **MCP** at `/api/cms/mcp` for coding agents (Claude Code, Cursor, …),
|
|
21
17
|
served with the official MCP SDK.
|
|
22
18
|
- **CLI** (`agent-cms put notes/launch.md --publish`) for agents with a shell.
|
|
23
19
|
- **REST** for everything else.
|
|
20
|
+
|
|
21
|
+
The list itself is in `./tools` (`toolsFor`, `callTool`), so an agent
|
|
22
|
+
running inside your app gets the same tools whatever framework runs it.
|
|
23
|
+
This package never calls a model: the model, its key and the agent loop
|
|
24
|
+
stay with you.
|
|
24
25
|
Agents change one section at a time (`patch_document`), check a draft
|
|
25
26
|
before saving (`diagnose_document`), and people review what agents changed
|
|
26
27
|
block by block.
|
|
@@ -40,6 +41,7 @@ notes, a help center, internal docs, a notice board.
|
|
|
40
41
|
> Design follows [Payload](https://payloadcms.com)'s collection, version and
|
|
41
42
|
> MCP shapes, written to run on Next.js 14+/React 18 and Postgres + Drizzle.
|
|
42
43
|
|
|
44
|
+
Used `./ai`? It is gone: read [UPGRADE-0.8.md](./UPGRADE-0.8.md).
|
|
43
45
|
Upgrading from 0.5? Read [UPGRADE-0.6.md](./UPGRADE-0.6.md) first (the
|
|
44
46
|
`cms_gaps` table needs moving before anything drops it). Changes are in
|
|
45
47
|
[CHANGELOG.md](./CHANGELOG.md).
|
|
@@ -51,9 +53,9 @@ npm i @mainsoft/agent-cms
|
|
|
51
53
|
npx agent-cms init
|
|
52
54
|
```
|
|
53
55
|
|
|
54
|
-
Peer dependencies: `drizzle-orm
|
|
55
|
-
|
|
56
|
-
|
|
56
|
+
Peer dependencies: `drizzle-orm` and `zod` (`^3.25` or `^4`). `init` writes
|
|
57
|
+
`agent-cms.config.ts`, `lib/cms.ts`, the API route, a schema re-export and
|
|
58
|
+
`.env.example` lines, and never overwrites a file.
|
|
57
59
|
|
|
58
60
|
## Set up
|
|
59
61
|
|
|
@@ -61,7 +63,7 @@ a schema re-export and `.env.example` lines, and never overwrites a file.
|
|
|
61
63
|
them, or put the SQL in a migration:
|
|
62
64
|
|
|
63
65
|
```ts
|
|
64
|
-
export { cmsDocuments, cmsVersions, cmsApiKeys, cmsHits, cmsMeta, cmsAudit } from "@mainsoft/agent-cms/tables";
|
|
66
|
+
export { cmsDocuments, cmsVersions, cmsApiKeys, cmsHits, cmsMeta, cmsAudit, cmsAssets, cmsAssetRefs } from "@mainsoft/agent-cms/tables";
|
|
65
67
|
```
|
|
66
68
|
|
|
67
69
|
```
|
|
@@ -146,7 +148,7 @@ they go and how imports are written) and talk to the CMS through
|
|
|
146
148
|
|
|
147
149
|
```
|
|
148
150
|
npx agent-cms add --list
|
|
149
|
-
npx agent-cms add cms-shell cms-doc-list cms-doc-editor cms-versions cms-keys cms-audit cms-command
|
|
151
|
+
npx agent-cms add cms-shell cms-doc-list cms-doc-editor cms-versions cms-keys cms-audit cms-command cms-media cms-files cms-trash cms-releases
|
|
150
152
|
npx agent-cms add --diff # what a new release would change in your copies
|
|
151
153
|
npx agent-cms add --update # update files you did not edit; yours get a .new copy
|
|
152
154
|
```
|
|
@@ -176,6 +178,12 @@ npx shadcn@latest add <registry-url>/cms-doc-editor.json
|
|
|
176
178
|
| `cms-keys` | Keys with expiry; the secret is shown once with MCP and CLI set-up |
|
|
177
179
|
| `cms-audit` | Who did what, filterable |
|
|
178
180
|
| `cms-command` | ⌘K to find any document, drafts included |
|
|
181
|
+
| `cms-media` | The media library: stores and folders, grid or list, a file's alt text, tags and the documents that use it, uploads with progress, delete with a look at where the file is used |
|
|
182
|
+
| `cms-media-picker` | The "choose media" dialog behind image and file fields and the editor's "Insert media" (comes with `cms-doc-editor`) |
|
|
183
|
+
| `cms-files` | The file manager: a bucket folder by folder, also files nobody uploaded through the CMS; move, download, share links and delete for several at once |
|
|
184
|
+
| `cms-trash` | Deleted documents and files: restore, or delete forever (admins) |
|
|
185
|
+
| `cms-releases` | Releases: documents that go out together, the version of each, what blocks them, publish now or at a set time |
|
|
186
|
+
| `cms-preview-comments` | For your public page: the comments on a draft opened through a preview link, and a box for a guest to add one |
|
|
179
187
|
| `cms-empty` | Empty collection: new document, or how to write with an agent |
|
|
180
188
|
|
|
181
189
|
UI text is English by default; a Korean catalog ships with the screens.
|
|
@@ -203,39 +211,284 @@ UI text is English by default; a Korean catalog ships with the screens.
|
|
|
203
211
|
"unarchive" | "delete", items)` runs each document on its own and returns
|
|
204
212
|
`{ slug, ok, error? }` for each.
|
|
205
213
|
|
|
206
|
-
|
|
214
|
+
### Scheduling, review, comments, releases, trash
|
|
215
|
+
|
|
216
|
+
The editor, the list and two more screens (`cms-trash`, `cms-releases`) cover
|
|
217
|
+
the publishing flow. Nothing here needs set-up except the cron call.
|
|
218
|
+
|
|
219
|
+
- **Schedule.** The arrow beside "Publish" sets a time to publish and a time
|
|
220
|
+
to unpublish, entered on the clock of `createCms({ timeZone })`. What goes
|
|
221
|
+
out is the version that was current when it was scheduled; an edit after
|
|
222
|
+
that shows a warning with "Schedule the latest version". Schedules run when
|
|
223
|
+
something calls the cron route, so their precision is your cron's interval:
|
|
224
|
+
|
|
225
|
+
```ts
|
|
226
|
+
createCms({ cronSecret: process.env.CMS_CRON_SECRET /* ... */ });
|
|
227
|
+
// every minute or so: POST /api/cms/_cron Authorization: Bearer <secret>
|
|
228
|
+
```
|
|
207
229
|
|
|
208
|
-
|
|
230
|
+
The same call publishes scheduled releases and empties the trash of what is
|
|
231
|
+
older than `trash.days`.
|
|
232
|
+
- **Review.** `defineCollection({ review: { agents: "required" } })` keeps what
|
|
233
|
+
an API key or an agent wrote from going public until a person approves it;
|
|
234
|
+
`everyone: "required"` asks the same of people, and the one who asked cannot
|
|
235
|
+
approve. The editor shows the request with "Send back" and "Approve and
|
|
236
|
+
publish"; the list has an "In review" tab.
|
|
237
|
+
- **Comments.** On a section or on selected text, with replies and resolve.
|
|
238
|
+
They follow the text while it is edited, and move to "Lost their place" when
|
|
239
|
+
the text is gone. A preview link made with "Allow comments" lets someone
|
|
240
|
+
without an account comment: `readPreview(token)` returns `comments: true`
|
|
241
|
+
for such a link, and `<CmsPreviewComments token={token} />` on your page
|
|
242
|
+
(`add cms-preview-comments`, no provider needed) shows the box.
|
|
243
|
+
- **Paste.** Text copied from a web page or a document program is pasted as
|
|
244
|
+
markdown (headings, lists, bold, links, tables, code); invisible characters
|
|
245
|
+
and curly quotes are tidied. Colours and font sizes are left out, and the
|
|
246
|
+
editor says so once.
|
|
247
|
+
- **Editing together.** Who else has the document open is shown in the editor
|
|
248
|
+
and in the list, with their cursors in the body. When someone else saves,
|
|
249
|
+
the editor takes the new version, merging it with unsaved edits when the
|
|
250
|
+
two do not overlap. It asks every 15 seconds (every 3 while someone else is
|
|
251
|
+
there); `presenceMs={0}` turns it off.
|
|
252
|
+
- **Releases.** Put documents in a release from the editor's menu or from the
|
|
253
|
+
release screen; publishing is all or nothing and lists what blocked it.
|
|
254
|
+
- **Trash.** Deleted documents and files stay for 30 days
|
|
255
|
+
(`createCms({ trash: { days } })`, `0` deletes at once). A restored document
|
|
256
|
+
that was published is public again.
|
|
257
|
+
- **Versions** take a name and a pin (pinned versions are never cleaned up).
|
|
258
|
+
**Saved filters** keep a tab, a search, a category and an author under a
|
|
259
|
+
name, for yourself or (admins) for everyone.
|
|
260
|
+
|
|
261
|
+
## Media library
|
|
262
|
+
|
|
263
|
+
Documents can hold images, video and files. The files live in your own
|
|
264
|
+
storage bucket; the CMS keeps a row per file and hands the browser a signed
|
|
265
|
+
address, so uploads go straight to the storage and never through your app
|
|
266
|
+
server (which is why a 5GB video works on a serverless host). Without `media`
|
|
267
|
+
the feature is off and nothing changes.
|
|
209
268
|
|
|
210
269
|
```ts
|
|
211
|
-
import {
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
270
|
+
import { s3Storage } from "@mainsoft/agent-cms/storage-s3";
|
|
271
|
+
|
|
272
|
+
const s3 = (bucket: string, publicUrl?: string) =>
|
|
273
|
+
s3Storage({ bucket, region: "auto", endpoint: process.env.S3_ENDPOINT, accessKeyId: process.env.S3_KEY!, secretAccessKey: process.env.S3_SECRET!, publicUrl });
|
|
274
|
+
|
|
275
|
+
export const cms = createCms({
|
|
276
|
+
// …
|
|
277
|
+
media: {
|
|
278
|
+
stores: {
|
|
279
|
+
// The first store is the default. `public`: anyone with the address can read.
|
|
280
|
+
public: { label: "Public", visibility: "public", adapter: s3("site-media", "https://media.example.com") },
|
|
281
|
+
// `private`: opened through the CMS after a permission check, with a link that works for 5 minutes.
|
|
282
|
+
private: { label: "Private", visibility: "private", adapter: s3("site-private"), accept: ["application/pdf"], maxFileSize: 100 * 1024 ** 2 },
|
|
283
|
+
},
|
|
284
|
+
// accept: ["image/*", "video/*", ".pdf"], // what every store takes; default below
|
|
285
|
+
// maxFileSize: 5 * 1024 ** 3, // default 5GB
|
|
286
|
+
imageUrl: ({ url, width }) => `/_next/image?url=${encodeURIComponent(url)}&w=${width}&q=75`,
|
|
220
287
|
},
|
|
221
|
-
messages,
|
|
222
288
|
});
|
|
223
289
|
```
|
|
224
290
|
|
|
225
|
-
|
|
291
|
+
`s3Storage` works with AWS S3 (leave `endpoint` out, set `region`),
|
|
292
|
+
Cloudflare R2 (`region: "auto"`, the account's S3 endpoint) and MinIO or any
|
|
293
|
+
other S3-compatible server. It signs requests itself (`aws4fetch`), so there
|
|
294
|
+
is no AWS SDK to install. Another kind of storage is a `StorageAdapter`
|
|
295
|
+
(`./storage`).
|
|
296
|
+
|
|
297
|
+
**The bucket needs a CORS rule** that lets your site `PUT` to it. Add `media`
|
|
298
|
+
(the same object) to `agent-cms.config.ts` and run:
|
|
299
|
+
|
|
300
|
+
```
|
|
301
|
+
npx agent-cms storage check --origin https://your-site.example
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
It uploads, reads, moves and deletes a test file in every store for real
|
|
305
|
+
(also in parts, also with a browser-style signed address), tests the CORS
|
|
306
|
+
rule, prints the rule to paste into the bucket, and lists what each store
|
|
307
|
+
accepts. `npx agent-cms storage cleanup` removes uploads that were started
|
|
308
|
+
and never finished (`doctor` tells you when there are any).
|
|
309
|
+
|
|
310
|
+
**What may be uploaded** is yours to decide, at three levels: `media.accept`
|
|
311
|
+
for the app, `stores.<name>.accept` for one store (replaces the app-wide
|
|
312
|
+
list), and `admin.fields.<field>.accept` for one field (narrows its store's
|
|
313
|
+
list). Entries are MIME types (`image/png`), groups (`image/*`) or
|
|
314
|
+
extensions (`.pdf`); `["*/*"]` takes anything. Unset, the default
|
|
315
|
+
(`DEFAULT_ACCEPT`) takes images, video, sound, PDF, office documents, plain
|
|
316
|
+
text and ZIP; web pages and programs only when you list them. `maxFileSize`
|
|
317
|
+
has the same three levels. The server checks the name and declared type when
|
|
318
|
+
an upload starts, and the first bytes of what actually arrived when it ends:
|
|
319
|
+
a web page named `photo.png` is deleted again (`asset_type_mismatch`).
|
|
320
|
+
|
|
321
|
+
**Your own check.** `media.scan` is called once for every file that arrives:
|
|
322
|
+
when a browser upload completes, when a file is imported or stored by the
|
|
323
|
+
server, and when a file that was already in the bucket gets registered. It
|
|
324
|
+
is where a virus scanner or a content policy goes:
|
|
325
|
+
|
|
326
|
+
```ts
|
|
327
|
+
media: {
|
|
328
|
+
stores: { /* … */ },
|
|
329
|
+
scan: async ({ url, bytes, name, mime, size }) => {
|
|
330
|
+
// `url`: a signed address that works for 10 minutes. `bytes` instead when the CMS holds the file in memory.
|
|
331
|
+
const verdict = await myScanner.check(url ?? bytes);
|
|
332
|
+
return verdict.clean ? true : { ok: false, reason: verdict.name };
|
|
333
|
+
},
|
|
334
|
+
},
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
A refused file is deleted from the storage and never becomes usable (a
|
|
338
|
+
registered one is left where it was); the caller gets `asset_rejected` and
|
|
339
|
+
the audit log has the reason. A check that throws refuses the file too.
|
|
340
|
+
|
|
341
|
+
**In a document** a file is named by its id, so moving or renaming it never
|
|
342
|
+
breaks a page:
|
|
343
|
+
|
|
344
|
+
```md
|
|
345
|
+

|
|
346
|
+
|
|
347
|
+
Read [the full report](asset:r7w2k9m4x1pa/report-2026.pdf).
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
An image line of its own is a media block (a picture, a video player or a
|
|
351
|
+
download card, by the file's type). `` shows an image from
|
|
352
|
+
elsewhere. For a field, use the `image` or `file` widget; the value is the
|
|
353
|
+
file's id:
|
|
226
354
|
|
|
227
355
|
```ts
|
|
228
|
-
import {
|
|
356
|
+
import { assetId } from "@mainsoft/agent-cms";
|
|
229
357
|
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
);
|
|
358
|
+
fields: z.object({ cover: assetId().optional(), brochure: assetId().optional() }),
|
|
359
|
+
admin: { fields: { cover: { widget: "image" }, brochure: { widget: "file", accept: [".pdf"], maxFileSize: 20 * 1024 ** 2 } } },
|
|
360
|
+
media: { requireAlt: true }, // an image without alt text stops a save (default: a warning)
|
|
234
361
|
```
|
|
235
362
|
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
363
|
+
Saving checks the files a document names: one that does not exist or is the
|
|
364
|
+
wrong kind for its field is an error; a missing alt text or a private file
|
|
365
|
+
in a public document is a warning.
|
|
366
|
+
|
|
367
|
+
**On your page**, ask for the files a document uses and render the block
|
|
368
|
+
tree as before:
|
|
369
|
+
|
|
370
|
+
```ts
|
|
371
|
+
const doc = await cms.get(anon, "posts", slug);
|
|
372
|
+
const files = await cms.assetsFor(doc); // { [id]: { url, width, height, alt, kind, mime, … } }
|
|
373
|
+
const cover = files[doc.fields.cover];
|
|
374
|
+
<img src={cms.imageUrl(cover, { width: 1200 })} width={cover.width} height={cover.height} alt={cover.alt} />
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
`parseMarkdown` gives `{ t: "media", asset, alt, caption }` blocks; look the
|
|
378
|
+
`asset` up in `files`. The CMS stores originals only. Resizing is your
|
|
379
|
+
framework's or CDN's job, through `media.imageUrl`.
|
|
380
|
+
|
|
381
|
+
**Who may do what.** Listing files and opening private ones: signed-in
|
|
382
|
+
people and keys. Uploading, importing, alt text, tags, new folders: admins
|
|
383
|
+
and keys with `write`. Moving, renaming and deleting: admins and keys with
|
|
384
|
+
`publish`. A store's `access: { read, write, delete }` replaces any of the
|
|
385
|
+
three. Deleting a file that documents use fails with `asset_in_use` and the
|
|
386
|
+
list of documents until the caller confirms. Uploads, moves and deletes are
|
|
387
|
+
in the audit log.
|
|
388
|
+
|
|
389
|
+
The file route is `GET /api/cms/files/<id>/<name>`: it checks permission and
|
|
390
|
+
redirects to the public address or to a short-lived signed one
|
|
391
|
+
(`media.linkTtlSeconds`, default 300). Set `media.filesUrl` when your handler
|
|
392
|
+
is not mounted at `/api/cms`.
|
|
393
|
+
|
|
394
|
+
**In the admin**, add the screen (`npx agent-cms add cms-media`) and a page
|
|
395
|
+
for it; the sidebar shows "Media" by itself when the app has a library:
|
|
396
|
+
|
|
397
|
+
```tsx
|
|
398
|
+
// app/admin/media/page.tsx
|
|
399
|
+
"use client";
|
|
400
|
+
import { CmsMedia } from "@/components/cms/cms-media";
|
|
401
|
+
export default function MediaPage() {
|
|
402
|
+
return <CmsMedia />;
|
|
403
|
+
}
|
|
404
|
+
```
|
|
405
|
+
|
|
406
|
+
The browser sends files straight to the storage, four parts at a time for
|
|
407
|
+
large ones, tries a failed part again three times, and "Try again" sends only
|
|
408
|
+
what is still missing. It also makes a small picture of each image and video
|
|
409
|
+
(480px, WebP) for the library, and reads width, height and length.
|
|
410
|
+
"Import from URL" fetches a public https address into the open folder
|
|
411
|
+
(addresses inside your network are refused, as for agents), and the pencil
|
|
412
|
+
in a file's panel renames it; the extension stays, so the type cannot change.
|
|
413
|
+
`<CmsProvider slots={{ assetAlt }}>` lets an extension package put its own
|
|
414
|
+
control next to a file's alt text field.
|
|
415
|
+
|
|
416
|
+
Agents get six more tools when the app has a media library: `list_assets`,
|
|
417
|
+
`get_asset` (read), `import_asset` (fetch an https address into the library;
|
|
418
|
+
addresses inside your network are refused), `update_asset` (write),
|
|
419
|
+
`move_asset` and `delete_asset` (publish). From a terminal:
|
|
420
|
+
|
|
421
|
+
```
|
|
422
|
+
npx agent-cms upload ./hero.png ./talk.mp4 --folder launch --alt "The launch screen" --tag launch
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
### File manager
|
|
426
|
+
|
|
427
|
+
The media library shows the files the CMS knows. The file manager
|
|
428
|
+
(`npx agent-cms add cms-files`, a page with `<CmsFiles />`) shows a bucket as
|
|
429
|
+
it is, folder by folder: files another program put there appear too. The
|
|
430
|
+
sidebar shows "Files" to whoever may look around a store (by default whoever
|
|
431
|
+
may read it; a store's `access.browse` narrows that).
|
|
432
|
+
|
|
433
|
+
- A file the CMS did not know gets a row when someone opens it, tags it,
|
|
434
|
+
shares it or an agent registers it. From then on it works in documents like
|
|
435
|
+
any other file. `npx agent-cms storage sync [--store name] [--folder path]`
|
|
436
|
+
registers everything at once and lists files the CMS knows that are gone
|
|
437
|
+
from the bucket (it deletes nothing).
|
|
438
|
+
- Several files and whole folders can be moved or deleted at once (up to
|
|
439
|
+
1000 objects per request). A move copies and deletes, one file after the
|
|
440
|
+
other: files that fail are reported, and moving again takes the rest. A name
|
|
441
|
+
that is taken at the destination gets a number; nothing is overwritten.
|
|
442
|
+
Deleting shows the documents that use any of the files first.
|
|
443
|
+
- "Make a link" gives an address for someone outside. For a private store it
|
|
444
|
+
works for 1 hour, 24 hours or 7 days and **cannot be taken back** (it is a
|
|
445
|
+
signed address); for a public store it is the file's public address. Making
|
|
446
|
+
one needs the permission to delete in that store, and is in the audit log.
|
|
447
|
+
- The CMS's own folder (`_cms/`, thumbnails) is hidden and cannot be touched.
|
|
448
|
+
|
|
449
|
+
Agents get three more tools: `list_store_files` (read), `register_asset`
|
|
450
|
+
(write) and `create_share_link` (publish).
|
|
451
|
+
|
|
452
|
+
## Agents
|
|
453
|
+
|
|
454
|
+
This package never calls a model. It has no model or key settings. It hands
|
|
455
|
+
your agent a list of tools; the model and the loop that drives it are yours.
|
|
456
|
+
|
|
457
|
+
### Your own agent
|
|
458
|
+
|
|
459
|
+
`toolsFor(cms, actor)` lists the tools this actor may use (name, description,
|
|
460
|
+
a zod schema for the input). `callTool` runs one. Wrap them in whatever your
|
|
461
|
+
agent framework calls a tool:
|
|
462
|
+
|
|
463
|
+
```ts
|
|
464
|
+
import { toolsFor, callTool } from "@mainsoft/agent-cms/tools";
|
|
465
|
+
|
|
466
|
+
const actor = { kind: "system", label: "assistant" } as const;
|
|
467
|
+
|
|
468
|
+
const tools = toolsFor(cms, actor).map((t) => ({
|
|
469
|
+
name: t.name,
|
|
470
|
+
description: t.description,
|
|
471
|
+
input: t.input, // a zod object; toJsonSchema(t.input) from ./mcp gives JSON Schema
|
|
472
|
+
run: (args: unknown) => callTool(cms, actor, t.name, args),
|
|
473
|
+
}));
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
`callTool(cms, actor, name, args, { only })` checks the input, runs the tool
|
|
477
|
+
with the actor's permissions, and records the call as made by an agent.
|
|
478
|
+
`toolsFor(cms, actor, only)` and the `only` option narrow the list.
|
|
479
|
+
|
|
480
|
+
From another process (a script, a scheduled job, another service), use a key:
|
|
481
|
+
|
|
482
|
+
```ts
|
|
483
|
+
import { createCmsClient } from "@mainsoft/agent-cms/client";
|
|
484
|
+
import { toolErrorResult } from "@mainsoft/agent-cms/tools";
|
|
485
|
+
|
|
486
|
+
const api = createCmsClient({ url: "https://app.example.com/api/cms", key: process.env.AGENT_CMS_KEY! });
|
|
487
|
+
|
|
488
|
+
const tools = await api.listTools(); // only what this key may use: { name, description, inputSchema }
|
|
489
|
+
const run = (name: string, args: Record<string, unknown>) =>
|
|
490
|
+
api.call(name, args).catch((e) => toolErrorResult(e) ?? Promise.reject(e));
|
|
491
|
+
```
|
|
239
492
|
|
|
240
493
|
Tool errors come back as results, not throws, so the model can re-read and
|
|
241
494
|
retry: `{ error: "conflict_version", kind: "conflict", message, params: {
|
|
@@ -246,6 +499,12 @@ expected, current } }`. Every code is in `./errors` (`ERROR_CODES`).
|
|
|
246
499
|
| `list_collections`, `search_documents`, `read_for_answer`, `list_documents`, `get_document` | read |
|
|
247
500
|
| `create_document`, `update_document`, `patch_document`, `diagnose_document`, `list_versions`, `restore_version` | write |
|
|
248
501
|
| `publish_document`, `unpublish_document`, `archive_document`, `delete_document`, `bulk_documents` | publish |
|
|
502
|
+
| `list_assets`, `get_asset` (with a media library) | read |
|
|
503
|
+
| `import_asset`, `update_asset` | write |
|
|
504
|
+
| `move_asset`, `delete_asset` | publish |
|
|
505
|
+
| `list_store_files` (the bucket as it is) | read |
|
|
506
|
+
| `register_asset` | write |
|
|
507
|
+
| `create_share_link` | publish |
|
|
249
508
|
|
|
250
509
|
`lookupForAgent(cms, actor, collections, question, { budget, countTokens })`
|
|
251
510
|
(`./agent`) is the answer-a-user helper behind `read_for_answer`: matching
|
|
@@ -328,7 +587,7 @@ Body in **markdown**.
|
|
|
328
587
|
|
|
329
588
|
`@mainsoft/agent-cms/markdown` is browser-safe: `parseMarkdown` gives a
|
|
330
589
|
small block tree (headings with stable anchors, lists, callouts `> [!tip]`,
|
|
331
|
-
code, link rows) and `extractToc` a table of contents. Render it with your
|
|
590
|
+
code, link rows, media) and `extractToc` a table of contents. Render it with your
|
|
332
591
|
own components.
|
|
333
592
|
|
|
334
593
|
## Develop
|