uncial-cms 0.0.0

package/dist/github/adapter.js

@@ -0,0 +1,135 @@
+import { bytesToBase64, decodeBase64, encodeBase64 } from '../base64.js';
+import { MAX_CONTENT_BYTES } from '../constants.js';
+import { ConflictError, NotFoundError } from '../errors.js';
+import { clearCachedSession, readCachedSession, writeCachedSession } from '../session.js';
+export const GITHUB_API_URL = 'https://api.github.com';
+function encodeRepoPath(path) {
+    return path.split('/').map(encodeURIComponent).join('/');
+}
+class GitHubAdapter {
+    #config = null;
+    #provider = null;
+    #session = null;
+    async authenticate(config, provider) {
+        if (config.forge !== 'github') {
+            throw new Error('GitHub adapter requires a GitHub site configuration.');
+        }
+        this.#config = config;
+        this.#provider = provider;
+        this.#session = readCachedSession(config.repo) ?? (await this.#renewSession());
+        return this.#session;
+    }
+    async readFile(path) {
+        const response = await this.#request(`${this.#contentsUrl(path)}?ref=${this.#config.branch}`);
+        if (response.status === 404) {
+            throw new NotFoundError(`File not found in ${this.#config.repo}@${this.#config.branch}: ${path}`);
+        }
+        await this.#assertOk(response, `read ${path}`);
+        const file = (await response.json());
+        if (Array.isArray(file)) {
+            throw new Error(`Expected a file but found a directory: ${path}`);
+        }
+        if (file.encoding !== 'base64' || (file.size ?? 0) > MAX_CONTENT_BYTES) {
+            throw new Error(`Document ${path} exceeds the 1 MB limit of the GitHub Contents API and cannot be edited.`);
+        }
+        return { content: decodeBase64(file.content ?? ''), sha: file.sha };
+    }
+    async writeFile(path, content, opts) {
+        const response = await this.#request(this.#contentsUrl(path), {
+            method: 'PUT',
+            body: JSON.stringify({
+                message: opts.message,
+                content: typeof content === 'string' ? encodeBase64(content) : bytesToBase64(content),
+                branch: this.#config.branch,
+                ...(opts.sha === undefined ? {} : { sha: opts.sha }),
+                author: opts.author
+            })
+        });
+        if (response.status === 409)
+            throw new ConflictError();
+        await this.#assertOk(response, `write ${path}`);
+        const result = (await response.json());
+        return { sha: result.content.sha, commitSha: result.commit.sha };
+    }
+    async deleteFile(path, opts) {
+        const response = await this.#request(this.#contentsUrl(path), {
+            method: 'DELETE',
+            body: JSON.stringify({
+                message: opts.message,
+                sha: opts.sha,
+                branch: this.#config.branch
+            })
+        });
+        if (response.status === 409)
+            throw new ConflictError();
+        await this.#assertOk(response, `delete ${path}`);
+    }
+    async listDir(path) {
+        const response = await this.#request(`${this.#contentsUrl(path)}?ref=${this.#config.branch}`);
+        await this.#assertOk(response, `list ${path}`);
+        const entries = (await response.json());
+        if (!Array.isArray(entries)) {
+            throw new Error(`Expected a directory but found a file: ${path}`);
+        }
+        return entries
+            .filter((entry) => entry.type === 'file' || entry.type === 'dir')
+            .map((entry) => ({ path: entry.path, type: entry.type }));
+    }
+    async commitStatus(commitSha) {
+        const response = await this.#request(`${GITHUB_API_URL}/repos/${this.#config.repo}/commits/${encodeURIComponent(commitSha)}/status`);
+        if (!response.ok)
+            return 'unknown';
+        const { state } = (await response.json());
+        if (state === 'pending' || state === 'success')
+            return state;
+        if (state === 'failure' || state === 'error')
+            return 'failure';
+        return 'unknown';
+    }
+    #contentsUrl(path) {
+        return `${GITHUB_API_URL}/repos/${this.#config.repo}/contents/${encodeRepoPath(path)}`;
+    }
+    async #renewSession() {
+        const session = await this.#provider(this.#config);
+        writeCachedSession(session);
+        return session;
+    }
+    async #request(url, init = {}) {
+        const response = await this.#send(url, init);
+        if (response.status !== 401)
+            return response;
+        // Expired/revoked token: clear the session, re-invoke the provider, retry once.
+        clearCachedSession(this.#config.repo);
+        this.#session = await this.#renewSession();
+        return this.#send(url, init);
+    }
+    async #send(url, init) {
+        if (!this.#config || !this.#session) {
+            throw new Error('GitHub adapter is not authenticated; call authenticate() first.');
+        }
+        return fetch(url, {
+            ...init,
+            headers: {
+                Accept: 'application/vnd.github+json',
+                Authorization: `Bearer ${this.#session.token}`,
+                'X-GitHub-Api-Version': '2022-11-28',
+                ...init.headers
+            }
+        });
+    }
+    async #assertOk(response, action) {
+        if (response.ok)
+            return;
+        let detail = '';
+        try {
+            detail = (await response.json()).message ?? '';
+        }
+        catch {
+            // Non-JSON error body; the status code is enough.
+        }
+        throw new Error(`GitHub request failed (${response.status}) while trying to ${action}${detail ? `: ${detail}` : ''}`);
+    }
+}
+export function createGitHubAdapter() {
+    return new GitHubAdapter();
+}

package/dist/github/index.d.ts

@@ -0,0 +1,3 @@
+export { createGitHubAdapter } from './adapter.js';
+export { patSessionProvider } from './pat.js';
+export { popupSessionProvider } from './popup.js';

package/dist/github/index.js

@@ -0,0 +1,3 @@
+export { createGitHubAdapter } from './adapter.js';
+export { patSessionProvider } from './pat.js';
+export { popupSessionProvider } from './popup.js';

package/dist/github/pat.d.ts

@@ -0,0 +1,7 @@
+import type { SessionProvider } from '../types.js';
+/**
+ * Zero-backend session provider: prompts for a fine-grained personal access
+ * token and validates it via `GET /user`. The permanent dev/self-service auth
+ * mode; the worker-based provider (issue 03) is layered on the same seam.
+ */
+export declare const patSessionProvider: SessionProvider;

package/dist/github/pat.js

@@ -0,0 +1,35 @@
+import { GITHUB_API_URL } from './adapter.js';
+/**
+ * Zero-backend session provider: prompts for a fine-grained personal access
+ * token and validates it via `GET /user`. The permanent dev/self-service auth
+ * mode; the worker-based provider (issue 03) is layered on the same seam.
+ */
+export const patSessionProvider = async (config) => {
+    const githubConfig = config;
+    const token = window
+        .prompt(`Paste a GitHub personal access token with contents read/write access to ${githubConfig.repo}:`)
+        ?.trim();
+    if (!token)
+        throw new Error('A personal access token is required to edit this page.');
+    const response = await fetch(`${GITHUB_API_URL}/user`, {
+        headers: {
+            Accept: 'application/vnd.github+json',
+            Authorization: `Bearer ${token}`,
+            'X-GitHub-Api-Version': '2022-11-28'
+        }
+    });
+    if (!response.ok) {
+        throw new Error(`GitHub rejected the personal access token (${response.status}).`);
+    }
+    const user = (await response.json());
+    return {
+        token,
+        expiresAt: null,
+        repo: githubConfig.repo,
+        user: {
+            login: user.login,
+            name: user.name ?? user.login,
+            email: `${user.id}+${user.login}@users.noreply.github.com`
+        }
+    };
+};

package/dist/github/popup.d.ts

@@ -0,0 +1,9 @@
+import type { SessionProvider } from '../types.js';
+/**
+ * Default session provider (issue 03): opens the auth worker in a popup with a
+ * PKCE challenge, waits for the worker's callback page to relay {code, state},
+ * then finishes the exchange at POST /token. The verifier never leaves this
+ * page, and the token that comes back is an installation token scoped to the
+ * one configured repository.
+ */
+export declare const popupSessionProvider: SessionProvider;

package/dist/github/popup.js

@@ -0,0 +1,75 @@
+function base64UrlEncode(bytes) {
+    const view = bytes instanceof ArrayBuffer ? new Uint8Array(bytes) : bytes;
+    let binary = '';
+    for (const byte of view)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
+}
+function waitForRelay(workerOrigin, popup) {
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            window.removeEventListener('message', onMessage);
+            clearInterval(closedPoll);
+        };
+        const onMessage = (event) => {
+            if (event.origin !== workerOrigin)
+                return;
+            const data = event.data;
+            if (data?.source !== 'uncial-cms-auth' ||
+                typeof data.code !== 'string' ||
+                typeof data.state !== 'string') {
+                return;
+            }
+            cleanup();
+            resolve({ code: data.code, state: data.state });
+        };
+        const closedPoll = setInterval(() => {
+            if (popup.closed) {
+                cleanup();
+                reject(new Error('The sign-in popup was closed before completing.'));
+            }
+        }, 500);
+        window.addEventListener('message', onMessage);
+    });
+}
+/**
+ * Default session provider (issue 03): opens the auth worker in a popup with a
+ * PKCE challenge, waits for the worker's callback page to relay {code, state},
+ * then finishes the exchange at POST /token. The verifier never leaves this
+ * page, and the token that comes back is an installation token scoped to the
+ * one configured repository.
+ */
+export const popupSessionProvider = async (config) => {
+    const githubConfig = config;
+    if (!githubConfig.authWorkerUrl) {
+        throw new Error('config.authWorkerUrl is not set; configure the auth worker or use patSessionProvider.');
+    }
+    const workerBase = githubConfig.authWorkerUrl.replace(/\/+$/, '');
+    const workerOrigin = new URL(workerBase).origin;
+    const verifier = base64UrlEncode(crypto.getRandomValues(new Uint8Array(32)));
+    const challenge = base64UrlEncode(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier)));
+    const authUrl = new URL(`${workerBase}/auth`);
+    authUrl.searchParams.set('repo', githubConfig.repo);
+    authUrl.searchParams.set('origin', window.location.origin);
+    authUrl.searchParams.set('challenge', challenge);
+    const popup = window.open(authUrl.toString(), 'uncial-cms-auth', 'popup,width=640,height=760');
+    if (!popup)
+        throw new Error('The sign-in popup was blocked; allow popups for this site.');
+    const { code, state } = await waitForRelay(workerOrigin, popup);
+    const response = await fetch(`${workerBase}/token`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ code, state, verifier })
+    });
+    if (!response.ok) {
+        const { error } = (await response.json().catch(() => ({})));
+        throw new Error(`Sign-in failed (${error ?? response.status}).`);
+    }
+    const session = (await response.json());
+    return {
+        token: session.token,
+        expiresAt: session.expiresAt,
+        repo: session.repo,
+        user: session.user
+    };
+};

package/dist/index-actions.d.ts

@@ -0,0 +1,74 @@
+import type { Site } from './define-site.js';
+import { type FitOptions, type ImageEncoder } from './fit-image.js';
+import type { ForgeAdapter } from './types.js';
+export interface CreatePageDeps {
+    adapter: ForgeAdapter;
+    blocks: unknown;
+    schema: unknown;
+    author: {
+        name: string;
+        email: string;
+    };
+}
+export interface PageRef {
+    pagePath: string;
+    sourcePath: string;
+}
+/** Seed `sourcePath` with a normalized empty document (create-mode commit). */
+export declare function createPage(deps: CreatePageDeps, { pagePath, sourcePath }: PageRef): Promise<{
+    sha: string;
+    commitSha: string;
+}>;
+/** Delete `sourcePath` at its current sha. */
+export declare function deletePage(adapter: ForgeAdapter, { pagePath, sourcePath }: PageRef): Promise<void>;
+export interface UploadAssetFile {
+    bytes: Uint8Array;
+    filename: string;
+    contentType: string;
+}
+export interface UploadAssetOptions {
+    /** Repo-root-relative dir the asset is committed into; defaults from `site`. */
+    mediaDir?: string;
+    /** Supplies `mediaDir` when it is not passed explicitly. */
+    site?: Site;
+    author: {
+        name: string;
+        email: string;
+    };
+}
+export interface UploadAssetResult {
+    path: string;
+    sha: string;
+    commitSha: string;
+}
+/**
+ * Commit an image into the repo at a content-addressed path under `mediaDir`.
+ * Identical bytes hash to the same path, so re-uploads reuse the existing file
+ * (no second commit). Files over the Contents API limit reject before any
+ * network call — there is no git-blobs-API fallback (spec media non-goal).
+ */
+export declare function uploadAsset(deps: {
+    adapter: ForgeAdapter;
+}, file: UploadAssetFile, opts: UploadAssetOptions): Promise<UploadAssetResult>;
+export interface UploadImageAssetOptions {
+    mediaDir?: string;
+    site?: Site;
+    /**
+     * Re-encode an oversize image to fit the forge's limit before committing.
+     * `true` takes the defaults; the object form also accepts an `encoder`, the
+     * seam {@link fitImage} decodes and encodes through.
+     */
+    fit?: boolean | (FitOptions & {
+        encoder?: ImageEncoder;
+    });
+}
+/**
+ * Editor-facing convenience over {@link uploadAsset}: resolves the adapter,
+ * author and `mediaDir` from the {@link getActiveForge active editor session}
+ * so a block's Upload affordance only has to supply the file. Throws a clear
+ * error when no editor is mounted (e.g. called before sign-in). Import this
+ * dynamically from a block so the reader bundle stays free of CMS runtime.
+ */
+export declare function uploadImageAsset(file: UploadAssetFile | File, opts?: UploadImageAssetOptions): Promise<UploadAssetResult>;
+/** Recursively list the content dir's JSON sources, sorted by page path. */
+export declare function listPages(adapter: ForgeAdapter, contentDir: string, mapSourceToPath?: (source: string) => string): Promise<PageRef[]>;

package/dist/index-actions.js

@@ -0,0 +1,147 @@
+/**
+ * Forge-level actions behind the `/uncial/` index UI (PRD §6.6): list the
+ * content dir, seed a new page, delete a page. DOM-free so they unit-test
+ * against a fake adapter; `mountIndexPage` wires them to the UI.
+ */
+import { normalizeDocument } from 'uncial/core';
+import { MAX_CONTENT_BYTES } from './constants.js';
+import { serializeDocument } from './document.js';
+import { NotFoundError } from './errors.js';
+import { fitImage } from './fit-image.js';
+import { defaultMapSourceToPath } from './paths/index.js';
+import { getActiveForge } from './upload-context.js';
+/** Seed `sourcePath` with a normalized empty document (create-mode commit). */
+export async function createPage(deps, { pagePath, sourcePath }) {
+    const blocks = deps.blocks;
+    const schema = deps.schema;
+    let exists = true;
+    try {
+        await deps.adapter.readFile(sourcePath);
+    }
+    catch (error) {
+        if (!(error instanceof NotFoundError))
+            throw error;
+        exists = false;
+    }
+    if (exists) {
+        throw new Error(`A page already exists at "${pagePath}" (${sourcePath}).`);
+    }
+    const seed = normalizeDocument({ type: 'doc', content: [{ type: 'paragraph' }] }, blocks, schema);
+    return deps.adapter.writeFile(sourcePath, serializeDocument(seed, blocks, schema), {
+        message: `uncial-cms: create ${pagePath}`,
+        author: deps.author
+    });
+}
+/** Delete `sourcePath` at its current sha. */
+export async function deletePage(adapter, { pagePath, sourcePath }) {
+    const { sha } = await adapter.readFile(sourcePath);
+    await adapter.deleteFile(sourcePath, { message: `uncial-cms: delete ${pagePath}`, sha });
+}
+const EXTENSION_FROM_CONTENT_TYPE = {
+    'image/jpeg': 'jpg',
+    'image/svg+xml': 'svg'
+};
+/** Extension from the filename if present, else derived from the content type. */
+function assetExtension(filename, contentType) {
+    const dot = filename.lastIndexOf('.');
+    if (dot > 0 && dot < filename.length - 1) {
+        return filename.slice(dot + 1).toLowerCase();
+    }
+    const type = contentType.toLowerCase();
+    return EXTENSION_FROM_CONTENT_TYPE[type] ?? type.split('/')[1] ?? 'bin';
+}
+/** SHA-256 of the bytes, hex, truncated — the content-addressed asset name. */
+async function contentHash(bytes) {
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    const hex = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0'));
+    return hex.join('').slice(0, 32);
+}
+/**
+ * Commit an image into the repo at a content-addressed path under `mediaDir`.
+ * Identical bytes hash to the same path, so re-uploads reuse the existing file
+ * (no second commit). Files over the Contents API limit reject before any
+ * network call — there is no git-blobs-API fallback (spec media non-goal).
+ */
+export async function uploadAsset(deps, file, opts) {
+    if (file.bytes.byteLength > MAX_CONTENT_BYTES) {
+        throw new Error(`Image "${file.filename}" is ${file.bytes.byteLength} bytes, over the 1 MB limit of the GitHub Contents API.`);
+    }
+    const ext = assetExtension(file.filename, file.contentType);
+    const hash = await contentHash(file.bytes);
+    const dir = resolveMediaDir(opts.mediaDir, opts.site?.config.mediaDir).replace(/\/+$/, '');
+    const path = `${dir}/${hash}.${ext}`;
+    // Content-addressed: if the path already exists, the bytes are identical.
+    try {
+        const existing = await deps.adapter.readFile(path);
+        return { path, sha: existing.sha, commitSha: '' };
+    }
+    catch (error) {
+        if (!(error instanceof NotFoundError))
+            throw error;
+    }
+    const { sha, commitSha } = await deps.adapter.writeFile(path, file.bytes, {
+        message: `uncial-cms: upload ${path}`,
+        author: opts.author
+    });
+    return { path, sha, commitSha };
+}
+/** `mediaDir` from the most specific source that supplies one. */
+function resolveMediaDir(...candidates) {
+    const dir = candidates.find((candidate) => candidate);
+    if (!dir) {
+        throw new Error('No media directory for the upload: pass `mediaDir`, or give a `site` whose config sets it.');
+    }
+    return dir;
+}
+/** Read a picked `File` (or a `Blob`) into the bytes `uploadAsset` commits. */
+async function assetFileFromBlob(file) {
+    return {
+        bytes: new Uint8Array(await file.arrayBuffer()),
+        filename: file.name || 'image',
+        contentType: file.type || 'application/octet-stream'
+    };
+}
+/** A `Blob` view of an already-read asset, for handing to {@link fitImage}. */
+function blobFromAssetFile(file) {
+    const blob = new Blob([file.bytes], {
+        type: file.contentType
+    });
+    blob.name = file.filename;
+    return blob;
+}
+/**
+ * Editor-facing convenience over {@link uploadAsset}: resolves the adapter,
+ * author and `mediaDir` from the {@link getActiveForge active editor session}
+ * so a block's Upload affordance only has to supply the file. Throws a clear
+ * error when no editor is mounted (e.g. called before sign-in). Import this
+ * dynamically from a block so the reader bundle stays free of CMS runtime.
+ */
+export async function uploadImageAsset(file, opts = {}) {
+    const forge = getActiveForge();
+    if (!forge) {
+        throw new Error('No active editor session — open a page in the editor and sign in before uploading.');
+    }
+    const mediaDir = resolveMediaDir(opts.mediaDir, opts.site?.config.mediaDir, forge.config.mediaDir);
+    const asset = opts.fit
+        ? await fitImage(file instanceof Blob ? file : blobFromAssetFile(file), opts.fit === true ? {} : opts.fit)
+        : file instanceof Blob
+            ? await assetFileFromBlob(file)
+            : file;
+    return uploadAsset({ adapter: forge.adapter }, asset, { mediaDir, author: forge.author });
+}
+/** Recursively list the content dir's JSON sources, sorted by page path. */
+export async function listPages(adapter, contentDir, mapSourceToPath = (source) => defaultMapSourceToPath(source, contentDir)) {
+    const sources = [];
+    const walk = async (dir) => {
+        for (const entry of await adapter.listDir(dir)) {
+            if (entry.type === 'dir')
+                await walk(entry.path);
+            else if (entry.path.endsWith('.json'))
+                sources.push(entry.path);
+        }
+    };
+    await walk(contentDir);
+    return sources
+        .map((sourcePath) => ({ pagePath: mapSourceToPath(sourcePath), sourcePath }))
+        .sort((a, b) => a.pagePath.localeCompare(b.pagePath));
+}

package/dist/index-page.d.ts

@@ -0,0 +1,19 @@
+import type { SessionProvider, UncialCmsSiteConfig } from './types.js';
+export interface MountIndexPageOptions {
+    config: UncialCmsSiteConfig;
+    blocks: unknown;
+    schema: unknown;
+    sessionProvider?: SessionProvider;
+    /** Site-relative page path → repo-root-relative JSON path. Defaults to the
+     * mapping convention; must match the one baked into the editor variants. */
+    mapPathToSource?: (path: string) => string;
+    /** Inverse of mapPathToSource, used to label listed sources. */
+    mapSourceToPath?: (source: string) => string;
+    /** URL prefix for live-page links (the framework's base path), e.g.
+     * '/uncial/cms-demo'. Default ''. */
+    basePath?: string;
+    editorStylesheets?: string[];
+}
+export declare function mountIndexPage(target: HTMLElement, opts: MountIndexPageOptions): {
+    destroy(): void;
+};