docs-i18n 0.11.1 → 0.12.1

package/admin/server/functions/auth.ts

@@ -37,53 +37,5 @@ export const getSession = createServerFn({ method: 'GET' }).handler(async () =>
     headers: request.headers,
   });
 
-  // Seed admin user on first access if no users exist
-  await seedAdminIfNeeded(auth);
-
   return session;
 });
-
-let _seeded = false;
-
-/**
- * Seed a default admin user if none exists.
- * Only runs once per server lifetime.
- */
-async function seedAdminIfNeeded(auth: any) {
-  if (_seeded) return;
-  _seeded = true;
-
-  try {
-    const existing = await auth.api.listUsers({
-      query: { limit: 1 },
-      headers: new Headers(),
-    });
-
-    if (existing?.users && existing.users.length > 0) {
-      return; // Users exist, skip seeding
-    }
-
-    // Create the default admin user
-    const result = await auth.api.signUpEmail({
-      body: {
-        email: 'admin@docs-i18n.local',
-        password: 'admin',
-        name: 'Admin',
-        username: 'admin',
-      },
-    });
-
-    if (result?.user?.id) {
-      await auth.api.setRole({
-        body: {
-          userId: result.user.id,
-          role: 'admin',
-        },
-      });
-      console.log('[auth] Default admin user created (username: admin, password: admin)');
-    }
-  } catch (err) {
-    // Swallow errors — seeding is best-effort
-    console.warn('[auth] Admin seed skipped:', err instanceof Error ? err.message : err);
-  }
-}

package/admin/vite.config.ts

@@ -19,7 +19,7 @@ if (isCfBuild) {
   plugins.unshift(cloudflare({ viteEnvironment: { name: 'ssr' } }));
 }
 
-export default defineConfig({
+export default defineConfig(({ command }) => ({
   plugins,
   // Bundle all deps into server build so it can run without node_modules
   // (Only for non-CF builds; CF plugin manages its own SSR environment)
@@ -31,10 +31,14 @@ export default defineConfig({
             external: [/^node:/, 'better-sqlite3'],
           },
         },
-        resolve: {
-          noExternal: true,
-        },
+        // Only bundle all deps for production builds — during dev,
+        // Node.js resolves deps natively (avoids CJS/ESM issues in Vite's module runner)
+        ...(command === 'build' && {
+          resolve: {
+            noExternal: true,
+          },
+        }),
       },
     },
   }),
-});
+}));

package/dist/chunk-BHYFOPS6.js

@@ -0,0 +1,111 @@
+import {
+  flattenSources
+} from "./chunk-TRURQFP4.js";
+
+// src/plugins/runner.ts
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "fs";
+import { join, resolve } from "path";
+import matter from "gray-matter";
+function walkFiles(dir, extensions) {
+  const results = [];
+  if (!existsSync(dir)) return results;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkFiles(fullPath, extensions));
+    } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+function runBeforeScan(plugins, config, opts) {
+  const beforeScanPlugins = plugins.filter((p) => p.beforeScan);
+  if (beforeScanPlugins.length === 0) return 0;
+  const sources = flattenSources(config);
+  const extensions = (config.include ?? ["**/*.mdx", "**/*.md"]).map(
+    (p) => p.replace("**/*", "")
+  );
+  let modifiedCount = 0;
+  for (const source of sources) {
+    if (opts?.project && source.project !== opts.project) continue;
+    if (opts?.version && source.version !== opts.version) continue;
+    const enDir = resolve(source.sourcePath);
+    if (!existsSync(enDir)) {
+      console.log(`  [SKIP] ${source.versionKey}: source dir not found`);
+      continue;
+    }
+    const files = walkFiles(enDir, extensions);
+    for (const filePath of files) {
+      const content = readFileSync(filePath, "utf-8");
+      let parsed;
+      try {
+        parsed = matter(content);
+      } catch {
+        continue;
+      }
+      const readFile = (refPath) => {
+        const fromDir = filePath.substring(0, filePath.lastIndexOf("/"));
+        const candidates = [
+          resolve(fromDir, refPath),
+          resolve(enDir, refPath),
+          resolve(process.cwd(), refPath)
+        ];
+        for (const candidate of candidates) {
+          if (existsSync(candidate)) {
+            return readFileSync(candidate, "utf-8");
+          }
+        }
+        return null;
+      };
+      let modified = content;
+      let wasModified = false;
+      for (const plugin of beforeScanPlugins) {
+        const result = plugin.beforeScan({
+          filePath,
+          content: modified,
+          frontmatter: parsed.data,
+          readFile,
+          project: source.project,
+          version: source.version
+        });
+        if (typeof result === "string") {
+          modified = result;
+          wasModified = true;
+          try {
+            parsed = matter(modified);
+          } catch {
+          }
+        }
+      }
+      if (wasModified) {
+        const relPath = filePath.slice(enDir.length + 1);
+        if (opts?.dryRun) {
+          console.log(`  [DRY-RUN] ${source.versionKey}/${relPath}`);
+        } else {
+          writeFileSync(filePath, modified, "utf-8");
+          console.log(`  [RESOLVED] ${source.versionKey}/${relPath}`);
+        }
+        modifiedCount++;
+      }
+    }
+  }
+  return modifiedCount;
+}
+function createShouldScanBody(plugins) {
+  const hooks = plugins.filter((p) => p.shouldScanBody);
+  if (hooks.length === 0) return void 0;
+  return (ctx) => {
+    for (const plugin of hooks) {
+      if (plugin.shouldScanBody(ctx) === false) {
+        return false;
+      }
+    }
+    return true;
+  };
+}
+
+export {
+  runBeforeScan,
+  createShouldScanBody
+};

package/dist/cli.js

@@ -144,6 +144,8 @@ Commands:
   translate    Translate content to target language(s)
   assemble     Assemble translated files from EN + cache
   rescan       Rescan source files and clean orphans
+  resolve      Run beforeScan plugins (e.g., resolve ref directives)
+  pipeline     Run full pipeline: sync \u2192 resolve \u2192 rescan \u2192 translate \u2192 upload \u2192 status
   status       Show translation coverage
   admin        Start admin dashboard
   site         Manage documentation site (dev, build, upload, deploy) [--custom]
@@ -159,6 +161,9 @@ Options:
   --max-tokens <n>      Max output tokens (default: 16384)
   --context-length <n>  Model context window (default: 32768)
   --dry-run             Preview without making changes
+  --skip-sync           Pipeline: skip sync step
+  --skip-translate      Pipeline: skip translate step
+  --skip-upload         Pipeline: skip upload step
   --port <n>            Admin dashboard port (default: 3456) / Site dev port (default: 3000)
 `);
     return;
@@ -176,7 +181,7 @@ Options:
         console.error("Error: --lang is required");
         process.exit(1);
       }
-      const { translate } = await import("./translate-A5X6MX4Y.js");
+      const { translate } = await import("./translate-AGUNMZMQ.js");
       await translate(config, {
         lang,
         project: getOpt("project") || void 0,
@@ -193,7 +198,7 @@ Options:
       break;
     }
     case "assemble": {
-      const { assembleAll } = await import("./assemble-CP2BRYQJ.js");
+      const { assembleAll } = await import("./assemble-S3MWVLBI.js");
       await assembleAll(config, {
         project: getOpt("project") || void 0,
         version: getOpt("version") || void 0,
@@ -202,15 +207,49 @@ Options:
       break;
     }
     case "rescan": {
-      const { rescan } = await import("./rescan-HXMWFAOC.js");
+      const { rescan } = await import("./rescan-7XDHUNH5.js");
+      const plugins = config.plugins ?? [];
+      const shouldScanBody = plugins.length > 0 ? (await import("./runner-KUGSO4CL.js")).createShouldScanBody(plugins) : void 0;
       await rescan(config, {
         project: getOpt("project") || void 0,
-        version: getOpt("version") || void 0
+        version: getOpt("version") || void 0,
+        shouldScanBody
+      });
+      break;
+    }
+    case "resolve": {
+      const resolvePlugins = config.plugins ?? [];
+      if (resolvePlugins.length === 0) {
+        console.log("No plugins configured. Nothing to resolve.");
+        break;
+      }
+      const { runBeforeScan } = await import("./runner-KUGSO4CL.js");
+      const modified = runBeforeScan(resolvePlugins, config, {
+        project: getOpt("project") || void 0,
+        version: getOpt("version") || void 0,
+        dryRun: hasFlag("dry-run")
+      });
+      console.log(`
+${modified} file(s) resolved`);
+      break;
+    }
+    case "pipeline": {
+      const { pipeline } = await import("./pipeline-3XGFR4QL.js");
+      await pipeline(config, {
+        skipSync: hasFlag("skip-sync"),
+        skipTranslate: hasFlag("skip-translate"),
+        skipUpload: hasFlag("skip-upload"),
+        dryRun: hasFlag("dry-run"),
+        project: getOpt("project") || void 0,
+        version: getOpt("version") || void 0,
+        lang: getOpt("lang") || void 0,
+        max: getOpt("max") ? Number(getOpt("max")) : void 0,
+        concurrency: getOpt("concurrency") ? Number(getOpt("concurrency")) : void 0
       });
       break;
     }
     case "status": {
-      const { status } = await import("./status-AGZDXOTZ.js");
+      const { status } = await import("./status-NX47XZIU.js");
       await status(config, { lang: getOpt("lang") || void 0 });
       break;
     }

package/dist/index.d.ts

@@ -2,10 +2,44 @@ import * as unified from 'unified';
 import * as mdast from 'mdast';
 import { Root } from 'hast';
 
+/**
+ * Plugin interface for docs-i18n.
+ *
+ * Plugins can hook into the scan pipeline to transform source files
+ * before they are parsed and to control which parts of a file are scanned.
+ */
+interface DocsI18nPlugin {
+    name: string;
+    /**
+     * Called before scanning a source file.
+     * Receives the file content and frontmatter, and can return modified content.
+     * If the plugin returns a string, the file content is replaced with that string.
+     * If undefined/void is returned, the file is left unchanged.
+     */
+    beforeScan?: (ctx: {
+        filePath: string;
+        content: string;
+        frontmatter: Record<string, any>;
+        readFile: (refPath: string) => string | null;
+        project: string;
+        version: string;
+    }) => string | undefined | void;
+    /**
+     * Called to determine whether a file's body should be scanned for translation nodes.
+     * If any plugin returns false, only frontmatter fields will be scanned.
+     * If all plugins return true (or don't implement this hook), the full body is scanned.
+     */
+    shouldScanBody?: (ctx: {
+        filePath: string;
+        frontmatter: Record<string, any>;
+    }) => boolean;
+}
+
 /**
  * docs-i18n configuration schema.
  * Each project provides a `docs-i18n.config.ts` file.
  */
+
 interface ProjectConfig {
     /** Map of version → source directory (relative to project root) */
     sources: Record<string, string>;
@@ -37,6 +71,15 @@ interface DocsI18nConfig {
         version: string;
         lang: string;
     }) => Promise<void>;
+    /** Shell command to run before pipeline (e.g., sync upstream content) */
+    syncScript?: string;
+    /** Plugins for the scan pipeline */
+    plugins?: DocsI18nPlugin[];
+    /** Cloudflare D1 database configuration for remote upload */
+    d1?: {
+        database: string;
+        accountId?: string;
+    };
 }
 declare function defineConfig(config: DocsI18nConfig): DocsI18nConfig;
 /** Load config from file */
@@ -296,4 +339,68 @@ declare function normalize(content: string): string;
  */
 declare function getPackageVersion(): string;
 
-export { type DocsI18nConfig, type Heading, type ProjectConfig, type RenderedMarkdown, TranslationCache, assemble, defineConfig, extractHeadings, extractTranslatableFields, flattenSources, getPackageVersion, loadConfig, normalize, parseMdx, processor, reconstructFrontmatter, renderMarkdown };
+/**
+ * Plugin execution engine.
+ *
+ * Provides functions to run plugin hooks across source files.
+ */
+
+/**
+ * Run beforeScan hooks for all plugins on all source files.
+ *
+ * Walks every source directory, reads each file, runs every plugin's
+ * beforeScan hook, and writes back modified content.
+ *
+ * Returns the number of files that were modified.
+ */
+declare function runBeforeScan(plugins: DocsI18nPlugin[], config: DocsI18nConfig, opts?: {
+    project?: string;
+    version?: string;
+    dryRun?: boolean;
+}): number;
+/**
+ * Create a shouldScanBody function that checks all plugins.
+ *
+ * Returns a function that takes a file path and frontmatter and returns
+ * false if any plugin says the body should not be scanned.
+ */
+declare function createShouldScanBody(plugins: DocsI18nPlugin[]): ((ctx: {
+    filePath: string;
+    frontmatter: Record<string, any>;
+}) => boolean) | undefined;
+
+/**
+ * TanStack ref resolver plugin.
+ *
+ * Resolves `ref` frontmatter directives in markdown files, following ref chains
+ * up to a maximum depth. Applies `replace{}` text substitutions and section
+ * replacements from the origin file's frontmatter.
+ *
+ * Ported from tanstack-i18n-docs/scripts/resolve-refs.ts
+ */
+
+/**
+ * Create the TanStack ref resolver plugin.
+ *
+ * This plugin resolves `ref` frontmatter directives by following ref chains
+ * and applying replace/section substitutions.
+ */
+declare function tanstackRefPlugin(): DocsI18nPlugin;
+
+/**
+ * Next.js source filter plugin.
+ *
+ * Files with a `source:` field in frontmatter reference external content
+ * that will be fetched at build time. Their body should not be scanned
+ * for translation since it's just a placeholder / empty.
+ */
+
+/**
+ * Create the Next.js source filter plugin.
+ *
+ * When a file has `source:` in its frontmatter, shouldScanBody returns false
+ * so only translatable frontmatter fields (title, description, etc.) are scanned.
+ */
+declare function nextjsSourcePlugin(): DocsI18nPlugin;
+
+export { type DocsI18nConfig, type DocsI18nPlugin, type Heading, type ProjectConfig, type RenderedMarkdown, TranslationCache, assemble, createShouldScanBody, defineConfig, extractHeadings, extractTranslatableFields, flattenSources, getPackageVersion, loadConfig, nextjsSourcePlugin, normalize, parseMdx, processor, reconstructFrontmatter, renderMarkdown, runBeforeScan, tanstackRefPlugin };

package/dist/index.js

@@ -617,18 +617,241 @@ function getPackageVersion() {
   }
   return "unknown";
 }
+
+// src/plugins/runner.ts
+import { existsSync, readFileSync as readFileSync2, readdirSync, writeFileSync } from "fs";
+import { join, resolve as resolve2 } from "path";
+import matter from "gray-matter";
+function walkFiles(dir, extensions) {
+  const results = [];
+  if (!existsSync(dir)) return results;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkFiles(fullPath, extensions));
+    } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+function runBeforeScan(plugins, config, opts) {
+  const beforeScanPlugins = plugins.filter((p) => p.beforeScan);
+  if (beforeScanPlugins.length === 0) return 0;
+  const sources = flattenSources(config);
+  const extensions = (config.include ?? ["**/*.mdx", "**/*.md"]).map(
+    (p) => p.replace("**/*", "")
+  );
+  let modifiedCount = 0;
+  for (const source of sources) {
+    if (opts?.project && source.project !== opts.project) continue;
+    if (opts?.version && source.version !== opts.version) continue;
+    const enDir = resolve2(source.sourcePath);
+    if (!existsSync(enDir)) {
+      console.log(`  [SKIP] ${source.versionKey}: source dir not found`);
+      continue;
+    }
+    const files = walkFiles(enDir, extensions);
+    for (const filePath of files) {
+      const content = readFileSync2(filePath, "utf-8");
+      let parsed;
+      try {
+        parsed = matter(content);
+      } catch {
+        continue;
+      }
+      const readFile = (refPath) => {
+        const fromDir = filePath.substring(0, filePath.lastIndexOf("/"));
+        const candidates = [
+          resolve2(fromDir, refPath),
+          resolve2(enDir, refPath),
+          resolve2(process.cwd(), refPath)
+        ];
+        for (const candidate of candidates) {
+          if (existsSync(candidate)) {
+            return readFileSync2(candidate, "utf-8");
+          }
+        }
+        return null;
+      };
+      let modified = content;
+      let wasModified = false;
+      for (const plugin of beforeScanPlugins) {
+        const result = plugin.beforeScan({
+          filePath,
+          content: modified,
+          frontmatter: parsed.data,
+          readFile,
+          project: source.project,
+          version: source.version
+        });
+        if (typeof result === "string") {
+          modified = result;
+          wasModified = true;
+          try {
+            parsed = matter(modified);
+          } catch {
+          }
+        }
+      }
+      if (wasModified) {
+        const relPath = filePath.slice(enDir.length + 1);
+        if (opts?.dryRun) {
+          console.log(`  [DRY-RUN] ${source.versionKey}/${relPath}`);
+        } else {
+          writeFileSync(filePath, modified, "utf-8");
+          console.log(`  [RESOLVED] ${source.versionKey}/${relPath}`);
+        }
+        modifiedCount++;
+      }
+    }
+  }
+  return modifiedCount;
+}
+function createShouldScanBody(plugins) {
+  const hooks = plugins.filter((p) => p.shouldScanBody);
+  if (hooks.length === 0) return void 0;
+  return (ctx) => {
+    for (const plugin of hooks) {
+      if (plugin.shouldScanBody(ctx) === false) {
+        return false;
+      }
+    }
+    return true;
+  };
+}
+
+// src/plugins/presets/tanstack-ref.ts
+import matter2 from "gray-matter";
+var MAX_REF_DEPTH = 4;
+function replaceContent(text, originFrontmatter) {
+  let result = text;
+  const replace = originFrontmatter.data.replace;
+  if (replace) {
+    for (const [key, value] of Object.entries(replace)) {
+      result = result.replace(new RegExp(key, "g"), value);
+    }
+  }
+  return result;
+}
+function replaceSections(text, originFrontmatter) {
+  let result = text;
+  const sectionMarkerRegex = /\[\/\/\]: # '([a-zA-Z\d]*)'/g;
+  const sectionRegex = /\[\/\/\]: # '([a-zA-Z\d]*)'[\S\s]*?\[\/\/\]: # '([a-zA-Z\d]*)'/g;
+  const substitutes = /* @__PURE__ */ new Map();
+  for (const match of originFrontmatter.content.matchAll(sectionRegex)) {
+    if (match[1] !== match[2]) {
+      console.error(
+        `Origin section '${match[1]}' does not have matching closing token (found '${match[2]}'). Please make sure that each section has corresponding closing token and that sections are not nested.`
+      );
+    }
+    substitutes.set(match[1], match);
+  }
+  const sections = /* @__PURE__ */ new Map();
+  for (const match of result.matchAll(sectionRegex)) {
+    if (match[1] !== match[2]) {
+      console.error(
+        `Target section '${match[1]}' does not have matching closing token (found '${match[2]}'). Please make sure that each section has corresponding closing token and that sections are not nested.`
+      );
+    }
+    sections.set(match[1], match);
+  }
+  Array.from(substitutes.entries()).reverse().forEach(([key, value]) => {
+    const sectionMatch = sections.get(key);
+    if (sectionMatch) {
+      result = result.slice(0, sectionMatch.index) + value[0] + result.slice(sectionMatch.index + sectionMatch[0].length, result.length);
+    }
+  });
+  result = result.replaceAll(sectionMarkerRegex, "");
+  return result;
+}
+function normalizeRefPath(ref) {
+  if (ref.startsWith("docs/")) {
+    return ref.slice(5);
+  }
+  return ref;
+}
+function tryReadRef(refPath, readFile) {
+  let content = readFile(refPath);
+  if (content) return content;
+  const normalized = normalizeRefPath(refPath);
+  if (normalized !== refPath) {
+    content = readFile(normalized);
+    if (content) return content;
+  }
+  return null;
+}
+function tanstackRefPlugin() {
+  return {
+    name: "tanstack-ref",
+    beforeScan(ctx) {
+      const { filePath, content, frontmatter, readFile } = ctx;
+      if (!frontmatter.ref) {
+        return void 0;
+      }
+      const originParsed = matter2(content);
+      let refPath = frontmatter.ref;
+      let currentDepth = 1;
+      while (currentDepth <= MAX_REF_DEPTH) {
+        const refContent = tryReadRef(refPath, readFile);
+        if (!refContent) {
+          console.warn(`  [tanstack-ref] ${filePath}: ref target not found: ${refPath}`);
+          return void 0;
+        }
+        const refParsed = matter2(refContent);
+        if (!refParsed.data.ref) {
+          return resolveWithContent(refContent, originParsed);
+        }
+        refPath = refParsed.data.ref;
+        currentDepth++;
+      }
+      console.warn(`  [tanstack-ref] ${filePath}: ref chain exceeded max depth of ${MAX_REF_DEPTH}`);
+      return void 0;
+    }
+  };
+}
+function resolveWithContent(targetRaw, originParsed) {
+  let content = targetRaw;
+  content = replaceContent(content, originParsed);
+  content = replaceSections(content, originParsed);
+  const newData = { ...originParsed.data };
+  delete newData.ref;
+  delete newData.replace;
+  const targetParsed = matter2(content);
+  const mergedData = { ...targetParsed.data, ...newData };
+  delete mergedData.ref;
+  delete mergedData.replace;
+  return matter2.stringify(targetParsed.content, mergedData);
+}
+
+// src/plugins/presets/nextjs-source.ts
+function nextjsSourcePlugin() {
+  return {
+    name: "nextjs-source",
+    shouldScanBody(ctx) {
+      if (ctx.frontmatter.source) {
+        return false;
+      }
+      return true;
+    }
+  };
+}
 export {
   TranslationCache,
   assemble,
+  createShouldScanBody,
   defineConfig,
   extractHeadings,
   extractTranslatableFields,
   flattenSources,
   getPackageVersion,
   loadConfig,
+  nextjsSourcePlugin,
   normalize,
   parseMdx,
   processor,
   reconstructFrontmatter,
-  renderMarkdown
+  renderMarkdown,
+  runBeforeScan,
+  tanstackRefPlugin
 };