@velocity-astro/cms-astro 0.1.0-beta.1 → 0.1.0-beta.12

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 (137) hide show
  1. package/agents/cms.md +145 -0
  2. package/agents/skills/cms-add-content-type/SKILL.md +81 -0
  3. package/agents/skills/cms-add-form/SKILL.md +85 -0
  4. package/agents/skills/cms-add-section/SKILL.md +97 -0
  5. package/agents/skills/cms-add-to-site/SKILL.md +57 -0
  6. package/agents/skills/cms-connect-page/SKILL.md +64 -0
  7. package/agents/skills/cms-deploy/SKILL.md +64 -0
  8. package/agents/skills/cms-import-content/SKILL.md +63 -0
  9. package/agents/skills/cms-set-up-crm/SKILL.md +53 -0
  10. package/agents/skills/cms-write-plugin/SKILL.md +81 -0
  11. package/dist/admin-files.d.ts +2 -2
  12. package/dist/admin-files.d.ts.map +1 -1
  13. package/dist/admin-files.js +13 -7
  14. package/dist/admin-files.js.map +1 -1
  15. package/dist/agent-files.d.ts +23 -0
  16. package/dist/agent-files.d.ts.map +1 -0
  17. package/dist/agent-files.js +84 -0
  18. package/dist/agent-files.js.map +1 -0
  19. package/dist/challenge.d.ts +35 -0
  20. package/dist/challenge.d.ts.map +1 -0
  21. package/dist/challenge.js +84 -0
  22. package/dist/challenge.js.map +1 -0
  23. package/dist/check.d.ts +38 -0
  24. package/dist/check.d.ts.map +1 -0
  25. package/dist/check.js +194 -0
  26. package/dist/check.js.map +1 -0
  27. package/dist/cli-content.d.ts +22 -0
  28. package/dist/cli-content.d.ts.map +1 -0
  29. package/dist/cli-content.js +309 -0
  30. package/dist/cli-content.js.map +1 -0
  31. package/dist/cli.d.ts +3 -0
  32. package/dist/cli.d.ts.map +1 -1
  33. package/dist/cli.js +130 -6
  34. package/dist/cli.js.map +1 -1
  35. package/dist/connection.d.ts +1 -0
  36. package/dist/connection.d.ts.map +1 -1
  37. package/dist/connection.js +31 -6
  38. package/dist/connection.js.map +1 -1
  39. package/dist/editor.d.ts +2 -0
  40. package/dist/editor.d.ts.map +1 -1
  41. package/dist/editor.js +10 -1
  42. package/dist/editor.js.map +1 -1
  43. package/dist/form-post.d.ts +9 -1
  44. package/dist/form-post.d.ts.map +1 -1
  45. package/dist/form-post.js +10 -3
  46. package/dist/form-post.js.map +1 -1
  47. package/dist/hosted.d.ts +76 -0
  48. package/dist/hosted.d.ts.map +1 -0
  49. package/dist/hosted.js +104 -0
  50. package/dist/hosted.js.map +1 -0
  51. package/dist/image-optimizer.d.ts +35 -0
  52. package/dist/image-optimizer.d.ts.map +1 -0
  53. package/dist/image-optimizer.js +76 -0
  54. package/dist/image-optimizer.js.map +1 -0
  55. package/dist/import-files.d.ts +30 -0
  56. package/dist/import-files.d.ts.map +1 -0
  57. package/dist/import-files.js +100 -0
  58. package/dist/import-files.js.map +1 -0
  59. package/dist/index.d.ts +12 -3
  60. package/dist/index.d.ts.map +1 -1
  61. package/dist/index.js +12 -3
  62. package/dist/index.js.map +1 -1
  63. package/dist/init.d.ts +2 -0
  64. package/dist/init.d.ts.map +1 -1
  65. package/dist/init.js +16 -1
  66. package/dist/init.js.map +1 -1
  67. package/dist/integration.d.ts +9 -0
  68. package/dist/integration.d.ts.map +1 -1
  69. package/dist/integration.js +15 -1
  70. package/dist/integration.js.map +1 -1
  71. package/dist/link.d.ts.map +1 -1
  72. package/dist/link.js +6 -2
  73. package/dist/link.js.map +1 -1
  74. package/dist/live-loader.d.ts +7 -3
  75. package/dist/live-loader.d.ts.map +1 -1
  76. package/dist/live-loader.js +12 -6
  77. package/dist/live-loader.js.map +1 -1
  78. package/dist/media-store.d.ts +15 -0
  79. package/dist/media-store.d.ts.map +1 -1
  80. package/dist/media-store.js +26 -2
  81. package/dist/media-store.js.map +1 -1
  82. package/dist/page-marks.d.ts +50 -0
  83. package/dist/page-marks.d.ts.map +1 -0
  84. package/dist/page-marks.js +90 -0
  85. package/dist/page-marks.js.map +1 -0
  86. package/dist/preview.d.ts +34 -2
  87. package/dist/preview.d.ts.map +1 -1
  88. package/dist/preview.js +81 -15
  89. package/dist/preview.js.map +1 -1
  90. package/dist/resend-mailer.d.ts +18 -1
  91. package/dist/resend-mailer.d.ts.map +1 -1
  92. package/dist/resend-mailer.js +24 -3
  93. package/dist/resend-mailer.js.map +1 -1
  94. package/dist/secret.d.ts +1 -1
  95. package/dist/secret.d.ts.map +1 -1
  96. package/dist/secret.js +3 -2
  97. package/dist/secret.js.map +1 -1
  98. package/dist/single.d.ts +18 -0
  99. package/dist/single.d.ts.map +1 -0
  100. package/dist/single.js +37 -0
  101. package/dist/single.js.map +1 -0
  102. package/dist/site-client.d.ts +37 -0
  103. package/dist/site-client.d.ts.map +1 -0
  104. package/dist/site-client.js +73 -0
  105. package/dist/site-client.js.map +1 -0
  106. package/dist/site-editor.d.ts +1 -1
  107. package/dist/site-editor.d.ts.map +1 -1
  108. package/dist/site-editor.js +36 -6
  109. package/dist/site-editor.js.map +1 -1
  110. package/dist/site-forms.d.ts +11 -0
  111. package/dist/site-forms.d.ts.map +1 -1
  112. package/dist/site-forms.js +37 -19
  113. package/dist/site-forms.js.map +1 -1
  114. package/dist/site-mail.d.ts +45 -0
  115. package/dist/site-mail.d.ts.map +1 -0
  116. package/dist/site-mail.js +84 -0
  117. package/dist/site-mail.js.map +1 -0
  118. package/dist/site-media.d.ts +5 -1
  119. package/dist/site-media.d.ts.map +1 -1
  120. package/dist/site-media.js +14 -5
  121. package/dist/site-media.js.map +1 -1
  122. package/dist/site-name.d.ts +9 -0
  123. package/dist/site-name.d.ts.map +1 -0
  124. package/dist/site-name.js +21 -0
  125. package/dist/site-name.js.map +1 -0
  126. package/dist/site-storage.d.ts +34 -0
  127. package/dist/site-storage.d.ts.map +1 -0
  128. package/dist/site-storage.js +118 -0
  129. package/dist/site-storage.js.map +1 -0
  130. package/package.json +12 -8
  131. package/routes/editor.ts +7 -6
  132. package/routes/form-client.js.ts +68 -0
  133. package/routes/media.ts +2 -2
  134. package/routes/preview-client.js.ts +11 -56
  135. package/routes/published.ts +2 -2
  136. package/routes/sitemap-live.xml.ts +4 -1
  137. package/routes/sites.ts +11 -0
@@ -0,0 +1,63 @@
1
+ ---
2
+ name: cms-import-content
3
+ description: Bring existing content into Velocity CMS from another site or from files (WordPress, Markdown posts, a spreadsheet, JSON): map it onto content types, import entries and pictures as drafts, keep old addresses, and report what could not be taken. Use when asked to import, migrate, move content over, or load posts, products or listings from a file.
4
+ ---
5
+
6
+ # Import content
7
+
8
+ Read `.agents/cms.md` first ("Working with content"). Imports go through the site's API, as
9
+ drafts, so nothing reaches visitors until someone publishes.
10
+
11
+ ## 1. Get access
12
+
13
+ The commands need the site running (or its live address) and an access token:
14
+
15
+ - `npx velocity-cms token "Import" --save` makes one from this computer and writes
16
+ `VELOCITY_CMS_TOKEN` to `.env` (it needs the site's database, so it works locally). For a
17
+ live site, ask an owner to make one in the editor under Settings, Access tokens.
18
+ - Start the dev server (`npm run dev`), or set `VELOCITY_CMS_ORIGIN` to the live address.
19
+ - Check with `npx velocity-cms types`.
20
+
21
+ ## 2. Map the old content onto content types
22
+
23
+ 1. Look at a few items of the old content and at `npx velocity-cms type <type>`. Make a table:
24
+ old field, new field key, and what to do with it.
25
+ 2. If the site has no type for it, add one first (`cms-add-content-type`).
26
+ 3. Keep old addresses: the slug is the last part of the old URL. Where the URL pattern differs
27
+ (`/2024/05/hello` became `/blog/hello`), tell the person which redirects the host needs.
28
+
29
+ Get the content into one of these:
30
+
31
+ - **Markdown files** with front matter (a folder of `.md`): front matter keys become fields,
32
+ the text under it goes into the type's formatted text field (`--body <key>` to choose).
33
+ WordPress: export with a tool such as `wordpress-export-to-markdown`, or read its REST API
34
+ (`/wp-json/wp/v2/posts`) and write the files yourself.
35
+ - **JSON**: a list of `{ "slug": "...", "locale": "en", "data": { "<key>": value } }`. Formatted
36
+ text may be `{ "markdown": "..." }`. Build this from a CSV or an export with a short script.
37
+
38
+ ## 3. Try it, then import
39
+
40
+ ```sh
41
+ npx velocity-cms import posts ./old-posts --dry-run # says what would come in and what is left out
42
+ npx velocity-cms import posts ./old-posts --map date=publishedAt --map summary=excerpt
43
+ ```
44
+
45
+ - Keys the type has no field for are left out and named; `--map old=new` keeps one.
46
+ - A picture an `image` field names by a path on this computer is uploaded, and the field holds
47
+ its name. A picture by address must be downloaded first (by you, with the person's OK). Pictures
48
+ inside the text are left out: formatted text holds no pictures.
49
+ - An entry whose slug is already there is left alone unless `--update`.
50
+ - Everything comes in as a draft. Add `--publish` only when the person asks, and only with a
51
+ token that may publish.
52
+
53
+ ## 4. Report
54
+
55
+ Tell the person, from the command's own report:
56
+
57
+ - how many came in, and which were refused and why;
58
+ - what was left out (fields, pictures inside text) and what you suggest for each;
59
+ - which redirects the old addresses need;
60
+ - that the entries are drafts, and where to review them (`/admin`, the type's list).
61
+
62
+ Never import personal data (people's names, emails, orders) into a content type: contacts go to
63
+ the CRM (`cms-set-up-crm`), with the person's say-so.
@@ -0,0 +1,53 @@
1
+ ---
2
+ name: cms-set-up-crm
3
+ description: Set up the built-in CRM of a Velocity CMS site: name the pipeline's stages, add custom fields to contacts and deals, say who gets new contacts, set a monthly target, mark which content types deals can be about, and connect forms to it. Use when asked to set up a sales pipeline, the CRM, deals, lead stages or lead routing.
4
+ ---
5
+
6
+ # Set up the CRM
7
+
8
+ Read `.agents/cms.md` first. The CRM is part of the CMS: whoever sends a form becomes a contact,
9
+ contacts move through the pipeline's stages, and deals are what a contact may buy. It is
10
+ personal data, so this skill needs a token allowed to read contacts and forms.
11
+
12
+ ## 1. Get access
13
+
14
+ An owner makes a token in the editor (Settings, Access tokens) with "May read contacts, deals and
15
+ what forms received" ticked, or `npx velocity-cms token "CRM setup" --personal-data --save` on a
16
+ computer with the site's database. Put it in `VELOCITY_CMS_TOKEN`. The MCP tools below are the
17
+ same over `npx velocity-cms mcp` or the site's `/api/cms/mcp`.
18
+
19
+ ## 2. Ask the person
20
+
21
+ Don't guess a sales process. Ask, and confirm before saving:
22
+
23
+ - the stages a lead goes through, in order, and which mean won or lost (for example: New,
24
+ Contacted, Tour booked, Offer, Won, Lost), with how likely an open stage is to close;
25
+ - the currency, and a monthly target if they track one;
26
+ - who on the team looks after new contacts (`list_team`); new contacts go to whoever of them
27
+ has the fewest;
28
+ - what else they note about a contact or a deal (budget, source, move-in date).
29
+
30
+ ## 3. Save it
31
+
32
+ 1. `get_pipeline`, then `save_pipeline` with every stage in order. Keep the `id` of a stage that
33
+ stays, so contacts stay in it; a stage left out is removed and its contacts move to the first.
34
+ Labels may be left out for the stages the CMS came with.
35
+ 2. `get_custom_fields`, then `save_custom_fields` with the whole list for contacts and for deals.
36
+ Keep each field's `id`. Kinds: `text`, `email`, `phone`, `number`, `date`, `select`,
37
+ `boolean`, `url`. None can be required.
38
+ 3. Deals about the site's content (a listing, a service): set `forDeals: true` on that content
39
+ type in the model and run the seed. A form on its pages with `startsDeal: true` then starts a
40
+ deal about the entry.
41
+ 4. Forms: make sure each form names `contact` (`name`, `email`, `phone` keys) and, where an answer
42
+ belongs on the contact, `fills` (form field key to the custom field's id). See `cms-add-form`.
43
+
44
+ ## 4. Never
45
+
46
+ - Never copy contacts, deals or submissions into a file in the repository, a log, or a page.
47
+ - Never import contacts without the person's say-so; when they give a file, the editor's
48
+ Contacts screen imports CSV, and `create_contact` adds one at a time.
49
+
50
+ ## 5. Check
51
+
52
+ `get_pipeline` and `get_custom_fields` read back what you saved. Send a form on the dev server and
53
+ look at Contacts in `/admin`: the sender is there, in the first stage, given to someone.
@@ -0,0 +1,81 @@
1
+ ---
2
+ name: cms-write-plugin
3
+ description: Connect Velocity CMS to another service or add to its editor with a plugin (send leads to a dispatch system, sync to a CRM, add a reading-time panel), after checking the plugins that ship. Fewest permissions, secrets kept as secrets, outside calls through cms.tasks. Use when asked to integrate, sync, send data somewhere, add a webhook or extend the editor.
4
+ ---
5
+
6
+ # Write a plugin or an integration
7
+
8
+ Read `.agents/cms.md` first ("Plugins").
9
+
10
+ ## 1. Use what ships first
11
+
12
+ The CMS ships plugins an owner switches on under Plugins, with no code:
13
+
14
+ - **Webhooks**: posts what happens (a form sent, a contact or deal changed, a page published) to
15
+ addresses the owner lists, signed. Most "send X to our system" requests are this.
16
+ - **Mailchimp**: adds whoever sends a form to an audience, with consent.
17
+ - **Slack**: posts to a channel when a form is sent or a contact is made.
18
+ - **HubSpot**: copies contacts to HubSpot.
19
+ - **SEO**: judges each page's title and description.
20
+
21
+ If one fits, tell the person how to switch it on and fill its settings. Stop there.
22
+
23
+ ## 2. Otherwise, write one
24
+
25
+ A file in the site (such as `cms/plugins/dispatch.mjs`) named in
26
+ `velocityCms({ plugins: ['./cms/plugins/dispatch.mjs'] })`:
27
+
28
+ ```js
29
+ import { definePlugin } from '@velocity-astro/cms-astro';
30
+
31
+ export default definePlugin({
32
+ name: 'dispatch', // lowercase, unique
33
+ apiVersion: 1,
34
+ label: { en: 'Dispatch' },
35
+ version: '1.0.0',
36
+ permissions: ['submission:read'], // the fewest it needs; personal data only if it must
37
+ enabledByDefault: false,
38
+ settings: [{ key: 'form', type: 'text', label: { en: 'Form key to send' } }],
39
+ secrets: [{ key: 'apiKey', label: { en: 'API key' } }], // never a setting
40
+ setup(cms) {
41
+ cms.tasks.define('send', async (lead, task) => {
42
+ const key = await cms.secrets.get('apiKey');
43
+ if (!key) return;
44
+ const response = await fetch('https://api.dispatch.example/leads', {
45
+ method: 'POST',
46
+ // A piece of work may run twice: the id lets the other side tell.
47
+ headers: { authorization: `Bearer ${key}`, 'content-type': 'application/json', 'idempotency-key': task.id },
48
+ body: JSON.stringify(lead),
49
+ });
50
+ if (!response.ok) throw new Error(`Dispatch answered ${response.status}`); // the host retries
51
+ });
52
+ cms.events.on('submission.received', async ({ form, submission }) => {
53
+ const { form: wanted } = await cms.settings.get(); // settings by key; submission.data is by field id
54
+ if (form.key === wanted) await cms.tasks.add('send', { form: form.key, data: submission.data }, { label: 'New lead' });
55
+ });
56
+ },
57
+ });
58
+ ```
59
+
60
+ Check the exact names against `PluginContext` in `@velocity-astro/cms-core` (`plugin.ts`) before
61
+ relying on them; they are a promise to plugin authors, so they change only with `apiVersion`.
62
+
63
+ Rules:
64
+
65
+ - **Fewest permissions.** A plugin hears of a submission only if it declared `submission:read`.
66
+ - **A key is a secret** (`secrets`), saved by an owner one at a time, never shown again, read
67
+ only by `cms.secrets.get`.
68
+ - **Outside calls go through `cms.tasks`**, which retries for about a day and shows failures
69
+ under Plugins. A task's data may be personal: never log it, and keep errors to the host and
70
+ status, never the body.
71
+ - **Only public `https` addresses.** A host a person typed is checked with `cms.net.isPublic`.
72
+ - A plugin's failure never stops a save or a publish; don't catch and hide errors to "help".
73
+ - To change a page's head, use `pages.head` rules and call `pages.changed()`; nothing else of a
74
+ page is a plugin's.
75
+ - An editor part (`editor`) is one prebuilt module that builds only from the parts it is handed.
76
+
77
+ ## 3. Check
78
+
79
+ Build, start the dev server, switch the plugin on under Plugins, fill its settings and secret,
80
+ and make it happen (send the form). Look under Plugins for its tasks. Run `npx velocity-cms check`.
81
+ Tell the person which secret they must paste in themselves.
@@ -15,7 +15,7 @@ export declare const builtEditorDirectory: () => string;
15
15
  export declare class AdminFiles {
16
16
  #private;
17
17
  constructor(directory: string, config: EditorPageConfig);
18
- /** Answers a request for anything under the editor's address. */
19
- respond(request: Request): Response;
18
+ /** Answers a request for anything under the editor's address. `siteName` is what an owner called the site, when they did. */
19
+ respond(request: Request, siteName?: string | null): Response;
20
20
  }
21
21
  //# sourceMappingURL=admin-files.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"admin-files.d.ts","sourceRoot":"","sources":["../src/admin-files.ts"],"names":[],"mappings":"AAIA,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAkCD,mEAAmE;AACnE,eAAO,MAAM,oBAAoB,QAAO,MAAsB,CAAC;AAE/D;;;;GAIG;AACH,qBAAa,UAAU;;gBAKT,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB;IAkBvD,iEAAiE;IACjE,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ;CAkBpC"}
1
+ {"version":3,"file":"admin-files.d.ts","sourceRoot":"","sources":["../src/admin-files.ts"],"names":[],"mappings":"AAIA,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAkCD,mEAAmE;AACnE,eAAO,MAAM,oBAAoB,QAAO,MAAsB,CAAC;AAE/D;;;;GAIG;AACH,qBAAa,UAAU;;gBAMT,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB;IAwBvD,6HAA6H;IAC7H,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,QAAQ;CAkB9D"}
@@ -33,7 +33,8 @@ export const builtEditorDirectory = () => appDirectory;
33
33
  */
34
34
  export class AdminFiles {
35
35
  #files = new Map();
36
- #page;
36
+ #template;
37
+ #config;
37
38
  #adminPath;
38
39
  constructor(directory, config) {
39
40
  const index = path.join(directory, 'index.html');
@@ -47,14 +48,19 @@ export class AdminFiles {
47
48
  this.#files.set(name.replaceAll('\\', '/'), { body: fs.readFileSync(file), type });
48
49
  }
49
50
  this.#adminPath = config.adminPath;
51
+ this.#config = config;
52
+ this.#template = fs.readFileSync(index, 'utf8');
53
+ }
54
+ /** The editor's page with its settings written in, the site called `siteName` when one is given. */
55
+ #pageFor(siteName) {
56
+ const config = siteName ? { ...this.#config, siteName } : this.#config;
50
57
  // `<` is escaped so nothing in a site's name can end the block and start a script.
51
58
  const settings = JSON.stringify(config).replaceAll('<', '\\u003c');
52
- this.#page = fs
53
- .readFileSync(index, 'utf8')
54
- .replace(MARKER, `<base href="${config.adminPath}/" />\n <script type="application/json" id="velocity-cms-config">${settings}</script>`);
59
+ // A function, so nothing in the name is read as a pattern of the replacement.
60
+ return this.#template.replace(MARKER, () => `<base href="${config.adminPath}/" />\n <script type="application/json" id="velocity-cms-config">${settings}</script>`);
55
61
  }
56
- /** Answers a request for anything under the editor's address. */
57
- respond(request) {
62
+ /** Answers a request for anything under the editor's address. `siteName` is what an owner called the site, when they did. */
63
+ respond(request, siteName) {
58
64
  if (request.method !== 'GET' && request.method !== 'HEAD') {
59
65
  return new Response(null, { status: 405, headers: { allow: 'GET, HEAD' } });
60
66
  }
@@ -71,7 +77,7 @@ export class AdminFiles {
71
77
  if (inside.startsWith('assets/'))
72
78
  return new Response(null, { status: 404 });
73
79
  // Every other address is a screen of the editor, which works out which one in the browser.
74
- return new Response(this.#page, { headers: PAGE_HEADERS });
80
+ return new Response(this.#pageFor(siteName), { headers: PAGE_HEADERS });
75
81
  }
76
82
  }
77
83
  //# sourceMappingURL=admin-files.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"admin-files.js","sourceRoot":"","sources":["../src/admin-files.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"admin-files.js","sourceRoot":"","sources":["../src/admin-files.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,23 @@
1
+ /**
2
+ * The files that teach an AI coding agent how to build on the CMS: the rules (`.agents/cms.md`)
3
+ * and the `cms-*` skills, kept in both places agents look for skills (`.agents/skills/` and
4
+ * `.claude/skills/`). They ship in this package (`agents/`) and travel with the CMS, so a site
5
+ * on plain Astro gets them too and they match the version the site runs. `velocity-cms init`
6
+ * installs them and `velocity-cms agents` brings them up to date; both replace what the CMS
7
+ * wrote and leave the site's own files alone.
8
+ */
9
+ /** Where the rules go in a site. */
10
+ export declare const CMS_RULES_FILE = ".agents/cms.md";
11
+ /** The line the site's AGENTS.md gains, so an agent finds the rules. */
12
+ export declare const AGENTS_LINE = "- This site uses Velocity CMS. Before changing content types, pages, sections, forms, menus or how the site is deployed, read `.agents/cms.md` and use the `cms-*` skills.";
13
+ /** The version of the CMS the files come from. The rules carry it, and `velocity-cms check` compares it. */
14
+ export declare const AGENT_FILES_VERSION: string;
15
+ /** The skills this version ships, by name. */
16
+ export declare function shippedSkills(): string[];
17
+ /**
18
+ * Installs the rules and skills in a site's folder and points its AGENTS.md at them (making one
19
+ * if it has none, and a CLAUDE.md that reads it). A skill the CMS no longer ships is removed; a
20
+ * skill of the site's own, whose name does not start with `cms-`, is never touched.
21
+ */
22
+ export declare function installAgentFiles(dir: string, print: (line: string) => void): void;
23
+ //# sourceMappingURL=agent-files.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent-files.d.ts","sourceRoot":"","sources":["../src/agent-files.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AAEH,oCAAoC;AACpC,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAG/C,wEAAwE;AACxE,eAAO,MAAM,WAAW,+KAA+K,CAAC;AAIxM,4GAA4G;AAC5G,eAAO,MAAM,mBAAmB,EAAE,MAA0H,CAAC;AAE7J,8CAA8C;AAC9C,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAMxC;AAeD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAqClF"}
@@ -0,0 +1,84 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ /**
4
+ * The files that teach an AI coding agent how to build on the CMS: the rules (`.agents/cms.md`)
5
+ * and the `cms-*` skills, kept in both places agents look for skills (`.agents/skills/` and
6
+ * `.claude/skills/`). They ship in this package (`agents/`) and travel with the CMS, so a site
7
+ * on plain Astro gets them too and they match the version the site runs. `velocity-cms init`
8
+ * installs them and `velocity-cms agents` brings them up to date; both replace what the CMS
9
+ * wrote and leave the site's own files alone.
10
+ */
11
+ /** Where the rules go in a site. */
12
+ export const CMS_RULES_FILE = '.agents/cms.md';
13
+ /** The folders a skill is written to, one copy in each. */
14
+ const SKILL_FOLDERS = ['.agents/skills', '.claude/skills'];
15
+ /** The line the site's AGENTS.md gains, so an agent finds the rules. */
16
+ export const AGENTS_LINE = '- This site uses Velocity CMS. Before changing content types, pages, sections, forms, menus or how the site is deployed, read `.agents/cms.md` and use the `cms-*` skills.';
17
+ const source = new URL('../agents/', import.meta.url);
18
+ /** The version of the CMS the files come from. The rules carry it, and `velocity-cms check` compares it. */
19
+ export const AGENT_FILES_VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
20
+ /** The skills this version ships, by name. */
21
+ export function shippedSkills() {
22
+ return fs
23
+ .readdirSync(new URL('skills/', source), { withFileTypes: true })
24
+ .filter((entry) => entry.isDirectory() && entry.name.startsWith('cms-'))
25
+ .map((entry) => entry.name)
26
+ .sort();
27
+ }
28
+ function stamped(text) {
29
+ const mark = `<!-- velocity-cms ${AGENT_FILES_VERSION}. Written by \`velocity-cms agents\`, which replaces this file: keep your own notes in AGENTS.md. -->`;
30
+ return `${mark}\n\n${text}`;
31
+ }
32
+ /** Writes a file unless it already holds exactly that. Answers whether it changed. */
33
+ function write(file, text) {
34
+ if (fs.existsSync(file) && fs.readFileSync(file, 'utf8') === text)
35
+ return false;
36
+ fs.mkdirSync(path.dirname(file), { recursive: true });
37
+ fs.writeFileSync(file, text);
38
+ return true;
39
+ }
40
+ /**
41
+ * Installs the rules and skills in a site's folder and points its AGENTS.md at them (making one
42
+ * if it has none, and a CLAUDE.md that reads it). A skill the CMS no longer ships is removed; a
43
+ * skill of the site's own, whose name does not start with `cms-`, is never touched.
44
+ */
45
+ export function installAgentFiles(dir, print) {
46
+ const at = (file) => path.join(dir, file);
47
+ const changed = [];
48
+ if (write(at(CMS_RULES_FILE), stamped(fs.readFileSync(new URL('cms.md', source), 'utf8'))))
49
+ changed.push(CMS_RULES_FILE);
50
+ const skills = shippedSkills();
51
+ for (const folder of SKILL_FOLDERS) {
52
+ for (const skill of skills) {
53
+ if (write(at(`${folder}/${skill}/SKILL.md`), fs.readFileSync(new URL(`skills/${skill}/SKILL.md`, source), 'utf8')))
54
+ changed.push(`${folder}/${skill}`);
55
+ }
56
+ // A cms- skill an earlier version wrote and this one does not ship.
57
+ if (!fs.existsSync(at(folder)))
58
+ continue;
59
+ for (const entry of fs.readdirSync(at(folder), { withFileTypes: true })) {
60
+ if (entry.isDirectory() && entry.name.startsWith('cms-') && !skills.includes(entry.name)) {
61
+ fs.rmSync(at(`${folder}/${entry.name}`), { recursive: true });
62
+ changed.push(`${folder}/${entry.name} (removed)`);
63
+ }
64
+ }
65
+ }
66
+ const agents = at('AGENTS.md');
67
+ if (!fs.existsSync(agents)) {
68
+ fs.writeFileSync(agents, `# Agent guide\n\nInstructions for AI coding agents working on this site.\n\n${AGENTS_LINE}\n`);
69
+ changed.push('AGENTS.md');
70
+ if (!fs.existsSync(at('CLAUDE.md'))) {
71
+ fs.writeFileSync(at('CLAUDE.md'), '@AGENTS.md\n');
72
+ changed.push('CLAUDE.md');
73
+ }
74
+ }
75
+ else {
76
+ const text = fs.readFileSync(agents, 'utf8');
77
+ if (!text.includes(CMS_RULES_FILE)) {
78
+ fs.writeFileSync(agents, `${text}${text.endsWith('\n') ? '' : '\n'}\n${AGENTS_LINE}\n`);
79
+ changed.push('AGENTS.md');
80
+ }
81
+ }
82
+ print(changed.length > 0 ? `Agent files: wrote ${changed.join(', ')}.` : 'Agent files: already up to date.');
83
+ }
84
+ //# sourceMappingURL=agent-files.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent-files.js","sourceRoot":"","sources":["../src/agent-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;;;GAOG;AAEH,oCAAoC;AACpC,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAC;AAC/C,2DAA2D;AAC3D,MAAM,aAAa,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC;AAC3D,wEAAwE;AACxE,MAAM,CAAC,MAAM,WAAW,GAAG,4KAA4K,CAAC;AAExM,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAEtD,4GAA4G;AAC5G,MAAM,CAAC,MAAM,mBAAmB,GAAY,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAyB,CAAC,OAAO,CAAC;AAE7J,8CAA8C;AAC9C,MAAM,UAAU,aAAa;IAC3B,OAAO,EAAE;SACN,WAAW,CAAC,IAAI,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;SAChE,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;SACvE,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC;SAC1B,IAAI,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,OAAO,CAAC,IAAY;IAC3B,MAAM,IAAI,GAAG,qBAAqB,mBAAmB,uGAAuG,CAAC;IAC7J,OAAO,GAAG,IAAI,OAAO,IAAI,EAAE,CAAC;AAC9B,CAAC;AAED,sFAAsF;AACtF,SAAS,KAAK,CAAC,IAAY,EAAE,IAAY;IACvC,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAChF,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC7B,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,KAA6B;IAC1E,MAAM,EAAE,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAClD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,KAAK,CAAC,EAAE,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAEzH,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;IAC/B,KAAK,MAAM,MAAM,IAAI,aAAa,EAAE,CAAC;QACnC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,KAAK,CAAC,EAAE,CAAC,GAAG,MAAM,IAAI,KAAK,WAAW,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,UAAU,KAAK,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,KAAK,EAAE,CAAC,CAAC;QACzJ,CAAC;QACD,oEAAoE;QACpE,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;YAAE,SAAS;QACzC,KAAK,MAAM,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;YACxE,IAAI,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzF,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,MAAM,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC9D,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,KAAK,CAAC,IAAI,YAAY,CAAC,CAAC;YACpD,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,EAAE,CAAC,WAAW,CAAC,CAAC;IAC/B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,EAAE,CAAC,aAAa,CAAC,MAAM,EAAE,+EAA+E,WAAW,IAAI,CAAC,CAAC;QACzH,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC1B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC;YACpC,EAAE,CAAC,aAAa,CAAC,EAAE,CAAC,WAAW,CAAC,EAAE,cAAc,CAAC,CAAC;YAClD,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7C,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;YACnC,EAAE,CAAC,aAAa,CAAC,MAAM,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,CAAC;YACxF,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,sBAAsB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,kCAAkC,CAAC,CAAC;AAC/G,CAAC"}
@@ -0,0 +1,35 @@
1
+ import { type ChallengeAccount, type ChallengeRoom } from '@velocity-astro/cms-core';
2
+ /** Where Cloudflare Turnstile is asked whether an answer is a person's. The only address a check goes to. */
3
+ export declare const TURNSTILE_VERIFY = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
4
+ /** The host a page with a form loads the challenge from, for a site's content security policy (scripts and frames). */
5
+ export declare const TURNSTILE_HOST = "https://challenges.cloudflare.com";
6
+ /** The script that draws the challenge. `render=explicit`: the form's own script says where. */
7
+ export declare const TURNSTILE_SCRIPT = "https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit";
8
+ /** The name the challenge's answer is posted under. */
9
+ export declare const FORM_CHALLENGE_FIELD = "cf-turnstile-response";
10
+ /** Says whether what a post carries shows its sender passed the challenge. */
11
+ export interface ChallengeCheck {
12
+ /** True when the sender passed, and when the site asks for no challenge. */
13
+ passed(answer: unknown): Promise<boolean>;
14
+ }
15
+ export interface SiteChallengeOptions {
16
+ /** The challenge an owner set up in the editor's settings, read for each post. */
17
+ readonly account: () => Promise<ChallengeAccount | null>;
18
+ /** Defaults to the platform's own `fetch`. */
19
+ readonly fetch?: typeof globalThis.fetch;
20
+ /** Told when the challenge service could not be asked. Never given what a visitor sent. */
21
+ readonly onFault?: (error: unknown) => void;
22
+ }
23
+ /**
24
+ * Checks a form's sender with the challenge an owner set up (Cloudflare Turnstile). A sender who
25
+ * did not pass is suspected, and what they sent is kept as spam like any other suspected post.
26
+ * A service that cannot be asked, or that does not know the site's key, is never held against a
27
+ * visitor: the other checks still stand, and the fault is told to the log.
28
+ */
29
+ export declare class SiteChallenge implements ChallengeCheck, ChallengeRoom {
30
+ #private;
31
+ constructor(options: SiteChallengeOptions);
32
+ passed(answer: unknown): Promise<boolean>;
33
+ test(): Promise<void>;
34
+ }
35
+ //# sourceMappingURL=challenge.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"challenge.d.ts","sourceRoot":"","sources":["../src/challenge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEpG,6GAA6G;AAC7G,eAAO,MAAM,gBAAgB,8DAA8D,CAAC;AAC5F,uHAAuH;AACvH,eAAO,MAAM,cAAc,sCAAsC,CAAC;AAClE,gGAAgG;AAChG,eAAO,MAAM,gBAAgB,0EAA0D,CAAC;AACxF,uDAAuD;AACvD,eAAO,MAAM,oBAAoB,0BAA0B,CAAC;AAM5D,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACzD,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IACzC,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC7C;AAID;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,cAAc,EAAE,aAAa;;gBAGrD,OAAO,EAAE,oBAAoB;IAInC,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBzC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CA+B5B"}
@@ -0,0 +1,84 @@
1
+ import { ConflictError } from '@velocity-astro/cms-core';
2
+ /** Where Cloudflare Turnstile is asked whether an answer is a person's. The only address a check goes to. */
3
+ export const TURNSTILE_VERIFY = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
4
+ /** The host a page with a form loads the challenge from, for a site's content security policy (scripts and frames). */
5
+ export const TURNSTILE_HOST = 'https://challenges.cloudflare.com';
6
+ /** The script that draws the challenge. `render=explicit`: the form's own script says where. */
7
+ export const TURNSTILE_SCRIPT = `${TURNSTILE_HOST}/turnstile/v0/api.js?render=explicit`;
8
+ /** The name the challenge's answer is posted under. */
9
+ export const FORM_CHALLENGE_FIELD = 'cf-turnstile-response';
10
+ /** The longest answer Turnstile gives. */
11
+ const MAX_ANSWER_LENGTH = 2048;
12
+ /** What a test sends in place of a person's answer. Cloudflare refuses it, and says first whether it knows the key. */
13
+ const TEST_ANSWER = 'velocity-cms-key-check';
14
+ /**
15
+ * Checks a form's sender with the challenge an owner set up (Cloudflare Turnstile). A sender who
16
+ * did not pass is suspected, and what they sent is kept as spam like any other suspected post.
17
+ * A service that cannot be asked, or that does not know the site's key, is never held against a
18
+ * visitor: the other checks still stand, and the fault is told to the log.
19
+ */
20
+ export class SiteChallenge {
21
+ #options;
22
+ constructor(options) {
23
+ this.#options = options;
24
+ }
25
+ async passed(answer) {
26
+ let account;
27
+ try {
28
+ account = await this.#options.account();
29
+ }
30
+ catch (error) {
31
+ this.#options.onFault?.(error);
32
+ return true;
33
+ }
34
+ if (account === null)
35
+ return true;
36
+ if (typeof answer !== 'string' || answer === '' || answer.length > MAX_ANSWER_LENGTH)
37
+ return false;
38
+ const verdict = await this.#ask(account.secretKey, answer);
39
+ if (verdict === 'wrong-secret')
40
+ this.#options.onFault?.(new Error('Cloudflare Turnstile does not know the secret key saved under Settings, Forms and spam, so forms are not being checked with it.'));
41
+ if (verdict === 'unreachable')
42
+ this.#options.onFault?.(new Error('Cloudflare Turnstile could not be asked about a form\'s sender, so that post was not checked with it.'));
43
+ return verdict !== 'not-a-person';
44
+ }
45
+ async test() {
46
+ const account = await this.#options.account();
47
+ if (account === null)
48
+ throw new ConflictError('There are no keys to check yet. Save the site key and the secret key first.');
49
+ const verdict = await this.#ask(account.secretKey, TEST_ANSWER);
50
+ if (verdict === 'wrong-secret')
51
+ throw new ConflictError('Cloudflare does not know this secret key. Copy it again from the widget\'s settings in Cloudflare, under Turnstile.');
52
+ if (verdict === 'unreachable')
53
+ throw new ConflictError('Cloudflare could not be reached to check the key. Try again in a moment.');
54
+ }
55
+ /** Asks the one address checks go to. The visitor's own address is not sent along. */
56
+ async #ask(secret, answer) {
57
+ const send = this.#options.fetch ?? ((input, init) => globalThis.fetch(input, init));
58
+ try {
59
+ const response = await send(TURNSTILE_VERIFY, {
60
+ method: 'POST',
61
+ headers: { 'content-type': 'application/x-www-form-urlencoded' },
62
+ body: new URLSearchParams({ secret, response: answer }).toString(),
63
+ redirect: 'error',
64
+ signal: AbortSignal.timeout(5000),
65
+ });
66
+ const body = await response.json();
67
+ if (typeof body !== 'object' || body === null)
68
+ return 'unreachable';
69
+ const { success, 'error-codes': codes } = body;
70
+ if (success === true)
71
+ return 'person';
72
+ const said = Array.isArray(codes) ? codes.filter((code) => typeof code === 'string') : [];
73
+ if (said.includes('invalid-input-secret') || said.includes('missing-input-secret'))
74
+ return 'wrong-secret';
75
+ if (said.includes('internal-error') || success !== false)
76
+ return 'unreachable';
77
+ return 'not-a-person';
78
+ }
79
+ catch {
80
+ return 'unreachable';
81
+ }
82
+ }
83
+ }
84
+ //# sourceMappingURL=challenge.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"challenge.js","sourceRoot":"","sources":["../src/challenge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAA6C,MAAM,0BAA0B,CAAC;AAEpG,6GAA6G;AAC7G,MAAM,CAAC,MAAM,gBAAgB,GAAG,2DAA2D,CAAC;AAC5F,uHAAuH;AACvH,MAAM,CAAC,MAAM,cAAc,GAAG,mCAAmC,CAAC;AAClE,gGAAgG;AAChG,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,cAAc,sCAAsC,CAAC;AACxF,uDAAuD;AACvD,MAAM,CAAC,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAC5D,0CAA0C;AAC1C,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAC/B,uHAAuH;AACvH,MAAM,WAAW,GAAG,wBAAwB,CAAC;AAmB7C;;;;;GAKG;AACH,MAAM,OAAO,aAAa;IACf,QAAQ,CAAuB;IAExC,YAAY,OAA6B;QACvC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAe;QAC1B,IAAI,OAAgC,CAAC;QACrC,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QAC1C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;YAC/B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAClC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,EAAE,IAAI,MAAM,CAAC,MAAM,GAAG,iBAAiB;YAAE,OAAO,KAAK,CAAC;QACnG,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAC3D,IAAI,OAAO,KAAK,cAAc;YAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,KAAK,CAAC,iIAAiI,CAAC,CAAC,CAAC;QACtM,IAAI,OAAO,KAAK,aAAa;YAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,KAAK,CAAC,uGAAuG,CAAC,CAAC,CAAC;QAC3K,OAAO,OAAO,KAAK,cAAc,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QAC9C,IAAI,OAAO,KAAK,IAAI;YAAE,MAAM,IAAI,aAAa,CAAC,6EAA6E,CAAC,CAAC;QAC7H,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;QAChE,IAAI,OAAO,KAAK,cAAc;YAAE,MAAM,IAAI,aAAa,CAAC,qHAAqH,CAAC,CAAC;QAC/K,IAAI,OAAO,KAAK,aAAa;YAAE,MAAM,IAAI,aAAa,CAAC,0EAA0E,CAAC,CAAC;IACrI,CAAC;IAED,sFAAsF;IACtF,KAAK,CAAC,IAAI,CAAC,MAAc,EAAE,MAAc;QACvC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;QACrF,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,gBAAgB,EAAE;gBAC5C,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,mCAAmC,EAAE;gBAChE,IAAI,EAAE,IAAI,eAAe,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;gBAClE,QAAQ,EAAE,OAAO;gBACjB,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC;aAClC,CAAC,CAAC;YACH,MAAM,IAAI,GAAY,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAO,aAAa,CAAC;YACpE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,IAAsD,CAAC;YACjG,IAAI,OAAO,KAAK,IAAI;gBAAE,OAAO,QAAQ,CAAC;YACtC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1G,IAAI,IAAI,CAAC,QAAQ,CAAC,sBAAsB,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,sBAAsB,CAAC;gBAAE,OAAO,cAAc,CAAC;YAC1G,IAAI,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,OAAO,KAAK,KAAK;gBAAE,OAAO,aAAa,CAAC;YAC/E,OAAO,cAAc,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,aAAa,CAAC;QACvB,CAAC;IACH,CAAC;CACF"}
@@ -0,0 +1,38 @@
1
+ import { type ContentTypeDef } from '@velocity-astro/cms-core';
2
+ /**
3
+ * `velocity-cms check`: inspects a site on the CMS and names each problem with its file, the
4
+ * rule in `.agents/cms.md` it breaks and the fix, so an agent (or a person) can prove its work
5
+ * before saying it is done. It reads the site's files and, where it can, the content types in
6
+ * its database; it changes nothing.
7
+ */
8
+ export type FindingLevel = 'error' | 'warning';
9
+ export interface Finding {
10
+ /** A short name for the rule, such as `prerendered-cms-page`. */
11
+ readonly rule: string;
12
+ readonly level: FindingLevel;
13
+ /** The file it is about, from the site's folder. */
14
+ readonly file: string;
15
+ readonly message: string;
16
+ /** The heading in `.agents/cms.md` the rule is written under. */
17
+ readonly see: string;
18
+ readonly fix: string;
19
+ }
20
+ export interface CheckResult {
21
+ readonly findings: readonly Finding[];
22
+ /** What the check could not look at, and why: a database it could not read, say. */
23
+ readonly skipped: readonly string[];
24
+ }
25
+ export interface CheckOptions {
26
+ readonly dir: string;
27
+ /** The content types, as the site's database holds them. Left out, the rules that need them are skipped. */
28
+ readonly types?: readonly ContentTypeDef[];
29
+ /** Why there are no types, when there are none. */
30
+ readonly typesSkipped?: string;
31
+ readonly env?: Readonly<Record<string, string | undefined>>;
32
+ }
33
+ /** The keys of an object literal that maps blocks to components: `export const blocks = { hero: Hero, 'call-to-action': Cta }`. */
34
+ export declare function blockMapKeys(text: string): Map<string, string> | null;
35
+ export declare function checkSite({ dir, types, typesSkipped, env }: CheckOptions): CheckResult;
36
+ /** The result as a person reads it: one finding a few lines, the errors first. */
37
+ export declare function formatCheck({ findings, skipped }: CheckResult): string;
38
+ //# sourceMappingURL=check.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAEA,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI1F;;;;;GAKG;AAEH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC;AAE/C,MAAM,WAAW,OAAO;IACtB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,4GAA4G;IAC5G,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,mDAAmD;IACnD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CAC7D;AAyCD,mIAAmI;AACnI,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAiBrE;AAeD,wBAAgB,SAAS,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,GAAQ,EAAE,EAAE,YAAY,GAAG,WAAW,CAkG3F;AAED,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,WAAW,GAAG,MAAM,CAOtE"}