tgo-wiki 0.1.0

package/packages/core/src/sources/source-writer.ts

@@ -0,0 +1,419 @@
+import { randomBytes } from "node:crypto";
+import { lstat, link, mkdir, realpath, rename, rmdir, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { WikiError } from "../errors.js";
+import { assertValidSourceId } from "./source-id.js";
+import { sourceDirectory, sourceMetadataPath, sourceRawMarkdownPath } from "./source-paths.js";
+
+export type SourceWriterAsset = {
+  path: string;
+  content: Buffer | Uint8Array | string;
+};
+
+export type PublishSourceMode = "create" | "replace";
+
+export type PublishSourceInput = {
+  worktreeRoot: string;
+  sourceId: string;
+  markdown: string;
+  assets?: SourceWriterAsset[];
+  metadataJson: string;
+  mode: PublishSourceMode;
+};
+
+type PreparedSourcePaths = {
+  sourceRoot: string;
+  realSourceRoot: string;
+  rawMarkdownPath: string;
+  metadataPath: string;
+  createdDirectories: string[];
+};
+
+type PreparedAsset = {
+  path: string;
+  content: Buffer | Uint8Array | string;
+};
+
+type ReplaceRecord = {
+  finalPath: string;
+  backupPath?: string;
+};
+
+export async function publishSource(input: PublishSourceInput): Promise<void> {
+  assertValidSourceId(input.sourceId);
+  const createdDirectories: string[] = [];
+  const prepared = await prepareSourceForWrite(input.worktreeRoot, input.sourceId, input.mode === "create" ? createdDirectories : undefined);
+
+  if (input.mode === "replace") {
+    const assets = await prepareSourceAssets(prepared, input.assets ?? []);
+    await publishSourceReplace(prepared, assets, input);
+    return;
+  }
+
+  try {
+    const assets = await prepareSourceAssets(prepared, input.assets ?? [], createdDirectories);
+    await publishSourceCreate(prepared, assets, input);
+  } catch (error) {
+    await cleanupCreatedDirectories(createdDirectories);
+    throw error;
+  }
+}
+
+export async function assertNoExistingSourceForCreate(worktreeRoot: string, sourceId: string): Promise<void> {
+  assertValidSourceId(sourceId);
+  const realWorktreeRoot = await realpath(worktreeRoot);
+  const sourcesRoot = path.join(worktreeRoot, "sources");
+  const existingSourcesRoot = await lstatIfExists(sourcesRoot);
+  if (existingSourcesRoot) {
+    if (existingSourcesRoot.isSymbolicLink()) {
+      throw new WikiError("invalid_path", `Sources directory is a symlink: ${sourcesRoot}`);
+    }
+
+    if (!existingSourcesRoot.isDirectory()) {
+      throw new WikiError("invalid_path", `Sources directory is not a directory: ${sourcesRoot}`);
+    }
+
+    const realSourcesRoot = await realpath(sourcesRoot);
+    ensureInsideRealRoot(realWorktreeRoot, realSourcesRoot, sourcesRoot, "Sources directory escapes boundary");
+  }
+
+  const sourceRoot = sourceDirectory(worktreeRoot, sourceId);
+  const existingSourceRoot = await lstatIfExists(sourceRoot);
+  if (existingSourceRoot?.isSymbolicLink()) {
+    throw new WikiError("invalid_path", `Source directory is a symlink: ${sourceRoot}`);
+  }
+
+  if (existingSourceRoot) {
+    throw new WikiError("source_exists", `Source already exists: ${sourceId}`);
+  }
+}
+
+async function publishSourceCreate(
+  prepared: PreparedSourcePaths,
+  assets: PreparedAsset[],
+  input: PublishSourceInput
+): Promise<void> {
+  const published: string[] = [];
+
+  try {
+    await publishFileCreate(prepared.sourceRoot, prepared.rawMarkdownPath, input.markdown, input.sourceId);
+    published.push(prepared.rawMarkdownPath);
+
+    for (const asset of assets) {
+      await publishFileCreate(path.dirname(asset.path), asset.path, asset.content, path.basename(asset.path));
+      published.push(asset.path);
+    }
+
+    await publishFileCreate(prepared.sourceRoot, prepared.metadataPath, input.metadataJson, input.sourceId);
+    published.push(prepared.metadataPath);
+  } catch (error) {
+    await Promise.all(published.map(filePath => unlinkIfExists(filePath)));
+    throw error;
+  }
+}
+
+async function publishSourceReplace(
+  prepared: PreparedSourcePaths,
+  assets: PreparedAsset[],
+  input: PublishSourceInput
+): Promise<void> {
+  const replaced: ReplaceRecord[] = [];
+
+  try {
+    await publishFileReplace(prepared.sourceRoot, prepared.rawMarkdownPath, input.markdown, replaced);
+
+    for (const asset of assets) {
+      await publishFileReplace(path.dirname(asset.path), asset.path, asset.content, replaced);
+    }
+
+    await publishFileReplace(prepared.sourceRoot, prepared.metadataPath, input.metadataJson, replaced);
+    await Promise.all(replaced.map(record => (record.backupPath ? unlinkIfExists(record.backupPath) : Promise.resolve())));
+  } catch (error) {
+    await rollbackReplacements(replaced);
+    throw error;
+  }
+}
+
+async function prepareSourceForWrite(
+  worktreeRoot: string,
+  sourceId: string,
+  createdDirectories?: string[]
+): Promise<PreparedSourcePaths> {
+  const realWorktreeRoot = await realpath(worktreeRoot);
+  const sourcesRoot = path.join(worktreeRoot, "sources");
+  await ensureDirectoryForWrite(sourcesRoot, realWorktreeRoot, "Sources directory", createdDirectories);
+  const realSourcesRoot = await realpath(sourcesRoot);
+
+  const sourceRoot = sourceDirectory(worktreeRoot, sourceId);
+  await ensureDirectoryForWrite(sourceRoot, realSourcesRoot, "Source directory", createdDirectories);
+  const realSourceRoot = await realpath(sourceRoot);
+
+  const rawMarkdownPath = sourceRawMarkdownPath(worktreeRoot, sourceId);
+  const metadataPath = sourceMetadataPath(worktreeRoot, sourceId);
+  await rejectExistingSymlink(rawMarkdownPath, "Source raw markdown");
+  await rejectExistingSymlink(metadataPath, "Source metadata");
+  ensureInsideRealRoot(realSourceRoot, path.resolve(rawMarkdownPath), rawMarkdownPath, "Raw markdown path escapes source directory");
+  ensureInsideRealRoot(realSourceRoot, path.resolve(metadataPath), metadataPath, "Metadata path escapes source directory");
+
+  return {
+    sourceRoot,
+    realSourceRoot,
+    rawMarkdownPath,
+    metadataPath,
+    createdDirectories: createdDirectories ?? []
+  };
+}
+
+async function lstatIfExists(filePath: string): Promise<Awaited<ReturnType<typeof lstat>> | undefined> {
+  try {
+    return await lstat(filePath);
+  } catch (error) {
+    if (isEnoent(error)) {
+      return undefined;
+    }
+
+    throw error;
+  }
+}
+
+async function prepareSourceAssets(
+  prepared: PreparedSourcePaths,
+  assets: SourceWriterAsset[],
+  createdDirectories?: string[]
+): Promise<PreparedAsset[]> {
+  if (assets.length === 0) {
+    return [];
+  }
+
+  const assetsRoot = path.join(prepared.sourceRoot, "assets");
+  const resolved = assets.map(asset => ({
+    path: resolveAssetPath(assetsRoot, asset.path),
+    content: asset.content
+  }));
+
+  await ensureDirectoryForWrite(assetsRoot, prepared.realSourceRoot, "Source assets directory", createdDirectories);
+  const realAssetsRoot = await realpath(assetsRoot);
+
+  for (const asset of resolved) {
+    const parent = path.dirname(asset.path);
+    await ensureNestedDirectoryForWrite(assetsRoot, path.relative(assetsRoot, parent), realAssetsRoot, createdDirectories);
+    await rejectExistingSymlink(asset.path, "Parser asset");
+    const realParent = await realpath(parent);
+    ensureInsideRealRoot(realAssetsRoot, realParent, parent, "Asset parent path escapes assets directory");
+  }
+
+  return resolved;
+}
+
+function resolveAssetPath(assetsRoot: string, relativePath: string): string {
+  if (
+    relativePath.length === 0 ||
+    path.isAbsolute(relativePath) ||
+    path.win32.isAbsolute(relativePath) ||
+    relativePath.split(/[\\/]/).includes("..")
+  ) {
+    throw new WikiError("invalid_path", `Invalid parser asset path: ${relativePath}`);
+  }
+
+  return path.join(assetsRoot, relativePath);
+}
+
+async function publishFileCreate(
+  tempDirectory: string,
+  finalPath: string,
+  content: Buffer | Uint8Array | string,
+  label: string
+): Promise<void> {
+  const tempPath = await writeTempFile(tempDirectory, path.basename(finalPath), content);
+
+  try {
+    await link(tempPath, finalPath);
+  } catch (error) {
+    if (isFileExists(error)) {
+      throw new WikiError("source_exists", `Source already exists: ${label}`);
+    }
+
+    throw error;
+  } finally {
+    await unlinkIfExists(tempPath);
+  }
+}
+
+async function publishFileReplace(
+  tempDirectory: string,
+  finalPath: string,
+  content: Buffer | Uint8Array | string,
+  replaced: ReplaceRecord[]
+): Promise<void> {
+  const tempPath = await writeTempFile(tempDirectory, path.basename(finalPath), content);
+  const backupPath = path.join(tempDirectory, `.${path.basename(finalPath)}.${randomBytes(8).toString("hex")}.backup`);
+  let record: ReplaceRecord | undefined;
+
+  try {
+    try {
+      await rename(finalPath, backupPath);
+      record = { finalPath, backupPath };
+    } catch (error) {
+      if (!isEnoent(error)) {
+        throw error;
+      }
+
+      record = { finalPath };
+    }
+
+    await rename(tempPath, finalPath);
+    replaced.push(record);
+  } catch (error) {
+    if (record?.backupPath) {
+      await rename(record.backupPath, record.finalPath);
+    }
+
+    throw error;
+  } finally {
+    await unlinkIfExists(tempPath);
+  }
+}
+
+async function rollbackReplacements(replaced: ReplaceRecord[]): Promise<void> {
+  for (const record of [...replaced].reverse()) {
+    await unlinkIfExists(record.finalPath);
+    if (record.backupPath) {
+      await rename(record.backupPath, record.finalPath);
+    }
+  }
+}
+
+async function writeTempFile(directory: string, finalBaseName: string, content: Buffer | Uint8Array | string): Promise<string> {
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    const tempPath = path.join(directory, `.${finalBaseName}.${randomBytes(8).toString("hex")}.tmp`);
+
+    try {
+      await writeFile(tempPath, content, { flag: "wx" });
+      return tempPath;
+    } catch (error) {
+      if (isFileExists(error)) {
+        continue;
+      }
+
+      throw error;
+    }
+  }
+
+  throw new WikiError("validation_failed", `Could not create unique temp file for: ${finalBaseName}`);
+}
+
+async function ensureNestedDirectoryForWrite(
+  root: string,
+  relativePath: string,
+  realBoundary: string,
+  createdDirectories?: string[]
+): Promise<void> {
+  const segments = relativePath.split(path.sep).filter(segment => segment.length > 0 && segment !== ".");
+  let current = root;
+
+  for (const segment of segments) {
+    current = path.join(current, segment);
+    await ensureDirectoryForWrite(current, realBoundary, "Asset parent directory", createdDirectories);
+  }
+}
+
+async function ensureDirectoryForWrite(
+  directoryPath: string,
+  realBoundary: string,
+  label: string,
+  createdDirectories?: string[]
+): Promise<void> {
+  let created = false;
+
+  try {
+    const stat = await lstat(directoryPath);
+
+    if (stat.isSymbolicLink()) {
+      throw new WikiError("invalid_path", `${label} is a symlink: ${directoryPath}`);
+    }
+
+    if (!stat.isDirectory()) {
+      throw new WikiError("invalid_path", `${label} is not a directory: ${directoryPath}`);
+    }
+  } catch (error) {
+    if (!isEnoent(error)) {
+      throw error;
+    }
+
+    await mkdir(directoryPath);
+    created = true;
+    await ensureDirectoryNotSymlink(directoryPath, label);
+  }
+
+  const realDirectory = await realpath(directoryPath);
+  ensureInsideRealRoot(realBoundary, realDirectory, directoryPath, `${label} escapes boundary`);
+
+  if (created) {
+    createdDirectories?.push(directoryPath);
+  }
+}
+
+async function ensureDirectoryNotSymlink(directoryPath: string, label: string): Promise<void> {
+  const stat = await lstat(directoryPath);
+
+  if (stat.isSymbolicLink()) {
+    throw new WikiError("invalid_path", `${label} is a symlink: ${directoryPath}`);
+  }
+
+  if (!stat.isDirectory()) {
+    throw new WikiError("invalid_path", `${label} is not a directory: ${directoryPath}`);
+  }
+}
+
+async function rejectExistingSymlink(filePath: string, label: string): Promise<void> {
+  try {
+    const stat = await lstat(filePath);
+    if (stat.isSymbolicLink()) {
+      throw new WikiError("invalid_path", `${label} is a symlink: ${filePath}`);
+    }
+  } catch (error) {
+    if (isEnoent(error)) {
+      return;
+    }
+
+    throw error;
+  }
+}
+
+function ensureInsideRealRoot(realRoot: string, target: string, originalPath: string, message: string): void {
+  if (!target.startsWith(`${realRoot}${path.sep}`) && target !== realRoot) {
+    throw new WikiError("invalid_path", `${message}: ${originalPath}`);
+  }
+}
+
+async function unlinkIfExists(filePath: string): Promise<void> {
+  try {
+    await unlink(filePath);
+  } catch (error) {
+    if (!isEnoent(error)) {
+      throw error;
+    }
+  }
+}
+
+async function cleanupCreatedDirectories(createdDirectories: string[]): Promise<void> {
+  for (const directoryPath of [...createdDirectories].reverse()) {
+    await rmdir(directoryPath).catch(error => {
+      if (!isEnoent(error) && !isDirectoryNotEmpty(error)) {
+        throw error;
+      }
+    });
+  }
+}
+
+function isEnoent(error: unknown): boolean {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}
+
+function isFileExists(error: unknown): boolean {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === "EEXIST");
+}
+
+function isDirectoryNotEmpty(error: unknown): boolean {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOTEMPTY");
+}

package/packages/core/src/validation/frontmatter-validator.ts

@@ -0,0 +1,128 @@
+import matter from "gray-matter";
+
+export type ParsedFrontmatter = {
+  title?: string;
+  summary?: string;
+  tags?: string[];
+  updated?: string;
+  sources?: string[];
+};
+
+export type ParsedMarkdownPage = {
+  frontmatter: ParsedFrontmatter;
+  content: string;
+};
+
+export type FrontmatterIssue = {
+  path: string;
+  code: "invalid_frontmatter";
+  message: string;
+};
+
+const datePattern = /^\d{4}-\d{2}-\d{2}$/;
+
+export function parseFrontmatter(filePath: string, source: string): {
+  page: ParsedMarkdownPage;
+  issues: FrontmatterIssue[];
+} {
+  let parsed: matter.GrayMatterFile<string>;
+
+  try {
+    parsed = matter(source);
+  } catch (error) {
+    return {
+      page: {
+        frontmatter: {},
+        content: contentWithoutFrontmatter(source)
+      },
+      issues: [
+        {
+          path: filePath,
+          code: "invalid_frontmatter",
+          message: error instanceof Error ? error.message : "Invalid frontmatter"
+        }
+      ]
+    };
+  }
+
+  const data = parsed.data as Record<string, unknown>;
+  const issues: FrontmatterIssue[] = [];
+
+  if (Object.keys(data).length === 0) {
+    issues.push({
+      path: filePath,
+      code: "invalid_frontmatter",
+      message: "Markdown file is missing required frontmatter"
+    });
+  } else {
+    const invalidFields = requiredInvalidFields(data);
+
+    if (invalidFields.length > 0) {
+      issues.push({
+        path: filePath,
+        code: "invalid_frontmatter",
+        message: `Invalid frontmatter fields: ${invalidFields.join(", ")}`
+      });
+    }
+  }
+
+  return {
+    page: {
+      frontmatter: {
+        title: typeof data.title === "string" ? data.title : undefined,
+        summary: typeof data.summary === "string" ? data.summary : undefined,
+        tags: isStringArray(data.tags) ? data.tags : undefined,
+        updated: typeof data.updated === "string" ? data.updated : undefined,
+        sources: isStringArray(data.sources) ? data.sources : undefined
+      },
+      content: parsed.content
+    },
+    issues
+  };
+}
+
+function requiredInvalidFields(data: Record<string, unknown>): string[] {
+  const invalid: string[] = [];
+
+  if (typeof data.title !== "string" || data.title.trim().length === 0) {
+    invalid.push("title");
+  }
+
+  if (typeof data.summary !== "string" || data.summary.trim().length === 0) {
+    invalid.push("summary");
+  }
+
+  if (!isStringArray(data.tags)) {
+    invalid.push("tags");
+  }
+
+  if (typeof data.updated !== "string" || !datePattern.test(data.updated)) {
+    invalid.push("updated");
+  }
+
+  if (Object.hasOwn(data, "sources") && !isStringArray(data.sources)) {
+    invalid.push("sources");
+  }
+
+  return invalid;
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every(item => typeof item === "string");
+}
+
+function contentWithoutFrontmatter(source: string): string {
+  const lines = source.split(/\r?\n/);
+
+  if (lines[0] !== "---") {
+    return source;
+  }
+
+  const closingFenceIndex = lines.findIndex((line, index) => index > 0 && line === "---");
+
+  if (closingFenceIndex === -1) {
+    return source;
+  }
+
+  return lines.slice(closingFenceIndex + 1).join("\n");
+}

package/packages/core/src/validation/link-validator.ts

@@ -0,0 +1,55 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+import type { MarkdownLink } from "../markdown/markdown-scanner.js";
+import { normalizeWikiPath, resolveInsideRoot } from "./path-validator.js";
+
+export type LinkValidationIssue = {
+  path: string;
+  code: "broken_link";
+  message: string;
+};
+
+export async function validateLinks(
+  worktreeRoot: string,
+  currentWikiPath: string,
+  links: MarkdownLink[]
+): Promise<LinkValidationIssue[]> {
+  const issues: LinkValidationIssue[] = [];
+
+  for (const link of links) {
+    try {
+      const targetPath = link.kind === "wiki" ? link.target : resolveMarkdownTarget(currentWikiPath, link.target);
+      const absoluteTarget = resolveInsideRoot(worktreeRoot, targetPath);
+      await access(absoluteTarget);
+    } catch {
+      issues.push({
+        path: currentWikiPath,
+        code: "broken_link",
+        message: `Broken link ${link.raw} points to an invalid or missing target`
+      });
+    }
+  }
+
+  return issues;
+}
+
+function resolveMarkdownTarget(currentWikiPath: string, target: string): string {
+  const [targetWithoutHash] = target.split("#", 1);
+
+  if (!targetWithoutHash) {
+    return currentWikiPath;
+  }
+
+  if (path.posix.isAbsolute(targetWithoutHash) || targetWithoutHash.startsWith("wiki/")) {
+    return normalizeWikiPath(targetWithoutHash);
+  }
+
+  const currentDir = path.posix.dirname(currentWikiPath);
+  const resolvedTarget = path.posix.normalize(path.posix.join(currentDir, targetWithoutHash));
+
+  if (!resolvedTarget.startsWith("wiki/")) {
+    throw new Error(`Link target escapes wiki root: ${target}`);
+  }
+
+  return normalizeWikiPath(resolvedTarget);
+}

package/packages/core/src/validation/path-validator.ts

@@ -0,0 +1,65 @@
+import path from "node:path";
+import { WikiError } from "../errors.js";
+
+export function normalizeWikiPath(input: string): string {
+  const unixInput = input.replaceAll("\\", "/");
+
+  if (path.posix.isAbsolute(unixInput) || /^[A-Za-z]:\//.test(unixInput)) {
+    throw new WikiError("invalid_path", `Path must be relative: ${input}`);
+  }
+
+  if (hasParentSegment(unixInput)) {
+    throw new WikiError("invalid_path", `Path escapes wiki root: ${input}`);
+  }
+
+  const relativeInput = path.posix.normalize(unixInput);
+
+  if (relativeInput.startsWith("../") || relativeInput.includes("/../") || relativeInput === "..") {
+    throw new WikiError("invalid_path", `Path escapes wiki root: ${input}`);
+  }
+
+  const withWiki = toWikiPath(input, relativeInput);
+  const parsed = path.posix.normalize(withWiki);
+
+  if (parsed.startsWith("../") || parsed.includes("/../") || parsed === "..") {
+    throw new WikiError("invalid_path", `Path escapes wiki root: ${input}`);
+  }
+
+  if (!parsed.startsWith("wiki/")) {
+    throw new WikiError("invalid_path", `Path must be inside wiki/: ${input}`);
+  }
+
+  if (!parsed.endsWith(".md")) {
+    throw new WikiError("invalid_path", `Path must point to a Markdown file: ${input}`);
+  }
+
+  return parsed;
+}
+
+function hasParentSegment(input: string): boolean {
+  return input.split("/").some(segment => segment === "..");
+}
+
+function toWikiPath(input: string, relativeInput: string): string {
+  if (relativeInput.startsWith("wiki/")) {
+    return relativeInput;
+  }
+
+  if (!relativeInput.includes("/")) {
+    return `wiki/${relativeInput}`;
+  }
+
+  throw new WikiError("invalid_path", `Path must be inside wiki/: ${input}`);
+}
+
+export function resolveInsideRoot(root: string, wikiPath: string): string {
+  const normalized = normalizeWikiPath(wikiPath);
+  const absolute = path.resolve(root, normalized);
+  const allowedRoot = path.resolve(root, "wiki");
+
+  if (!absolute.startsWith(`${allowedRoot}${path.sep}`) && absolute !== allowedRoot) {
+    throw new WikiError("invalid_path", `Path escapes wiki root: ${wikiPath}`);
+  }
+
+  return absolute;
+}