create-eziwiki 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# create-eziwiki
+
+Scaffold a new [eziwiki](https://github.com/i3months/eziwiki) documentation site.
+
+```bash
+npx create-eziwiki my-docs
+cd my-docs
+npm install
+npm run dev
+```
+
+## What you get
+
+A complete, static-exportable wiki:
+
+- **Pages from files** — every Markdown file under `content/` is published, no registration step
+- **Search** — full-text over titles, headings, and body, with a ⌘K palette; runs entirely in the browser
+- **Contents rail** with scroll tracking, generated at build time
+- **Wiki links** — `[[page]]` resolves by path, file name, or title
+- **Backlinks** on every page, and a **graph view** of how pages connect
+- **Build-time rendering** — Markdown is compiled and syntax-highlighted during the build, so no parser ships to the browser
+- Dark mode, maths, GFM, SEO metadata, sitemap
+
+## Layout
+
+```
+my-docs/
+├── content/           # Your Markdown. Folders become sidebar sections.
+│   └── _meta.json     # Optional per-folder name, order, colour
+├── payload/config.ts  # Title, theme, URL strategy, optional navigation
+├── public/            # Static assets
+└── app/ lib/ components/   # The engine — edit only if you want to
+```
+
+## Development
+
+The template is generated from the eziwiki repository rather than kept as a
+separate copy, so it never drifts from the tested source:
+
+```bash
+npm run build:template   # in the eziwiki repo, regenerates ./template
+```
+
+## Licence
+
+MIT

package/bin/create-eziwiki.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { scaffold, validateProjectName } from '../lib/scaffold.mjs';
+
+/**
+ * `create-eziwiki` command line entry point.
+ *
+ * Deliberately non-interactive: it takes a name, writes a project, and prints
+ * the next commands. Anything it could prompt for is a value the user can
+ * change in `payload/config.ts` afterwards, and a prompt would only get in the
+ * way of scripted use.
+ */
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = path.resolve(HERE, '..', 'template');
+
+const HELP = `
+  create-eziwiki — scaffold a new eziwiki documentation site
+
+  Usage
+    $ npx create-eziwiki <project-name>
+
+  Options
+    -h, --help     Show this message
+    -v, --version  Show the version
+
+  Example
+    $ npx create-eziwiki my-docs
+    $ cd my-docs
+    $ npm install
+    $ npm run dev
+`;
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('-h') || args.includes('--help') || args.length === 0) {
+    console.log(HELP);
+    process.exit(args.length === 0 ? 1 : 0);
+  }
+
+  if (args.includes('-v') || args.includes('--version')) {
+    console.log(process.env.npm_package_version ?? 'unknown');
+    process.exit(0);
+  }
+
+  const projectName = args.find((arg) => !arg.startsWith('-'));
+  const check = validateProjectName(projectName);
+
+  if (!check.valid) {
+    console.error(`\n  ✖ ${check.problem}\n`);
+    process.exit(1);
+  }
+
+  const targetDir = path.resolve(process.cwd(), projectName);
+
+  let result;
+  try {
+    result = scaffold({ templateDir: TEMPLATE_DIR, targetDir, projectName });
+  } catch (error) {
+    console.error(`\n  ✖ ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+  }
+
+  const relative = path.relative(process.cwd(), targetDir) || '.';
+
+  console.log(`
+  ✔ Created ${projectName} (${result.files} files)
+
+  Next steps:
+
+    cd ${relative}
+    npm install
+    npm run dev
+
+  Then edit content/ to write pages, and payload/config.ts for the title,
+  navigation, and theme.
+`);
+}
+
+main();

package/lib/scaffold.mjs

@@ -0,0 +1,230 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Scaffolding logic for `create-eziwiki`.
+ *
+ * Kept separate from the CLI entry point so the decisions — what a valid
+ * project name is, how the template's package.json is rewritten, which files
+ * get renamed on the way out — can be tested without spawning a process or
+ * touching a real project directory.
+ */
+
+/**
+ * Files that npm refuses to publish under their real name, and what they must
+ * be restored to on disk.
+ *
+ * npm silently excludes `.gitignore` from a package tarball and renames
+ * `.npmrc`, so the template ships them under safe names.
+ */
+export const RENAME_ON_COPY = {
+  gitignore: '.gitignore',
+  npmrc: '.npmrc',
+  'eslintrc.js': '.eslintrc.js',
+  prettierrc: '.prettierrc',
+  prettierignore: '.prettierignore',
+  eslintignore: '.eslintignore',
+};
+
+/** Directory names never copied out of the template. */
+export const SKIP_DIRS = new Set(['node_modules', '.next', 'out', '.git']);
+
+/**
+ * Validates a project directory name.
+ *
+ * The name becomes both a directory and the `name` field of a package.json, so
+ * it has to satisfy npm's rules; rejecting it up front is friendlier than
+ * letting `npm install` fail later with a less obvious message.
+ *
+ * @param {string} name - Proposed project name
+ * @returns {{ valid: boolean, problem?: string }} Validation outcome
+ *
+ * @example
+ * validateProjectName('my-wiki'); // { valid: true }
+ * validateProjectName('My Wiki'); // { valid: false, problem: '...' }
+ */
+export function validateProjectName(name) {
+  if (!name || !name.trim()) {
+    return { valid: false, problem: 'Project name is required.' };
+  }
+
+  if (name.length > 214) {
+    return { valid: false, problem: 'Project name must be 214 characters or fewer.' };
+  }
+
+  if (name.startsWith('.') || name.startsWith('_')) {
+    return { valid: false, problem: 'Project name cannot start with "." or "_".' };
+  }
+
+  if (name !== name.toLowerCase()) {
+    return { valid: false, problem: 'Project name must be lowercase.' };
+  }
+
+  if (!/^[a-z0-9-~][a-z0-9._~-]*$/.test(name)) {
+    return {
+      valid: false,
+      problem: 'Project name may only contain lowercase letters, digits, "-", "_", "." and "~".',
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Rewrites the template's package.json for a freshly created project.
+ *
+ * The new project is the user's own, so anything identifying it as the eziwiki
+ * repository — the name, the repository link, the published-package fields — is
+ * replaced or dropped rather than inherited.
+ *
+ * @param {object} pkg - Parsed template package.json
+ * @param {string} projectName - Name for the new project
+ * @returns {object} The rewritten manifest
+ */
+export function buildProjectPackageJson(pkg, projectName) {
+  const next = {
+    ...pkg,
+    name: projectName,
+    version: '0.1.0',
+    private: true,
+    description: `Documentation site built with eziwiki`,
+  };
+
+  // Fields that only make sense for the source repository.
+  delete next.repository;
+  delete next.homepage;
+  delete next.bugs;
+  delete next.bin;
+  delete next.files;
+  delete next.publishConfig;
+  delete next.workspaces;
+
+  return next;
+}
+
+/**
+ * Whether a directory can be used as the target for a new project.
+ *
+ * An existing but empty directory is fine — people often `mkdir` first — while
+ * one with files in it is refused, because overwriting someone's work is not
+ * something a scaffolder should decide on their behalf.
+ *
+ * @param {string} target - Absolute path to the intended project directory
+ * @returns {{ ok: boolean, problem?: string }} Whether scaffolding may proceed
+ */
+export function checkTarget(target) {
+  if (!fs.existsSync(target)) return { ok: true };
+
+  const stat = fs.statSync(target);
+  if (!stat.isDirectory()) {
+    return { ok: false, problem: `${target} exists and is not a directory.` };
+  }
+
+  const entries = fs.readdirSync(target).filter((entry) => entry !== '.git');
+  if (entries.length > 0) {
+    return { ok: false, problem: `${target} is not empty.` };
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Maps a template file name to the name it takes in the created project.
+ *
+ * @param {string} name - File name inside the template
+ * @returns {string} Name to write
+ */
+export function targetFileName(name) {
+  return RENAME_ON_COPY[name] ?? name;
+}
+
+/**
+ * Recursively copies the template into a target directory.
+ *
+ * @param {string} from - Template directory
+ * @param {string} to - Destination directory
+ * @returns {number} Number of files written
+ */
+export function copyTemplate(from, to) {
+  let written = 0;
+
+  fs.mkdirSync(to, { recursive: true });
+
+  for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+    if (SKIP_DIRS.has(entry.name)) continue;
+
+    const source = path.join(from, entry.name);
+    const destination = path.join(to, targetFileName(entry.name));
+
+    if (entry.isDirectory()) {
+      written += copyTemplate(source, destination);
+    } else {
+      fs.copyFileSync(source, destination);
+      written += 1;
+    }
+  }
+
+  return written;
+}
+
+/**
+ * Creates a new eziwiki project from the template.
+ *
+ * @param {object} options
+ * @param {string} options.templateDir - Directory holding the template
+ * @param {string} options.targetDir - Directory to create the project in
+ * @param {string} options.projectName - Name for the project
+ * @returns {{ files: number }} Summary of what was written
+ * @throws {Error} If the target is unusable or the template is missing
+ */
+export function scaffold({ templateDir, targetDir, projectName }) {
+  if (!fs.existsSync(templateDir)) {
+    throw new Error(
+      `Template not found at ${templateDir}. ` +
+        'If you are running from a clone, build it first with `npm run build:template`.',
+    );
+  }
+
+  const target = checkTarget(targetDir);
+  if (!target.ok) throw new Error(target.problem);
+
+  const files = copyTemplate(templateDir, targetDir);
+
+  const manifestPath = path.join(targetDir, 'package.json');
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+
+  fs.writeFileSync(
+    manifestPath,
+    `${JSON.stringify(buildProjectPackageJson(manifest, projectName), null, 2)}\n`,
+    'utf-8',
+  );
+
+  renameLockfileRoot(targetDir, projectName);
+
+  return { files };
+}
+
+/**
+ * Points the shipped lockfile at the new project's name.
+ *
+ * npm would otherwise notice the mismatch on first install and rewrite the
+ * lockfile, producing a spurious diff in the user's very first commit.
+ *
+ * @param {string} targetDir - Project directory
+ * @param {string} projectName - Name the project was created with
+ */
+export function renameLockfileRoot(targetDir, projectName) {
+  const lockPath = path.join(targetDir, 'package-lock.json');
+  if (!fs.existsSync(lockPath)) return;
+
+  const lock = JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+
+  lock.name = projectName;
+  lock.version = '0.1.0';
+  if (lock.packages?.['']) {
+    lock.packages[''].name = projectName;
+    lock.packages[''].version = '0.1.0';
+  }
+
+  fs.writeFileSync(lockPath, `${JSON.stringify(lock, null, 2)}\n`, 'utf-8');
+}

package/lib/scaffold.test.mjs

@@ -0,0 +1,270 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import {
+  buildProjectPackageJson,
+  checkTarget,
+  copyTemplate,
+  scaffold,
+  targetFileName,
+  validateProjectName,
+} from './scaffold.mjs';
+
+let workdir;
+
+beforeEach(() => {
+  workdir = fs.mkdtempSync(path.join(os.tmpdir(), 'eziwiki-scaffold-'));
+});
+
+afterEach(() => {
+  fs.rmSync(workdir, { recursive: true, force: true });
+});
+
+/** Writes a minimal fake template into a directory. */
+function makeTemplate(dir) {
+  fs.mkdirSync(path.join(dir, 'content'), { recursive: true });
+  fs.mkdirSync(path.join(dir, 'node_modules'), { recursive: true });
+
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({
+      name: 'my-wiki',
+      version: '9.9.9',
+      description: 'template',
+      repository: 'github:someone/eziwiki',
+      bin: { thing: './x.js' },
+      files: ['bin'],
+      dependencies: { next: '^14.0.0' },
+    }),
+  );
+  fs.writeFileSync(path.join(dir, 'gitignore'), 'node_modules\n');
+  fs.writeFileSync(path.join(dir, 'content', 'intro.md'), '# Hi\n');
+  fs.writeFileSync(path.join(dir, 'node_modules', 'junk.js'), 'nope');
+
+  return dir;
+}
+
+describe('validateProjectName', () => {
+  it('accepts ordinary names', () => {
+    for (const name of ['my-wiki', 'docs', 'a1', 'my.wiki', 'my_wiki']) {
+      expect(validateProjectName(name).valid, name).toBe(true);
+    }
+  });
+
+  it('rejects an empty name', () => {
+    expect(validateProjectName('').valid).toBe(false);
+    expect(validateProjectName('   ').valid).toBe(false);
+    expect(validateProjectName(undefined).valid).toBe(false);
+  });
+
+  it('rejects uppercase, which npm does not allow', () => {
+    expect(validateProjectName('MyWiki').valid).toBe(false);
+  });
+
+  it('rejects spaces and other illegal characters', () => {
+    expect(validateProjectName('my wiki').valid).toBe(false);
+    expect(validateProjectName('my/wiki').valid).toBe(false);
+  });
+
+  it('rejects names starting with a dot or underscore', () => {
+    expect(validateProjectName('.hidden').valid).toBe(false);
+    expect(validateProjectName('_private').valid).toBe(false);
+  });
+
+  it('rejects names longer than npm permits', () => {
+    expect(validateProjectName('a'.repeat(215)).valid).toBe(false);
+  });
+
+  it('explains why it refused', () => {
+    expect(validateProjectName('My Wiki').problem).toBeTruthy();
+  });
+});
+
+describe('buildProjectPackageJson', () => {
+  const template = {
+    name: 'my-wiki',
+    version: '9.9.9',
+    repository: 'github:someone/eziwiki',
+    homepage: 'https://example.com',
+    bugs: 'https://example.com/issues',
+    bin: { x: './x.js' },
+    files: ['bin'],
+    publishConfig: { access: 'public' },
+    scripts: { build: 'next build' },
+    dependencies: { next: '^14.0.0' },
+  };
+
+  it('uses the requested project name and a fresh version', () => {
+    const pkg = buildProjectPackageJson(template, 'my-docs');
+
+    expect(pkg.name).toBe('my-docs');
+    expect(pkg.version).toBe('0.1.0');
+  });
+
+  it('marks the project private so it is never published by accident', () => {
+    expect(buildProjectPackageJson(template, 'my-docs').private).toBe(true);
+  });
+
+  it('drops fields belonging to the source repository', () => {
+    const pkg = buildProjectPackageJson(template, 'my-docs');
+
+    for (const field of ['repository', 'homepage', 'bugs', 'bin', 'files', 'publishConfig']) {
+      expect(pkg, field).not.toHaveProperty(field);
+    }
+  });
+
+  it('keeps scripts and dependencies', () => {
+    const pkg = buildProjectPackageJson(template, 'my-docs');
+
+    expect(pkg.scripts).toEqual({ build: 'next build' });
+    expect(pkg.dependencies).toEqual({ next: '^14.0.0' });
+  });
+
+  it('does not mutate the input', () => {
+    const before = JSON.stringify(template);
+    buildProjectPackageJson(template, 'my-docs');
+
+    expect(JSON.stringify(template)).toBe(before);
+  });
+});
+
+describe('checkTarget', () => {
+  it('accepts a path that does not exist', () => {
+    expect(checkTarget(path.join(workdir, 'new')).ok).toBe(true);
+  });
+
+  it('accepts an existing empty directory', () => {
+    const dir = path.join(workdir, 'empty');
+    fs.mkdirSync(dir);
+
+    expect(checkTarget(dir).ok).toBe(true);
+  });
+
+  it('accepts a directory containing only a git repo', () => {
+    const dir = path.join(workdir, 'gitonly');
+    fs.mkdirSync(path.join(dir, '.git'), { recursive: true });
+
+    expect(checkTarget(dir).ok).toBe(true);
+  });
+
+  it('refuses a directory with files in it', () => {
+    const dir = path.join(workdir, 'busy');
+    fs.mkdirSync(dir);
+    fs.writeFileSync(path.join(dir, 'keep.txt'), 'mine');
+
+    const result = checkTarget(dir);
+    expect(result.ok).toBe(false);
+    expect(result.problem).toContain('not empty');
+  });
+
+  it('refuses a path that is a file', () => {
+    const file = path.join(workdir, 'file.txt');
+    fs.writeFileSync(file, 'x');
+
+    expect(checkTarget(file).ok).toBe(false);
+  });
+});
+
+describe('targetFileName', () => {
+  it('restores names npm strips from a tarball', () => {
+    expect(targetFileName('gitignore')).toBe('.gitignore');
+    expect(targetFileName('npmrc')).toBe('.npmrc');
+    expect(targetFileName('prettierrc')).toBe('.prettierrc');
+  });
+
+  it('leaves ordinary names alone', () => {
+    expect(targetFileName('package.json')).toBe('package.json');
+  });
+});
+
+describe('copyTemplate', () => {
+  it('copies files and directories', () => {
+    const template = makeTemplate(path.join(workdir, 'template'));
+    const target = path.join(workdir, 'out');
+
+    copyTemplate(template, target);
+
+    expect(fs.existsSync(path.join(target, 'package.json'))).toBe(true);
+    expect(fs.existsSync(path.join(target, 'content', 'intro.md'))).toBe(true);
+  });
+
+  it('renames dotfiles on the way out', () => {
+    const template = makeTemplate(path.join(workdir, 'template'));
+    const target = path.join(workdir, 'out');
+
+    copyTemplate(template, target);
+
+    expect(fs.existsSync(path.join(target, '.gitignore'))).toBe(true);
+    expect(fs.existsSync(path.join(target, 'gitignore'))).toBe(false);
+  });
+
+  it('never copies node_modules', () => {
+    const template = makeTemplate(path.join(workdir, 'template'));
+    const target = path.join(workdir, 'out');
+
+    copyTemplate(template, target);
+
+    expect(fs.existsSync(path.join(target, 'node_modules'))).toBe(false);
+  });
+});
+
+describe('scaffold', () => {
+  it('creates a working project directory', () => {
+    const templateDir = makeTemplate(path.join(workdir, 'template'));
+    const targetDir = path.join(workdir, 'my-docs');
+
+    const result = scaffold({ templateDir, targetDir, projectName: 'my-docs' });
+
+    expect(result.files).toBeGreaterThan(0);
+    expect(fs.existsSync(path.join(targetDir, 'content', 'intro.md'))).toBe(true);
+  });
+
+  it('rewrites the manifest for the new project', () => {
+    const templateDir = makeTemplate(path.join(workdir, 'template'));
+    const targetDir = path.join(workdir, 'my-docs');
+
+    scaffold({ templateDir, targetDir, projectName: 'my-docs' });
+
+    const pkg = JSON.parse(fs.readFileSync(path.join(targetDir, 'package.json'), 'utf-8'));
+    expect(pkg.name).toBe('my-docs');
+    expect(pkg.private).toBe(true);
+    expect(pkg).not.toHaveProperty('repository');
+  });
+
+  it('points a shipped lockfile at the new name', () => {
+    const templateDir = makeTemplate(path.join(workdir, 'template'));
+    fs.writeFileSync(
+      path.join(templateDir, 'package-lock.json'),
+      JSON.stringify({ name: 'my-wiki', version: '9.9.9', packages: { '': { name: 'my-wiki' } } }),
+    );
+
+    const targetDir = path.join(workdir, 'my-docs');
+    scaffold({ templateDir, targetDir, projectName: 'my-docs' });
+
+    const lock = JSON.parse(fs.readFileSync(path.join(targetDir, 'package-lock.json'), 'utf-8'));
+    expect(lock.name).toBe('my-docs');
+    expect(lock.packages[''].name).toBe('my-docs');
+  });
+
+  it('refuses to overwrite a non-empty directory', () => {
+    const templateDir = makeTemplate(path.join(workdir, 'template'));
+    const targetDir = path.join(workdir, 'busy');
+
+    fs.mkdirSync(targetDir);
+    fs.writeFileSync(path.join(targetDir, 'important.txt'), 'do not lose me');
+
+    expect(() => scaffold({ templateDir, targetDir, projectName: 'busy' })).toThrow(/not empty/);
+    expect(fs.readFileSync(path.join(targetDir, 'important.txt'), 'utf-8')).toBe('do not lose me');
+  });
+
+  it('explains what to do when the template is missing', () => {
+    expect(() =>
+      scaffold({
+        templateDir: path.join(workdir, 'nope'),
+        targetDir: path.join(workdir, 'out'),
+        projectName: 'out',
+      }),
+    ).toThrow(/build:template/);
+  });
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "create-eziwiki",
+  "version": "0.1.0",
+  "description": "Scaffold a new eziwiki documentation site",
+  "type": "module",
+  "bin": {
+    "create-eziwiki": "./bin/create-eziwiki.mjs"
+  },
+  "scripts": {
+    "test": "vitest --run lib",
+    "//prepack": "The template is generated from the repository source rather than committed, so it must be rebuilt before packing. npm runs prepack for both `npm pack` and `npm publish`, which is what stops a stale engine being shipped to users.",
+    "prepack": "cd ../.. && npm run build:template"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "template",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/i3months/eziwiki.git",
+    "directory": "packages/create-eziwiki"
+  },
+  "homepage": "https://github.com/i3months/eziwiki#readme",
+  "bugs": "https://github.com/i3months/eziwiki/issues",
+  "keywords": [
+    "wiki",
+    "documentation",
+    "static-site-generator",
+    "markdown",
+    "nextjs"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}