@tenphi/cookbook 0.15.0 → 0.16.0

package/README.md

@@ -1,5 +1,13 @@
 # @tenphi/cookbook
 
+Before changing a site's appearance, read the
+[customization rules](./docs/customization-rules.md)
+([online](https://cookbook.tenphi.me/customization-rules/)). The package ships
+the complete [Cookbook documentation](./docs/index.md) and local Tasty and Glaze
+references under `docs/upstream/`, including Tasty's
+[style rules for AI agents](./docs/upstream/tasty/docs/ai-agents.md).
+The guide includes a project instruction snippet and the lint setup.
+
 Install the complete integration with `npx astro add @tenphi/cookbook`:
 
 ```ts

package/docs/architecture.md

@@ -0,0 +1,91 @@
+---
+title: Architecture
+description: Understand the four packages and the static content pipeline behind Cookbook.
+sidebar:
+  order: 8
+---
+
+Cookbook keeps content concerns separate from rendering so another renderer
+can consume the same validated graph in the future.
+
+## Packages
+
+| Package                   | Responsibility                                                                                              |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `@tenphi/create-cookbook` | Inspect an npm artifact and scaffold a reproducible documentation project                                   |
+| `@tenphi/cookbook`        | Provide the memorable Astro integration, public config exports, and CLI                                     |
+| `@tenphi/docs`            | Discover sources, resolve packages, build the content graph, transform Markdown, and report diagnostics     |
+| `@tenphi/starlight`       | Adapt the graph to Astro/Starlight and provide the Tasty/Glaze theme, components, search, and static assets |
+
+The `@tenphi/cookbook` default export represents the complete product. Consumers do
+not compose Starlight or renderer internals themselves.
+
+## Build pipeline
+
+1. Validate and normalize the configuration.
+2. Collect local and locked package sources.
+3. Assign canonical routes to every document.
+4. Parse Markdown and collect headings, links, and assets.
+5. Rewrite internal references through the completed route graph.
+6. Reject unsafe paths and report strict diagnostics.
+7. Render static pages through Astro and Starlight.
+8. Copy content-hashed assets and build the local Pagefind index.
+
+Source documents are read-only throughout this process. The transformed body
+exists in the in-memory graph and the renderer's virtual module; a build never
+rewrites the repository Markdown.
+
+## Theme pipeline
+
+Theme resolution has three deliberately separate layers:
+
+1. Glaze resolves semantic palette inputs into light, dark, and high-contrast
+   colors.
+2. The Glaze values, design tokens, typography presets, states, and units are
+   registered directly with Tasty.
+3. Cookbook components use `tasty()` and the Tasty selector bridge styles DOM
+   owned by Astro, Starlight, Expressive Code, Pagefind, and rendered Markdown.
+
+The palette owns color relationships. Components never choose raw light/dark
+colors, and shape tokens never contain palette logic. This keeps a palette
+change, a density change, and a typography change independent. Astro runs
+Tasty in extract mode, so these runtime style calls become a shared static CSS
+asset during the build; no Tasty styling runtime ships to the browser.
+
+## Public graph API
+
+Renderer and tooling authors can work directly with `@tenphi/docs`:
+
+```ts
+import {
+  assertValidDocs,
+  createDocsGraph,
+  defineDocsConfig,
+} from "@tenphi/docs";
+
+const config = defineDocsConfig({
+  content: {
+    sources: [{ glob: "docs/**/*.md", base: "docs" }],
+  },
+});
+
+const graph = await createDocsGraph({ root: process.cwd(), config });
+assertValidDocs(graph);
+
+for (const route of graph.routes) {
+  console.log(route.route, route.sourcePath);
+}
+```
+
+The graph exposes normalized entries, routes, assets, and structured
+diagnostics without importing Starlight.
+
+## Reference app
+
+The monorepo's `apps/reference` project is both the deployed documentation site
+and an end-to-end fixture. Its integration discovers `docs.config.ts`, whose
+`root: "../.."` loads this `docs/` tree through the same route pipeline used by
+convention-mode sites. CI builds the same app before GitHub Pages publishes it.
+
+Return to [Cookbook](./index.md) or inspect the
+[repository](https://github.com/tenphi/cookbook).

package/docs/authoring.mdx

@@ -0,0 +1,86 @@
+---
+title: Authoring components
+description: Use accessible tabs, callouts, code groups, cards, steps, and isolated previews.
+sidebar:
+  order: 4
+---
+
+import { Callout, CodeGroup, Tab, Tabs } from "@tenphi/cookbook/components";
+
+Write ordinary Markdown for most pages. Use MDX when a page needs components,
+and import them from `@tenphi/cookbook/components`. Local MDX is supported by
+default; npm MDX requires an explicit `trust: "mdx"` source declaration.
+
+## Tabs
+
+Every panel requires a `label`. Arrow keys, Home, and End move between tabs;
+right-to-left layouts reverse the horizontal arrow direction. Without
+JavaScript, all panels remain readable under their headings.
+
+```mdx
+import { Tab, Tabs } from "@tenphi/cookbook/components";
+
+<Tabs label="Installation">
+  <Tab label="npm">Run `npm install your-package`.</Tab>
+  <Tab label="pnpm">Run `pnpm add your-package`.</Tab>
+</Tabs>
+```
+
+<Tabs label="Installation">
+  <Tab label="npm">Run `npm install your-package`.</Tab>
+  <Tab label="pnpm">Run `pnpm add your-package`.</Tab>
+</Tabs>
+
+## Callouts
+
+Use `kind="note"`, `"tip"`, `"caution"`, or `"danger"`; `title` overrides the
+visible label. The default kind is `note`. Status colors come from
+`theme.palette.info`, `success`, `warning`, and `danger` and adapt to all schemes
+and contrast modes.
+
+```mdx
+<Callout kind="tip" title="Keep content close to code">
+  Relative Markdown links continue to work after Cookbook assigns public routes.
+</Callout>
+```
+
+<Callout kind="tip" title="Keep content close to code">
+  Relative Markdown links continue to work after Cookbook assigns public routes.
+</Callout>
+
+## Code groups
+
+Pass labeled source strings to create an accessible tabbed code group. `language`
+is an optional visible label; these programmatic snippets render as escaped plain
+text. Ordinary fenced Markdown provides syntax highlighting.
+
+```mdx
+<CodeGroup
+  label="Install Cookbook"
+  items={[
+    { label: "npm", language: "shell", code: "npm install @tenphi/cookbook" },
+    { label: "pnpm", language: "shell", code: "pnpm add @tenphi/cookbook" },
+  ]}
+/>
+```
+
+<CodeGroup
+  label="Install Cookbook"
+  items={[
+    { label: "npm", language: "shell", code: "npm install @tenphi/cookbook" },
+    { label: "pnpm", language: "shell", code: "pnpm add @tenphi/cookbook" },
+  ]}
+/>
+
+## Other components
+
+| Component | Props and behavior                                                                                                |
+| --------- | ----------------------------------------------------------------------------------------------------------------- |
+| `Card`    | Optional `title` and `href`; renders an article or link with slot content                                         |
+| `Steps`   | Ordered list container; supply `li` elements                                                                      |
+| `Logo`    | Optional `label`, `decorative`, and `class`; renders the Cookbook mark                                            |
+| `Preview` | Required `title`; optional `html`, `css`, and `javascript`; isolates examples in Shadow DOM or a sandboxed iframe |
+
+The public package exports each component's props type, such as `TabProps`,
+`CalloutProps`, and `CodeGroupProps`. Styles and all named sub-elements are
+listed in [Theme and components](./theme-and-components.md#style-customization).

package/docs/cli.md

@@ -0,0 +1,88 @@
+---
+title: CLI commands
+description: Validate documentation and reconcile package locks using the same configuration as Astro.
+sidebar:
+  order: 6
+---
+
+The integration and CLI discover `docs.config.ts`, `.mts`, `.js`, or `.mjs` in the
+project directory. Its `root` sets the content and lock directory. Use `--root`
+to select another project, or `--config` for an explicit config path relative to
+that project.
+
+## Validate with doctor
+
+```sh
+npx @tenphi/cookbook doctor
+npx @tenphi/cookbook doctor --root ./apps/docs
+npx @tenphi/cookbook doctor --config ./config/manual.ts --json
+```
+
+Doctor checks the content graph, configuration, semantic theme, links, assets,
+navigation, and redirects without starting Astro. It exits non-zero for errors.
+It does not compile MDX or replace a full Astro build.
+
+JSON results use a stable envelope, including configuration failures:
+
+```json
+{
+  "ok": true,
+  "pages": 8,
+  "assets": 3,
+  "diagnostics": []
+}
+```
+
+## Update package content
+
+```sh
+npx @tenphi/cookbook update
+npx @tenphi/cookbook update @scope/package --dry-run
+npx @tenphi/cookbook update --json
+```
+
+`update` reads package sources from configuration, creates the first lock,
+resolves changed tags or ranges, and removes entries that are no longer declared.
+A package name or exact requested specifier selects individual updates. An
+unselected source must already have a matching lock; otherwise run a full update.
+
+`--dry-run` resolves versions and shows the proposed changes without writing
+files. JSON output adds `dryRun`, `changes`, `removed`, and `lock` to the envelope.
+Review and commit the resulting lock diff before deploying. Builds require an
+exact requested-specifier match and never silently substitute a lock for another
+range or tag.
+
+Vendored sources remain vendored. New artifacts are stored in separate integrity
+folders before the lock is replaced, so a failed download leaves the old lock
+and its content available. Old vendor folders can be removed after reviewing
+which paths the new lock references.
+
+## Creator flags
+
+Start with local content, an existing repository, or an npm artifact:
+
+```sh
+npm create @tenphi/cookbook@latest docs-site -- --yes
+npm create @tenphi/cookbook@latest docs-site -- --source . --yes
+npm create @tenphi/cookbook@latest docs-site -- --package @scope/package --yes
+```
+
+| Flag                                | Purpose                                           |
+| ----------------------------------- | ------------------------------------------------- |
+| `--source <directory>`              | Document an existing local repository             |
+| `--package <specifier>`             | Document a locked npm artifact                    |
+| `--yes`, `-y`                       | Use non-interactive defaults                      |
+| `--brand <color>`                   | Set the Glaze brand seed                          |
+| `--site <url>`                      | Set the canonical site URL                        |
+| `--base <path>`                     | Set Astro's hosting subpath                       |
+| `--deploy github-pages\|none`       | Add a deployment workflow                         |
+| `--package-manager npm\|pnpm\|yarn` | Select the project manager                        |
+| `--no-install`                      | Generate files without installing dependencies    |
+| `--vendor`                          | Vendor the npm artifact for offline builds        |
+| `--trust-package`                   | Permit MDX execution from the locked npm artifact |
+| `--open`                            | Start and open the development server             |
+
+`--source` and `--package` are mutually exclusive. With neither, the creator
+writes a local starter. `--vendor` and `--trust-package` require `--package`.
+`--open` requires installation. A non-empty destination requires interactive
+confirmation before generated files can be overwritten.