tgo-wiki 0.1.0

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

@@ -0,0 +1,223 @@
+import { access, mkdir, readFile, readdir, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { defaultConfig } from "../config/defaults.js";
+import { resolveWorkspacePaths, type WorkspacePaths } from "../config/workspace-resolver.js";
+import { toWikiError } from "../errors.js";
+import { GitService } from "../git/git-service.js";
+import { err, ok, type Result } from "../result.js";
+
+export type WorkspaceInitResult = {
+  workspaceRoot: string;
+  stableCommit: string;
+};
+
+export type WorkspaceStatus = {
+  workspaceRoot: string;
+  repoPath: string;
+  branch: string;
+  commit: string;
+  worktree: string;
+  dirty: boolean;
+  sessionCount: number;
+};
+
+const initialIndexPage = `---
+title: "Home"
+summary: "Entry point for the wiki."
+tags: ["home"]
+updated: "2026-06-11"
+---
+
+# Home
+
+Welcome to the wiki.
+`;
+
+export class WorkspaceService {
+  private readonly paths: WorkspacePaths;
+  private readonly git: GitService;
+
+  constructor(workspaceRoot: string, git = new GitService()) {
+    this.paths = resolveWorkspacePaths(workspaceRoot);
+    this.git = git;
+  }
+
+  async init(): Promise<Result<WorkspaceInitResult>> {
+    try {
+      await this.ensureWorkspaceDirs();
+      await this.ensureConfig();
+      await this.ensureRepo();
+      const stableCommit = await this.ensureStableBranch();
+      await this.ensureStableWorktree();
+      await this.ensureStableWorktreeReadable();
+
+      return ok({
+        workspaceRoot: this.paths.workspaceRoot,
+        stableCommit
+      });
+    } catch (error) {
+      return err(toWikiError(error, "git_error"));
+    }
+  }
+
+  async status(): Promise<Result<WorkspaceStatus>> {
+    try {
+      const commit = (await this.git.run(["rev-parse", defaultConfig.stableBranch], { cwd: this.paths.repoPath })).stdout.trim();
+      const porcelain = (
+        await this.git.run(["status", "--porcelain"], { cwd: this.paths.stableWorktreePath })
+      ).stdout.trim();
+      const sessions = await this.sessionCount();
+
+      return ok({
+        workspaceRoot: this.paths.workspaceRoot,
+        repoPath: this.paths.repoPath,
+        branch: defaultConfig.stableBranch,
+        commit,
+        worktree: this.paths.stableWorktreePath,
+        dirty: porcelain.length > 0,
+        sessionCount: sessions
+      });
+    } catch (error) {
+      return err(toWikiError(error, "git_error"));
+    }
+  }
+
+  private async ensureWorkspaceDirs(): Promise<void> {
+    await Promise.all([
+      mkdir(this.paths.repoPath, { recursive: true }),
+      mkdir(this.paths.statePath, { recursive: true }),
+      mkdir(this.paths.sessionsStatePath, { recursive: true }),
+      mkdir(this.paths.documentsStatePath, { recursive: true }),
+      mkdir(this.paths.documentBlobsPath, { recursive: true }),
+      mkdir(this.paths.pendingDocumentsPath, { recursive: true }),
+      mkdir(this.paths.worktreesPath, { recursive: true }),
+      mkdir(this.paths.sessionsWorktreePath, { recursive: true })
+    ]);
+  }
+
+  private async ensureConfig(): Promise<void> {
+    const configPath = path.join(this.paths.statePath, "config.json");
+
+    if (await exists(configPath)) {
+      return;
+    }
+
+    await writeFile(configPath, `${JSON.stringify(defaultConfig, null, 2)}\n`, "utf8");
+  }
+
+  private async ensureRepo(): Promise<void> {
+    if (!(await exists(path.join(this.paths.repoPath, ".git")))) {
+      await this.git.run(["init"], { cwd: this.paths.repoPath });
+    }
+
+    if (!(await this.hasCommits())) {
+      await this.git.run(["symbolic-ref", "HEAD", `refs/heads/${defaultConfig.repoManagementBranch}`], {
+        cwd: this.paths.repoPath
+      });
+      await this.writeInitialPage();
+      await this.git.commit(this.paths.repoPath, "chore: initialize wiki");
+      return;
+    }
+
+    if (!(await this.branchExists(defaultConfig.repoManagementBranch))) {
+      await this.git.run(["branch", defaultConfig.repoManagementBranch, "HEAD"], { cwd: this.paths.repoPath });
+    }
+
+    await this.git.run(["checkout", defaultConfig.repoManagementBranch], { cwd: this.paths.repoPath });
+  }
+
+  private async writeInitialPage(): Promise<void> {
+    const wikiPath = path.join(this.paths.repoPath, this.paths.wikiRootName);
+    await mkdir(wikiPath, { recursive: true });
+    await writeFile(path.join(wikiPath, "index.md"), initialIndexPage, "utf8");
+  }
+
+  private async ensureStableBranch(): Promise<string> {
+    const head = (await this.git.run(["rev-parse", "HEAD"], { cwd: this.paths.repoPath })).stdout.trim();
+
+    if (!(await this.branchExists(defaultConfig.stableBranch))) {
+      await this.git.run(["branch", defaultConfig.stableBranch, head], { cwd: this.paths.repoPath });
+    }
+
+    return (await this.git.run(["rev-parse", defaultConfig.stableBranch], { cwd: this.paths.repoPath })).stdout.trim();
+  }
+
+  private async ensureStableWorktree(): Promise<void> {
+    if (await this.hasWorktree(this.paths.stableWorktreePath)) {
+      return;
+    }
+
+    await this.git.run(["worktree", "add", this.paths.stableWorktreePath, defaultConfig.stableBranch], {
+      cwd: this.paths.repoPath
+    });
+  }
+
+  private async ensureStableWorktreeReadable(): Promise<void> {
+    await readFile(path.join(this.paths.stableWorktreePath, this.paths.wikiRootName, "index.md"), "utf8");
+  }
+
+  private async hasCommits(): Promise<boolean> {
+    try {
+      await this.git.run(["rev-parse", "--verify", "HEAD"], { cwd: this.paths.repoPath });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private async branchExists(branch: string): Promise<boolean> {
+    try {
+      await this.git.run(["rev-parse", "--verify", `refs/heads/${branch}`], { cwd: this.paths.repoPath });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private async hasWorktree(worktreePath: string): Promise<boolean> {
+    const expectedPath = await canonicalPath(worktreePath);
+    const list = await this.git.run(["worktree", "list", "--porcelain"], { cwd: this.paths.repoPath });
+    const worktrees = list.stdout
+      .split("\n")
+      .filter(line => line.startsWith("worktree "))
+      .map(line => line.slice("worktree ".length));
+
+    for (const worktree of worktrees) {
+      if ((await canonicalPath(worktree)) === expectedPath) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  private async sessionCount(): Promise<number> {
+    try {
+      const entries = await readdir(this.paths.sessionsStatePath, { withFileTypes: true });
+      return entries.filter(entry => entry.isFile() && entry.name.endsWith(".json")).length;
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+        return 0;
+      }
+
+      throw error;
+    }
+  }
+}
+
+async function exists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function canonicalPath(filePath: string): Promise<string> {
+  try {
+    return await realpath(filePath);
+  } catch {
+    return path.resolve(filePath);
+  }
+}

package/packages/core/src/session/session-id.ts

@@ -0,0 +1,14 @@
+import { randomBytes } from "node:crypto";
+import { WikiError } from "../errors.js";
+
+export function generateSessionId(now = new Date()): string {
+  const date = now.toISOString().slice(0, 10).replaceAll("-", "");
+  const suffix = randomBytes(4).toString("hex");
+  return `${date}-${suffix}`;
+}
+
+export function assertValidSessionId(sessionId: string): void {
+  if (!/^[a-zA-Z0-9._-]+$/.test(sessionId)) {
+    throw new WikiError("session_not_found", `Invalid session id: ${sessionId}`);
+  }
+}

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

@@ -0,0 +1,77 @@
+import path from "node:path";
+import { defaultConfig } from "../config/defaults.js";
+import { resolveWorkspacePaths, type WorkspacePaths } from "../config/workspace-resolver.js";
+import { toWikiError } from "../errors.js";
+import { GitService } from "../git/git-service.js";
+import { err, ok, type Result } from "../result.js";
+import { assertValidSessionId, generateSessionId } from "./session-id.js";
+import { SessionStore } from "./session-store.js";
+import type { SessionMetadata } from "./session-types.js";
+
+export type SessionStartInput = {
+  baseRef?: "stable" | string;
+  purpose?: string;
+  agentId?: string;
+};
+
+export type SessionStartResult = {
+  sessionId: string;
+  branch: string;
+  worktree: string;
+  baseRef: string;
+  baseCommit: string;
+};
+
+export class SessionService {
+  private readonly paths: WorkspacePaths;
+  private readonly store: SessionStore;
+
+  constructor(
+    workspaceRoot: string,
+    private readonly idGenerator = generateSessionId,
+    private readonly git = new GitService()
+  ) {
+    this.paths = resolveWorkspacePaths(workspaceRoot);
+    this.store = new SessionStore(this.paths);
+  }
+
+  async start(input: SessionStartInput = {}): Promise<Result<SessionStartResult>> {
+    try {
+      const baseRef = input.baseRef ?? "stable";
+      const gitBaseRef = baseRef === "stable" ? defaultConfig.stableBranch : baseRef;
+      const baseCommit = (await this.git.run(["rev-parse", gitBaseRef], { cwd: this.paths.repoPath })).stdout.trim();
+      const sessionId = this.idGenerator();
+      assertValidSessionId(sessionId);
+
+      const branch = `wiki/session/${sessionId}`;
+      const worktree = path.join(this.paths.sessionsWorktreePath, sessionId);
+
+      await this.git.run(["worktree", "add", "-b", branch, worktree, baseCommit], { cwd: this.paths.repoPath });
+
+      const now = new Date().toISOString();
+      const metadata: SessionMetadata = {
+        sessionId,
+        agentId: input.agentId,
+        purpose: input.purpose,
+        baseRef,
+        baseCommit,
+        branch,
+        worktree: path.relative(this.paths.workspaceRoot, worktree),
+        createdAt: now,
+        updatedAt: now,
+        status: "open"
+      };
+      await this.store.write(metadata);
+
+      return ok({
+        sessionId,
+        branch,
+        worktree,
+        baseRef,
+        baseCommit
+      });
+    } catch (error) {
+      return err(toWikiError(error, "git_error"));
+    }
+  }
+}

package/packages/core/src/session/session-store.ts

@@ -0,0 +1,91 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { WorkspacePaths } from "../config/workspace-resolver.js";
+import { WikiError } from "../errors.js";
+import { assertValidSessionId } from "./session-id.js";
+import type { SessionMetadata, SessionStatus } from "./session-types.js";
+
+export class SessionStore {
+  constructor(private readonly paths: WorkspacePaths) {}
+
+  async read(sessionId: string): Promise<SessionMetadata> {
+    assertValidSessionId(sessionId);
+
+    let raw: string;
+    try {
+      raw = await readFile(this.metadataPath(sessionId), "utf8");
+    } catch (error) {
+      throw new WikiError("session_not_found", `Session metadata not found: ${sessionId}`, {
+        cause: error instanceof Error ? error.message : String(error)
+      });
+    }
+
+    let metadata: unknown;
+    try {
+      metadata = JSON.parse(raw);
+    } catch (error) {
+      throw new WikiError("session_metadata_invalid", `Session metadata is malformed JSON: ${sessionId}`, {
+        cause: error instanceof Error ? error.message : String(error)
+      });
+    }
+
+    if (!isSessionMetadata(metadata, sessionId)) {
+      throw new WikiError("session_metadata_invalid", `Session metadata is invalid: ${sessionId}`);
+    }
+
+    return metadata;
+  }
+
+  async write(metadata: SessionMetadata): Promise<void> {
+    assertValidSessionId(metadata.sessionId);
+    await mkdir(this.paths.sessionsStatePath, { recursive: true });
+    await writeFile(this.metadataPath(metadata.sessionId), `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
+  }
+
+  async update(sessionId: string, update: (metadata: SessionMetadata) => SessionMetadata): Promise<SessionMetadata> {
+    const current = await this.read(sessionId);
+    const next = update(current);
+    await this.write(next);
+    return next;
+  }
+
+  metadataPath(sessionId: string): string {
+    assertValidSessionId(sessionId);
+    return path.join(this.paths.sessionsStatePath, `${sessionId}.json`);
+  }
+}
+
+function isSessionMetadata(value: unknown, sessionId: string): value is SessionMetadata {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+
+  const metadata = value as Partial<SessionMetadata>;
+  return (
+    metadata.sessionId === sessionId &&
+    isString(metadata.baseRef) &&
+    isString(metadata.baseCommit) &&
+    isString(metadata.branch) &&
+    isString(metadata.worktree) &&
+    isString(metadata.createdAt) &&
+    isString(metadata.updatedAt) &&
+    isSessionStatus(metadata.status) &&
+    isOptionalString(metadata.agentId) &&
+    isOptionalString(metadata.purpose) &&
+    isOptionalString(metadata.lastCommit) &&
+    isOptionalString(metadata.publishedAt) &&
+    isOptionalString(metadata.publishedCommit)
+  );
+}
+
+function isSessionStatus(value: unknown): value is SessionStatus {
+  return value === "open" || value === "published" || value === "abandoned";
+}
+
+function isString(value: unknown): value is string {
+  return typeof value === "string";
+}
+
+function isOptionalString(value: unknown): value is string | undefined {
+  return value === undefined || typeof value === "string";
+}

package/packages/core/src/session/session-types.ts

@@ -0,0 +1,17 @@
+export type SessionStatus = "open" | "published" | "abandoned";
+
+export type SessionMetadata = {
+  sessionId: string;
+  agentId?: string;
+  purpose?: string;
+  baseRef: string;
+  baseCommit: string;
+  branch: string;
+  worktree: string;
+  createdAt: string;
+  updatedAt: string;
+  status: SessionStatus;
+  lastCommit?: string;
+  publishedAt?: string;
+  publishedCommit?: string;
+};

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

@@ -0,0 +1,19 @@
+import path from "node:path";
+import { WikiError } from "../errors.js";
+
+const sourceIdPattern = /^[a-zA-Z0-9._-]+$/;
+
+export function assertValidSourceId(id: string): void {
+  if (
+    id.length === 0 ||
+    !sourceIdPattern.test(id) ||
+    id.includes("/") ||
+    id.includes("\\") ||
+    id === "." ||
+    id === ".." ||
+    path.isAbsolute(id) ||
+    path.win32.isAbsolute(id)
+  ) {
+    throw new WikiError("invalid_path", `Invalid source id: ${id}`);
+  }
+}

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

@@ -0,0 +1,15 @@
+import path from "node:path";
+import { assertValidSourceId } from "./source-id.js";
+
+export function sourceDirectory(worktreeRoot: string, id: string): string {
+  assertValidSourceId(id);
+  return path.join(worktreeRoot, "sources", id);
+}
+
+export function sourceMetadataPath(worktreeRoot: string, id: string): string {
+  return path.join(sourceDirectory(worktreeRoot, id), "metadata.json");
+}
+
+export function sourceRawMarkdownPath(worktreeRoot: string, id: string): string {
+  return path.join(sourceDirectory(worktreeRoot, id), "raw.md");
+}