docs-ready 0.6.0 → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 udhaykumarbala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,321 @@
+# docs-ready
+
+**Make your docs AI-ready. Keep them that way.**
+
+`docs-ready` generates `llms.txt`, `llms-full.txt`, and `ai-context.md` from your existing documentation, then guards them against staleness and validates them for format compliance.
+
+Born from real production work making [0G Labs](https://0g.ai) docs AI-ready.
+
+---
+
+## Install
+
+```bash
+# Run directly
+npx docs-ready
+
+# Or install globally
+npm install -g docs-ready
+```
+
+Requires Node.js 18+.
+
+## Quick Start
+
+```bash
+# 1. Initialize config
+docs-ready init
+
+# 2. Generate AI-facing files
+docs-ready generate
+
+# 3. Check for staleness
+docs-ready guard
+
+# 4. Validate output
+docs-ready validate
+```
+
+`init` detects your framework and deployment platform, then writes a `.docs-ready.yaml` config file. `generate` produces the output files. `guard` monitors upstream sources for version bumps, endpoint changes, and keyword drift. `validate` lints the generated files for format, dead links, token limits, and coverage.
+
+---
+
+## Three Pillars
+
+### Generate
+
+Produces three AI-facing files from your documentation source:
+
+| File | Purpose |
+|------|---------|
+| `llms.txt` | Structured index of your docs with title, description, and page listing |
+| `llms-full.txt` | Full content of every doc page, concatenated and cleaned |
+| `ai-context.md` | Curated context page with key pages, summaries, and extra sections |
+
+MDX components are cleaned automatically. Token counts are reported for each file.
+
+### Guard
+
+Monitors upstream sources and flags when your AI docs may be stale:
+
+- **npm monitor** -- checks if documented npm package versions are outdated
+- **GitHub releases monitor** -- checks for new releases in tracked repositories
+- **Endpoint monitor** -- verifies that documented API endpoints are still reachable
+- **README keyword monitor** -- scans upstream READMEs for keyword drift
+
+Results can be output as console text, JSON, or markdown. Guard checks run in parallel for speed.
+
+### Validate
+
+Lints AI-facing docs for compliance:
+
+- **Format** -- checks that `llms.txt` follows the expected structure
+- **Links** -- verifies internal and external links are not dead
+- **Tokens** -- ensures total token count stays within the configured limit (default: 150,000)
+- **Coverage** -- checks that generated docs cover a sufficient percentage of source pages
+
+---
+
+## Configuration
+
+`docs-ready init` generates a `.docs-ready.yaml` file. You can also use `.docs-ready.yml` or `.docs-ready.json`.
+
+```yaml
+# --- Project metadata (required) ---
+title: "My Project"
+description: "Project documentation"
+url: "https://docs.example.com"
+
+# --- Documentation source ---
+docs:
+  dir: "./docs"
+  include:
+    - "**/*.md"
+    - "**/*.mdx"
+  exclude:
+    - "**/node_modules/**"
+    - "**/_*"
+
+# --- Generation ---
+generate:
+  llms_txt: true
+  llms_full_txt: true
+  ai_context: true
+  output_dir: "./build"
+  sections:                        # optional: group pages into sections
+    - title: "Getting Started"
+      patterns: ["getting-started/**"]
+  ai_context_config:               # optional: customize ai-context.md
+    key_pages:
+      - path: "intro.md"
+        section: "Overview"
+    extra_sections:
+      - title: "Architecture"
+        source: "architecture.md"
+
+# --- Guard ---
+guard:
+  npm_packages:
+    - name: "@0glabs/sdk"
+      label: "0G SDK"
+  github_releases:
+    - repo: "0glabs/0g-chain"
+      label: "0G Chain"
+  endpoints:
+    - url: "https://api.example.com/v1/health"
+      label: "API Health"
+      expected_status: [200]
+  readme_scans:
+    - repo: "0glabs/0g-chain"
+      keywords: ["install", "quickstart", "api"]
+  workflow:
+    enabled: true
+    schedule: "0 9 */3 * *"
+    create_issues: true
+    labels: ["ai-context-review", "documentation"]
+
+# --- Deployment ---
+deploy:
+  platform: "vercel"               # vercel | netlify | cloudflare | none
+  cors:
+    enabled: true
+    origins: ["*"]
+
+# --- Validation ---
+validate:
+  max_tokens: 150000
+  check_links: true
+  check_coverage: true
+  coverage_threshold: 0.95
+```
+
+---
+
+## CLI Reference
+
+### Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--quiet` | Only show errors |
+| `--verbose` | Show debug logging |
+| `--no-color` | Disable colored output |
+| `--version` | Print version |
+| `--help` | Show help |
+
+### `docs-ready init`
+
+Initialize a `.docs-ready.yaml` config file. Auto-detects framework, docs directory, and deployment platform.
+
+```bash
+docs-ready init
+```
+
+### `docs-ready generate`
+
+Generate AI-facing documentation files based on your config.
+
+```bash
+docs-ready generate
+docs-ready generate --dry-run
+docs-ready generate --only llms-txt
+docs-ready generate --watch
+```
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Show what would be generated without writing files |
+| `--only <type>` | Generate only one file: `llms-txt`, `llms-full`, or `ai-context` |
+| `--watch` | Watch for changes and regenerate automatically |
+
+### `docs-ready guard`
+
+Run staleness checks against upstream sources.
+
+```bash
+docs-ready guard
+docs-ready guard --output json
+docs-ready guard --output markdown
+docs-ready guard --init-workflow
+```
+
+| Flag | Description |
+|------|-------------|
+| `--output <format>` | Output format: `console` (default), `json`, or `markdown` |
+| `--init-workflow` | Generate a GitHub Actions workflow at `.github/workflows/docs-ready-guard.yml` |
+
+### `docs-ready validate`
+
+Lint and validate generated AI-facing docs.
+
+```bash
+docs-ready validate
+docs-ready validate --no-links
+```
+
+| Flag | Description |
+|------|-------------|
+| `--no-links` | Skip link checking |
+
+---
+
+## Frameworks Supported
+
+`docs-ready init` auto-detects the following frameworks and sets the correct docs directory:
+
+| Framework | Docs Directory |
+|-----------|---------------|
+| Docusaurus | `docs/` |
+| VitePress | `docs/` or custom |
+| MkDocs | `docs/` |
+| Starlight | `src/content/docs/` |
+| Plain Markdown | `./` or custom |
+
+Framework-specific readers handle sidebar configs, frontmatter conventions, and file organization for each.
+
+---
+
+## Deployment
+
+`docs-ready` generates platform-specific configuration to serve AI-facing files with proper CORS headers so LLMs can fetch them.
+
+### Vercel
+
+Adds rewrite rules and CORS headers to `vercel.json`:
+
+```json
+{
+  "headers": [
+    {
+      "source": "/llms.txt",
+      "headers": [
+        { "key": "Access-Control-Allow-Origin", "value": "*" },
+        { "key": "Content-Type", "value": "text/plain; charset=utf-8" }
+      ]
+    }
+  ]
+}
+```
+
+### Netlify
+
+Adds headers to `_headers` or `netlify.toml`:
+
+```
+/llms.txt
+  Access-Control-Allow-Origin: *
+  Content-Type: text/plain; charset=utf-8
+```
+
+### Cloudflare
+
+Adds rules to `_headers` for Cloudflare Pages:
+
+```
+/llms.txt
+  Access-Control-Allow-Origin: *
+  Content-Type: text/plain; charset=utf-8
+```
+
+---
+
+## Comparison
+
+| Feature | docs-ready | docusaurus-plugin-llms | afdocs |
+|---------|-----------|----------------------|--------|
+| `llms.txt` generation | Yes | Yes | Yes |
+| `llms-full.txt` generation | Yes | Yes | Yes |
+| `ai-context.md` generation | Yes | No | No |
+| Staleness monitoring (guard) | Yes | No | No |
+| Validation / linting | Yes | No | No |
+| GitHub Actions workflow | Yes | No | No |
+| Framework support | Docusaurus, VitePress, MkDocs, Starlight, plain MD | Docusaurus only | Multiple |
+| Watch mode | Yes | Via Docusaurus | No |
+| Deploy config generation | Vercel, Netlify, Cloudflare | No | No |
+| Config format | YAML / JSON | Docusaurus plugin config | YAML |
+
+`docusaurus-plugin-llms` is a good choice if you only use Docusaurus and only need file generation. `docs-ready` covers the full lifecycle: generate, guard against staleness, and validate compliance. If you already use `docusaurus-plugin-llms` for generation, `docs-ready init` detects it and disables duplicate generation -- you can still use guard and validate.
+
+---
+
+## Origin Story
+
+`docs-ready` was built while making the [0G Labs](https://0g.ai) documentation AI-ready. The generate step came first, then guard was added after discovering that AI context files silently went stale when upstream SDKs released new versions. Validate was added to catch format regressions in CI. The tool was extracted into a standalone package so any docs team can use it.
+
+---
+
+## Contributing
+
+Contributions are welcome. See the [GitHub repository](https://github.com/udhaykumarbala/docs-ready) for issues and pull requests.
+
+```bash
+git clone https://github.com/udhaykumarbala/docs-ready.git
+cd docs-ready
+npm install
+npm run dev
+npm test
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/chunk-PXQN4E6K.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+// src/utils/logger.ts
+import chalk from "chalk";
+import ora from "ora";
+var currentLevel = "normal";
+function setLogLevel(level) {
+  currentLevel = level;
+}
+var log = {
+  info: (msg) => {
+    if (currentLevel !== "quiet") console.log(chalk.blue("\u2139"), msg);
+  },
+  success: (msg) => {
+    if (currentLevel !== "quiet") console.log(chalk.green("\u2714"), msg);
+  },
+  warn: (msg) => {
+    console.log(chalk.yellow("\u26A0"), msg);
+  },
+  error: (msg) => {
+    console.error(chalk.red("\u2716"), msg);
+  },
+  dim: (msg) => {
+    if (currentLevel !== "quiet") console.log(chalk.dim(msg));
+  },
+  debug: (msg) => {
+    if (currentLevel === "verbose") console.log(chalk.gray("[debug]"), msg);
+  }
+};
+function spinner(text) {
+  if (currentLevel === "quiet") {
+    return { start: () => ({}), stop: () => ({}), succeed: () => ({}), fail: () => ({}) };
+  }
+  return ora({ text, color: "cyan" });
+}
+
+export {
+  setLogLevel,
+  log,
+  spinner
+};
+//# sourceMappingURL=chunk-PXQN4E6K.js.map

package/dist/chunk-PXQN4E6K.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/logger.ts"],"sourcesContent":["import chalk from \"chalk\";\nimport ora, { type Ora } from \"ora\";\n\nexport type LogLevel = \"quiet\" | \"normal\" | \"verbose\";\n\nlet currentLevel: LogLevel = \"normal\";\n\nexport function setLogLevel(level: LogLevel): void {\n  currentLevel = level;\n}\n\nexport const log = {\n  info: (msg: string) => {\n    if (currentLevel !== \"quiet\") console.log(chalk.blue(\"ℹ\"), msg);\n  },\n  success: (msg: string) => {\n    if (currentLevel !== \"quiet\") console.log(chalk.green(\"✔\"), msg);\n  },\n  warn: (msg: string) => {\n    console.log(chalk.yellow(\"⚠\"), msg);\n  },\n  error: (msg: string) => {\n    console.error(chalk.red(\"✖\"), msg);\n  },\n  dim: (msg: string) => {\n    if (currentLevel !== \"quiet\") console.log(chalk.dim(msg));\n  },\n  debug: (msg: string) => {\n    if (currentLevel === \"verbose\") console.log(chalk.gray(\"[debug]\"), msg);\n  },\n};\n\nexport function spinner(text: string): Ora {\n  if (currentLevel === \"quiet\") {\n    // Return a no-op spinner\n    return { start: () => ({} as Ora), stop: () => ({} as Ora), succeed: () => ({} as Ora), fail: () => ({} as Ora) } as unknown as Ora;\n  }\n  return ora({ text, color: \"cyan\" });\n}\n"],"mappings":";;;AAAA,OAAO,WAAW;AAClB,OAAO,SAAuB;AAI9B,IAAI,eAAyB;AAEtB,SAAS,YAAY,OAAuB;AACjD,iBAAe;AACjB;AAEO,IAAM,MAAM;AAAA,EACjB,MAAM,CAAC,QAAgB;AACrB,QAAI,iBAAiB,QAAS,SAAQ,IAAI,MAAM,KAAK,QAAG,GAAG,GAAG;AAAA,EAChE;AAAA,EACA,SAAS,CAAC,QAAgB;AACxB,QAAI,iBAAiB,QAAS,SAAQ,IAAI,MAAM,MAAM,QAAG,GAAG,GAAG;AAAA,EACjE;AAAA,EACA,MAAM,CAAC,QAAgB;AACrB,YAAQ,IAAI,MAAM,OAAO,QAAG,GAAG,GAAG;AAAA,EACpC;AAAA,EACA,OAAO,CAAC,QAAgB;AACtB,YAAQ,MAAM,MAAM,IAAI,QAAG,GAAG,GAAG;AAAA,EACnC;AAAA,EACA,KAAK,CAAC,QAAgB;AACpB,QAAI,iBAAiB,QAAS,SAAQ,IAAI,MAAM,IAAI,GAAG,CAAC;AAAA,EAC1D;AAAA,EACA,OAAO,CAAC,QAAgB;AACtB,QAAI,iBAAiB,UAAW,SAAQ,IAAI,MAAM,KAAK,SAAS,GAAG,GAAG;AAAA,EACxE;AACF;AAEO,SAAS,QAAQ,MAAmB;AACzC,MAAI,iBAAiB,SAAS;AAE5B,WAAO,EAAE,OAAO,OAAO,CAAC,IAAW,MAAM,OAAO,CAAC,IAAW,SAAS,OAAO,CAAC,IAAW,MAAM,OAAO,CAAC,GAAU;AAAA,EAClH;AACA,SAAO,IAAI,EAAE,MAAM,OAAO,OAAO,CAAC;AACpC;","names":[]}

package/dist/{generate-4EHDLBJX.js → generate-2KF6X5GF.js}

@@ -10,7 +10,7 @@ import {
 import {
   log,
   spinner
-} from "./chunk-7YN54Y4Y.js";
+} from "./chunk-PXQN4E6K.js";
 
 // src/cli/commands/generate.ts
 import fs from "fs/promises";
@@ -2004,8 +2004,22 @@ async function generateCommand(options = {}) {
       log.success(`Generated ai-context.md (${formatTokens(estimateTokens(aiContext))})`);
     }
   }
+  if (options.watch) {
+    log.info("Watching for changes... (press Ctrl+C to stop)");
+    const { watchDocs } = await import("./watcher-TAYSGKGV.js");
+    watchDocs({
+      dir: docsDir,
+      patterns: config.docs.include,
+      onChange: async () => {
+        log.info("Changes detected, regenerating...");
+        await generateCommand({ ...options, watch: false });
+      }
+    });
+    await new Promise(() => {
+    });
+  }
 }
 export {
   generateCommand
 };
-//# sourceMappingURL=generate-4EHDLBJX.js.map
+//# sourceMappingURL=generate-2KF6X5GF.js.map