tgo-wiki 0.1.0

package/packages/core/src/result.ts

@@ -0,0 +1,13 @@
+import type { WikiError } from "./errors.js";
+
+export type Result<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: WikiError };
+
+export function ok<T>(value: T): Result<T> {
+  return { ok: true, value };
+}
+
+export function err<T = never>(error: WikiError): Result<T> {
+  return { ok: false, error };
+}

package/packages/core/src/services/session-workflow-service.ts

@@ -0,0 +1,493 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveWorkspacePaths, type WorkspacePaths } from "../config/workspace-resolver.js";
+import { WikiError } from "../errors.js";
+import { GitService } from "../git/git-service.js";
+import { err, ok, type Result } from "../result.js";
+import { SessionService, type SessionStartInput, type SessionStartResult } from "../session/session-service.js";
+import { SessionStore } from "../session/session-store.js";
+import type { SessionMetadata } from "../session/session-types.js";
+import { assertValidSourceId } from "../sources/source-id.js";
+import { normalizeWikiPath, resolveInsideRoot } from "../validation/path-validator.js";
+import { validateSourceAssetPaths, validateSourceDirectory } from "../validation/source-reference-validator.js";
+import { ValidationService, type ValidationResult } from "../validation/validation-service.js";
+
+export type SessionPatchInput = {
+  sessionId: string;
+  path: string;
+  content?: string;
+  patch?: string;
+  reason?: string;
+};
+
+export type SessionPatchResult = {
+  path: string;
+  changed: boolean;
+  sha_before?: string;
+  sha_after: string;
+};
+
+export type SessionValidateInput = {
+  sessionId: string;
+  paths?: string[];
+};
+
+export type SessionDiffInput = {
+  sessionId: string;
+  paths?: string[];
+};
+
+export type SessionDiffResult = {
+  session_id: string;
+  base_ref: string;
+  diff: string;
+  committed_diff: string;
+  working_diff: string;
+  changed_files: string[];
+};
+
+export type SessionCommitInput = {
+  sessionId: string;
+  message: string;
+};
+
+export type SessionCommitResult = {
+  commit: string;
+  branch: string;
+  changed_files: string[];
+};
+
+export class SessionWorkflowService {
+  private readonly paths: WorkspacePaths;
+  private readonly store: SessionStore;
+  private readonly sessions: SessionService;
+
+  constructor(
+    workspaceRoot: string,
+    idGenerator?: () => string,
+    private readonly git = new GitService()
+  ) {
+    this.paths = resolveWorkspacePaths(workspaceRoot);
+    this.store = new SessionStore(this.paths);
+    this.sessions = new SessionService(workspaceRoot, idGenerator, git);
+  }
+
+  async start(input: SessionStartInput = {}): Promise<Result<SessionStartResult>> {
+    return this.sessions.start(input);
+  }
+
+  async patch(input: SessionPatchInput): Promise<Result<SessionPatchResult>> {
+    try {
+      if (input.patch !== undefined) {
+        return err(new WikiError("invalid_path", "Full content replacement is required; unified patch input is not supported"));
+      }
+
+      if (input.content === undefined) {
+        return err(new WikiError("invalid_path", "Full content replacement is required"));
+      }
+
+      if (isSourcePatchAttempt(input.path)) {
+        return err(new WikiError("source_write_denied", "Source files are parser-owned and cannot be patched directly"));
+      }
+
+      const metadata = await this.openSession(input.sessionId);
+      const wikiPath = normalizeWikiPath(input.path);
+      const worktreeRoot = this.worktreeRoot(metadata);
+      const filePath = resolveInsideRoot(worktreeRoot, wikiPath);
+      await ensureSafeWriteTarget(worktreeRoot, wikiPath, filePath);
+      const before = await readOptional(filePath);
+      const shaBefore = before === undefined ? undefined : contentSha(before);
+      const shaAfter = contentSha(input.content);
+
+      await writeFile(filePath, input.content, "utf8");
+      await this.touch(input.sessionId);
+
+      return ok({
+        path: wikiPath,
+        changed: before !== input.content,
+        ...(shaBefore ? { sha_before: shaBefore } : {}),
+        sha_after: shaAfter
+      });
+    } catch (error) {
+      return err(toWorkflowError(error, "invalid_path"));
+    }
+  }
+
+  async validate(input: SessionValidateInput): Promise<Result<ValidationResult>> {
+    try {
+      const metadata = await this.store.read(input.sessionId);
+      const worktreeRoot = this.worktreeRoot(metadata);
+      const paths = validationPaths(input.paths?.map(normalizeWikiPath) ?? (await this.changedFiles(metadata)));
+      const validation = new ValidationService(worktreeRoot);
+
+      return ok(await validation.validatePaths(paths));
+    } catch (error) {
+      return err(toWorkflowError(error, "session_not_found"));
+    }
+  }
+
+  async diff(input: SessionDiffInput): Promise<Result<SessionDiffResult>> {
+    try {
+      const metadata = await this.store.read(input.sessionId);
+      const worktreeRoot = this.worktreeRoot(metadata);
+      const diffPaths = diffPathspec(input.paths);
+      const addIntentPaths = await existingPathspecs(worktreeRoot, diffPaths);
+
+      if (addIntentPaths.length > 0) {
+        await this.git.run(["add", "-N", ...addIntentPaths], { cwd: worktreeRoot });
+      }
+
+      const [committed, working, changedFiles] = await Promise.all([
+        this.git.run(["diff", metadata.baseCommit, "HEAD", "--", ...diffPaths], { cwd: worktreeRoot }),
+        this.git.run(["diff", "HEAD", "--", ...diffPaths], { cwd: worktreeRoot }),
+        this.changedFiles(metadata, input.paths)
+      ]);
+
+      const sections = [committed.stdout, working.stdout].filter(section => section.length > 0);
+
+      return ok({
+        session_id: metadata.sessionId,
+        base_ref: metadata.baseRef,
+        diff: sections.join("\n"),
+        committed_diff: committed.stdout,
+        working_diff: working.stdout,
+        changed_files: changedFiles
+      });
+    } catch (error) {
+      return err(toWorkflowError(error, "git_error"));
+    }
+  }
+
+  async commit(input: SessionCommitInput): Promise<Result<SessionCommitResult>> {
+    try {
+      const metadata = await this.openSession(input.sessionId);
+      const worktreeRoot = this.worktreeRoot(metadata);
+      const pendingFiles = await this.pendingFiles(metadata, ["."]);
+      const unsupportedFiles = pendingFiles.filter(file => !isAllowedSessionCommitPath(file));
+
+      if (unsupportedFiles.length > 0) {
+        return err(
+          new WikiError("validation_failed", "Session contains unsupported pending files", { files: unsupportedFiles })
+        );
+      }
+
+      const changedFiles = pendingFiles.filter(isAllowedSessionCommitPath);
+
+      if (changedFiles.length === 0) {
+        return err(new WikiError("session_dirty", "No session changes to commit"));
+      }
+
+      const sourceValidationErrors = (
+        await Promise.all(affectedSourceIds(changedFiles).map(sourceId => validateSourceDirectory(worktreeRoot, sourceId)))
+      ).filter(result => !result.ok);
+      const assetValidationErrors = (
+        await Promise.all(
+          affectedAssetSourceIds(changedFiles).map(sourceId =>
+            validateSourceAssetPaths(worktreeRoot, sourceId, changedFiles.filter(file => isSourceAssetPath(file, sourceId)))
+          )
+        )
+      ).filter(result => !result.ok);
+      const allSourceValidationErrors = [...sourceValidationErrors, ...assetValidationErrors];
+
+      if (allSourceValidationErrors.length > 0) {
+        return err(
+          new WikiError("validation_failed", "Session contains invalid source files", {
+            sources: allSourceValidationErrors
+          })
+        );
+      }
+
+      const validation = await this.validate({ sessionId: input.sessionId });
+
+      if (!validation.ok) {
+        return validation;
+      }
+
+      if (!validation.value.ok) {
+        return err(new WikiError("validation_failed", "Session validation failed", { validation: validation.value }));
+      }
+
+      const commit = await this.git.commit(worktreeRoot, input.message, changedFiles);
+      await this.store.update(input.sessionId, current => ({
+        ...current,
+        lastCommit: commit,
+        updatedAt: new Date().toISOString()
+      }));
+
+      return ok({
+        commit,
+        branch: metadata.branch,
+        changed_files: changedFiles
+      });
+    } catch (error) {
+      return err(toWorkflowError(error, "git_error"));
+    }
+  }
+
+  private async openSession(sessionId: string): Promise<SessionMetadata> {
+    const metadata = await this.store.read(sessionId);
+
+    if (metadata.status !== "open") {
+      throw new WikiError("session_dirty", `Session is not open: ${sessionId}`, { status: metadata.status });
+    }
+
+    return metadata;
+  }
+
+  private worktreeRoot(metadata: SessionMetadata): string {
+    const absolute = path.resolve(this.paths.workspaceRoot, metadata.worktree);
+    const sessionsRoot = path.resolve(this.paths.sessionsWorktreePath);
+
+    if (!absolute.startsWith(`${sessionsRoot}${path.sep}`) && absolute !== sessionsRoot) {
+      throw new WikiError("session_metadata_invalid", `Session worktree escapes sessions root: ${metadata.sessionId}`);
+    }
+
+    return absolute;
+  }
+
+  private async changedFiles(metadata: SessionMetadata, paths?: string[]): Promise<string[]> {
+    const worktreeRoot = this.worktreeRoot(metadata);
+    const diffPaths = diffPathspec(paths);
+
+    const results = await Promise.all([
+      this.git.run(["diff", "--name-only", "-z", metadata.baseCommit, "HEAD", "--", ...diffPaths], { cwd: worktreeRoot }),
+      this.pendingFileOutput(worktreeRoot, diffPaths)
+    ]);
+
+    const changedPaths = uniquePaths(results.flatMap(result => parseNulPaths(result.stdout)));
+    return paths === undefined ? changedPaths.filter(isAllowedSessionCommitPath) : uniqueWikiPaths(changedPaths);
+  }
+
+  private async pendingFiles(metadata: SessionMetadata, diffPaths: string[]): Promise<string[]> {
+    const worktreeRoot = this.worktreeRoot(metadata);
+    return uniquePaths(parseNulPaths((await this.pendingFileOutput(worktreeRoot, diffPaths)).stdout));
+  }
+
+  private async pendingFileOutput(worktreeRoot: string, diffPaths: string[]): Promise<{ stdout: string }> {
+    const results = await Promise.all([
+      this.git.run(["diff", "--name-only", "-z", "HEAD", "--", ...diffPaths], { cwd: worktreeRoot }),
+      this.git.run(["diff", "--name-only", "-z", "--cached", "HEAD", "--", ...diffPaths], { cwd: worktreeRoot }),
+      this.git.run(["ls-files", "-z", "--others", "--exclude-standard", "--", ...diffPaths], { cwd: worktreeRoot })
+    ]);
+
+    return {
+      stdout: results.map(result => result.stdout).join("")
+    };
+  }
+
+  private async touch(sessionId: string): Promise<void> {
+    await this.store.update(sessionId, metadata => ({
+      ...metadata,
+      updatedAt: new Date().toISOString()
+    }));
+  }
+}
+
+async function readOptional(filePath: string): Promise<string | undefined> {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if (isEnoent(error)) {
+      return undefined;
+    }
+
+    throw error;
+  }
+}
+
+async function ensureSafeWriteTarget(worktreeRoot: string, wikiPath: string, filePath: string): Promise<void> {
+  const wikiRootPath = path.join(worktreeRoot, "wiki");
+  await ensureDirectoryNotSymlink(worktreeRoot);
+  await ensureDirectoryNotSymlink(wikiRootPath);
+  const realWikiRoot = await realpath(wikiRootPath);
+  const relativePath = wikiPath.slice("wiki/".length);
+  const parentSegments = path.posix.dirname(relativePath).split("/").filter(segment => segment.length > 0 && segment !== ".");
+  let currentPath = wikiRootPath;
+
+  for (const segment of parentSegments) {
+    currentPath = path.join(currentPath, segment);
+
+    try {
+      const stat = await lstat(currentPath);
+
+      if (stat.isSymbolicLink()) {
+        throw new WikiError("invalid_path", `Path is a symlink: ${currentPath}`);
+      }
+    } catch (error) {
+      if (isEnoent(error)) {
+        break;
+      }
+
+      throw error;
+    }
+  }
+
+  try {
+    const stat = await lstat(filePath);
+
+    if (stat.isSymbolicLink()) {
+      throw new WikiError("invalid_path", `Path is a symlink: ${filePath}`);
+    }
+
+    const realTarget = await realpath(filePath);
+    ensureInsideRealWikiRoot(realWikiRoot, realTarget, filePath);
+  } catch (error) {
+    if (!isEnoent(error)) {
+      throw error;
+    }
+  }
+
+  const parentPath = path.dirname(filePath);
+  await mkdir(parentPath, { recursive: true });
+  const realParent = await realpath(parentPath);
+  ensureInsideRealWikiRoot(realWikiRoot, realParent, parentPath);
+}
+
+async function ensureDirectoryNotSymlink(directoryPath: string): Promise<void> {
+  let stat;
+
+  try {
+    stat = await lstat(directoryPath);
+  } catch (error) {
+    if (isEnoent(error)) {
+      throw new WikiError("invalid_path", `Directory does not exist: ${directoryPath}`);
+    }
+
+    throw error;
+  }
+
+  if (stat.isSymbolicLink()) {
+    throw new WikiError("invalid_path", `Path is a symlink: ${directoryPath}`);
+  }
+
+  if (!stat.isDirectory()) {
+    throw new WikiError("invalid_path", `Path is not a directory: ${directoryPath}`);
+  }
+}
+
+function ensureInsideRealWikiRoot(realWikiRoot: string, target: string, originalPath: string): void {
+  if (!target.startsWith(`${realWikiRoot}${path.sep}`) && target !== realWikiRoot) {
+    throw new WikiError("invalid_path", `Path escapes wiki root: ${originalPath}`);
+  }
+}
+
+function isEnoent(error: unknown): boolean {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}
+
+function contentSha(content: string): string {
+  return createHash("sha1").update(content).digest("hex");
+}
+
+function uniqueWikiPaths(paths: string[]): string[] {
+  return uniquePaths(paths).filter(isWikiMarkdownPath);
+}
+
+function uniquePaths(paths: string[]): string[] {
+  return [...new Set(paths)].sort();
+}
+
+function diffPathspec(paths?: string[]): string[] {
+  if (paths !== undefined) {
+    return [...new Set(paths.map(normalizeWikiPath))].sort();
+  }
+
+  return ["wiki", "sources"];
+}
+
+function parseNulPaths(output: string): string[] {
+  return output.length === 0 ? [] : output.split("\0").filter(path => path.length > 0);
+}
+
+function isWikiMarkdownPath(filePath: string): boolean {
+  return filePath.startsWith("wiki/") && filePath.endsWith(".md");
+}
+
+function isSourcePatchAttempt(filePath: string): boolean {
+  return filePath.replaceAll("\\", "/").startsWith("sources/");
+}
+
+function isSourcePath(filePath: string): boolean {
+  const segments = filePath.split("/");
+
+  if (segments.length < 3 || segments[0] !== "sources") {
+    return false;
+  }
+
+  try {
+    assertValidSourceId(segments[1]);
+  } catch {
+    return false;
+  }
+
+  if (segments.length === 3 && (segments[2] === "raw.md" || segments[2] === "metadata.json")) {
+    return true;
+  }
+
+  return (
+    segments.length >= 4 &&
+    segments[2] === "assets" &&
+    segments.slice(3).every(segment => segment.length > 0 && segment !== "." && segment !== "..")
+  );
+}
+
+function isAllowedSessionCommitPath(filePath: string): boolean {
+  return isWikiMarkdownPath(filePath) || isSourcePath(filePath);
+}
+
+function validationPaths(paths: string[]): string[] {
+  return uniqueWikiPaths(paths);
+}
+
+function affectedSourceIds(paths: string[]): string[] {
+  return uniquePaths(paths.filter(isSourcePath).map(filePath => filePath.split("/")[1]));
+}
+
+function affectedAssetSourceIds(paths: string[]): string[] {
+  return uniquePaths(
+    paths
+      .filter(filePath => isSourcePath(filePath) && filePath.split("/")[2] === "assets")
+      .map(filePath => filePath.split("/")[1])
+  );
+}
+
+function isSourceAssetPath(filePath: string, sourceId: string): boolean {
+  return filePath.startsWith(`sources/${sourceId}/assets/`) && isSourcePath(filePath);
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await lstat(filePath);
+    return true;
+  } catch (error) {
+    if (isEnoent(error)) {
+      return false;
+    }
+
+    throw error;
+  }
+}
+
+async function existingPathspecs(worktreeRoot: string, pathspecs: string[]): Promise<string[]> {
+  const existing = await Promise.all(
+    pathspecs.map(async pathspec => ({
+      pathspec,
+      exists: await pathExists(path.join(worktreeRoot, pathspec))
+    }))
+  );
+
+  return existing.filter(item => item.exists).map(item => item.pathspec);
+}
+
+function toWorkflowError(error: unknown, fallbackCode: "git_error" | "invalid_path" | "session_not_found"): WikiError {
+  if (error instanceof WikiError) {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    return new WikiError(fallbackCode, error.message);
+  }
+
+  return new WikiError(fallbackCode, String(error));
+}

package/packages/core/src/services/wiki-service.ts

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import matter from "gray-matter";
+import { resolveWorkspacePaths, type WorkspacePaths } from "../config/workspace-resolver.js";
+import { WikiError } from "../errors.js";
+import { GitService } from "../git/git-service.js";
+import { err, ok, type Result } from "../result.js";
+import { normalizeWikiPath, resolveInsideRoot } from "../validation/path-validator.js";
+
+export type WikiReadInput = {
+  path: string;
+  ref?: "stable" | string;
+  includeFrontmatter?: boolean;
+};
+
+export type WikiReadResult = {
+  path: string;
+  ref: "stable";
+  frontmatter?: Record<string, unknown>;
+  content: string;
+  sha: string;
+};
+
+export type ChannelStatusInput = {
+  channel?: "stable" | string;
+};
+
+export type ChannelStatusResult = {
+  channel: "stable";
+  branch: "wiki/stable";
+  commit: string;
+  worktree: string;
+  dirty: boolean;
+};
+
+export class WikiService {
+  private readonly paths: WorkspacePaths;
+  private readonly git: GitService;
+
+  constructor(workspaceRoot: string, git = new GitService()) {
+    this.paths = resolveWorkspacePaths(workspaceRoot);
+    this.git = git;
+  }
+
+  async read(input: WikiReadInput): Promise<Result<WikiReadResult>> {
+    if ((input.ref ?? "stable") !== "stable") {
+      return err(new WikiError("unsupported_channel", `Unsupported wiki ref: ${input.ref}`));
+    }
+
+    try {
+      const wikiPath = normalizeWikiPath(input.path);
+      const filePath = resolveInsideRoot(this.paths.stableWorktreePath, wikiPath);
+      await ensureRealPathInsideWikiRoot(filePath, this.paths.stableWorktreePath);
+      const raw = await readFile(filePath, "utf8");
+      const parsed = parseMarkdown(raw);
+
+      return ok({
+        path: wikiPath,
+        ref: "stable",
+        ...(input.includeFrontmatter ? { frontmatter: parsed.data } : {}),
+        content: parsed.content,
+        sha: contentSha(raw)
+      });
+    } catch (error) {
+      if (error instanceof WikiError) {
+        return err(error);
+      }
+
+      return err(new WikiError("invalid_path", error instanceof Error ? error.message : String(error)));
+    }
+  }
+
+  async channelStatus(input: ChannelStatusInput): Promise<Result<ChannelStatusResult>> {
+    if ((input.channel ?? "stable") !== "stable") {
+      return err(new WikiError("unsupported_channel", `Unsupported wiki channel: ${input.channel}`));
+    }
+
+    try {
+      const commit = (await this.git.run(["rev-parse", "HEAD"], { cwd: this.paths.stableWorktreePath })).stdout.trim();
+      const status = (await this.git.run(["status", "--short"], { cwd: this.paths.stableWorktreePath })).stdout.trim();
+
+      return ok({
+        channel: "stable",
+        branch: "wiki/stable",
+        commit,
+        worktree: this.paths.stableWorktreePath,
+        dirty: status.length > 0
+      });
+    } catch (error) {
+      if (error instanceof WikiError) {
+        return err(error);
+      }
+
+      return err(new WikiError("git_error", error instanceof Error ? error.message : String(error)));
+    }
+  }
+}
+
+function contentSha(content: string): string {
+  return createHash("sha1").update(content).digest("hex");
+}
+
+async function ensureRealPathInsideWikiRoot(filePath: string, stableWorktreePath: string): Promise<void> {
+  const wikiRoot = await realpath(path.join(stableWorktreePath, "wiki"));
+  const target = await realpath(filePath);
+
+  if (!target.startsWith(`${wikiRoot}${path.sep}`) && target !== wikiRoot) {
+    throw new WikiError("invalid_path", `Path escapes wiki root: ${filePath}`);
+  }
+}
+
+function parseMarkdown(raw: string): ReturnType<typeof matter> {
+  try {
+    return matter(raw);
+  } catch (error) {
+    throw new WikiError("invalid_frontmatter", error instanceof Error ? error.message : String(error));
+  }
+}