@heliosgraphics/epoque 0.0.1-alpha.0

package/package.json

@@ -0,0 +1,18 @@
+{
+	"name": "@heliosgraphics/epoque",
+	"version": "0.0.1-alpha.0",
+	"author": "Chris Puska <chris@puska.org>",
+	"description": "sync a local folder",
+	"type": "module",
+	"bin": {
+		"epoque": "./src/cli.ts"
+	},
+	"files": [
+		"src"
+	],
+	"scripts": {
+		"typecheck": "tsc --noEmit --project tsconfig.json"
+	},
+	"dependencies": {},
+	"devDependencies": {}
+}

package/src/api.ts

@@ -0,0 +1,98 @@
+import { readFile } from "node:fs/promises"
+import type { RemoteArchive, RemoteArticle, RemoteArticleImage, RemoteCollection } from "./types"
+
+interface ApiErrorBody {
+	error?: string
+	message?: string
+}
+
+type JsonBody = Record<string, unknown> | Array<unknown>
+
+export class EpoqueApi {
+	readonly #apiKey: string
+	readonly #origin: string
+
+	constructor({ apiKey, origin }: { apiKey: string; origin: string }) {
+		this.#apiKey = apiKey
+		this.#origin = origin.replace(/\/+$/, "")
+	}
+
+	async listCollections(): Promise<Array<RemoteCollection>> {
+		return this.#request<Array<RemoteCollection>>("/api/v1/collections")
+	}
+
+	async getCollection(id: string): Promise<RemoteCollection> {
+		return this.#request<RemoteCollection>(`/api/v1/collections/${encodeURIComponent(id)}`)
+	}
+
+	async getArchive(collectionId: string): Promise<RemoteArchive> {
+		return this.#request<RemoteArchive>(`/api/v1/collections/${encodeURIComponent(collectionId)}/archive`)
+	}
+
+	async createArticle(collectionId: string): Promise<RemoteArticle> {
+		return this.#request<RemoteArticle>("/api/v1/articles", { method: "POST", json: { collectionId } })
+	}
+
+	async updateArticle({ articleId, values }: { articleId: string; values: JsonBody }): Promise<RemoteArticle> {
+		return this.#request<RemoteArticle>(`/api/v1/articles/${encodeURIComponent(articleId)}`, { method: "PUT", json: values })
+	}
+
+	async deleteArticle(articleId: string): Promise<void> {
+		await this.#request<unknown>(`/api/v1/articles/${encodeURIComponent(articleId)}`, { method: "DELETE" })
+	}
+
+	async uploadAttachment({ articleId, path }: { articleId: string; path: string }): Promise<RemoteArticleImage> {
+		const body = await readFile(path)
+
+		return this.#request<RemoteArticleImage>(`/api/v1/article-images?articleId=${encodeURIComponent(articleId)}`, {
+			body,
+			method: "POST",
+		})
+	}
+
+	async deleteAttachment(url: string): Promise<void> {
+		await this.#request<unknown>("/api/v1/article-images", { method: "DELETE", json: { url } })
+	}
+
+	async reorderAttachments({ articleId, imageIds }: { articleId: string; imageIds: Array<string> }): Promise<void> {
+		await this.#request<unknown>(`/api/v1/article-images?articleId=${encodeURIComponent(articleId)}`, {
+			method: "PUT",
+			json: imageIds,
+		})
+	}
+
+	async #request<T>(path: string, options: { method?: string; json?: JsonBody; body?: Uint8Array } = {}): Promise<T> {
+		const headers = new Headers({ Authorization: `Bearer ${this.#apiKey}` })
+		let body: BodyInit | undefined
+
+		if (options.json !== undefined) {
+			headers.set("Content-Type", "application/json")
+			body = JSON.stringify(options.json)
+		} else if (options.body) {
+			headers.set("Content-Type", "application/octet-stream")
+			const bytes = new Uint8Array(options.body.byteLength)
+			bytes.set(options.body)
+			body = new Blob([bytes])
+		}
+
+		const response = await fetch(`${this.#origin}${path}`, { body, headers, method: options.method ?? "GET" })
+
+		if (!response.ok) {
+			throw new Error(await getResponseError(response))
+		}
+
+		if (response.status === 204) return undefined as T
+
+		return response.json() as Promise<T>
+	}
+}
+
+const getResponseError = async (response: Response): Promise<string> => {
+	try {
+		const body = (await response.json()) as ApiErrorBody
+
+		return body.error || body.message || `request failed with ${response.status}`
+	} catch (_error) {
+		return `request failed with ${response.status}`
+	}
+}

package/src/archive.ts

@@ -0,0 +1,130 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises"
+import { basename, dirname, extname, join, relative } from "node:path"
+import { parseFrontmatter, serializeFrontmatter } from "./frontmatter"
+import type { LocalArticle, LocalAttachment, RemoteArchive, RemoteArticle } from "./types"
+
+const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown"])
+const ATTACHMENTS_DIRECTORY = "attachments" as const
+
+const toPortablePath = (path: string): string => path.split("\\").join("/")
+
+const getString = (value: unknown): string | null => (typeof value === "string" && value.trim() ? value.trim() : null)
+
+const getBoolean = (value: unknown): boolean | null => (typeof value === "boolean" ? value : null)
+
+const getAttachmentHash = async (absolutePath: string): Promise<string> => {
+	const buffer = await readFile(absolutePath)
+	const digest = await crypto.subtle.digest("SHA-256", buffer)
+	const bytes = new Uint8Array(digest)
+
+	return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")
+}
+
+const listMarkdownFiles = async (cwd: string, directory: string = cwd): Promise<Array<string>> => {
+	const entries = await readdir(directory, { withFileTypes: true })
+	const files: Array<string> = []
+
+	for (const entry of entries) {
+		if (entry.name === ATTACHMENTS_DIRECTORY || entry.name === "node_modules" || entry.name.startsWith(".")) continue
+
+		const absolutePath = join(directory, entry.name)
+		if (entry.isDirectory()) {
+			files.push(...(await listMarkdownFiles(cwd, absolutePath)))
+			continue
+		}
+
+		if (entry.isFile() && MARKDOWN_EXTENSIONS.has(extname(entry.name))) {
+			files.push(absolutePath)
+		}
+	}
+
+	return files.sort((left, right) => left.localeCompare(right))
+}
+
+const readAttachmentDirectory = async (cwd: string, articleKeys: Array<string>): Promise<Array<LocalAttachment>> => {
+	for (const key of articleKeys) {
+		const directory = join(cwd, ATTACHMENTS_DIRECTORY, key)
+
+		try {
+			const entries = await readdir(directory, { withFileTypes: true })
+			const attachments: Array<LocalAttachment> = []
+
+			for (const entry of entries) {
+				if (!entry.isFile()) continue
+
+				const absolutePath = join(directory, entry.name)
+				const relativePath = toPortablePath(relative(cwd, absolutePath))
+
+				attachments.push({
+					absolutePath,
+					hash: await getAttachmentHash(absolutePath),
+					name: entry.name,
+					relativePath,
+				})
+			}
+
+			return attachments.sort((left, right) => left.relativePath.localeCompare(right.relativePath))
+		} catch (_error) {}
+	}
+
+	return []
+}
+
+export const readArchive = async (cwd: string): Promise<Array<LocalArticle>> => {
+	const files = await listMarkdownFiles(cwd)
+	const articles: Array<LocalArticle> = []
+
+	for (const absolutePath of files) {
+		const content = await readFile(absolutePath, "utf8")
+		const { frontmatter, body } = parseFrontmatter(content)
+		const id = getString(frontmatter.id)
+		const slug = getString(frontmatter.slug)
+		const file = toPortablePath(relative(cwd, absolutePath))
+		const fileKey = basename(file, extname(file))
+		const publishedAt = getString(frontmatter.publishedAt)
+		const isPublished = getBoolean(frontmatter.published) ?? getBoolean(frontmatter.isPublished) ?? Boolean(publishedAt)
+		const attachments = await readAttachmentDirectory(
+			cwd,
+			[id, slug, fileKey].filter((value): value is string => !!value),
+		)
+
+		articles.push({
+			absolutePath,
+			attachments,
+			body,
+			createdAt: getString(frontmatter.createdAt),
+			file,
+			frontmatter,
+			id,
+			isPublished,
+			location: getString(frontmatter.location),
+			publishedAt,
+			slug,
+		})
+	}
+
+	return articles
+}
+
+export const writeArticleFile = async ({ article, body }: { article: LocalArticle; body?: string }): Promise<void> => {
+	await mkdir(dirname(article.absolutePath), { recursive: true })
+	await writeFile(article.absolutePath, serializeFrontmatter(article.frontmatter, body ?? article.body))
+}
+
+const getArticleFileName = (article: RemoteArticle): string => `${article.id}.md`
+
+export const buildArchiveFromRemote = (archive: RemoteArchive): Array<{ file: string; content: string }> =>
+	archive.articles.map((article) => ({
+		file: getArticleFileName(article),
+		content: serializeFrontmatter(
+			{
+				id: article.id,
+				slug: article.slug,
+				published: article.isPublished,
+				publishedAt: article.publishedAt,
+				createdAt: article.createdAt,
+				location: article.location,
+			},
+			article.post ?? "",
+		),
+	}))

package/src/cli.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env bun
+
+import { createInterface } from "node:readline/promises"
+import { stdin as input, stdout as output } from "node:process"
+import { EpoqueApi } from "./api"
+import { getApiKey, getStoredOrigin, normalizeOrigin, readGlobalConfig, readProjectConfig, writeGlobalConfig } from "./config"
+import { syncFolder } from "./sync"
+
+const HELP = `Usage:
+  epoque login [--origin https://epoque.app]
+  epoque sync [--dry-run] [--origin https://epoque.app]
+`
+
+const promptLine = async (question: string): Promise<string> => {
+	const readline = createInterface({ input, output })
+
+	try {
+		return await readline.question(question)
+	} finally {
+		readline.close()
+	}
+}
+
+const promptSecret = async (question: string): Promise<string> => {
+	const stdin = process.stdin as NodeJS.ReadStream & { setRawMode?: (mode: boolean) => void }
+
+	if (!stdin.isTTY || !stdin.setRawMode) return promptLine(question)
+
+	return new Promise((resolve, reject) => {
+		let value = ""
+
+		const cleanup = (): void => {
+			stdin.off("data", onData)
+			stdin.setRawMode?.(false)
+			stdin.pause()
+			process.stdout.write("\n")
+		}
+
+		const onData = (data: Buffer): void => {
+			const text = data.toString("utf8")
+
+			for (const character of text) {
+				if (character === "\u0003") {
+					cleanup()
+					reject(new Error("cancelled"))
+					return
+				}
+
+				if (character === "\r" || character === "\n") {
+					cleanup()
+					resolve(value)
+					return
+				}
+
+				if (character === "\u007f") {
+					value = value.slice(0, -1)
+					continue
+				}
+
+				value += character
+			}
+		}
+
+		process.stdout.write(question)
+		stdin.resume()
+		stdin.setRawMode(true)
+		stdin.on("data", onData)
+	})
+}
+
+const getFlagValue = (args: Array<string>, name: string): string | undefined => {
+	const index = args.indexOf(name)
+	if (index === -1) return undefined
+
+	return args[index + 1]
+}
+
+const hasFlag = (args: Array<string>, name: string): boolean => args.includes(name)
+
+const login = async (args: Array<string>): Promise<void> => {
+	const origin = normalizeOrigin(getFlagValue(args, "--origin") ?? (await getStoredOrigin()))
+	const apiKey = (await promptSecret("API key: ")).trim()
+
+	if (!apiKey) throw new Error("api key is required")
+
+	const api = new EpoqueApi({ apiKey, origin })
+	await api.listCollections()
+
+	const existing = await readGlobalConfig()
+	await writeGlobalConfig({ ...existing, apiKey, origin })
+	console.log("Saved API key to ~/.config/epoque/config.json")
+}
+
+const sync = async (args: Array<string>): Promise<void> => {
+	const cwd = process.cwd()
+	const projectConfig = await readProjectConfig(cwd)
+	const origin = normalizeOrigin(getFlagValue(args, "--origin") ?? projectConfig?.origin ?? (await getStoredOrigin()))
+	const apiKey = await getApiKey()
+
+	if (!apiKey) throw new Error("not logged in. Run `epoque login` first or set EPOQUE_API_KEY")
+
+	const summary = await syncFolder({
+		api: new EpoqueApi({ apiKey, origin }),
+		cwd,
+		dryRun: hasFlag(args, "--dry-run"),
+		origin,
+		prompt: promptLine,
+	})
+
+	console.log(
+		`Articles: ${summary.createdArticles} created, ${summary.updatedArticles} updated, ${summary.deletedArticles} deleted`,
+	)
+	console.log(`Attachments: ${summary.uploadedAttachments} uploaded, ${summary.deletedAttachments} deleted`)
+}
+
+const main = async (): Promise<void> => {
+	const [command, ...args] = process.argv.slice(2)
+
+	switch (command) {
+		case "login":
+			await login(args)
+			return
+		case "sync":
+			await sync(args)
+			return
+		case "help":
+		case "--help":
+		case "-h":
+		case undefined:
+			console.log(HELP)
+			return
+		default:
+			throw new Error(`unknown command: ${command}`)
+	}
+}
+
+main().catch((error: unknown) => {
+	console.error(error instanceof Error ? error.message : String(error))
+	process.exitCode = 1
+})

package/src/config.ts

@@ -0,0 +1,74 @@
+import { mkdir, readFile, writeFile, chmod } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { homedir } from "node:os"
+import type { GlobalConfig, ProjectConfig } from "./types"
+
+const DEFAULT_ORIGIN = "https://epoque.app" as const
+const PROJECT_CONFIG_FILE = "epoque.json" as const
+const PROJECT_SCHEMA_URL = "https://epoque.app/schemas/epoque.json" as const
+
+export const normalizeOrigin = (origin: string | undefined): string => (origin || DEFAULT_ORIGIN).replace(/\/+$/, "")
+
+export const getProjectConfigPath = (cwd: string): string => join(cwd, PROJECT_CONFIG_FILE)
+
+const getGlobalConfigPath = (): string => {
+	const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config")
+
+	return join(configHome, "epoque", "config.json")
+}
+
+export const readGlobalConfig = async (): Promise<GlobalConfig> => {
+	try {
+		const content = await readFile(getGlobalConfigPath(), "utf8")
+
+		return JSON.parse(content) as GlobalConfig
+	} catch (_error) {
+		return {}
+	}
+}
+
+export const writeGlobalConfig = async (config: GlobalConfig): Promise<void> => {
+	const configPath = getGlobalConfigPath()
+	await mkdir(dirname(configPath), { recursive: true, mode: 0o700 })
+	await writeFile(configPath, `${JSON.stringify(config, null, "\t")}\n`, { mode: 0o600 })
+	await chmod(configPath, 0o600)
+}
+
+export const getApiKey = async (): Promise<string | null> => {
+	if (process.env.EPOQUE_API_KEY) return process.env.EPOQUE_API_KEY
+
+	const config = await readGlobalConfig()
+
+	return config.apiKey ?? null
+}
+
+export const getStoredOrigin = async (originOverride?: string): Promise<string> => {
+	if (originOverride) return normalizeOrigin(originOverride)
+
+	const config = await readGlobalConfig()
+
+	return normalizeOrigin(config.origin)
+}
+
+export const readProjectConfig = async (cwd: string): Promise<ProjectConfig | null> => {
+	try {
+		const content = await readFile(getProjectConfigPath(cwd), "utf8")
+
+		return JSON.parse(content) as ProjectConfig
+	} catch (_error) {
+		return null
+	}
+}
+
+export const writeProjectConfig = async (cwd: string, config: ProjectConfig): Promise<void> => {
+	await writeFile(getProjectConfigPath(cwd), `${JSON.stringify(config, null, "\t")}\n`)
+}
+
+export const createProjectConfig = ({ origin, collectionId }: { origin: string; collectionId: string }): ProjectConfig => ({
+	$schema: PROJECT_SCHEMA_URL,
+	version: 1,
+	origin: normalizeOrigin(origin),
+	collectionId,
+	lastSyncedAt: null,
+	articles: {},
+})

package/src/frontmatter.ts

@@ -0,0 +1,54 @@
+const FRONTMATTER_PATTERN: RegExp = /^---\s*\n([\s\S]*?)\n---\s*\n?/
+
+const parseValue = (value: string): unknown => {
+	const trimmed = value.trim()
+
+	if (trimmed === "null") return null
+	if (trimmed === "true") return true
+	if (trimmed === "false") return false
+	if (/^-?\d+(?:\.\d+)?$/.test(trimmed)) return Number(trimmed)
+	if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+		return trimmed.slice(1, -1)
+	}
+
+	return trimmed
+}
+
+const serializeValue = (value: unknown): string => {
+	if (value === null) return "null"
+	if (typeof value === "boolean" || typeof value === "number") return String(value)
+	if (typeof value === "string") return JSON.stringify(value)
+
+	return JSON.stringify(value)
+}
+
+export const parseFrontmatter = (content: string): { frontmatter: Record<string, unknown>; body: string } => {
+	const match = content.match(FRONTMATTER_PATTERN)
+	if (!match) return { frontmatter: {}, body: content }
+
+	const frontmatter: Record<string, unknown> = {}
+	const rawFrontmatter = match[1] ?? ""
+	const body = content.slice(match[0].length)
+
+	for (const line of rawFrontmatter.split("\n")) {
+		const trimmed = line.trim()
+		if (!trimmed || trimmed.startsWith("#")) continue
+
+		const separatorIndex = trimmed.indexOf(":")
+		if (separatorIndex === -1) continue
+
+		const key = trimmed.slice(0, separatorIndex).trim()
+		const value = trimmed.slice(separatorIndex + 1)
+		if (key) frontmatter[key] = parseValue(value)
+	}
+
+	return { frontmatter, body }
+}
+
+export const serializeFrontmatter = (frontmatter: Record<string, unknown>, body: string): string => {
+	const lines = Object.entries(frontmatter)
+		.filter(([, value]) => value !== undefined)
+		.map(([key, value]) => `${key}: ${serializeValue(value)}`)
+
+	return `---\n${lines.join("\n")}\n---\n\n${body.trimStart()}`
+}

package/src/sync.ts

@@ -0,0 +1,301 @@
+import { basename, extname } from "node:path"
+import { readArchive, writeArticleFile } from "./archive"
+import { createProjectConfig, readProjectConfig, writeProjectConfig } from "./config"
+import type { EpoqueApi } from "./api"
+import type { ArticleSyncState, LocalArticle, ProjectConfig, RemoteArchive, RemoteArticle } from "./types"
+
+type Prompt = (question: string) => Promise<string>
+
+export interface SyncOptions {
+	cwd: string
+	origin: string
+	api: EpoqueApi
+	dryRun: boolean
+	prompt: Prompt
+}
+
+export interface SyncSummary {
+	createdArticles: number
+	updatedArticles: number
+	deletedArticles: number
+	uploadedAttachments: number
+	deletedAttachments: number
+	reorderedArticles: number
+}
+
+const EMPTY_SUMMARY: SyncSummary = {
+	createdArticles: 0,
+	deletedArticles: 0,
+	deletedAttachments: 0,
+	reorderedArticles: 0,
+	updatedArticles: 0,
+	uploadedAttachments: 0,
+}
+
+const isUuid = (value: string): boolean =>
+	/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)
+
+const isAfter = (left: string | null | undefined, right: string | null | undefined): boolean => {
+	if (!left || !right) return false
+
+	return new Date(left).getTime() > new Date(right).getTime()
+}
+
+const getCollectionSearchTerms = (input: string): Array<string> => {
+	try {
+		const url = new URL(input)
+		const segments = url.pathname
+			.split("/")
+			.map((segment) => segment.trim())
+			.filter(Boolean)
+		const hostSegments = url.hostname.split(".").filter(Boolean)
+
+		return [...segments, ...hostSegments, input]
+	} catch (_error) {
+		return [input]
+	}
+}
+
+const resolveCollectionId = async ({ api, prompt }: { api: EpoqueApi; prompt: Prompt }): Promise<string> => {
+	const input = (await prompt("Collection name, id, or URL: ")).trim()
+	if (!input) throw new Error("collection is required")
+	if (isUuid(input)) return (await api.getCollection(input)).id
+
+	const terms = getCollectionSearchTerms(input).map((term) => term.toLowerCase())
+	const collections = await api.listCollections()
+	const matches = collections.filter((collection) => {
+		const values = [collection.id, collection.title, collection.subdomain].map((value) => value.toLowerCase())
+
+		return terms.some((term) => values.includes(term))
+	})
+
+	if (matches.length === 1) return matches[0].id
+	if (!matches.length) throw new Error(`collection not found: ${input}`)
+
+	console.log("Multiple collections matched:")
+	matches.forEach((collection, index) => console.log(`${index + 1}. ${collection.title} (${collection.subdomain})`))
+
+	const selected = Number.parseInt(await prompt("Select a collection number: "), 10)
+	const collection = matches[selected - 1]
+	if (!collection) throw new Error("invalid collection selection")
+
+	return collection.id
+}
+
+const ensureProjectConfig = async ({ api, cwd, dryRun, origin, prompt }: SyncOptions): Promise<ProjectConfig> => {
+	const existing = await readProjectConfig(cwd)
+	if (existing) return { ...existing, origin }
+
+	const collectionId = await resolveCollectionId({ api, prompt })
+	const config = createProjectConfig({ collectionId, origin })
+
+	if (!dryRun) await writeProjectConfig(cwd, config)
+
+	return config
+}
+
+const getLocalById = (articles: Array<LocalArticle>): Map<string, LocalArticle> => {
+	const map = new Map<string, LocalArticle>()
+
+	for (const article of articles) {
+		if (article.id) map.set(article.id, article)
+	}
+
+	return map
+}
+
+const getRemoteById = (archive: RemoteArchive): Map<string, RemoteArticle> =>
+	new Map(archive.articles.map((article) => [article.id, article]))
+
+const assertNoUpstreamChanges = ({
+	archive,
+	config,
+	localArticles,
+}: {
+	archive: RemoteArchive
+	config: ProjectConfig
+	localArticles: Array<LocalArticle>
+}): void => {
+	const conflicts: Array<string> = []
+	const localById = getLocalById(localArticles)
+
+	if (isAfter(archive.collection.updatedAt, config.lastSyncedAt)) {
+		conflicts.push(`collection updated upstream at ${archive.collection.updatedAt}`)
+	}
+
+	for (const remoteArticle of archive.articles) {
+		const state = config.articles[remoteArticle.id]
+
+		if (!state && !localById.has(remoteArticle.id)) {
+			conflicts.push(`untracked remote article ${remoteArticle.id}`)
+			continue
+		}
+
+		if (!state && remoteArticle.images.length) {
+			conflicts.push(`untracked remote attachments for article ${remoteArticle.id}`)
+			continue
+		}
+
+		if (state?.remoteUpdatedAt && isAfter(remoteArticle.updatedAt, state.remoteUpdatedAt)) {
+			conflicts.push(`article ${remoteArticle.id} updated upstream at ${remoteArticle.updatedAt}`)
+		}
+
+		const trackedImageIds = new Set(Object.values(state?.attachments ?? {}).map((attachment) => attachment.id))
+		for (const image of remoteArticle.images) {
+			if (!trackedImageIds.has(image.id))
+				conflicts.push(`untracked remote attachment ${image.id} on article ${remoteArticle.id}`)
+		}
+	}
+
+	if (conflicts.length) {
+		throw new Error(`sync aborted because upstream is newer:\n${conflicts.map((conflict) => `- ${conflict}`).join("\n")}`)
+	}
+}
+
+const getUpdateBody = (article: LocalArticle): Record<string, unknown> => ({
+	isPublished: article.isPublished,
+	location: article.location,
+	post: article.body,
+	publishedAt: article.publishedAt,
+	slug: article.slug,
+})
+
+const updateLocalFrontmatter = ({ article, remote }: { article: LocalArticle; remote: RemoteArticle }): void => {
+	article.id = remote.id
+	article.frontmatter.id = remote.id
+	article.frontmatter.slug = remote.slug
+	article.frontmatter.published = remote.isPublished
+	article.frontmatter.publishedAt = remote.publishedAt
+	article.frontmatter.createdAt = remote.createdAt
+	article.frontmatter.location = remote.location
+}
+
+const getNewArticleFileKey = (article: LocalArticle): string => basename(article.file, extname(article.file))
+
+const syncAttachments = async ({
+	api,
+	article,
+	dryRun,
+	state,
+	summary,
+}: {
+	api: EpoqueApi
+	article: LocalArticle
+	dryRun: boolean
+	state: ArticleSyncState
+	summary: SyncSummary
+}): Promise<ArticleSyncState> => {
+	const nextState: ArticleSyncState = { ...state, attachments: {} }
+	const localPaths = new Set(article.attachments.map((attachment) => attachment.relativePath))
+	const imageIds: Array<string> = []
+
+	for (const attachment of article.attachments) {
+		const existing = state.attachments[attachment.relativePath]
+
+		if (existing?.hash === attachment.hash) {
+			nextState.attachments[attachment.relativePath] = existing
+			imageIds.push(existing.id)
+			continue
+		}
+
+		if (existing) {
+			summary.deletedAttachments += 1
+			if (!dryRun) await api.deleteAttachment(existing.url)
+		}
+
+		summary.uploadedAttachments += 1
+		if (dryRun) continue
+
+		const uploaded = await api.uploadAttachment({
+			articleId: article.id ?? getNewArticleFileKey(article),
+			path: attachment.absolutePath,
+		})
+		nextState.attachments[attachment.relativePath] = { hash: attachment.hash, id: uploaded.id, url: uploaded.url }
+		imageIds.push(uploaded.id)
+	}
+
+	for (const [relativePath, attachment] of Object.entries(state.attachments)) {
+		if (localPaths.has(relativePath)) continue
+
+		summary.deletedAttachments += 1
+		if (!dryRun) await api.deleteAttachment(attachment.url)
+	}
+
+	if (imageIds.length) {
+		summary.reorderedArticles += 1
+		if (!dryRun) await api.reorderAttachments({ articleId: article.id ?? getNewArticleFileKey(article), imageIds })
+	}
+
+	return nextState
+}
+
+export const syncFolder = async (options: SyncOptions): Promise<SyncSummary> => {
+	const config = await ensureProjectConfig(options)
+	const archive = await options.api.getArchive(config.collectionId)
+	const localArticles = await readArchive(options.cwd)
+	const remoteById = getRemoteById(archive)
+	const localById = getLocalById(localArticles)
+	const summary: SyncSummary = { ...EMPTY_SUMMARY }
+
+	assertNoUpstreamChanges({ archive, config, localArticles })
+
+	for (const articleId of Object.keys(config.articles)) {
+		if (localById.has(articleId) || !remoteById.has(articleId)) continue
+
+		summary.deletedArticles += 1
+		if (!options.dryRun) await options.api.deleteArticle(articleId)
+		delete config.articles[articleId]
+	}
+
+	for (const localArticle of localArticles) {
+		let articleId = localArticle.id
+		let remoteArticle = articleId ? remoteById.get(articleId) : undefined
+
+		if (!articleId) {
+			summary.createdArticles += 1
+
+			if (!options.dryRun) {
+				const createdArticle = await options.api.createArticle(config.collectionId)
+				articleId = createdArticle.id
+				localArticle.id = articleId
+				remoteArticle = createdArticle
+			}
+		} else {
+			summary.updatedArticles += 1
+		}
+
+		if (!options.dryRun && articleId) {
+			remoteArticle = await options.api.updateArticle({ articleId, values: getUpdateBody(localArticle) })
+			updateLocalFrontmatter({ article: localArticle, remote: remoteArticle })
+			await writeArticleFile({ article: localArticle })
+		}
+
+		if (!articleId) continue
+
+		const state: ArticleSyncState = config.articles[articleId] ?? {
+			attachments: {},
+			file: localArticle.file,
+			remoteUpdatedAt: null,
+		}
+		const syncedState = await syncAttachments({
+			api: options.api,
+			article: localArticle,
+			dryRun: options.dryRun,
+			state: { ...state, file: localArticle.file, remoteUpdatedAt: remoteArticle?.updatedAt ?? state.remoteUpdatedAt },
+			summary,
+		})
+
+		config.articles[articleId] = {
+			...syncedState,
+			file: localArticle.file,
+			remoteUpdatedAt: remoteArticle?.updatedAt ?? syncedState.remoteUpdatedAt,
+		}
+	}
+
+	config.lastSyncedAt = new Date().toISOString()
+	config.origin = options.origin
+
+	if (!options.dryRun) await writeProjectConfig(options.cwd, config)
+
+	return summary
+}

package/src/types.ts

@@ -0,0 +1,86 @@
+export interface RemoteCollection {
+	id: string
+	title: string
+	subdomain: string
+	description: string | null
+	updatedAt: string
+}
+
+export interface RemoteArticleImage {
+	id: string
+	articleId: string
+	url: string
+	width: number
+	height: number
+	color: string | null
+	description: string | null
+	source: string | null
+	createdAt: string
+	updatedAt: string | null
+}
+
+export interface RemoteArticle {
+	id: string
+	collectionId: string
+	categoryId: string | null
+	createdAt: string
+	updatedAt: string
+	isPublished: boolean
+	location: string | null
+	post: string | null
+	publishedAt: string | null
+	slug: string | null
+	images: Array<RemoteArticleImage>
+}
+
+export interface RemoteArchive {
+	collection: RemoteCollection
+	articles: Array<RemoteArticle>
+}
+
+export interface AttachmentSyncState {
+	id: string
+	url: string
+	hash: string
+}
+
+export interface ArticleSyncState {
+	file: string
+	remoteUpdatedAt: string | null
+	attachments: Record<string, AttachmentSyncState>
+}
+
+export interface ProjectConfig {
+	$schema?: string
+	version: 1
+	origin: string
+	collectionId: string
+	lastSyncedAt: string | null
+	articles: Record<string, ArticleSyncState>
+}
+
+export interface GlobalConfig {
+	origin?: string
+	apiKey?: string
+}
+
+export interface LocalAttachment {
+	relativePath: string
+	absolutePath: string
+	name: string
+	hash: string
+}
+
+export interface LocalArticle {
+	file: string
+	absolutePath: string
+	frontmatter: Record<string, unknown>
+	id: string | null
+	slug: string | null
+	isPublished: boolean
+	publishedAt: string | null
+	createdAt: string | null
+	location: string | null
+	body: string
+	attachments: Array<LocalAttachment>
+}