dogsbay 0.2.0-beta.2 → 0.2.0-beta.21

package/skills/platform/plugin-api/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: dogsbay:plugin-api
+description: Authoring contract for Dogsbay plugins — DogsbayPlugin hooks, factory pattern, name resolution, and lifecycle. Use when writing a plugin, debugging an installed plugin, or configuring plugins in dogsbay.config.yml.
+---
+
+# Dogsbay plugin API
+
+Plugins extend the build pipeline at well-defined hooks. Each
+plugin is an **npm package** that exports a default factory
+function — Dogsbay calls the factory once per build with the
+user's options, and the returned `DogsbayPlugin` object
+contributes to the lifecycle.
+
+## Plugin shape
+
+```ts
+import type { DogsbayPlugin, PluginContext } from "@dogsbay/types";
+
+export default function imageZoom(
+  options: { medium?: { background?: string } } = {},
+): DogsbayPlugin {
+  return {
+    id: "image-zoom",
+    description: "Click-to-enlarge images, view-transition aware.",
+
+    extendConfig(ctx) {
+      // Mutate the resolved DogsbayConfig before content imports
+    },
+
+    onContentImported(pages, nav, ctx) {
+      // Walk the page tree; tag images with data-zoomable, etc.
+    },
+
+    transformNav(nav, ctx) {
+      // Mutate the nav tree (add groups, reorder, etc.)
+    },
+
+    emitFiles(helpers, ctx) {
+      // Write extra files into the output directory
+    },
+
+    clientModules() {
+      // Import paths that get bundled into every page's client JS
+      return ["./client.js"];
+    },
+
+    styles() {
+      // CSS files to include in the build
+      return ["./styles.css"];
+    },
+
+    defineClientConfig(ctx) {
+      // Build-time config that becomes a client-side constant
+      return { background: options.medium?.background ?? "#000" };
+    },
+
+    componentWrappers() {
+      // Astro components that wrap MarkdownContent slots
+      return [{ slot: "MarkdownContent", component: "./MyWrapper.astro" }];
+    },
+
+    auditRules(ctx) {
+      // Register dogsbay site-check rules
+      return [
+        {
+          name: "image-zoom/missing-alt",
+          severity: "warning",
+          run(page) { /* ... */ },
+        },
+      ];
+    },
+
+    addAstroIntegrations() {
+      // Astro integrations to register in astro.config.mjs
+      return [{ packageName: "@astrojs/some-integration", options: {} }];
+    },
+  };
+}
+```
+
+All hooks are optional. A plugin that only contributes a CSS
+file declares `styles()` and nothing else.
+
+## Hooks — when each runs
+
+| Hook | When | Mutates | Common use |
+|---|---|---|---|
+| `extendConfig` | Right after config load, before resolver | DogsbayConfig | Inject sources / plugins / taxonomies |
+| `onContentImported` | After all sources imported, before draft filter | `pages[]`, `nav[]` | Walk trees, tag nodes, inject pages |
+| `transformNav` | After `onContentImported`, before nav emit | `nav[]` | Reorder, group, decorate |
+| `emitFiles` | After standard emitters | output dir | Write extra files (sitemaps, search indexes, etc.) |
+| `clientModules` | At codegen time | adds to plugin-runtime entry | Inject browser-side JS |
+| `styles` | At codegen time | adds to global CSS | Inject CSS files |
+| `defineClientConfig` | At codegen time | writes per-plugin config module | Bridge build-time → client constants |
+| `componentWrappers` | At per-page emit | wraps named slots | Wrap MarkdownContent with custom component (e.g. provider, decorator) |
+| `auditRules` | When `dogsbay site check` runs | registers rules | Enforce conventions specific to the plugin |
+| `addAstroIntegrations` | At astro.config.mjs scaffold | registers integrations | Pull in existing Astro integrations |
+
+## Factory pattern + ordering
+
+Plugins are listed in `dogsbay.config.yml`'s `plugins:` field.
+Each entry is either a string (package name) or an object with
+options:
+
+```yaml
+plugins:
+  - image-zoom                      # short — auto-prefix to @dogsbay/plugin-image-zoom
+  - "@your-org/plugin-foo"          # explicit
+  - name: typedoc
+    id: api-typedoc                 # optional: override the plugin's default id
+    options:
+      sourceRoot: ./src
+      include: ["*.ts"]
+```
+
+Name resolution:
+
+1. If the value contains `/` (scope), use as-is
+2. If `dogsbay-plugin-X` exists, use that
+3. If `@dogsbay/plugin-X` exists, use that
+4. Treat as absolute path / relative path / directory
+
+The auto-prefix lets users write `image-zoom` and have it
+resolve to `@dogsbay/plugin-image-zoom`.
+
+## Order — `before` / `after`
+
+Each plugin's id is unique within a build. Plugins can declare
+ordering constraints:
+
+```ts
+return {
+  id: "my-plugin",
+  before: ["image-zoom"],     // runs before image-zoom
+  after: ["typedoc"],         // runs after typedoc
+  // ...
+};
+```
+
+The loader topologically sorts the plugin list. Cycles fail at
+load time with a clear error.
+
+## Plugin context
+
+Every hook receives a `PluginContext` with:
+
+```ts
+interface PluginContext {
+  config: PluginVisibleConfig;   // the resolved DogsbayConfig (filtered to "user-visible" fields)
+  outputDir: string;             // absolute path to output dir (default ./astro)
+  logger: PluginLogger;          // pre-fixed with [plugin: <id>]
+}
+```
+
+`logger.info / warn / error` route through the CLI's logger and
+prefix with the plugin id, so users can trace warnings to a
+specific plugin.
+
+## EmitFiles helpers
+
+The `emitFiles` hook receives a helper bag:
+
+```ts
+interface EmitFilesHelpers {
+  writeFile(relativePath: string, content: string | Uint8Array): void;
+  copyDir(srcAbs: string, destRelative: string): void;
+}
+```
+
+Both helpers are scoped to `outputDir` — relative paths are
+resolved against it. A plugin can't escape its sandbox.
+
+## Plugin-contributed skills (Phase 3+)
+
+Plugins can ship their own skills in their package, under
+`skills/*.md`. The plugin loader merges them into the project's
+discovery surface when the plugin is enabled.
+
+```
+@dogsbay/plugin-image-zoom/
+├── package.json
+├── dist/
+├── skills/
+│   └── image-zoom-config.md      ← merged into .dogsbay/skills/plugins/
+└── styles.css
+```
+
+This means installing a plugin AUTOMATICALLY teaches the user's
+LLM how to use it — no separate skill install step.
+
+## Reference plugins
+
+Two plugins ship from the Dogsbay monorepo as references:
+
+- `@dogsbay/plugin-image-zoom` — image-zoom on click. Exercises
+  `onContentImported` (tags images), `clientModules` (medium-zoom
+  binding), `styles`, `defineClientConfig`. Source:
+  `packages/plugin-image-zoom/`.
+- `@dogsbay/plugin-typedoc` — TypeScript API docs from source
+  files. Exercises `onContentImported` (injects pages from
+  reflection), `transformNav`, `auditRules`. Source:
+  `packages/plugin-typedoc/`.
+
+Both are good "read me first" references for new plugin
+authors.
+
+## Common patterns
+
+### Pure styling plugin
+
+```ts
+export default function darkOptional(): DogsbayPlugin {
+  return {
+    id: "dark-optional",
+    styles: () => ["./dark.css"],
+  };
+}
+```
+
+### Tag-based content transformer
+
+```ts
+export default function imageZoom(opts: Options = {}): DogsbayPlugin {
+  return {
+    id: "image-zoom",
+    onContentImported(pages) {
+      for (const page of pages) {
+        walkTree(page.tree, (node) => {
+          if (node.type === "image") {
+            node.props = { ...node.props, "data-zoomable": "true" };
+          }
+        });
+      }
+      return { pages, nav: [] };
+    },
+    clientModules: () => ["./client.js"],
+    styles: () => ["./styles.css"],
+  };
+}
+```
+
+### Page-injecting plugin
+
+```ts
+export default function typedoc(opts: Options): DogsbayPlugin {
+  let reflections: Reflection[] = [];
+  return {
+    id: "typedoc",
+    extendConfig(ctx) {
+      reflections = reflectFromSourceRoot(opts.sourceRoot);
+    },
+    onContentImported(pages, nav) {
+      const newPages = reflections.map(reflectionToExportPage);
+      const apiNav = buildNavFromReflections(reflections);
+      return { pages: [...pages, ...newPages], nav: [...nav, ...apiNav] };
+    },
+    auditRules() {
+      return [{ name: "typedoc/missing-doc", run: checkUndocumented }];
+    },
+  };
+}
+```
+
+## Common mistakes
+
+- ❌ Forgetting to make the factory the **default export** — the
+  loader specifically looks for `module.default`.
+- ❌ Returning a Promise from a synchronous hook (e.g.
+  `extendConfig`) — most hooks accept sync OR async, but check
+  the type signature.
+- ❌ Mutating the input arrays in `onContentImported` (e.g.
+  `pages.push(...)`) instead of returning the new shape — works
+  by accident today but is fragile across versions. Always
+  return `{ pages, nav }`.
+- ❌ Writing to absolute paths from `emitFiles` — the helper is
+  sandboxed to `outputDir`. Use relative paths.
+- ❌ Hardcoding the plugin id — accept it from options if the
+  user might want to install the same plugin twice with
+  different configs (the loader auto-suffixes duplicates with
+  `#1`, `#2`).

package/skills/platform/project-anatomy/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: dogsbay:project-anatomy
+description: Understand the file layout of a Dogsbay project — where the config lives, where content goes, what astro/ contains, what's regenerated each build vs scaffolded once. Use when navigating an existing site or wiring user-authored files into the build.
+---
+
+# Dogsbay project anatomy
+
+Every Dogsbay-owned project (the `dogsbay site …` flow) has the
+same shape. Knowing which directory holds what — and which files
+are user-edited vs auto-regenerated — prevents the most common
+"why didn't my change show up" confusions.
+
+## The layout
+
+```
+my-docs/
+├── dogsbay.config.yml          ← user-edited; site config
+├── content/                    ← user-edited; markdown source
+│   ├── index.md
+│   ├── getting-started.md
+│   └── nav.yml                 ← user-edited; sidebar
+├── public/                     ← user-edited; static assets pass-through
+│   └── …
+├── .dogsbay/                   ← scaffolded; user can shadow specific files
+│   ├── skills/
+│   │   ├── platform/           ← symlinked → node_modules/dogsbay/skills/platform/
+│   │   ├── plugins/            ← merged from enabled plugins (when present)
+│   │   └── site/               ← user-authored; empty until populated
+│   ├── patterns/               ← installed pattern packages (Diátaxis, etc.)
+│   └── workflows/              ← installed workflow packages (PR review, etc.)
+├── astro/                      ← REGENERATED EACH BUILD; do not hand-edit
+│   ├── package.json            ← scaffold-once; user can add deps
+│   ├── astro.config.mjs        ← scaffold-once
+│   ├── tsconfig.json           ← scaffold-once
+│   ├── src/
+│   │   ├── components/ui/      ← scaffold-once; user can edit individual components
+│   │   ├── content/            ← REGENERATED — astro content collections
+│   │   ├── data/               ← REGENERATED — nav.json, site.json, switcherMap.json
+│   │   ├── lib/                ← REGENERATED — plugin-runtime, etc.
+│   │   ├── middleware.ts       ← REGENERATED
+│   │   ├── pages/              ← REGENERATED EVERY BUILD; never hand-edit
+│   │   ├── styles/             ← scaffold-once; theme.css + global.css
+│   │   └── wrappers/           ← REGENERATED — plugin wrapper stacks
+│   ├── public/                 ← copied from project root /public/
+│   ├── dist/                   ← astro build output (gitignored)
+│   └── node_modules/           ← gitignored
+├── .claude/skills/             ← created by `dogsbay agent install --agent claude`
+└── .cursor/rules/              ← created by `dogsbay agent install --agent cursor`
+```
+
+## Two-directory model — why
+
+Dogsbay separates the **content + config** that a writer thinks
+about (project root) from the **buildable Astro project** that
+the build pipeline owns (`astro/`). This is the single most
+important thing to understand when working with a Dogsbay site.
+
+| Project root | astro/ subdirectory |
+|---|---|
+| `dogsbay.config.yml`, `content/`, `public/`, `.dogsbay/` | `package.json`, `astro.config.mjs`, `src/pages/`, `node_modules/` |
+| Hand-edited; in source control | Scaffolded once + regenerated on each `site build`; node_modules + dist gitignored |
+| Where writers spend 99% of their time | Where the build pipeline lives |
+| Run `dogsbay site …` from here | `pnpm install` runs here for first-time deps |
+
+The config at the root anchors path resolution. Source paths in
+`dogsbay.config.yml` (`./content`, `./openapi/spec.yaml`,
+output: `./astro`) all resolve against the config file's
+directory.
+
+## Scaffold tiers — what's written when
+
+`format-astro` emits files in four tiers. Knowing which tier a
+file belongs to tells you when it changes.
+
+| Tier | Function | Files | When written |
+|---|---|---|---|
+| Static (scaffold-once) | `emitSiteScaffold` | `package.json`, `theme.css`, `astro.config.mjs`, `tsconfig.json`, `src/components/ui/*` | Only on first init or with `--force` |
+| Content | `emitAstroPages` | `nav.json`, per-page `.astro` + `.md.ts` mirrors, root `index.astro` redirect | Every `site build` |
+| Config-derived | `emitConfigDerivedFiles` | `public/robots.txt` (with `Content-Signal`) | Every `site build` |
+| Agent | `emitAgentReadinessFiles` | `public/llms.txt`, `llms-full.txt`, per-section, `public/_headers`, `src/middleware.ts` | Every `site build` (gated by `agent.llmsTxt` / `agent.mdMirror`) |
+
+Hand-edits to scaffold-once files (theme.css, individual
+components) survive subsequent builds. Hand-edits to
+regenerated-every-build files (pages, nav.json, llms.txt) get
+overwritten.
+
+## What runs where
+
+- `dogsbay site …` runs at the **project root** (anywhere with a
+  `dogsbay.config.yml` at or above cwd).
+- `pnpm install` / `pnpm run build` / `pnpm run dev` / `astro
+  …` run in **`astro/`** (the buildable Astro project's
+  package.json lives here).
+- `dogsbay site dev` and `site preview` are wrappers — they run
+  from the project root, do `dogsbay site build`, then `cd astro
+  && astro …` for you. Use these.
+
+## Common confusions
+
+### "I ran `npm run build` and got 'no package.json'"
+
+You ran it at the project root. There's no `package.json` at the
+root — the build script lives in `astro/package.json`. Use
+`dogsbay site preview` instead, which handles the `cd astro` for
+you.
+
+### "I edited `astro/src/pages/index.astro` and my change disappeared"
+
+That directory is regenerated every `site build`. Edit
+`content/index.md` instead — the build emits the .astro from
+markdown.
+
+### "I edited `astro/src/components/ui/card/Card.astro` and my change DID survive"
+
+Components are scaffold-once. The build doesn't touch them once
+written. You own them like any shadcn-style component — edit
+freely.
+
+### "Where do I put images?"
+
+In `public/` at the project root. The build copies the directory
+into `astro/public/` so Astro serves it as static assets.
+
+### "Why is there an `index.astro` in `astro/src/pages/` AND
+`docs/index.astro`?"
+
+The root `index.astro` is a 0-byte redirect to your `basePath`
+(default `/docs/`). The real home page is at
+`docs/index.astro`, generated from `content/index.md`.
+
+## Plugin runtime emission
+
+Plugins contribute additional files at build time:
+
+- `astro/src/lib/plugin-runtime.ts` — entry that imports each
+  plugin's clientModules
+- `astro/src/lib/plugin-config/<id>.ts` — per-plugin config
+- `astro/src/styles/plugins/*.css` — per-plugin stylesheets
+- `astro/src/components/wrappers/*.astro` — wrapper stacks for
+  the MarkdownContent slot
+- `astro/astro.config.plugins.mjs` — plugin alias map +
+  `vite.server.fs.allow` entries
+
+These all live under `astro/src/lib/` or `astro/src/components/wrappers/`.
+Hand-editing any of them gets overwritten on rebuild.
+
+## Output dir customisation
+
+The default is `./astro`. Users can override via `dogsbay.config.yml`:
+
+```yaml
+output: ./build/site
+```
+
+But almost no one does this. Stick with `./astro` unless there's
+a specific reason.