@knpkv/confluence-to-markdown 0.2.0

package/dist/internal/frontmatter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Front-matter parsing and serialization utilities.
+ *
+ * @module
+ * @internal
+ */
+import * as Effect from "effect/Effect";
+import { FrontMatterError } from "../ConfluenceError.js";
+import type { NewPageFrontMatter, PageFrontMatter } from "../Schemas.js";
+/**
+ * Parsed markdown file with front-matter.
+ */
+export interface ParsedMarkdown {
+    readonly frontMatter: PageFrontMatter | NewPageFrontMatter | null;
+    readonly content: string;
+    readonly isNew: boolean;
+}
+/**
+ * Parse a markdown file with YAML front-matter.
+ *
+ * @param filePath - Path to the file (for error messages)
+ * @param content - The file content
+ * @returns Parsed markdown with front-matter and content
+ *
+ * @internal
+ */
+export declare const parseMarkdown: (filePath: string, content: string) => Effect.Effect<ParsedMarkdown, FrontMatterError>;
+/**
+ * Serialize markdown with YAML front-matter.
+ *
+ * @param frontMatter - The front-matter data
+ * @param content - The markdown content
+ * @returns The serialized markdown file content
+ *
+ * @internal
+ */
+export declare const serializeMarkdown: (frontMatter: PageFrontMatter, content: string) => string;
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/internal/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/internal/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAGxE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,eAAe,GAAG,kBAAkB,GAAG,IAAI,CAAA;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CACxB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GACxB,UAAU,MAAM,EAChB,SAAS,MAAM,KACd,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,gBAAgB,CAqC7C,CAAA;AAEJ;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAC5B,aAAa,eAAe,EAC5B,SAAS,MAAM,KACd,MAYF,CAAA"}

package/dist/internal/frontmatter.js

@@ -0,0 +1,69 @@
+/**
+ * Front-matter parsing and serialization utilities.
+ *
+ * @module
+ * @internal
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import matter from "gray-matter";
+import { FrontMatterError } from "../ConfluenceError.js";
+import { NewPageFrontMatterSchema, PageFrontMatterSchema } from "../Schemas.js";
+/**
+ * Parse a markdown file with YAML front-matter.
+ *
+ * @param filePath - Path to the file (for error messages)
+ * @param content - The file content
+ * @returns Parsed markdown with front-matter and content
+ *
+ * @internal
+ */
+export const parseMarkdown = (filePath, content) => Effect.gen(function* () {
+    const parsed = yield* Effect.try({
+        try: () => matter(content),
+        catch: (cause) => new FrontMatterError({ path: filePath, cause })
+    });
+    // If no front-matter or empty, treat as new page
+    if (!parsed.data || Object.keys(parsed.data).length === 0) {
+        return {
+            frontMatter: null,
+            content: parsed.content.trim(),
+            isNew: true
+        };
+    }
+    // Try to parse as existing page front-matter
+    const existingResult = yield* Schema.decodeUnknown(PageFrontMatterSchema)(parsed.data).pipe(Effect.map((fm) => ({
+        frontMatter: fm,
+        content: parsed.content.trim(),
+        isNew: false
+    })), Effect.catchAll(() => 
+    // Try to parse as new page front-matter
+    Schema.decodeUnknown(NewPageFrontMatterSchema)(parsed.data).pipe(Effect.map((fm) => ({
+        frontMatter: fm,
+        content: parsed.content.trim(),
+        isNew: true
+    })), Effect.catchAll((cause) => Effect.fail(new FrontMatterError({ path: filePath, cause }))))));
+    return existingResult;
+});
+/**
+ * Serialize markdown with YAML front-matter.
+ *
+ * @param frontMatter - The front-matter data
+ * @param content - The markdown content
+ * @returns The serialized markdown file content
+ *
+ * @internal
+ */
+export const serializeMarkdown = (frontMatter, content) => {
+    const fm = {
+        pageId: frontMatter.pageId,
+        version: frontMatter.version,
+        title: frontMatter.title,
+        updated: frontMatter.updated.toISOString(),
+        ...(frontMatter.parentId !== undefined ? { parentId: frontMatter.parentId } : {}),
+        ...(frontMatter.position !== undefined ? { position: frontMatter.position } : {}),
+        contentHash: frontMatter.contentHash
+    };
+    return matter.stringify(content, fm);
+};
+//# sourceMappingURL=frontmatter.js.map

package/dist/internal/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/internal/frontmatter.ts"],"names":[],"mappings":"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"}

package/dist/internal/hashUtils.d.ts

@@ -0,0 +1,11 @@
+import type { ContentHash } from "../Brand.js";
+/**
+ * Compute SHA256 hash of content.
+ *
+ * @param content - The content to hash
+ * @returns The hex-encoded SHA256 hash
+ *
+ * @internal
+ */
+export declare const computeHash: (content: string) => ContentHash;
+//# sourceMappingURL=hashUtils.d.ts.map

package/dist/internal/hashUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashUtils.d.ts","sourceRoot":"","sources":["../../src/internal/hashUtils.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,MAAM,KAAG,WACoC,CAAA"}

package/dist/internal/hashUtils.js

@@ -0,0 +1,17 @@
+/**
+ * Content hashing utilities for change detection.
+ *
+ * @module
+ * @internal
+ */
+import * as crypto from "node:crypto";
+/**
+ * Compute SHA256 hash of content.
+ *
+ * @param content - The content to hash
+ * @returns The hex-encoded SHA256 hash
+ *
+ * @internal
+ */
+export const computeHash = (content) => crypto.createHash("sha256").update(content, "utf8").digest("hex");
+//# sourceMappingURL=hashUtils.js.map

package/dist/internal/hashUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashUtils.js","sourceRoot":"","sources":["../../src/internal/hashUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAGrC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAe,EAAe,EAAE,CAC1D,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAgB,CAAA"}

package/dist/internal/pathUtils.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Convert a page title to a URL-safe slug.
+ * Prevents path traversal by only allowing alphanumeric characters and hyphens.
+ *
+ * @param title - The page title
+ * @returns A slugified version of the title
+ *
+ * @internal
+ */
+export declare const slugify: (title: string) => string;
+/**
+ * Convert a page to a local file path.
+ *
+ * @param title - The page title
+ * @param hasChildren - Whether the page has child pages
+ * @param parentPath - The parent directory path
+ * @returns The local file path for the page
+ *
+ * @internal
+ */
+export declare const pageToPath: (title: string, hasChildren: boolean, parentPath: string) => string;
+/**
+ * Get the directory path for a page (used when creating children).
+ *
+ * @param title - The page title
+ * @param parentPath - The parent directory path
+ * @returns The directory path for the page's children
+ *
+ * @internal
+ */
+export declare const pageToDir: (title: string, parentPath: string) => string;
+/**
+ * Extract page slug from a file path.
+ *
+ * @param filePath - The file path
+ * @returns The page slug
+ *
+ * @internal
+ */
+export declare const pathToSlug: (filePath: string) => string;
+//# sourceMappingURL=pathUtils.d.ts.map

package/dist/internal/pathUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathUtils.d.ts","sourceRoot":"","sources":["../../src/internal/pathUtils.ts"],"names":[],"mappings":"AAQA;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,KAAG,MAWvC,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,GACrB,OAAO,MAAM,EACb,aAAa,OAAO,EACpB,YAAY,MAAM,KACjB,MAKF,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,MAAM,EAAE,YAAY,MAAM,KAAG,MAG7D,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GAAI,UAAU,MAAM,KAAG,MAG7C,CAAA"}

package/dist/internal/pathUtils.js

@@ -0,0 +1,69 @@
+/**
+ * Path utilities for converting page titles to file paths.
+ *
+ * @module
+ * @internal
+ */
+import * as path from "node:path";
+/**
+ * Convert a page title to a URL-safe slug.
+ * Prevents path traversal by only allowing alphanumeric characters and hyphens.
+ *
+ * @param title - The page title
+ * @returns A slugified version of the title
+ *
+ * @internal
+ */
+export const slugify = (title) => {
+    const slug = title
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "") // Remove diacritics
+        .replace(/[^a-z0-9]+/g, "-") // Replace non-alphanumeric with hyphens (prevents ../ path traversal)
+        .replace(/^-+|-+$/g, "") // Trim leading/trailing hyphens
+        .substring(0, 100); // Limit length
+    // Ensure we have a valid slug (not empty after sanitization)
+    return slug || "untitled";
+};
+/**
+ * Convert a page to a local file path.
+ *
+ * @param title - The page title
+ * @param hasChildren - Whether the page has child pages
+ * @param parentPath - The parent directory path
+ * @returns The local file path for the page
+ *
+ * @internal
+ */
+export const pageToPath = (title, hasChildren, parentPath) => {
+    const slug = slugify(title);
+    return hasChildren
+        ? path.join(parentPath, slug, "index.md")
+        : path.join(parentPath, `${slug}.md`);
+};
+/**
+ * Get the directory path for a page (used when creating children).
+ *
+ * @param title - The page title
+ * @param parentPath - The parent directory path
+ * @returns The directory path for the page's children
+ *
+ * @internal
+ */
+export const pageToDir = (title, parentPath) => {
+    const slug = slugify(title);
+    return path.join(parentPath, slug);
+};
+/**
+ * Extract page slug from a file path.
+ *
+ * @param filePath - The file path
+ * @returns The page slug
+ *
+ * @internal
+ */
+export const pathToSlug = (filePath) => {
+    const basename = path.basename(filePath, ".md");
+    return basename === "index" ? path.basename(path.dirname(filePath)) : basename;
+};
+//# sourceMappingURL=pathUtils.js.map

package/dist/internal/pathUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathUtils.js","sourceRoot":"","sources":["../../src/internal/pathUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AAEjC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAa,EAAU,EAAE;IAC/C,MAAM,IAAI,GAAG,KAAK;SACf,WAAW,EAAE;SACb,SAAS,CAAC,KAAK,CAAC;SAChB,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC,oBAAoB;SACpD,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,sEAAsE;SAClG,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,gCAAgC;SACxD,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA,CAAC,eAAe;IAEpC,6DAA6D;IAC7D,OAAO,IAAI,IAAI,UAAU,CAAA;AAC3B,CAAC,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CACxB,KAAa,EACb,WAAoB,EACpB,UAAkB,EACV,EAAE;IACV,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;IAC3B,OAAO,WAAW;QAChB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,UAAU,CAAC;QACzC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,IAAI,KAAK,CAAC,CAAA;AACzC,CAAC,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAa,EAAE,UAAkB,EAAU,EAAE;IACrE,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;IAC3B,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAA;AACpC,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,QAAgB,EAAU,EAAE;IACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;IAC/C,OAAO,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAA;AAChF,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "@knpkv/confluence-to-markdown",
+  "version": "0.2.0",
+  "description": "Sync Confluence Cloud pages to local GitHub Flavored Markdown files",
+  "license": "MIT",
+  "author": "knpkv",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/knpkv/npm.git",
+    "directory": "packages/confluence-to-markdown"
+  },
+  "bugs": {
+    "url": "https://github.com/knpkv/npm/issues"
+  },
+  "homepage": "https://github.com/knpkv/npm/tree/main/packages/confluence-to-markdown#readme",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "confluence": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./Brand": {
+      "import": "./dist/Brand.js",
+      "types": "./dist/Brand.d.ts"
+    },
+    "./Schemas": {
+      "import": "./dist/Schemas.js",
+      "types": "./dist/Schemas.d.ts"
+    },
+    "./ConfluenceError": {
+      "import": "./dist/ConfluenceError.js",
+      "types": "./dist/ConfluenceError.d.ts"
+    },
+    "./ConfluenceConfig": {
+      "import": "./dist/ConfluenceConfig.js",
+      "types": "./dist/ConfluenceConfig.d.ts"
+    },
+    "./ConfluenceAuth": {
+      "import": "./dist/ConfluenceAuth.js",
+      "types": "./dist/ConfluenceAuth.d.ts"
+    },
+    "./ConfluenceClient": {
+      "import": "./dist/ConfluenceClient.js",
+      "types": "./dist/ConfluenceClient.d.ts"
+    },
+    "./MarkdownConverter": {
+      "import": "./dist/MarkdownConverter.js",
+      "types": "./dist/MarkdownConverter.d.ts"
+    },
+    "./LocalFileSystem": {
+      "import": "./dist/LocalFileSystem.js",
+      "types": "./dist/LocalFileSystem.d.ts"
+    },
+    "./SyncEngine": {
+      "import": "./dist/SyncEngine.js",
+      "types": "./dist/SyncEngine.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist dist-test .tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "vitest run --config vitest.config.integration.ts",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "check": "tsc --noEmit",
+    "link": "npm link"
+  },
+  "peerDependencies": {
+    "effect": "^3.19.3"
+  },
+  "dependencies": {
+    "@effect/cli": "^0.61.0",
+    "@effect/platform": "^0.93.0",
+    "@effect/platform-node": "^0.87.0",
+    "gray-matter": "^4.0.3",
+    "rehype-parse": "^9.0.1",
+    "rehype-remark": "^10.0.1",
+    "rehype-stringify": "^10.0.1",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.1",
+    "remark-stringify": "^11.0.0",
+    "unified": "^11.0.5"
+  },
+  "devDependencies": {
+    "@effect/vitest": "^0.27.0",
+    "@types/node": "^22.15.21",
+    "effect": "^3.19.3",
+    "typescript": "~5.9.0",
+    "vitest": "^4.0.13"
+  },
+  "keywords": [
+    "effect",
+    "effect-ts",
+    "confluence",
+    "markdown",
+    "sync",
+    "atlassian",
+    "documentation",
+    "cli"
+  ]
+}

package/src/Brand.ts

@@ -0,0 +1,104 @@
+/**
+ * Branded types for type-safe Confluence identifiers.
+ *
+ * @module
+ */
+import * as Brand from "effect/Brand"
+import * as Schema from "effect/Schema"
+
+/**
+ * Branded type for Confluence page IDs.
+ *
+ * @example
+ * ```typescript
+ * import { PageId } from "@knpkv/confluence-to-markdown/Brand"
+ *
+ * const id = PageId("12345") // Valid
+ * const invalid = PageId("") // Throws BrandErrors
+ * ```
+ *
+ * @category Brand
+ */
+export type PageId = string & Brand.Brand<"PageId">
+
+/**
+ * Refined brand constructor for PageId.
+ *
+ * @category Brand
+ */
+export const PageId = Brand.refined<PageId>(
+  (s): s is PageId => typeof s === "string" && s.length > 0,
+  (s) => Brand.error(`Invalid page ID: "${s}" (must be non-empty string)`)
+)
+
+/**
+ * Schema for PageId validation and parsing.
+ *
+ * @category Schema
+ */
+export const PageIdSchema = Schema.String.pipe(
+  Schema.nonEmptyString(),
+  Schema.brand("PageId")
+)
+
+/**
+ * Branded type for Confluence space keys.
+ *
+ * @example
+ * ```typescript
+ * import { SpaceKey } from "@knpkv/confluence-to-markdown/Brand"
+ *
+ * const key = SpaceKey("DOCS") // Valid
+ * ```
+ *
+ * @category Brand
+ */
+export type SpaceKey = string & Brand.Brand<"SpaceKey">
+
+/**
+ * Refined brand constructor for SpaceKey.
+ *
+ * @category Brand
+ */
+export const SpaceKey = Brand.refined<SpaceKey>(
+  (s): s is SpaceKey => typeof s === "string" && s.length > 0 && /^[A-Z0-9]+$/.test(s),
+  (s) => Brand.error(`Invalid space key: "${s}" (must be uppercase alphanumeric)`)
+)
+
+/**
+ * Schema for SpaceKey validation.
+ *
+ * @category Schema
+ */
+export const SpaceKeySchema = Schema.String.pipe(
+  Schema.nonEmptyString(),
+  Schema.pattern(/^[A-Z0-9]+$/),
+  Schema.brand("SpaceKey")
+)
+
+/**
+ * Branded type for content hash (SHA256).
+ *
+ * @category Brand
+ */
+export type ContentHash = string & Brand.Brand<"ContentHash">
+
+/**
+ * Refined brand constructor for ContentHash.
+ *
+ * @category Brand
+ */
+export const ContentHash = Brand.refined<ContentHash>(
+  (s): s is ContentHash => typeof s === "string" && /^[a-f0-9]{64}$/.test(s),
+  (s) => Brand.error(`Invalid content hash: "${s}" (must be 64-char hex string)`)
+)
+
+/**
+ * Schema for ContentHash validation.
+ *
+ * @category Schema
+ */
+export const ContentHashSchema = Schema.String.pipe(
+  Schema.pattern(/^[a-f0-9]{64}$/),
+  Schema.brand("ContentHash")
+)