@writedocs/generator 0.1.0 → 0.2.0

package/README.md

@@ -1,17 +1,28 @@
-# Writedocs
-
-A static site generator for documentation: a `writedocs.json` config + a folder of MDX/Markdown in, a fully static site out. Built on [Astro](https://astro.build), in the spirit of Docusaurus/Mintlify.
-
-## Quickstart
-
-```bash
-npm install -g @writedocs/generator
-
-cd my-docs   # any folder containing writedocs.json + docs/
-writedocs dev
-writedocs build
-```
-
-The npm package is `@writedocs/generator`; the CLI command it installs is still `writedocs` (see the `bin` field in `package.json`).
-
-`npx @writedocs/generator init/dev/build` still works too, for a one-off run with no install at all.
+# Writedocs
+
+A static site generator for documentation: a `writedocs.json` config + a folder of MDX/Markdown in, a fully static site out. Built on [Astro](https://astro.build), in the spirit of Docusaurus/Mintlify.
+
+## Quickstart
+
+```bash
+npm install -g @writedocs/generator
+
+cd my-docs   # any folder containing writedocs.json + docs/
+writedocs dev
+writedocs validate
+writedocs build
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `writedocs init [dir]` | Scaffolds a `writedocs.json` and a starter `docs/` folder. |
+| `writedocs dev [dir]` | Starts a local dev server with hot reload. |
+| `writedocs validate [dir]` | Checks `<dir>/writedocs.json` against the schema. Exits `0` when it is valid and `1` when it is not, so it can gate a CI job; prints one line per problem, in the same words the build uses. Runs entirely locally — no key, no network. Configuration only: it does not resolve OpenAPI specs, and it does not check that the pages named in `navigation` exist. |
+
+`[dir]` defaults to the current directory in every command.
+
+The npm package is `@writedocs/generator`; the CLI command it installs is still `writedocs` (see the `bin` field in `package.json`).
+
+`npx @writedocs/generator init/dev/build` still works too, for a one-off run with no install at all.

package/bin/writedocs.js

@@ -1,73 +1,126 @@
-#!/usr/bin/env node
-import { Command } from 'commander';
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import dotenv from 'dotenv';
-import { runDev } from '../src/cli/dev.js';
-import { runBuild } from '../src/cli/build.js';
-import { runInit } from '../src/cli/init.js';
-import { requireBuildKey } from '../src/cli/build-auth.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const packageRoot = path.resolve(__dirname, '..');
-// Read rather than hardcode - a literal version string here silently drifts
-// from package.json's own "version" the moment either one is bumped without
-// the other (exactly what `npm version <bump>` does: it only touches
-// package.json). `writedocs --version` should always reflect what actually
-// got published, not whatever this string happened to say at the time this
-// line was last hand-edited.
-const { version } = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
-
-const program = new Command();
-program
-  .name('writedocs')
-  .description('Static site generator for writedocs.json + MDX')
-  .version(version);
-
-program
-  .command('dev')
-  .description('Start a local dev server with hot reload')
-  .argument('[dir]', 'content directory (contains writedocs.json and docs/)', '.')
-  .option('-p, --port <port>', 'port to run on')
-  .action(async (dir, opts) => {
-    await runDev({
-      contentDir: path.resolve(process.cwd(), dir),
-      packageRoot,
-      port: opts.port,
-    });
-  });
-
-program
-  // { hidden: true } keeps `build` out of `writedocs --help` - it's not a
-  // command ordinary users are meant to discover or run themselves. See
-  // src/cli/build-auth.js for the second layer: even someone who knows the
-  // command exists still can't run it without the right key.
-  .command('build', { hidden: true })
-  .description('Build a static site into <dir>/dist')
-  .argument('[dir]', 'content directory (contains writedocs.json and docs/)', '.')
-  .option('-k, --key <key>', 'build authorization key (or set WRITEDOCS_API_KEY)')
-  .action(async (dir, opts) => {
-    const contentDir = path.resolve(process.cwd(), dir);
-    // Project-scoped, not global: a .env sitting next to this project's own
-    // writedocs.json (WRITEDOCS_KEY_SERVER_URL, WRITEDOCS_API_KEY) is picked
-    // up automatically, so build doesn't need those exported by hand every
-    // session. dotenv never overwrites a var already set in the real
-    // environment - an explicit `export`/CI secret still wins over the file.
-    dotenv.config({ path: path.join(contentDir, '.env'), quiet: true });
-    await requireBuildKey(opts.key || process.env.WRITEDOCS_API_KEY);
-    await runBuild({ contentDir, packageRoot });
-  });
-
-program
-  .command('init')
-  .description('Scaffold a writedocs.json and starter docs/ folder')
-  .argument('[dir]', 'directory to scaffold into', '.')
-  .action(async (dir) => {
-    await runInit({ targetDir: path.resolve(process.cwd(), dir) });
-  });
-
-program.parseAsync(process.argv).catch((err) => {
-  console.error(`[writedocs] ${err.message}`);
-  process.exit(1);
-});
+#!/usr/bin/env node
+import { Command } from 'commander';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import dotenv from 'dotenv';
+import { runDev } from '../src/cli/dev.js';
+import { runBuild } from '../src/cli/build.js';
+import { runInit } from '../src/cli/init.js';
+import { requireBuildKey } from '../src/cli/build-auth.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '..');
+// Read rather than hardcode - a literal version string here silently drifts
+// from package.json's own "version" the moment either one is bumped without
+// the other (exactly what `npm version <bump>` does: it only touches
+// package.json). `writedocs --version` should always reflect what actually
+// got published, not whatever this string happened to say at the time this
+// line was last hand-edited.
+const { version } = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
+
+const program = new Command();
+program
+  .name('writedocs')
+  .description('Static site generator for writedocs.json + MDX')
+  .version(version);
+
+program
+  .command('dev')
+  .description('Start a local dev server with hot reload')
+  .argument('[dir]', 'content directory (contains writedocs.json and docs/)', '.')
+  .option('-p, --port <port>', 'port to run on')
+  .action(async (dir, opts) => {
+    await runDev({
+      contentDir: path.resolve(process.cwd(), dir),
+      packageRoot,
+      port: opts.port,
+    });
+  });
+
+program
+  // { hidden: true } keeps `build` out of `writedocs --help` - it's not a
+  // command ordinary users are meant to discover or run themselves. See
+  // src/cli/build-auth.js for the second layer: even someone who knows the
+  // command exists still can't run it without the right key.
+  .command('build', { hidden: true })
+  .description('Build a static site into <dir>/dist')
+  .argument('[dir]', 'content directory (contains writedocs.json and docs/)', '.')
+  .option('-k, --key <key>', 'build authorization key (or set WRITEDOCS_API_KEY)')
+  .action(async (dir, opts) => {
+    const contentDir = path.resolve(process.cwd(), dir);
+    // Project-scoped, not global: a .env sitting next to this project's own
+    // writedocs.json (WRITEDOCS_KEY_SERVER_URL, WRITEDOCS_API_KEY) is picked
+    // up automatically, so build doesn't need those exported by hand every
+    // session. dotenv never overwrites a var already set in the real
+    // environment - an explicit `export`/CI secret still wins over the file.
+    dotenv.config({ path: path.join(contentDir, '.env'), quiet: true });
+    await requireBuildKey(opts.key || process.env.WRITEDOCS_API_KEY);
+    await runBuild({ contentDir, packageRoot });
+  });
+
+program
+  // Visivel, ao contrario do `build`: validar a propria configuracao e
+  // exatamente o tipo de coisa que um usuario deve poder rodar sozinho, no CI
+  // inclusive. Sem chave, sem dotenv, sem rede - le um arquivo e sai 0 ou 1.
+  .command('validate')
+  .description('Validate writedocs.json against the schema')
+  .argument('[dir]', 'content directory (contains writedocs.json)', '.')
+  .action(async (dir) => {
+    const contentDir = path.resolve(process.cwd(), dir);
+    const configPath = path.join(contentDir, 'writedocs.json');
+    if (!fs.existsSync(configPath)) {
+      // Mesma mensagem que loadDocsConfig() ja da pro mesmo caso.
+      console.error(
+        `[writedocs] writedocs.json not found at ${configPath}. Run "writedocs init" to scaffold one.`
+      );
+      process.exit(1);
+    }
+
+    // O MESMO modulo que o build usa (via loadDocsConfig) e que a plataforma
+    // importa por `@writedocs/generator/config-schema` - e o que faz os tres
+    // reportarem os mesmos problemas com as mesmas palavras, em vez de cada um
+    // manter a sua copia do schema.
+    //
+    // Import dinamico porque isto e um `.ts` sendo carregado por node puro (sem
+    // o transform do Astro/Vite): funciona com o type stripping nativo do Node,
+    // estavel a partir do 22.18/23.6. O astro deste pacote ja exige >=22.12, mas
+    // entre 22.12 e 22.18 o import falharia com uma mensagem cifrada sobre
+    // "Unknown file extension .ts" - a mensagem abaixo diz o que fazer.
+    let validateDocsConfig;
+    let formatValidationIssues;
+    try {
+      ({ validateDocsConfig, formatValidationIssues } = await import('../src/lib/config-schema.ts'));
+    } catch (err) {
+      console.error(
+        `[writedocs] validate needs a Node that can load TypeScript directly (Node 22.18+ or 23.6+); this one is ${process.version}.`
+      );
+      console.error(`[writedocs] ${err.message}`);
+      process.exit(1);
+    }
+
+    const result = validateDocsConfig(fs.readFileSync(configPath, 'utf-8'));
+    if (result.ok) {
+      console.log(`[writedocs] ${configPath} is valid.`);
+      return;
+    }
+
+    // Mesmo formato que o build imprime num config invalido - mesmo texto,
+    // mesma ordem, montado pelo mesmo formatador.
+    console.error('[writedocs] writedocs.json failed validation:');
+    console.error(formatValidationIssues(result.issues));
+    process.exit(1);
+  });
+
+program
+  .command('init')
+  .description('Scaffold a writedocs.json and starter docs/ folder')
+  .argument('[dir]', 'directory to scaffold into', '.')
+  .action(async (dir) => {
+    await runInit({ targetDir: path.resolve(process.cwd(), dir) });
+  });
+
+program.parseAsync(process.argv).catch((err) => {
+  console.error(`[writedocs] ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -1,79 +1,80 @@
-{
-  "name": "@writedocs/generator",
-  "version": "0.1.0",
-  "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
-  "type": "module",
-  "bin": {
-    "writedocs": "./bin/writedocs.js"
-  },
-  "exports": {
-    "./components": "./src/components/index.ts"
-  },
-  "files": [
-    "bin",
-    "src",
-    "astro.config.mjs"
-  ],
-  "scripts": {
-    "dev": "node bin/writedocs.js dev",
-    "build": "node bin/writedocs.js build",
-    "init": "node bin/writedocs.js init"
-  },
-  "keywords": [
-    "docs",
-    "documentation",
-    "static-site-generator",
-    "mdx",
-    "astro"
-  ],
-  "homepage": "https://github.com/writedocs/writedocs#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/writedocs/writedocs.git"
-  },
-  "bugs": {
-    "url": "https://github.com/writedocs/writedocs/issues"
-  },
-  "author": "Gabriel Raeder",
-  "license": "ISC",
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@apidevtools/swagger-parser": "^12.1.0",
-    "@astrojs/markdown-remark": "7.2.2",
-    "@astrojs/mdx": "^7.0.5",
-    "@astrojs/react": "^6.0.2",
-    "@astrojs/sitemap": "^3.7.3",
-    "@iconify-json/bi": "^1.2.7",
-    "@iconify-json/fa6-brands": "^1.2.6",
-    "@iconify-json/fa6-solid": "^1.2.4",
-    "@iconify-json/heroicons": "^1.2.3",
-    "@iconify-json/ion": "^1.2.7",
-    "@iconify-json/lucide": "^1.2.116",
-    "@iconify-json/mdi": "^1.2.3",
-    "@iconify-json/ri": "^1.2.10",
-    "@iconify-json/simple-icons": "^1.2.89",
-    "@iconify-json/tabler": "^1.2.35",
-    "@shikijs/transformers": "^4.3.1",
-    "@tailwindcss/vite": "^4.3.2",
-    "astro": "^7.2.2",
-    "astro-icon": "^1.1.5",
-    "commander": "^15.0.0",
-    "dotenv": "^17.4.2",
-    "gray-matter": "^4.0.3",
-    "katex": "^0.16.47",
-    "mermaid": "^11.16.0",
-    "pagefind": "^1.5.2",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "rehype-katex": "^7.0.1",
-    "remark-math": "^6.0.0",
-    "shiki": "^4.3.1",
-    "tailwindcss": "^4.3.2",
-    "zod": "^4.4.3"
-  },
-  "engines": {
-    "node": ">=20.3.0"
-  }
-}
+{
+  "name": "@writedocs/generator",
+  "version": "0.2.0",
+  "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
+  "type": "module",
+  "bin": {
+    "writedocs": "./bin/writedocs.js"
+  },
+  "exports": {
+    "./components": "./src/components/index.ts",
+    "./config-schema": "./src/lib/config-schema.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "astro.config.mjs"
+  ],
+  "scripts": {
+    "dev": "node bin/writedocs.js dev",
+    "build": "node bin/writedocs.js build",
+    "init": "node bin/writedocs.js init"
+  },
+  "keywords": [
+    "docs",
+    "documentation",
+    "static-site-generator",
+    "mdx",
+    "astro"
+  ],
+  "homepage": "https://github.com/writedocs/writedocs#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/writedocs/writedocs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/writedocs/writedocs/issues"
+  },
+  "author": "Gabriel Raeder",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^12.1.0",
+    "@astrojs/markdown-remark": "7.2.2",
+    "@astrojs/mdx": "^7.0.5",
+    "@astrojs/react": "^6.0.2",
+    "@astrojs/sitemap": "^3.7.3",
+    "@iconify-json/bi": "^1.2.7",
+    "@iconify-json/fa6-brands": "^1.2.6",
+    "@iconify-json/fa6-solid": "^1.2.4",
+    "@iconify-json/heroicons": "^1.2.3",
+    "@iconify-json/ion": "^1.2.7",
+    "@iconify-json/lucide": "^1.2.116",
+    "@iconify-json/mdi": "^1.2.3",
+    "@iconify-json/ri": "^1.2.10",
+    "@iconify-json/simple-icons": "^1.2.89",
+    "@iconify-json/tabler": "^1.2.35",
+    "@shikijs/transformers": "^4.3.1",
+    "@tailwindcss/vite": "^4.3.2",
+    "astro": "7.2.2",
+    "astro-icon": "^1.1.5",
+    "commander": "^15.0.0",
+    "dotenv": "^17.4.2",
+    "gray-matter": "^4.0.3",
+    "katex": "^0.16.47",
+    "mermaid": "^11.16.0",
+    "pagefind": "^1.5.2",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "rehype-katex": "^7.0.1",
+    "remark-math": "^6.0.0",
+    "shiki": "^4.3.1",
+    "tailwindcss": "^4.3.2",
+    "zod": "^4.4.3"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  }
+}