@knpkv/confluence-to-markdown 0.2.0 → 0.4.1

package/src/internal/NodeLayers.ts

@@ -0,0 +1,21 @@
+/**
+ * Node.js-specific layer implementations.
+ *
+ * This is the ONLY file that should import directly from node:* modules.
+ * All other code should use Effect platform abstractions.
+ *
+ * @module
+ * @internal
+ */
+import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer"
+import { createServer } from "node:http"
+import { makeHttpServerFactory } from "./oauthServer.js"
+
+/**
+ * HTTP Server factory layer using Node.js http module.
+ *
+ * @category Layers
+ */
+export const HttpServerFactoryLive = makeHttpServerFactory(
+  (port) => NodeHttpServer.layerServer(createServer, { port })
+)

package/src/internal/frontmatter.ts

@@ -96,3 +96,24 @@ export const serializeMarkdown = (
 
   return matter.stringify(content, fm)
 }
+
+/**
+ * Serialize a new page markdown with minimal front-matter.
+ *
+ * @param frontMatter - The new page front-matter (title only)
+ * @param content - The markdown content
+ * @returns The serialized markdown file content
+ *
+ * @internal
+ */
+export const serializeNewPageMarkdown = (
+  frontMatter: NewPageFrontMatter,
+  content: string
+): string => {
+  const fm = {
+    title: frontMatter.title,
+    ...(frontMatter.parentId !== undefined ? { parentId: frontMatter.parentId } : {})
+  }
+
+  return matter.stringify(content, fm)
+}

package/src/internal/gitCommands.ts

@@ -0,0 +1,229 @@
+/**
+ * Git shell command helpers.
+ *
+ * @module
+ * @internal
+ */
+import * as Command from "@effect/platform/Command"
+import type * as CommandExecutor from "@effect/platform/CommandExecutor"
+import type * as PlatformError from "@effect/platform/Error"
+import * as Effect from "effect/Effect"
+import * as String from "effect/String"
+import { GitError, GitNotInstalledError } from "../GitError.js"
+
+/**
+ * Git file status codes from `git status --porcelain`.
+ */
+export type GitFileStatus =
+  | "modified"
+  | "added"
+  | "deleted"
+  | "renamed"
+  | "copied"
+  | "untracked"
+  | "ignored"
+  | "unmerged"
+
+/**
+ * Parsed git status entry.
+ */
+export interface GitStatusEntry {
+  readonly status: GitFileStatus
+  readonly path: string
+  readonly staged: boolean
+}
+
+/**
+ * Parsed git log entry.
+ */
+export interface GitLogEntry {
+  readonly hash: string
+  readonly author: string
+  readonly email: string
+  readonly date: Date
+  readonly message: string
+}
+
+/**
+ * Convert PlatformError to GitError or GitNotInstalledError.
+ */
+const mapPlatformError = (
+  error: PlatformError.PlatformError,
+  commandStr: string
+): GitError | GitNotInstalledError => {
+  if (error._tag === "SystemError" && error.reason === "NotFound") {
+    return new GitNotInstalledError({
+      message: `Git not found: ${error.message}. Please install git.`
+    })
+  }
+  return new GitError({
+    command: commandStr,
+    message: error.message
+  })
+}
+
+/**
+ * Run a git command in the specified working directory.
+ *
+ * @param args - Git command arguments
+ * @param cwd - Working directory
+ * @returns Command output
+ *
+ * @internal
+ */
+export const runGit = (
+  args: ReadonlyArray<string>,
+  cwd: string
+): Effect.Effect<string, GitError | GitNotInstalledError, CommandExecutor.CommandExecutor> =>
+  Effect.gen(function*() {
+    const command = Command.make("git", ...args).pipe(
+      Command.workingDirectory(cwd)
+    )
+
+    const commandStr = `git ${args.join(" ")}`
+
+    const result = yield* Command.string(command).pipe(
+      Effect.mapError((error) => mapPlatformError(error, commandStr))
+    )
+
+    return result
+  })
+
+/**
+ * Run a git command that may fail with exit code 1 (e.g., diff with no changes).
+ * Returns empty string on exit code 1.
+ *
+ * @internal
+ */
+export const runGitAllowEmpty = (
+  args: ReadonlyArray<string>,
+  cwd: string
+): Effect.Effect<string, GitError | GitNotInstalledError, CommandExecutor.CommandExecutor> =>
+  runGit(args, cwd).pipe(
+    Effect.catchIf(
+      (e): e is GitError => e._tag === "GitError",
+      () => Effect.succeed("")
+    )
+  )
+
+/**
+ * Parse git status --porcelain output.
+ *
+ * @param output - Raw output from `git status --porcelain`
+ * @returns Parsed status entries
+ *
+ * @internal
+ */
+export const parseGitStatus = (output: string): ReadonlyArray<GitStatusEntry> => {
+  if (String.isEmpty(output.trim())) {
+    return []
+  }
+
+  return output
+    .split("\n")
+    .filter((line) => line.length >= 3) // Valid lines have XY + space + path
+    .map((line) => {
+      const indexStatus = line[0] ?? " "
+      const workTreeStatus = line[1] ?? " "
+      const path = line.slice(3)
+
+      const staged = indexStatus !== " " && indexStatus !== "?"
+      const status = parseStatusCode(staged ? indexStatus : workTreeStatus)
+
+      return { status, path, staged }
+    })
+}
+
+/**
+ * Parse a single status code character.
+ */
+const parseStatusCode = (code: string): GitFileStatus => {
+  switch (code) {
+    case "M":
+      return "modified"
+    case "A":
+      return "added"
+    case "D":
+      return "deleted"
+    case "R":
+      return "renamed"
+    case "C":
+      return "copied"
+    case "?":
+      return "untracked"
+    case "!":
+      return "ignored"
+    case "U":
+      return "unmerged"
+    default:
+      return "modified"
+  }
+}
+
+/**
+ * Parse git log output with custom format.
+ *
+ * Uses format: hash<|>author<|>email<|>date<|>message
+ *
+ * @param output - Raw output from git log
+ * @returns Parsed log entries
+ *
+ * @internal
+ */
+export const parseGitLog = (output: string): ReadonlyArray<GitLogEntry> => {
+  if (String.isEmpty(output.trim())) {
+    return []
+  }
+
+  return output
+    .trim()
+    .split("\n")
+    .flatMap((line) => {
+      const parts = line.split("<|>")
+      if (parts.length < 5) {
+        return []
+      }
+
+      const hash = parts[0]
+      const author = parts[1]
+      const email = parts[2]
+      const dateStr = parts[3]
+      const messageParts = parts.slice(4)
+
+      if (hash === undefined || author === undefined || email === undefined || dateStr === undefined) {
+        return []
+      }
+
+      const message = messageParts.join("<|>")
+
+      return [{
+        hash: hash.trim(),
+        author: author.trim(),
+        email: email.trim(),
+        date: new Date(dateStr.trim()),
+        message: message.trim()
+      }]
+    })
+}
+
+/**
+ * Git log format string for parseGitLog.
+ *
+ * @internal
+ */
+export const GIT_LOG_FORMAT = "%H<|>%an<|>%ae<|>%aI<|>%s"
+
+/**
+ * Check if output indicates merge conflicts.
+ *
+ * @param statusOutput - Output from `git status --porcelain`
+ * @returns List of conflicted files
+ *
+ * @internal
+ */
+export const getConflictedFiles = (statusOutput: string): ReadonlyArray<string> => {
+  const entries = parseGitStatus(statusOutput)
+  return entries
+    .filter((e) => e.status === "unmerged")
+    .map((e) => e.path)
+}

package/src/internal/hashUtils.ts

@@ -4,9 +4,68 @@
  * @module
  * @internal
  */
-import * as crypto from "node:crypto"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
 import type { ContentHash } from "../Brand.js"
 
+/**
+ * Hash computation service.
+ * This allows mocking in tests.
+ *
+ * @category Services
+ */
+export interface HashService {
+  readonly computeSha256: (content: string) => Effect.Effect<ContentHash>
+}
+
+/**
+ * Tag for the HashService.
+ *
+ * @category Services
+ */
+export class HashServiceTag extends Context.Tag("@knpkv/confluence-to-markdown/HashService")<
+  HashServiceTag,
+  HashService
+>() {}
+
+/**
+ * Create a HashService layer from a hash function.
+ * This allows injecting platform-specific implementations.
+ *
+ * @param hashFn - Function that computes SHA256 hash
+ * @category Layers
+ */
+export const makeHashServiceLive = (
+  hashFn: (content: string) => Promise<string>
+): Layer.Layer<HashServiceTag> =>
+  Layer.succeed(
+    HashServiceTag,
+    {
+      computeSha256: (content: string) =>
+        Effect.promise(() => hashFn(content)).pipe(
+          Effect.map((hash) => hash as ContentHash)
+        )
+    }
+  )
+
+/**
+ * Default implementation using Web Crypto API (available in all modern runtimes).
+ *
+ * @category Layers
+ */
+export const HashServiceLive: Layer.Layer<HashServiceTag> = makeHashServiceLive(
+  async (content: string) => {
+    const encoder = new TextEncoder()
+    const data = encoder.encode(content)
+    const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", data)
+    const hashArray = new Uint8Array(hashBuffer)
+    return Array.from(hashArray)
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("")
+  }
+)
+
 /**
  * Compute SHA256 hash of content.
  *
@@ -15,5 +74,8 @@ import type { ContentHash } from "../Brand.js"
  *
  * @internal
  */
-export const computeHash = (content: string): ContentHash =>
-  crypto.createHash("sha256").update(content, "utf8").digest("hex") as ContentHash
+export const computeHash = (content: string): Effect.Effect<ContentHash, never, HashServiceTag> =>
+  Effect.gen(function*() {
+    const hashService = yield* HashServiceTag
+    return yield* hashService.computeSha256(content)
+  })

package/src/internal/oauthServer.ts

@@ -0,0 +1,199 @@
+/**
+ * Local HTTP server for OAuth callback.
+ *
+ * @module
+ */
+import * as HttpRouter from "@effect/platform/HttpRouter"
+import * as HttpServer from "@effect/platform/HttpServer"
+import type { ServeError } from "@effect/platform/HttpServerError"
+import * as HttpServerRequest from "@effect/platform/HttpServerRequest"
+import * as HttpServerResponse from "@effect/platform/HttpServerResponse"
+import * as Context from "effect/Context"
+import * as Deferred from "effect/Deferred"
+import * as Effect from "effect/Effect"
+import * as Fiber from "effect/Fiber"
+import * as Layer from "effect/Layer"
+import { OAuthError } from "../ConfluenceError.js"
+
+const DEFAULT_PORT = 8585
+const MAX_PORT_ATTEMPTS = 10
+
+/**
+ * Factory service for creating HTTP servers.
+ * This allows mocking the server creation in tests.
+ *
+ * @category Services
+ */
+export interface HttpServerFactory {
+  readonly createServerLayer: (port: number) => Layer.Layer<
+    HttpServer.HttpServer,
+    ServeError,
+    never
+  >
+}
+
+/**
+ * Tag for the HttpServerFactory service.
+ *
+ * @category Services
+ */
+export class HttpServerFactoryTag extends Context.Tag("@knpkv/confluence-to-markdown/HttpServerFactory")<
+  HttpServerFactoryTag,
+  HttpServerFactory
+>() {}
+
+/**
+ * Create a HttpServerFactory layer from a layer factory function.
+ * This allows injecting platform-specific implementations.
+ *
+ * @param createLayerFn - Function that creates HttpServer layer for a given port
+ * @returns Layer providing HttpServerFactory
+ *
+ * @category Layers
+ */
+export const makeHttpServerFactory = (
+  createLayerFn: (port: number) => Layer.Layer<HttpServer.HttpServer, ServeError, never>
+): Layer.Layer<HttpServerFactoryTag> =>
+  Layer.succeed(HttpServerFactoryTag, {
+    createServerLayer: createLayerFn
+  })
+
+/**
+ * Check if a port is available by attempting to start a server.
+ */
+const isPortAvailable = (port: number): Effect.Effect<boolean, never, HttpServerFactoryTag> =>
+  Effect.gen(function*() {
+    const factory = yield* HttpServerFactoryTag
+    const serverLayer = factory.createServerLayer(port)
+
+    // Try to acquire and immediately release
+    const result = yield* Layer.build(serverLayer).pipe(
+      Effect.scoped,
+      Effect.as(true),
+      Effect.catchAll(() => Effect.succeed(false))
+    )
+    return result
+  })
+
+/**
+ * Find an available port starting from the default.
+ */
+const findAvailablePort = (): Effect.Effect<number, OAuthError, HttpServerFactoryTag> =>
+  Effect.gen(function*() {
+    for (let attempt = 0; attempt < MAX_PORT_ATTEMPTS; attempt++) {
+      const port = DEFAULT_PORT + attempt
+      const available = yield* isPortAvailable(port)
+      if (available) {
+        return port
+      }
+    }
+    return yield* Effect.fail(
+      new OAuthError({
+        step: "authorize",
+        cause: `Could not find available port (tried ${DEFAULT_PORT}-${
+          DEFAULT_PORT + MAX_PORT_ATTEMPTS - 1
+        }). Close other applications using these ports.`
+      })
+    )
+  })
+
+/**
+ * Result from the OAuth callback server.
+ */
+export interface CallbackServerResult {
+  /** Promise that resolves with the authorization code */
+  readonly codePromise: Effect.Effect<string, OAuthError>
+  /** Shutdown the callback server */
+  readonly shutdown: Effect.Effect<void, never>
+  /** The port the server is listening on */
+  readonly port: number
+}
+
+/**
+ * Start a local HTTP server to receive OAuth callback.
+ *
+ * @param expectedState - The state parameter to verify against CSRF
+ * @returns Server control interface with code promise, shutdown, and port
+ *
+ * @category OAuth
+ */
+export const startCallbackServer = (
+  expectedState: string
+): Effect.Effect<CallbackServerResult, OAuthError, HttpServerFactoryTag> =>
+  Effect.gen(function*() {
+    const factory = yield* HttpServerFactoryTag
+    const port = yield* findAvailablePort()
+    const deferred = yield* Deferred.make<string, OAuthError>()
+    const readyDeferred = yield* Deferred.make<void, OAuthError>()
+
+    const app = HttpRouter.empty.pipe(
+      HttpRouter.get(
+        "/callback",
+        Effect.gen(function*() {
+          const req = yield* HttpServerRequest.HttpServerRequest
+          const url = new URL(req.url, `http://localhost:${port}`)
+          const code = url.searchParams.get("code")
+          const state = url.searchParams.get("state")
+          const error = url.searchParams.get("error")
+          const errorDescription = url.searchParams.get("error_description")
+
+          if (error) {
+            yield* Deferred.fail(
+              deferred,
+              new OAuthError({ step: "authorize", cause: errorDescription || error })
+            )
+            return HttpServerResponse.html(
+              "<html><body><h1>Authorization Failed</h1><p>You can close this window.</p></body></html>"
+            )
+          }
+
+          if (state !== expectedState) {
+            yield* Deferred.fail(
+              deferred,
+              new OAuthError({ step: "authorize", cause: "State mismatch - possible CSRF attack" })
+            )
+            return HttpServerResponse.html(
+              "<html><body><h1>Security Error</h1><p>State verification failed.</p></body></html>"
+            )
+          }
+
+          if (!code) {
+            yield* Deferred.fail(
+              deferred,
+              new OAuthError({ step: "authorize", cause: "No authorization code received" })
+            )
+            return HttpServerResponse.html(
+              "<html><body><h1>Error</h1><p>No authorization code received.</p></body></html>"
+            )
+          }
+
+          yield* Deferred.succeed(deferred, code)
+          return HttpServerResponse.html(
+            "<html><body><h1>Success!</h1><p>You can close this window and return to the terminal.</p></body></html>"
+          )
+        })
+      )
+    )
+
+    const serverLayer = factory.createServerLayer(port)
+
+    const serverFiber = yield* HttpServer.serve(app).pipe(
+      Layer.provide(serverLayer),
+      Layer.build,
+      Effect.tap(() => Deferred.succeed(readyDeferred, undefined)),
+      Effect.tapError((err) => Deferred.fail(readyDeferred, new OAuthError({ step: "authorize", cause: err }))),
+      // Keep the layer alive until fiber is interrupted
+      Effect.flatMap(() => Effect.never),
+      Effect.scoped,
+      Effect.fork
+    )
+
+    // Wait for server to be ready (or fail)
+    yield* Deferred.await(readyDeferred)
+
+    return {
+      codePromise: Deferred.await(deferred),
+      shutdown: Fiber.interrupt(serverFiber).pipe(Effect.asVoid),
+      port
+    }
+  })

package/src/internal/pathUtils.ts

@@ -4,7 +4,8 @@
  * @module
  * @internal
  */
-import * as path from "node:path"
+import * as Path from "@effect/platform/Path"
+import * as Effect from "effect/Effect"
 
 /**
  * Convert a page title to a URL-safe slug.
@@ -31,8 +32,17 @@ export const slugify = (title: string): string => {
 /**
  * Convert a page to a local file path.
  *
+ * Pages are always stored as `slug.md`. If a page has children,
+ * the children are stored in a `slug/` directory alongside the parent file.
+ *
+ * Example structure:
+ * - guide.md           (page with children)
+ * - guide/             (directory for children)
+ *   - getting-started.md
+ *   - advanced.md
+ *
  * @param title - The page title
- * @param hasChildren - Whether the page has child pages
+ * @param _hasChildren - Whether the page has child pages (unused, kept for API compat)
  * @param parentPath - The parent directory path
  * @returns The local file path for the page
  *
@@ -40,14 +50,15 @@ export const slugify = (title: string): string => {
  */
 export const pageToPath = (
   title: string,
-  hasChildren: boolean,
+  _hasChildren: boolean,
   parentPath: string
-): string => {
-  const slug = slugify(title)
-  return hasChildren
-    ? path.join(parentPath, slug, "index.md")
-    : path.join(parentPath, `${slug}.md`)
-}
+): Effect.Effect<string, never, Path.Path> =>
+  Effect.gen(function*() {
+    const path = yield* Path.Path
+    const slug = slugify(title)
+    // Always use slug.md, children go in slug/ directory
+    return path.join(parentPath, `${slug}.md`)
+  })
 
 /**
  * Get the directory path for a page (used when creating children).
@@ -58,10 +69,15 @@ export const pageToPath = (
  *
  * @internal
  */
-export const pageToDir = (title: string, parentPath: string): string => {
-  const slug = slugify(title)
-  return path.join(parentPath, slug)
-}
+export const pageToDir = (
+  title: string,
+  parentPath: string
+): Effect.Effect<string, never, Path.Path> =>
+  Effect.gen(function*() {
+    const path = yield* Path.Path
+    const slug = slugify(title)
+    return path.join(parentPath, slug)
+  })
 
 /**
  * Extract page slug from a file path.
@@ -71,7 +87,8 @@ export const pageToDir = (title: string, parentPath: string): string => {
  *
  * @internal
  */
-export const pathToSlug = (filePath: string): string => {
-  const basename = path.basename(filePath, ".md")
-  return basename === "index" ? path.basename(path.dirname(filePath)) : basename
-}
+export const pathToSlug = (filePath: string): Effect.Effect<string, never, Path.Path> =>
+  Effect.gen(function*() {
+    const path = yield* Path.Path
+    return path.basename(filePath, ".md")
+  })