@knpkv/confluence-to-markdown 0.2.0 → 0.4.2

package/src/ConfluenceError.ts

@@ -26,7 +26,15 @@ import * as Data from "effect/Data"
  */
 export class ConfigNotFoundError extends Data.TaggedError("ConfigNotFoundError")<{
   readonly path: string
-}> {}
+  readonly message: string
+}> {
+  constructor(params: { path: string }) {
+    super({
+      path: params.path,
+      message: `Config not found: ${params.path}\nRun 'confluence clone' to initialize.`
+    })
+  }
+}
 
 /**
  * Error thrown when .confluence.json parsing fails.
@@ -36,7 +44,16 @@ export class ConfigNotFoundError extends Data.TaggedError("ConfigNotFoundError")
 export class ConfigParseError extends Data.TaggedError("ConfigParseError")<{
   readonly path: string
   readonly cause: unknown
-}> {}
+  readonly message: string
+}> {
+  constructor(params: { path: string; cause: unknown }) {
+    super({
+      path: params.path,
+      cause: params.cause,
+      message: `Invalid config file: ${params.path}`
+    })
+  }
+}
 
 /**
  * Error thrown when configuration validation fails.
@@ -58,8 +75,8 @@ export class ConfigError extends Data.TaggedError("ConfigError")<{
  * Effect.gen(function* () {
  *   // ... operation that needs auth
  * }).pipe(
- *   Effect.catchTag("AuthMissingError", () =>
- *     Effect.sync(() => console.error("Set CONFLUENCE_API_KEY or run: confluence auth login"))
+ *   Effect.catchTag("AuthMissingError", (error) =>
+ *     Effect.sync(() => console.error(error.message))
  *   )
  * )
  * ```
@@ -69,8 +86,11 @@ export class ConfigError extends Data.TaggedError("ConfigError")<{
 export class AuthMissingError extends Data.TaggedError("AuthMissingError")<{
   readonly message: string
 }> {
-  constructor() {
-    super({ message: "CONFLUENCE_API_KEY env var or OAuth2 credentials required" })
+  constructor(params?: { message?: string }) {
+    super({
+      message: params?.message ??
+        "Not authenticated. Run 'confluence login' or set CONFLUENCE_API_KEY + CONFLUENCE_EMAIL"
+    })
   }
 }
 
@@ -92,8 +112,16 @@ export class ApiError extends Data.TaggedError("ApiError")<{
  * @category Errors
  */
 export class RateLimitError extends Data.TaggedError("RateLimitError")<{
-  readonly retryAfter?: number
-}> {}
+  readonly retryAfter?: number | undefined
+  readonly message: string
+}> {
+  constructor(params?: { retryAfter?: number }) {
+    const message = params?.retryAfter
+      ? `Rate limited. Retry after ${params.retryAfter}s.`
+      : "Rate limited. Please wait and try again."
+    super({ retryAfter: params?.retryAfter, message })
+  }
+}
 
 /**
  * Error thrown when HTML/Markdown conversion fails.
@@ -103,7 +131,16 @@ export class RateLimitError extends Data.TaggedError("RateLimitError")<{
 export class ConversionError extends Data.TaggedError("ConversionError")<{
   readonly direction: "htmlToMarkdown" | "markdownToHtml"
   readonly cause: unknown
-}> {}
+  readonly message: string
+}> {
+  constructor(params: { direction: "htmlToMarkdown" | "markdownToHtml"; cause: unknown }) {
+    super({
+      direction: params.direction,
+      cause: params.cause,
+      message: `Conversion failed (${params.direction}): ${params.cause}`
+    })
+  }
+}
 
 /**
  * Error thrown when sync conflict is detected.
@@ -115,7 +152,15 @@ export class ConflictError extends Data.TaggedError("ConflictError")<{
   readonly localVersion: number
   readonly remoteVersion: number
   readonly path: string
-}> {}
+  readonly message: string
+}> {
+  constructor(params: { pageId: string; localVersion: number; remoteVersion: number; path: string }) {
+    super({
+      ...params,
+      message: `Conflict: ${params.path} (local v${params.localVersion} vs remote v${params.remoteVersion})`
+    })
+  }
+}
 
 /**
  * Error thrown when file system operation fails.
@@ -126,7 +171,15 @@ export class FileSystemError extends Data.TaggedError("FileSystemError")<{
   readonly operation: "read" | "write" | "delete" | "mkdir" | "rename"
   readonly path: string
   readonly cause: unknown
-}> {}
+  readonly message: string
+}> {
+  constructor(params: { operation: "read" | "write" | "delete" | "mkdir" | "rename"; path: string; cause: unknown }) {
+    super({
+      ...params,
+      message: `File ${params.operation} failed: ${params.path}`
+    })
+  }
+}
 
 /**
  * Error thrown when OAuth2 flow fails.
@@ -134,9 +187,17 @@ export class FileSystemError extends Data.TaggedError("FileSystemError")<{
  * @category Errors
  */
 export class OAuthError extends Data.TaggedError("OAuthError")<{
-  readonly step: "authorize" | "token" | "refresh"
+  readonly step: "authorize" | "token" | "refresh" | "revoke"
   readonly cause: unknown
-}> {}
+  readonly message: string
+}> {
+  constructor(params: { step: "authorize" | "token" | "refresh" | "revoke"; cause: unknown }) {
+    super({
+      ...params,
+      message: `OAuth ${params.step} failed: ${params.cause}`
+    })
+  }
+}
 
 /**
  * Error thrown when front-matter parsing fails.
@@ -146,6 +207,39 @@ export class OAuthError extends Data.TaggedError("OAuthError")<{
 export class FrontMatterError extends Data.TaggedError("FrontMatterError")<{
   readonly path: string
   readonly cause: unknown
+  readonly message: string
+}> {
+  constructor(params: { path: string; cause: unknown }) {
+    super({
+      ...params,
+      message: `Invalid front-matter in: ${params.path}`
+    })
+  }
+}
+
+/**
+ * Error thrown when directory structure is inconsistent.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect"
+ * import { StructureError } from "@knpkv/confluence-to-markdown/ConfluenceError"
+ *
+ * Effect.gen(function* () {
+ *   // ... validate structure
+ * }).pipe(
+ *   Effect.catchTag("StructureError", (error) =>
+ *     Effect.sync(() => console.error(`${error.message}\nAdvice: ${error.advice}`))
+ *   )
+ * )
+ * ```
+ *
+ * @category Errors
+ */
+export class StructureError extends Data.TaggedError("StructureError")<{
+  readonly path: string
+  readonly advice: string
+  readonly message: string
 }> {}
 
 /**
@@ -165,6 +259,7 @@ export type ConfluenceError =
   | FileSystemError
   | OAuthError
   | FrontMatterError
+  | StructureError
 
 /**
  * Type guard to check if error is a ConfluenceError.
@@ -189,5 +284,6 @@ export const isConfluenceError = (error: unknown): error is ConfluenceError =>
     "ConflictError",
     "FileSystemError",
     "OAuthError",
-    "FrontMatterError"
+    "FrontMatterError",
+    "StructureError"
   ].includes((error as { _tag: string })._tag)

package/src/GitError.ts

@@ -0,0 +1,92 @@
+/**
+ * Git-specific error types.
+ *
+ * @module
+ */
+import * as Data from "effect/Data"
+
+/**
+ * Base git error for command execution failures.
+ *
+ * @example
+ * ```typescript
+ * import { GitError } from "@knpkv/confluence-to-markdown/GitError"
+ *
+ * const error = new GitError({
+ *   command: "git commit",
+ *   message: "nothing to commit",
+ *   exitCode: 1
+ * })
+ * ```
+ *
+ * @category Error
+ */
+export class GitError extends Data.TaggedError("GitError")<{
+  readonly command: string
+  readonly message: string
+  readonly exitCode?: number
+}> {}
+
+/**
+ * Error when git is not installed on the system.
+ *
+ * @example
+ * ```typescript
+ * import { GitNotInstalledError } from "@knpkv/confluence-to-markdown/GitError"
+ *
+ * const error = new GitNotInstalledError({
+ *   message: "git command not found"
+ * })
+ * ```
+ *
+ * @category Error
+ */
+export class GitNotInstalledError extends Data.TaggedError("GitNotInstalledError")<{
+  readonly message: string
+}> {}
+
+/**
+ * Error when there are no changes to commit.
+ *
+ * @example
+ * ```typescript
+ * import { GitNoChangesError } from "@knpkv/confluence-to-markdown/GitError"
+ *
+ * const error = new GitNoChangesError({})
+ * ```
+ *
+ * @category Error
+ */
+export class GitNoChangesError extends Data.TaggedError("GitNoChangesError")<{}> {}
+
+/**
+ * Error when merge conflicts exist.
+ *
+ * @example
+ * ```typescript
+ * import { GitMergeConflictError } from "@knpkv/confluence-to-markdown/GitError"
+ *
+ * const error = new GitMergeConflictError({
+ *   files: ["docs/page1.md", "docs/page2.md"]
+ * })
+ * ```
+ *
+ * @category Error
+ */
+export class GitMergeConflictError extends Data.TaggedError("GitMergeConflictError")<{
+  readonly files: ReadonlyArray<string>
+}> {}
+
+/**
+ * Error when git repository is not initialized.
+ *
+ * @example
+ * ```typescript
+ * import { GitNotInitializedError } from "@knpkv/confluence-to-markdown/GitError"
+ *
+ * const error = new GitNotInitializedError({})
+ * ```
+ *
+ * @category Error
+ */
+export class GitNotInitializedError extends Data.TaggedError("GitNotInitializedError")<{}> {}