@valkyrianlabs/payload-markdown-docs 0.1.0-canary.0

package/dist/security/verify.js

@@ -0,0 +1,54 @@
+import { createPublicKey, verify } from 'node:crypto';
+import { sha256Hex } from '../sync/index.js';
+export const verifyBodySha256 = ({ body, expectedHash })=>{
+    const computedHash = sha256Hex(body);
+    if (!/^[a-f0-9]{64}$/i.test(expectedHash)) {
+        return {
+            computedHash,
+            ok: false
+        };
+    }
+    return {
+        computedHash,
+        ok: computedHash === expectedHash.toLowerCase()
+    };
+};
+export const validateTimestampSkew = ({ maxSkewSeconds, now = new Date(), timestamp })=>{
+    const date = new Date(timestamp);
+    if (Number.isNaN(date.getTime())) {
+        return {
+            message: 'Sync request timestamp is invalid.',
+            ok: false
+        };
+    }
+    const skewMs = Math.abs(now.getTime() - date.getTime());
+    if (skewMs > maxSkewSeconds * 1000) {
+        return {
+            message: 'Sync request timestamp is outside the allowed skew.',
+            ok: false
+        };
+    }
+    return {
+        date,
+        ok: true
+    };
+};
+const getPublicKeyInput = (publicKey)=>{
+    if (publicKey.includes('BEGIN PUBLIC KEY')) {
+        return publicKey;
+    }
+    return createPublicKey({
+        type: 'spki',
+        format: 'der',
+        key: Buffer.from(publicKey, 'base64')
+    });
+};
+export const verifyEd25519Signature = ({ canonicalString, publicKey, signature })=>{
+    try {
+        return verify(null, Buffer.from(canonicalString, 'utf8'), getPublicKeyInput(publicKey), Buffer.from(signature, 'base64'));
+    } catch  {
+        return false;
+    }
+};
+
+//# sourceMappingURL=verify.js.map

package/dist/security/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/security/verify.ts"],"sourcesContent":["import { createPublicKey, verify } from 'node:crypto'\n\nimport { sha256Hex } from '../sync/index.js'\n\nexport type VerifyBodyHashResult =\n  | {\n      computedHash: string\n      ok: false\n    }\n  | {\n      computedHash: string\n      ok: true\n    }\n\nexport type ValidateTimestampResult =\n  | {\n      date: Date\n      ok: true\n    }\n  | {\n      message: string\n      ok: false\n    }\n\nexport const verifyBodySha256 = ({\n  body,\n  expectedHash,\n}: {\n  body: string\n  expectedHash: string\n}): VerifyBodyHashResult => {\n  const computedHash = sha256Hex(body)\n\n  if (!/^[a-f0-9]{64}$/i.test(expectedHash)) {\n    return {\n      computedHash,\n      ok: false,\n    }\n  }\n\n  return {\n    computedHash,\n    ok: computedHash === expectedHash.toLowerCase(),\n  }\n}\n\nexport const validateTimestampSkew = ({\n  maxSkewSeconds,\n  now = new Date(),\n  timestamp,\n}: {\n  maxSkewSeconds: number\n  now?: Date\n  timestamp: string\n}): ValidateTimestampResult => {\n  const date = new Date(timestamp)\n\n  if (Number.isNaN(date.getTime())) {\n    return {\n      message: 'Sync request timestamp is invalid.',\n      ok: false,\n    }\n  }\n\n  const skewMs = Math.abs(now.getTime() - date.getTime())\n\n  if (skewMs > maxSkewSeconds * 1000) {\n    return {\n      message: 'Sync request timestamp is outside the allowed skew.',\n      ok: false,\n    }\n  }\n\n  return {\n    date,\n    ok: true,\n  }\n}\n\nconst getPublicKeyInput = (publicKey: string) => {\n  if (publicKey.includes('BEGIN PUBLIC KEY')) {\n    return publicKey\n  }\n\n  return createPublicKey({\n    type: 'spki',\n    format: 'der',\n    key: Buffer.from(publicKey, 'base64'),\n  })\n}\n\nexport const verifyEd25519Signature = ({\n  canonicalString,\n  publicKey,\n  signature,\n}: {\n  canonicalString: string\n  publicKey: string\n  signature: string\n}): boolean => {\n  try {\n    return verify(\n      null,\n      Buffer.from(canonicalString, 'utf8'),\n      getPublicKeyInput(publicKey),\n      Buffer.from(signature, 'base64'),\n    )\n  } catch {\n    return false\n  }\n}\n\n"],"names":["createPublicKey","verify","sha256Hex","verifyBodySha256","body","expectedHash","computedHash","test","ok","toLowerCase","validateTimestampSkew","maxSkewSeconds","now","Date","timestamp","date","Number","isNaN","getTime","message","skewMs","Math","abs","getPublicKeyInput","publicKey","includes","type","format","key","Buffer","from","verifyEd25519Signature","canonicalString","signature"],"mappings":"AAAA,SAASA,eAAe,EAAEC,MAAM,QAAQ,cAAa;AAErD,SAASC,SAAS,QAAQ,mBAAkB;AAsB5C,OAAO,MAAMC,mBAAmB,CAAC,EAC/BC,IAAI,EACJC,YAAY,EAIb;IACC,MAAMC,eAAeJ,UAAUE;IAE/B,IAAI,CAAC,kBAAkBG,IAAI,CAACF,eAAe;QACzC,OAAO;YACLC;YACAE,IAAI;QACN;IACF;IAEA,OAAO;QACLF;QACAE,IAAIF,iBAAiBD,aAAaI,WAAW;IAC/C;AACF,EAAC;AAED,OAAO,MAAMC,wBAAwB,CAAC,EACpCC,cAAc,EACdC,MAAM,IAAIC,MAAM,EAChBC,SAAS,EAKV;IACC,MAAMC,OAAO,IAAIF,KAAKC;IAEtB,IAAIE,OAAOC,KAAK,CAACF,KAAKG,OAAO,KAAK;QAChC,OAAO;YACLC,SAAS;YACTX,IAAI;QACN;IACF;IAEA,MAAMY,SAASC,KAAKC,GAAG,CAACV,IAAIM,OAAO,KAAKH,KAAKG,OAAO;IAEpD,IAAIE,SAAST,iBAAiB,MAAM;QAClC,OAAO;YACLQ,SAAS;YACTX,IAAI;QACN;IACF;IAEA,OAAO;QACLO;QACAP,IAAI;IACN;AACF,EAAC;AAED,MAAMe,oBAAoB,CAACC;IACzB,IAAIA,UAAUC,QAAQ,CAAC,qBAAqB;QAC1C,OAAOD;IACT;IAEA,OAAOxB,gBAAgB;QACrB0B,MAAM;QACNC,QAAQ;QACRC,KAAKC,OAAOC,IAAI,CAACN,WAAW;IAC9B;AACF;AAEA,OAAO,MAAMO,yBAAyB,CAAC,EACrCC,eAAe,EACfR,SAAS,EACTS,SAAS,EAKV;IACC,IAAI;QACF,OAAOhC,OACL,MACA4B,OAAOC,IAAI,CAACE,iBAAiB,SAC7BT,kBAAkBC,YAClBK,OAAOC,IAAI,CAACG,WAAW;IAE3B,EAAE,OAAM;QACN,OAAO;IACT;AACF,EAAC"}

package/dist/skills/codex/SKILL.md

@@ -0,0 +1,173 @@
+# Payload Markdown Docs Skill
+
+Use this skill when maintaining Git-backed documentation for a project that uses `@valkyrianlabs/payload-markdown-docs`.
+
+The docs source lives in `{{docsRoot}}` unless the user says otherwise. Edit Markdown source files first. Do not directly mutate generated Payload docs records unless the user explicitly asks for an admin-side override change.
+
+## Core Rules
+
+- Keep docs in repo-local Markdown files.
+- Use `.md` files only. Do not introduce MDX unless the project explicitly enables it in a future version.
+- Use supported frontmatter only.
+- Keep internal docs links root-relative inside the docs set, such as `/getting-started/quick-start`.
+- Use `payload-markdown` directives only when they are supported.
+- Do not invent directives, frontmatter fields, CLI flags, sync modes, or runtime features.
+- Do not describe unsupported features as implemented.
+- Run validation before finishing docs edits.
+- Treat sync and publishing as server-owned. The request may ask; the Payload plugin decides.
+
+## AI Markdown Export Manifest
+
+Treat `{{docsRoot}}/index.ai.yml` as part of the standard docs package.
+When creating, scaffolding, migrating, or updating Payload Markdown docs, create or
+update this file automatically. Do not wait for the user to request it.
+
+The manifest is source-controlled alongside the docs. It controls the generated
+AI-facing raw Markdown route, usually `/plugins/<docs-package>.md`, while the
+human docs continue to render at `/plugins/<docs-package>`.
+
+Rules for `index.ai.yml`:
+
+- Prefer `index.ai.yml`; `index.ai.yaml` is supported when already present.
+- Generate `order` from the actual Markdown files present under `{{docsRoot}}`.
+- Update `order` in the same change when docs pages are added, renamed, moved, or removed.
+- Do not invent page names just to fill the manifest.
+- Do not show the manifest in human docs navigation.
+- Do not render the manifest as a normal docs page.
+- Use it as the canonical ordering source for the `.md` export.
+- Avoid backend hand-sorting unless the project already has a docs sort field.
+
+Ordering source preference:
+
+1. `{{docsRoot}}/index.ai.yml`
+2. `{{docsRoot}}/index.ai.yaml`
+3. existing docs/nav order field
+4. deterministic fallback order: title, slug/path, id
+
+Default ordering pattern when applicable:
+
+1. `index.md`
+2. installation/setup docs
+3. basic usage docs
+4. rendering docs
+5. blocks/component docs
+6. styling/theming docs
+7. configuration docs
+8. advanced docs
+9. examples
+10. troubleshooting/reference
+
+Supported first-pass values:
+
+- `orphans: append`
+- `orphans: ignore`
+- `headingMode: normalize`
+- `headingMode: preserve`
+
+Defaults are `orphans: append` and `headingMode: normalize`.
+
+Example manifest:
+
+```yaml
+version: 1
+
+title: Payload Markdown Documentation
+canonical: /plugins/payload-markdown
+output: /plugins/payload-markdown.md
+
+description: >
+  Consolidated AI-facing documentation export for Payload Markdown.
+
+preamble: |
+  This file is intended for AI agents, editor tooling, Codex, ChatGPT,
+  and offline reference.
+
+  Read the documents in the listed order. Installation and basic usage
+  should be treated as prerequisite context before rendering, styling,
+  configuration, or advanced examples.
+
+order:
+  - ./index.md
+  - ./install.md
+  - ./usage.md
+  - ./rendering.md
+  - ./blocks.md
+  - ./styling.md
+  - ./configuration.md
+  - ./examples.md
+
+exclude:
+  - ./drafts/**
+  - ./internal.md
+
+orphans: append
+headingMode: normalize
+```
+
+Manifest fields:
+
+- `version`: manifest format version.
+- `title`: title of the generated Markdown export.
+- `canonical`: canonical human-facing docs URL.
+- `output`: canonical AI-facing Markdown export URL.
+- `description`: short summary included near the top of the export.
+- `preamble`: AI-facing usage note included before page content.
+- `order`: ordered list of docs files to include first.
+- `exclude`: glob/path list of docs to omit from the AI export.
+- `orphans`: behavior for docs not listed in `order`.
+- `headingMode`: heading normalization behavior.
+
+## Default Workflow
+
+```bash
+{{packageManager}} exec payload-markdown-docs validate {{docsRoot}} --source main-docs
+{{packageManager}} exec payload-markdown-docs plan {{docsRoot}} --source main-docs
+```
+
+Only push when the user asks for an upload and provides endpoint/auth context. Prefer GitHub OIDC in GitHub Actions:
+
+```bash
+{{packageManager}} exec payload-markdown-docs push {{docsRoot}} \
+  --endpoint "$DOCS_SYNC_ENDPOINT" \
+  --source main-docs \
+  --github-oidc \
+  --oidc-audience payload-markdown-docs \
+  --dry-run
+```
+
+Ed25519 signed sync is still supported for non-GitHub CI or local workflows:
+
+```bash
+{{packageManager}} exec payload-markdown-docs push {{docsRoot}} \
+  --endpoint "$DOCS_SYNC_ENDPOINT" \
+  --source main-docs \
+  --key-id github-actions-main \
+  --private-key-env DOCS_SYNC_PRIVATE_KEY \
+  --sync
+```
+
+Sync writes require `sync.allowWrites: true`. Publishing additionally requires `sync.allowPublish: true` and a draft-enabled docs collection.
+
+## References
+
+- `reference/payload-markdown-directives.md`
+- `reference/frontmatter.md`
+- `reference/workflow.md`
+- `reference/sync.md`
+- `reference/routing.md`
+- `reference/admin.md`
+- `reference/troubleshooting.md`
+- `examples/docs-page.md`
+- `examples/github-actions.md`
+
+## Safety Checklist
+
+Before finishing:
+
+1. Confirm changed docs have valid frontmatter.
+2. Confirm `index.ai.yml` matches the current docs files.
+3. Confirm internal links are root-relative.
+4. Confirm directives match the reference.
+5. Run validate.
+6. Run plan when sync behavior matters.
+7. Report any validation failures instead of guessing.

package/dist/skills/codex/examples/docs-page.md

@@ -0,0 +1,42 @@
+# Example Docs Page
+
+```markdown
+---
+title: Signed Push
+navTitle: Signed Push
+description: Upload docs with signed requests.
+order: 30
+status: published
+tags:
+  - workflow
+---
+
+# Signed Push
+
+:::toc {title="On this page" depth="3" theme="compact"}
+:::
+
+Use signed push to validate and upload docs.
+
+:::callout {variant="warning" title="Server-owned authority"}
+The request may ask. The Payload plugin decides.
+:::
+
+:::steps {variant="cards" layout="stack" numbered stepTheme="glass"}
+
+### Validate
+
+Run `payload-markdown-docs validate`.
+
+### Dry-run
+
+Run `payload-markdown-docs push --dry-run`.
+
+### Sync
+
+Run `payload-markdown-docs push --sync` only when the server allows writes.
+
+:::
+
+Read [Publishing](/workflow/publishing) next.
+```

package/dist/skills/codex/examples/github-actions.md

@@ -0,0 +1,64 @@
+# GitHub Actions Example
+
+```yaml
+name: Publish docs
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Validate docs
+        run: pnpm exec payload-markdown-docs validate ./docs --source main-docs
+
+      - name: Dry-run docs sync
+        if: github.event_name == 'pull_request'
+        run: |
+          pnpm exec payload-markdown-docs push ./docs \
+            --endpoint "$DOCS_SYNC_ENDPOINT" \
+            --source main-docs \
+            --github-oidc \
+            --oidc-audience payload-markdown-docs \
+            --dry-run
+        env:
+          DOCS_SYNC_ENDPOINT: ${{ secrets.DOCS_SYNC_ENDPOINT }}
+
+      - name: Publish docs
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          pnpm exec payload-markdown-docs push ./docs \
+            --endpoint "$DOCS_SYNC_ENDPOINT" \
+            --source main-docs \
+            --github-oidc \
+            --oidc-audience payload-markdown-docs \
+            --sync \
+            --publish
+        env:
+          DOCS_SYNC_ENDPOINT: ${{ secrets.DOCS_SYNC_ENDPOINT }}
+```

package/dist/skills/codex/reference/admin.md

@@ -0,0 +1,28 @@
+# Admin Manager
+
+The Docs Set Admin Manager is a read-only overview on the docs set edit view.
+
+It shows:
+
+- route base
+- sync metadata
+- total generated docs
+- archived docs
+- draft and published docs
+- hidden-from-nav docs
+- docs with overrides
+- generated docs grouped by source path
+- links to generated docs records
+
+Per-doc overrides live on generated docs records:
+
+- `navTitle`
+- `hideFromNav`
+- `theme`
+- `heroEyebrow`
+- `heroTitle`
+- `heroDescription`
+- `seoTitle`
+- `seoDescription`
+
+Inline override editing from the manager is not implemented yet. Open the generated docs record to edit overrides.

package/dist/skills/codex/reference/frontmatter.md

@@ -0,0 +1,39 @@
+# Frontmatter
+
+Use only this supported frontmatter subset.
+
+```yaml
+---
+title: Installation
+navTitle: Install
+description: Install and configure docs sync.
+order: 10
+status: published
+tags:
+  - getting-started
+redirectFrom:
+  - /docs/install
+---
+```
+
+Supported fields:
+
+- `title`
+- `navTitle`
+- `description`
+- `order`
+- `status`
+- `slug`
+- `tags`
+- `redirectFrom`
+- `draft`
+
+Rules:
+
+- `status` must be `draft` or `published`.
+- `order` must be a number.
+- `tags` and `redirectFrom` must use list item syntax.
+- `slug` may contain letters, numbers, and hyphens.
+- Avoid arbitrary nested YAML objects.
+- Avoid unsupported fields unless the user accepts validation warnings.
+- Explicit `title` is preferred even though title fallback exists.

package/dist/skills/codex/reference/payload-markdown-directives.md

@@ -0,0 +1,77 @@
+# Payload Markdown Directives
+
+Use directives to make docs clearer while keeping Markdown readable in Git.
+
+## Table Of Contents
+
+```markdown
+:::toc {title="On this page" depth="3" theme="compact"}
+:::
+```
+
+Use near the top of long reference or configuration pages.
+
+## Callout
+
+```markdown
+:::callout {variant="warning" title="Server-owned authority"}
+The request may ask. The Payload plugin decides.
+:::
+```
+
+Use for warnings, notes, tips, and important constraints.
+
+## Details
+
+```markdown
+:::details {title="Advanced notes"}
+Optional deeper explanation.
+:::
+```
+
+Use for advanced or secondary material.
+
+## Steps
+
+```markdown
+:::steps {variant="cards" layout="stack" numbered stepTheme="glass"}
+
+### Generate keys
+
+Run keygen.
+
+### Configure Payload
+
+Add the public key.
+
+:::
+```
+
+Use for ordered procedures.
+
+## Cards
+
+```markdown
+:::cards {columns="3" cardTheme="glass"}
+
+:::card {title="Signed sync" href="/workflow/signed-push"}
+Upload docs with signed requests.
+:::
+
+:::card {title="Route adapter" href="/frontend/route-adapter"}
+Render docs without turning them into Pages.
+:::
+
+:::
+```
+
+Use cards for overview pages and choice sets.
+
+## Gotchas
+
+- Do not invent directive names.
+- Keep blank lines around nested directive content.
+- Use `:::steps` for procedures.
+- Use `:::cards` for overview grids.
+- Use `:::callout` for warnings, tips, and notes.
+- Prefer root-relative docs links in directive attributes, such as `href="/workflow/signed-push"`.

package/dist/skills/codex/reference/routing.md

@@ -0,0 +1,35 @@
+# Routing
+
+Docs are managed as docs sets, not as one Page per Markdown file.
+
+## Docs Groups
+
+Docs groups reserve namespaces such as `/plugins` or `/internal/tools`.
+
+## Docs Sets
+
+Docs sets represent one documentation site. They map a `sourceId` to a server-owned `routeBase`, such as:
+
+```text
+/plugins/payload-markdown-docs
+```
+
+## Generated Docs
+
+Generated docs records are internal storage for routing, search, sync correctness, and per-doc overrides.
+
+`index.md` routes to the docs set route base. Nested files route below it.
+
+## Links
+
+Use root-relative links inside the docs set:
+
+```markdown
+[Quick start](/getting-started/quick-start)
+```
+
+Do not hardcode production docs domains for internal navigation.
+
+## Route Adapter
+
+The `/next` export can resolve docs routes and let an app fall back to normal Pages rendering when no docs route matches. It does not mutate Pages.

package/dist/skills/codex/reference/sync.md

@@ -0,0 +1,35 @@
+# Sync Safety Model
+
+The sync workflow is authenticated and server-owned.
+
+Important concepts:
+
+- `source.id` maps to a configured docs set or allowed source.
+- The docs set owns the route base.
+- The manifest does not choose target collections or fields.
+- `sync.allowWrites: true` is required for `mode: "sync"`.
+- `sync.allowPublish: true` and `target.enableDrafts: true` are required for publishing.
+- `sync.allowHardDelete: true` is required for hard delete.
+- Archive is safer than delete.
+- Manual edit conflicts abort before writes.
+
+Ed25519 signed pushes verify:
+
+- key id
+- timestamp skew
+- nonce replay
+- body SHA-256
+- Ed25519 signature
+- manifest validity
+
+GitHub OIDC pushes verify:
+
+- bearer JWT signature through GitHub JWKS
+- issuer and audience
+- repository, owner, ref, workflow, and environment allowlists when configured
+- pull request policy
+- JWT `jti` replay protection
+- body SHA-256
+- manifest validity
+
+Do not bypass failed auth or body verification. Fix the key, endpoint, source id, body, or server config.

package/dist/skills/codex/reference/troubleshooting.md

@@ -0,0 +1,53 @@
+# Troubleshooting
+
+## Invalid signature
+
+Check key id, private key, endpoint pathname, timestamp, nonce, and exact body string.
+
+## OIDC invalid token
+
+Check that the workflow uses `--github-oidc`, grants `id-token: write`, and requests the configured audience.
+
+## OIDC repository or ref not allowed
+
+Check server OIDC allowlists. The request may ask; the server decides which repository and ref are trusted.
+
+## OIDC replay
+
+Rerun the workflow so GitHub issues a fresh OIDC token with a new `jti`.
+
+## Body hash mismatch
+
+The signed body is not the body that was sent. Sign and send the exact same JSON string.
+
+## Nonce replay
+
+Generate a fresh request. Do not reuse signed headers.
+
+## Source not allowed
+
+Create or update a docs set with the expected `sourceId`, or update server fallback sources.
+
+## Publish disabled
+
+The server needs `sync.allowPublish: true` and a draft-enabled docs collection.
+
+## Hard delete disabled
+
+Hard delete requires `sync.allowHardDelete: true`. Prefer archive unless the user explicitly needs deletion.
+
+## Route collision
+
+A generated docs route overlaps another docs route or an opt-in Pages collision check.
+
+## Manual edit conflict
+
+A generated docs record was edited outside the docs sync workflow. The sync aborts before writes.
+
+## Invalid frontmatter
+
+Use only supported fields and simple YAML.
+
+## Non-root-relative link
+
+Internal docs links should look like `/workflow/signed-push`, not `workflow/signed-push` or a production URL.

package/dist/skills/codex/reference/workflow.md

@@ -0,0 +1,39 @@
+# Agent Docs Workflow
+
+Use this workflow when editing docs source files.
+
+1. Inspect the docs tree, usually `{{docsRoot}}`.
+2. Edit Markdown files in place.
+3. Keep frontmatter valid and simple.
+4. Keep internal docs links root-relative.
+5. Use only supported `payload-markdown` directives.
+6. Run validation.
+7. Run plan when sync impact matters.
+8. Only push when the user asks for upload/sync and provides endpoint/auth context.
+
+Validation:
+
+```bash
+{{packageManager}} exec payload-markdown-docs validate {{docsRoot}} --source main-docs
+```
+
+Plan:
+
+```bash
+{{packageManager}} exec payload-markdown-docs plan {{docsRoot}} --source main-docs
+```
+
+Dry-run upload with GitHub OIDC:
+
+```bash
+{{packageManager}} exec payload-markdown-docs push {{docsRoot}} \
+  --endpoint "$DOCS_SYNC_ENDPOINT" \
+  --source main-docs \
+  --github-oidc \
+  --oidc-audience payload-markdown-docs \
+  --dry-run
+```
+
+Use Ed25519 key flags only when the project is not using GitHub OIDC.
+
+Do not directly edit generated Payload docs records unless the user specifically asks for Payload-side overrides.