@rawsql-ts/ddl-docs-vitepress 0.2.1

package/README.md

@@ -0,0 +1,105 @@
+# @rawsql-ts/ddl-docs-vitepress
+
+A scaffold generator for VitePress-based database schema documentation sites.
+
+This package provides the `ddl-docs-vitepress init` command, which creates a ready-to-use project template that:
+
+- reads SQL files from `ddl/`
+- generates Markdown docs via `@rawsql-ts/ddl-docs-cli`
+- serves/builds a VitePress site from `docs/`
+
+## Generated project structure
+
+```
+my-db-docs/
+├── .github/workflows/deploy-docs.yml   # GitHub Pages deploy workflow
+├── .gitignore
+├── ddl/.gitkeep                        # Place your .sql files here
+├── docs/
+│   ├── index.md
+│   └── .vitepress/
+│       ├── config.mts
+│       └── theme/
+│           ├── custom.css
+│           └── index.ts
+├── package.json
+└── scripts/run-generate.cjs            # Calls ddl-docs-cli to generate Markdown
+```
+
+## Create a scaffold project
+
+```bash
+npx @rawsql-ts/ddl-docs-vitepress init my-db-docs
+cd my-db-docs
+npm install
+```
+
+### Safe-by-default init behavior
+
+- If target directory does not exist: scaffold is created.
+- If target directory exists and is empty: scaffold is created.
+- If target directory exists and is not empty: command fails by default.
+- Use `--force` to overwrite template paths in a non-empty directory.
+- `--force` is overwrite-only. It does not remove non-template files.
+- Use `--force --clean` to remove non-template files before scaffolding.
+
+```bash
+npx @rawsql-ts/ddl-docs-vitepress init existing-dir --force
+npx @rawsql-ts/ddl-docs-vitepress init existing-dir --force --clean
+```
+
+Warning: `--clean` removes non-template files and directories in the target path.
+
+### Help
+
+```bash
+npx @rawsql-ts/ddl-docs-vitepress --help
+npx @rawsql-ts/ddl-docs-vitepress help
+npx @rawsql-ts/ddl-docs-vitepress init --help
+```
+
+## Use the generated scaffold project
+
+In the generated project:
+
+1. Put your `.sql` files under `ddl/`.
+   The build script applies `--filter-pg-dump` automatically, so `pg_dump` output can be used directly — statements such as `SET`, `ALTER ... OWNER TO`, and `SELECT pg_catalog.*` are filtered out before parsing.
+2. Start local development:
+
+```bash
+npm run dev
+```
+
+3. Build static docs:
+
+```bash
+npm run build
+```
+
+4. Preview the built site:
+
+```bash
+npm run preview
+```
+
+### GitHub Pages deployment
+
+The scaffold includes `.github/workflows/deploy-docs.yml` which automatically builds and deploys docs to GitHub Pages on pushes to `main` that touch `ddl/` or `docs/.vitepress/`. The workflow sets `VITEPRESS_BASE` from the repository name.
+
+To enable it, go to your repository's **Settings > Pages** and set the source to **GitHub Actions**.
+
+### `VITEPRESS_BASE` for subpath hosting
+
+The scaffold template uses `process.env.VITEPRESS_BASE ?? '/'` in `docs/.vitepress/config.mts`.
+Set `VITEPRESS_BASE` when deploying under a subpath (for example GitHub Pages):
+
+```bash
+VITEPRESS_BASE=/my-repo/ npm run build
+```
+
+## Scripts in this package (maintainer note)
+
+In `packages/ddl-docs-vitepress` itself:
+
+- `pnpm build` compiles this CLI package with `tsc`.
+- It does **not** build the generated VitePress docs site.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function runCli(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,253 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCli = runCli;
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const TEMPLATE_GITIGNORE = 'gitignore';
+const TARGET_GITIGNORE = '.gitignore';
+const CLEAN_PREVIEW_LIMIT = 5;
+async function runCli(argv) {
+    const [command, ...rest] = argv;
+    if (!command || command === '--help' || command === '-h') {
+        printGlobalHelp();
+        return;
+    }
+    if (command === 'help') {
+        const target = rest[0];
+        if (target === 'init') {
+            printInitHelp();
+            return;
+        }
+        if (target) {
+            throw new Error(`Unknown command for help: ${target}`);
+        }
+        printGlobalHelp();
+        return;
+    }
+    if (command === 'init') {
+        await runInit(rest);
+        return;
+    }
+    throw new Error(`Unknown command: ${command}`);
+}
+async function runInit(args) {
+    let targetDir = '.';
+    let force = false;
+    let clean = false;
+    let targetProvided = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--help' || arg === '-h') {
+            printInitHelp();
+            return;
+        }
+        if (arg === '--force') {
+            force = true;
+            continue;
+        }
+        if (arg === '--clean') {
+            clean = true;
+            continue;
+        }
+        if (!arg.startsWith('--')) {
+            if (targetProvided) {
+                throw new Error(`Only one target directory is allowed. Received extra argument: ${arg}`);
+            }
+            targetDir = arg;
+            targetProvided = true;
+            continue;
+        }
+        throw new Error(`Unknown option for init: ${arg}`);
+    }
+    if (clean && !force) {
+        throw new Error('Option --clean requires --force. Use: init <targetDir> --force --clean');
+    }
+    const resolvedTarget = node_path_1.default.resolve(targetDir);
+    const templatesDir = node_path_1.default.join(__dirname, '..', 'templates');
+    if (!node_fs_1.default.existsSync(templatesDir)) {
+        throw new Error(`Templates directory not found: ${templatesDir}`);
+    }
+    const layout = collectTemplateLayout(templatesDir);
+    if (node_fs_1.default.existsSync(resolvedTarget)) {
+        if (!node_fs_1.default.statSync(resolvedTarget).isDirectory()) {
+            throw new Error(`Target path is not a directory: ${resolvedTarget}`);
+        }
+        // Protect existing projects from accidental overwrite unless --force is explicit.
+        const existingEntries = node_fs_1.default.readdirSync(resolvedTarget);
+        if (existingEntries.length > 0 && !force) {
+            throw new Error(`Target directory is not empty: ${resolvedTarget}. Use --force to overwrite existing files.`);
+        }
+    }
+    else {
+        node_fs_1.default.mkdirSync(resolvedTarget, { recursive: true });
+    }
+    const existingEntries = node_fs_1.default.readdirSync(resolvedTarget);
+    let deleted = 0;
+    if (clean && existingEntries.length > 0) {
+        const removedPaths = pruneNonTemplatePaths(resolvedTarget, layout);
+        deleted = removedPaths.length;
+    }
+    const { created, overwritten } = applyTemplate(resolvedTarget, templatesDir, layout);
+    console.log(`Scaffold created at: ${resolvedTarget}`);
+    console.log(`Summary: created=${created}, overwritten=${overwritten}, deleted=${deleted}`);
+    console.log('');
+    console.log('Next steps:');
+    console.log(`  cd ${targetDir}`);
+    console.log('  npm install');
+    console.log('  # Add your .sql files to ddl/');
+    console.log('  npm run dev');
+}
+function printGlobalHelp() {
+    console.log(`ddl-docs-vitepress <command> [options]
+
+Commands:
+  init [targetDir]   Scaffold a new DDL docs VitePress project (default: current directory)
+  help [command]     Show global help or command help
+
+Options:
+  --help, -h         Show this help message
+
+Init options:
+  --force            Overwrite template output paths in a non-empty directory (no deletion)
+  --clean            Delete non-template files before scaffolding (requires --force)
+
+Examples:
+  ddl-docs-vitepress init my-db-docs
+  ddl-docs-vitepress init existing-dir --force
+  ddl-docs-vitepress init existing-dir --force --clean
+  ddl-docs-vitepress help init
+`);
+}
+function printInitHelp() {
+    console.log(`ddl-docs-vitepress init [targetDir] [options]
+
+Options:
+  --force            Overwrite template output paths in a non-empty directory (does not delete other files)
+  --clean            Delete non-template files before scaffolding (requires --force)
+  --help, -h         Show init help
+
+Examples:
+  ddl-docs-vitepress init docs-site
+  ddl-docs-vitepress init docs-site --force
+  ddl-docs-vitepress init docs-site --force --clean
+`);
+}
+function collectTemplateLayout(templatesDir) {
+    const files = [];
+    const directories = new Set();
+    walkTemplateTree(templatesDir, '', files, directories);
+    const mappedFiles = files.map(mapTemplateRelativePath);
+    const mappedDirectories = Array.from(directories).map(mapTemplateRelativePath);
+    // Include parent directories for mapped files such as ".gitignore".
+    for (const filePath of mappedFiles) {
+        let current = node_path_1.default.dirname(filePath);
+        while (current && current !== '.') {
+            mappedDirectories.push(current);
+            current = node_path_1.default.dirname(current);
+        }
+    }
+    return {
+        files: mappedFiles,
+        directories: Array.from(new Set(mappedDirectories)),
+    };
+}
+function walkTemplateTree(rootDir, currentRelative, files, directories) {
+    const currentDir = currentRelative ? node_path_1.default.join(rootDir, currentRelative) : rootDir;
+    const entries = node_fs_1.default.readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const relativePath = currentRelative ? node_path_1.default.join(currentRelative, entry.name) : entry.name;
+        if (entry.isDirectory()) {
+            directories.add(relativePath);
+            walkTemplateTree(rootDir, relativePath, files, directories);
+            continue;
+        }
+        files.push(relativePath);
+    }
+}
+function mapTemplateRelativePath(relativePath) {
+    if (relativePath === TEMPLATE_GITIGNORE) {
+        return TARGET_GITIGNORE;
+    }
+    return relativePath;
+}
+function collectTargetEntries(targetDir) {
+    const entries = [];
+    walkTargetTree(targetDir, '', entries);
+    return entries;
+}
+function walkTargetTree(rootDir, currentRelative, entries) {
+    const currentDir = currentRelative ? node_path_1.default.join(rootDir, currentRelative) : rootDir;
+    const currentEntries = node_fs_1.default.readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of currentEntries) {
+        const relativePath = currentRelative ? node_path_1.default.join(currentRelative, entry.name) : entry.name;
+        if (entry.isDirectory()) {
+            entries.push({ relativePath, isDirectory: true });
+            walkTargetTree(rootDir, relativePath, entries);
+            continue;
+        }
+        entries.push({ relativePath, isDirectory: false });
+    }
+}
+function pruneNonTemplatePaths(targetDir, layout) {
+    const expectedPaths = new Set([...layout.files, ...layout.directories]);
+    const existingEntries = collectTargetEntries(targetDir);
+    const pathsToDelete = existingEntries
+        .filter((entry) => shouldDeleteEntry(entry, expectedPaths))
+        .sort((left, right) => getPathDepth(right.relativePath) - getPathDepth(left.relativePath))
+        .map((entry) => entry.relativePath);
+    console.log(`Clean mode: removing ${pathsToDelete.length} non-template path(s) from ${targetDir}`);
+    for (const relativePath of pathsToDelete.slice(0, CLEAN_PREVIEW_LIMIT)) {
+        console.log(`  - ${relativePath}`);
+    }
+    if (pathsToDelete.length > CLEAN_PREVIEW_LIMIT) {
+        console.log(`  ... and ${pathsToDelete.length - CLEAN_PREVIEW_LIMIT} more`);
+    }
+    for (const relativePath of pathsToDelete) {
+        node_fs_1.default.rmSync(node_path_1.default.join(targetDir, relativePath), { recursive: true, force: true });
+    }
+    return pathsToDelete;
+}
+function shouldDeleteEntry(entry, expectedPaths) {
+    if (expectedPaths.has(entry.relativePath)) {
+        return false;
+    }
+    // Keep parent directories when expected descendants exist under them.
+    if (entry.isDirectory) {
+        const directoryPrefix = `${entry.relativePath}${node_path_1.default.sep}`;
+        for (const expectedPath of expectedPaths) {
+            if (expectedPath.startsWith(directoryPrefix)) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+function getPathDepth(relativePath) {
+    return relativePath.split(node_path_1.default.sep).length;
+}
+function applyTemplate(targetDir, templatesDir, layout) {
+    let created = 0;
+    let overwritten = 0;
+    const sortedDirectories = [...layout.directories].sort((left, right) => left.length - right.length);
+    for (const directory of sortedDirectories) {
+        const targetDirectory = node_path_1.default.join(targetDir, directory);
+        node_fs_1.default.mkdirSync(targetDirectory, { recursive: true });
+    }
+    for (const relativePath of layout.files) {
+        const templateRelativePath = relativePath === TARGET_GITIGNORE ? TEMPLATE_GITIGNORE : relativePath;
+        const sourcePath = node_path_1.default.join(templatesDir, templateRelativePath);
+        const targetPath = node_path_1.default.join(targetDir, relativePath);
+        if (node_fs_1.default.existsSync(targetPath)) {
+            overwritten += 1;
+        }
+        else {
+            created += 1;
+        }
+        node_fs_1.default.copyFileSync(sourcePath, targetPath);
+    }
+    return { created, overwritten };
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cli_1 = require("./cli");
+(0, cli_1.runCli)(process.argv.slice(2)).catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAEA,+BAA+B;AAE/B,IAAA,YAAM,EAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IAC5C,OAAO,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC9D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@rawsql-ts/ddl-docs-vitepress",
+  "version": "0.2.1",
+  "description": "Scaffold generator for VitePress-based DB schema docs powered by ddl-docs-cli",
+  "main": "dist/index.js",
+  "bin": {
+    "ddl-docs-vitepress": "dist/index.js"
+  },
+  "scripts": {
+    "prepack": "node ./scripts/prepack.cjs",
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run packages/ddl-docs-vitepress/tests",
+    "generate": "node ./scripts/run-generate.cjs",
+    "dev": "pnpm generate && vitepress dev docs",
+    "preview": "vitepress preview docs"
+  },
+  "keywords": [
+    "rawsql-ts",
+    "ddl",
+    "vitepress",
+    "docs",
+    "scaffold",
+    "cli"
+  ],
+  "author": "msugiura",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "dependencies": {
+    "@rawsql-ts/ddl-docs-cli": "workspace:^"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "typescript": "^5.8.2",
+    "vitest": "^4.0.7"
+  }
+}

package/templates/.github/workflows/deploy-docs.yml

@@ -0,0 +1,53 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'ddl/**'
+      - 'docs/**'
+      - 'docs/.vitepress/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate and build docs
+        env:
+          VITEPRESS_BASE: /${{ github.event.repository.name }}/
+        run: npm run build
+
+      - uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e

package/templates/docs/.vitepress/config.mts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: 'DB Schema Docs',
+  description: 'Database schema documentation generated from DDL',
+  base: process.env.VITEPRESS_BASE ?? '/',
+  srcDir: '.',
+  themeConfig: {
+    search: { provider: 'local' },
+    aside: false,
+  },
+})

package/templates/docs/.vitepress/theme/custom.css

@@ -0,0 +1,13 @@
+.VPDoc .container,
+.VPDoc .content-container,
+.VPDoc .content {
+  max-width: none !important;
+  width: 100% !important;
+}
+
+.VPNavBar .wrapper,
+.VPNavBar .container {
+  max-width: none !important;
+  margin-left: 0 !important;
+  padding-left: 16px !important;
+}

package/templates/docs/.vitepress/theme/index.ts

@@ -0,0 +1,4 @@
+import DefaultTheme from 'vitepress/theme'
+import './custom.css'
+
+export default DefaultTheme

package/templates/docs/index.md

@@ -0,0 +1,31 @@
+---
+layout: home
+
+hero:
+  name: DB Schema Docs
+  text: Database schema documentation
+  tagline: Generated automatically from DDL files
+  actions:
+    - theme: brand
+      text: Browse Tables
+      link: /tables/
+
+features:
+  - title: DDL-driven
+    details: Place your .sql files in the ddl/ directory and documentation is generated automatically.
+  - title: Always up to date
+    details: Run npm run dev or npm run build to regenerate docs from the latest DDL.
+  - title: Searchable
+    details: Full-text search across all table and column documentation.
+---
+
+## Getting Started
+
+1. Add your DDL files to the `ddl/` directory.
+2. Run `npm run dev` to start the documentation site.
+
+```bash
+npm run dev
+```
+
+The `generate` step runs automatically before the dev server or build starts.

package/templates/gitignore

@@ -0,0 +1,4 @@
+docs/tables/
+docs/.vitepress/dist/
+docs/.vitepress/cache/
+node_modules/

package/templates/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "db-docs",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "generate": "node ./scripts/run-generate.cjs",
+    "dev": "node ./scripts/run-generate.cjs && vitepress dev docs",
+    "build": "node ./scripts/run-generate.cjs && vitepress build docs",
+    "preview": "vitepress preview docs"
+  },
+  "devDependencies": {
+    "@rawsql-ts/ddl-docs-cli": "^0.1.0",
+    "vitepress": "^1.6.4"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/templates/scripts/run-generate.cjs

@@ -0,0 +1,39 @@
+const { readdirSync, existsSync } = require("node:fs");
+const { spawnSync } = require("node:child_process");
+
+const ddlDir = "ddl";
+
+let cliEntry;
+try {
+  cliEntry = require.resolve("@rawsql-ts/ddl-docs-cli");
+} catch {
+  console.error("@rawsql-ts/ddl-docs-cli is not installed. Run: npm install");
+  process.exit(1);
+}
+
+const hasSqlInputs =
+  existsSync(ddlDir) &&
+  readdirSync(ddlDir, { recursive: true }).some(
+    (entry) => typeof entry === "string" && entry.endsWith(".sql"),
+  );
+
+if (!hasSqlInputs) {
+  console.log("No SQL files found in ddl/. Skipping ddl-docs generation.");
+  process.exit(0);
+}
+
+const args = [
+  cliEntry,
+  "generate",
+  "--ddl-dir",
+  "ddl",
+  "--out-dir",
+  "docs/tables",
+  "--label-separator",
+  " :",
+  // Accept pg_dump output directly by filtering admin-only statements first.
+  "--filter-pg-dump",
+];
+
+const result = spawnSync(process.execPath, args, { stdio: "inherit" });
+process.exit(result.status ?? 1);