@geekity/cms 0.3.0

package/dist/content/parser.js

@@ -0,0 +1,165 @@
+import { createHash } from 'node:crypto';
+import matter from 'gray-matter';
+import { KNOWN_FRONT_MATTER_KEYS } from './document.js';
+import { renderMarkdown } from './markdown.js';
+import { defaultPermalink, slugify } from './slug.js';
+import { normalizeBody, serializeDocument } from './writer.js';
+const KNOWN_KEYS = new Set(KNOWN_FRONT_MATTER_KEYS);
+/**
+ * Parse the text of a Markdown file into a {@link Document}.
+ *
+ * Front matter is read with gray-matter and the body rendered with
+ * markdown-it. Dates become ISO 8601 strings whether the file quoted them or
+ * left YAML to parse them, and every key the CMS does not model is kept.
+ */
+export function parseDocument(source, options) {
+    const path = normalizePath(options.path);
+    const text = source.replace(/\r\n?/g, '\n');
+    if (!/^---\n/.test(text)) {
+        throw new TypeError(`${path} has no YAML front matter.`);
+    }
+    // The empty options object opts out of gray-matter's module-level cache, so
+    // two documents parsed from identical text never share nested data objects.
+    const parsed = matter(text, {});
+    const data = parsed.data;
+    const title = requiredString(data['title'], 'title', path);
+    const type = options.type ?? typeForPath(path);
+    const date = asDate(data['date'], 'date', path);
+    const body = normalizeBody(parsed.content);
+    const permalink = asString(data['permalink']) ??
+        defaultPermalink({
+            type,
+            slug: fallbackSlug(title, path),
+            date,
+        });
+    const content = {
+        title,
+        permalink,
+        tags: asTags(data['tags']),
+        draft: data['draft'] === true,
+        extra: extraOf(data),
+        body,
+        ...(date === undefined ? {} : { date }),
+        ...optional('updated', asDate(data['updated'], 'updated', path)),
+        ...optional('description', asString(data['description'])),
+        ...optional('author', asString(data['author'])),
+        ...optional('activitypub', asActivityPub(data['activitypub'], path)),
+    };
+    return {
+        ...content,
+        type,
+        path,
+        slug: slugForPermalink(permalink) ?? fallbackSlug(title, path),
+        html: renderMarkdown(body),
+        hash: hashDocument(content),
+    };
+}
+/** The SHA-256 a {@link Document} carries: a hash of its canonical file text. */
+export function hashDocument(content) {
+    return createHash('sha256').update(serializeDocument(content), 'utf8').digest('hex');
+}
+/**
+ * Decide whether a path holds a post or a page. Only the directory matters, so
+ * a file that moves between `posts/` and `pages/` changes type with it.
+ */
+export function typeForPath(path) {
+    for (const segment of path.split('/')) {
+        if (segment === 'posts')
+            return 'post';
+        if (segment === 'pages')
+            return 'page';
+    }
+    throw new TypeError(`Cannot tell the type of ${path}: it is under neither posts/ nor pages/. Pass an explicit type.`);
+}
+/** Content paths are POSIX and relative, whatever the host filesystem says. */
+function normalizePath(path) {
+    return path.replace(/\\/g, '/').replace(/^\.?\//, '');
+}
+/**
+ * The slug a permalink implies: its last segment, without any file extension.
+ * `/2026/09/hello-world/` is `hello-world`; `/feed.xml` is `feed`.
+ */
+function slugForPermalink(permalink) {
+    const segments = permalink.split('/').filter((segment) => segment !== '');
+    const last = segments.at(-1);
+    if (last === undefined)
+        return undefined;
+    const slug = last.replace(/\.[^.]+$/, '');
+    return slug === '' ? undefined : slug;
+}
+/** The slug for a document whose permalink has not been decided yet. */
+function fallbackSlug(title, path) {
+    const fromTitle = slugify(title);
+    if (fromTitle !== '')
+        return fromTitle;
+    const basename = path.split('/').at(-1) ?? '';
+    return slugify(basename.replace(/\.md$/, '').replace(/^\d{4}-\d{2}-\d{2}-/, ''));
+}
+function extraOf(data) {
+    const extra = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (KNOWN_KEYS.has(key))
+            continue;
+        extra[key] = value;
+    }
+    return extra;
+}
+function optional(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}
+function requiredString(value, key, path) {
+    const text = asString(value);
+    if (text === undefined) {
+        throw new TypeError(`${path} needs a non-empty ${key} in its front matter.`);
+    }
+    return text;
+}
+function asString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    return value === '' ? undefined : value;
+}
+/**
+ * YAML parses an unquoted timestamp into a Date and leaves a quoted one a
+ * string. Either way a Document holds an ISO 8601 string, so the offset the
+ * author wrote survives when there was one.
+ */
+function asDate(value, key, path) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            throw new TypeError(`${path} has an unreadable ${key}.`);
+        }
+        return value.toISOString();
+    }
+    const text = asString(value);
+    if (text === undefined) {
+        throw new TypeError(`${path} has a ${key} that is neither a date nor a string.`);
+    }
+    return text;
+}
+/** Eleventy accepts one tag as a bare string; the CMS always keeps a list. */
+function asTags(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (typeof value === 'string')
+        return value === '' ? [] : [value];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((tag) => typeof tag === 'string' && tag !== '');
+}
+function asActivityPub(value, path) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        throw new TypeError(`${path} has an activitypub key that is not a mapping.`);
+    }
+    const block = value;
+    const metadata = {
+        ...optional('id', asString(block['id'])),
+        ...optional('published', asDate(block['published'], 'activitypub.published', path)),
+    };
+    return Object.keys(metadata).length === 0 ? undefined : metadata;
+}
+//# sourceMappingURL=parser.js.map

package/dist/content/parser.js.map

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

package/dist/content/save.d.ts

@@ -0,0 +1,60 @@
+import type { Document, DocumentContent, DocumentType } from './document.ts';
+import type { ContentStore } from './store.ts';
+/** What {@link contentFilePath} needs to name a file. */
+export interface ContentFilePathInput {
+    /** Posts get a dated filename; pages do not. */
+    type: DocumentType;
+    /** The slug, already URL-safe. It becomes the tail of the filename. */
+    slug: string;
+    /** Publish date, ISO 8601. Required for a post, ignored for a page. */
+    date?: string | Date | undefined;
+}
+/**
+ * Where a document's file goes, relative to the content directory.
+ *
+ * doc-2: a post filename carries its date so the directory sorts on disk, a
+ * page filename does not. Neither is ever parsed for a URL — the front matter's
+ * `permalink` is what decides that — so renaming a file changes nothing but
+ * the sort order.
+ */
+export declare function contentFilePath(input: ContentFilePathInput): string;
+/** What {@link freeSlug} looks for a gap in. */
+export interface FreeSlugOptions extends ContentFilePathInput {
+    /** The content directory the file would go in. */
+    contentDir: string;
+    /** The index, consulted so a permalink another file claims is skipped too. */
+    store: ContentStore;
+}
+/**
+ * The given slug, or the first numbered variant of it that neither the content
+ * directory nor the index has already claimed.
+ *
+ * Both are checked because they can disagree for a moment: a file the watcher
+ * has not picked up yet is on disk and not in the index, and a file that was
+ * deleted outside the CMS is the other way round. Overwriting either would
+ * lose someone's writing.
+ */
+export declare function freeSlug(options: FreeSlugOptions): Promise<string>;
+/** What {@link saveDocument} writes, and where. */
+export interface SaveDocumentOptions {
+    /** The content directory. Missing parent directories are created. */
+    contentDir: string;
+    /** The index to bring up to date once the bytes have landed. */
+    store: ContentStore;
+    /** The file's path relative to {@link SaveDocumentOptions.contentDir}. */
+    path: string;
+    /** The document to serialize. */
+    content: DocumentContent;
+}
+/**
+ * The admin's write path, per doc-1: serialize, write the file atomically, then
+ * update the index directly rather than waiting for the watcher.
+ *
+ * The temporary file is written in the same directory as its destination so the
+ * rename is a rename and not a copy across devices, and a reader either sees
+ * the old file or the whole new one, never a half-written one. The watcher
+ * event that follows the rename is a no-op, because the hash already matches
+ * what this put in the index.
+ */
+export declare function saveDocument(options: SaveDocumentOptions): Promise<Document>;
+//# sourceMappingURL=save.d.ts.map

package/dist/content/save.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"save.d.ts","sourceRoot":"","sources":["../../src/content/save.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,IAAI,EAAE,YAAY,CAAC;IACnB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAYnE;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAgB,SAAQ,oBAAoB;IAC3D,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAcxE;AAED,mDAAmD;AACnD,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,KAAK,EAAE,YAAY,CAAC;IACpB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,OAAO,EAAE,eAAe,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsBlF"}

package/dist/content/save.js

@@ -0,0 +1,103 @@
+import { randomBytes } from 'node:crypto';
+import { access, mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseDocument } from './parser.js';
+import { defaultPermalink } from './slug.js';
+import { serializeDocument } from './writer.js';
+/**
+ * Where a document's file goes, relative to the content directory.
+ *
+ * doc-2: a post filename carries its date so the directory sorts on disk, a
+ * page filename does not. Neither is ever parsed for a URL — the front matter's
+ * `permalink` is what decides that — so renaming a file changes nothing but
+ * the sort order.
+ */
+export function contentFilePath(input) {
+    if (input.slug === '') {
+        throw new TypeError('A content file needs a non-empty slug.');
+    }
+    if (input.type === 'page')
+        return `pages/${input.slug}.md`;
+    if (input.date === undefined) {
+        throw new TypeError(`A post filename needs a date; "${input.slug}" has none.`);
+    }
+    return `posts/${calendarDay(input.date)}-${input.slug}.md`;
+}
+/**
+ * The given slug, or the first numbered variant of it that neither the content
+ * directory nor the index has already claimed.
+ *
+ * Both are checked because they can disagree for a moment: a file the watcher
+ * has not picked up yet is on disk and not in the index, and a file that was
+ * deleted outside the CMS is the other way round. Overwriting either would
+ * lose someone's writing.
+ */
+export async function freeSlug(options) {
+    const { contentDir, store, ...input } = options;
+    for (let suffix = 1;; suffix += 1) {
+        const slug = suffix === 1 ? input.slug : `${input.slug}-${String(suffix)}`;
+        const relative = contentFilePath({ ...input, slug });
+        const permalink = defaultPermalink({ type: input.type, slug, date: input.date });
+        if (store.getByPath(relative) !== undefined)
+            continue;
+        if (store.getByPermalink(permalink) !== undefined)
+            continue;
+        if (await exists(path.join(contentDir, ...relative.split('/'))))
+            continue;
+        return slug;
+    }
+}
+/**
+ * The admin's write path, per doc-1: serialize, write the file atomically, then
+ * update the index directly rather than waiting for the watcher.
+ *
+ * The temporary file is written in the same directory as its destination so the
+ * rename is a rename and not a copy across devices, and a reader either sees
+ * the old file or the whole new one, never a half-written one. The watcher
+ * event that follows the rename is a no-op, because the hash already matches
+ * what this put in the index.
+ */
+export async function saveDocument(options) {
+    const relative = options.path.replace(/\\/g, '/');
+    const file = path.join(options.contentDir, ...relative.split('/'));
+    const source = serializeDocument(options.content);
+    // Parsed before it is written, so a document that cannot be read back is
+    // refused rather than left on disk for the watcher to complain about.
+    const document = parseDocument(source, { path: relative });
+    await mkdir(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${randomBytes(6).toString('hex')}.tmp`;
+    try {
+        await writeFile(temporary, source, 'utf8');
+        await rename(temporary, file);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+    options.store.upsert(document);
+    return document;
+}
+/** The calendar day of a date as written, without shifting it into another one. */
+function calendarDay(date) {
+    if (date instanceof Date) {
+        if (Number.isNaN(date.getTime())) {
+            throw new TypeError('A post filename needs a valid date.');
+        }
+        return date.toISOString().slice(0, 10);
+    }
+    const match = /^(\d{4}-\d{2}-\d{2})/.exec(date);
+    if (match?.[1] === undefined) {
+        throw new TypeError(`A post filename needs an ISO 8601 date, received ${JSON.stringify(date)}`);
+    }
+    return match[1];
+}
+async function exists(file) {
+    try {
+        await access(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=save.js.map

package/dist/content/save.js.map

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

package/dist/content/slug.d.ts

@@ -0,0 +1,25 @@
+import type { DocumentType } from './document.ts';
+/**
+ * Turn a title into a URL slug: lowercase ASCII letters, digits and hyphens.
+ *
+ * Accented letters lose their accents, a few letters that do not decompose are
+ * transliterated, and everything else becomes a separator. Returns an empty
+ * string when nothing survives, so callers can fall back to something else.
+ */
+export declare function slugify(title: string): string;
+/** What {@link defaultPermalink} needs to know about a document. */
+export interface DefaultPermalinkInput {
+    type: DocumentType;
+    slug: string;
+    /** Publish date. Required for posts, ignored for pages. */
+    date?: string | Date | undefined;
+}
+/**
+ * The permalink the admin form proposes for a new document.
+ *
+ * Posts live under their year and month, pages at the top level. Both end in a
+ * slash, which is the canonical form. The stored `permalink` is what actually
+ * counts: this only fills the field in when the form supplies none.
+ */
+export declare function defaultPermalink(input: DefaultPermalinkInput): string;
+//# sourceMappingURL=slug.d.ts.map

package/dist/content/slug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug.d.ts","sourceRoot":"","sources":["../../src/content/slug.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAoBlD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAW7C;AAED,oEAAoE;AACpE,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAarE"}

package/dist/content/slug.js

@@ -0,0 +1,75 @@
+/**
+ * Letters that Unicode decomposition leaves alone. NFKD splits `é` into `e` and
+ * a combining accent, but `æ` and `ß` are letters in their own right, so they
+ * need spelling out before the ASCII filter throws them away.
+ */
+const TRANSLITERATIONS = [
+    [/ß/g, 'ss'],
+    [/æ/g, 'ae'],
+    [/œ/g, 'oe'],
+    [/ø/g, 'o'],
+    [/đ|ð/g, 'd'],
+    [/ł/g, 'l'],
+    [/þ/g, 'th'],
+    [/ħ/g, 'h'],
+    [/ı/g, 'i'],
+    [/ŋ/g, 'n'],
+];
+/**
+ * Turn a title into a URL slug: lowercase ASCII letters, digits and hyphens.
+ *
+ * Accented letters lose their accents, a few letters that do not decompose are
+ * transliterated, and everything else becomes a separator. Returns an empty
+ * string when nothing survives, so callers can fall back to something else.
+ */
+export function slugify(title) {
+    let value = title.normalize('NFKD').toLowerCase();
+    for (const [pattern, replacement] of TRANSLITERATIONS) {
+        value = value.replace(pattern, replacement);
+    }
+    return value
+        .replace(/[\u0300-\u036f]/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * The permalink the admin form proposes for a new document.
+ *
+ * Posts live under their year and month, pages at the top level. Both end in a
+ * slash, which is the canonical form. The stored `permalink` is what actually
+ * counts: this only fills the field in when the form supplies none.
+ */
+export function defaultPermalink(input) {
+    if (input.slug === '') {
+        throw new TypeError('A permalink needs a non-empty slug.');
+    }
+    if (input.type === 'page')
+        return `/${input.slug}/`;
+    if (input.date === undefined) {
+        throw new TypeError(`A post permalink needs a date; "${input.slug}" has none.`);
+    }
+    const { year, month } = yearAndMonth(input.date);
+    return `/${year}/${month}/${input.slug}/`;
+}
+/**
+ * Read the calendar year and month of a date as written, without shifting it
+ * into UTC: a post published at 00:30 on 1 October in Berlin belongs to
+ * October, not to September.
+ */
+function yearAndMonth(date) {
+    if (date instanceof Date) {
+        if (Number.isNaN(date.getTime())) {
+            throw new TypeError('A post permalink needs a valid date.');
+        }
+        return {
+            year: String(date.getUTCFullYear()).padStart(4, '0'),
+            month: String(date.getUTCMonth() + 1).padStart(2, '0'),
+        };
+    }
+    const match = /^(\d{4})-(\d{2})/.exec(date);
+    if (match === null || match[1] === undefined || match[2] === undefined) {
+        throw new TypeError(`A post permalink needs an ISO 8601 date, received ${JSON.stringify(date)}`);
+    }
+    return { year: match[1], month: match[2] };
+}
+//# sourceMappingURL=slug.js.map

package/dist/content/slug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug.js","sourceRoot":"","sources":["../../src/content/slug.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,gBAAgB,GAA6C;IACjE,CAAC,IAAI,EAAE,IAAI,CAAC;IACZ,CAAC,IAAI,EAAE,IAAI,CAAC;IACZ,CAAC,IAAI,EAAE,IAAI,CAAC;IACZ,CAAC,IAAI,EAAE,GAAG,CAAC;IACX,CAAC,MAAM,EAAE,GAAG,CAAC;IACb,CAAC,IAAI,EAAE,GAAG,CAAC;IACX,CAAC,IAAI,EAAE,IAAI,CAAC;IACZ,CAAC,IAAI,EAAE,GAAG,CAAC;IACX,CAAC,IAAI,EAAE,GAAG,CAAC;IACX,CAAC,IAAI,EAAE,GAAG,CAAC;CACZ,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,IAAI,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;IAElD,KAAK,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,gBAAgB,EAAE,CAAC;QACtD,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAC9C,CAAC;IAED,OAAO,KAAK;SACT,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;SAC/B,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC;AAUD;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAA4B;IAC3D,IAAI,KAAK,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;QACtB,MAAM,IAAI,SAAS,CAAC,qCAAqC,CAAC,CAAC;IAC7D,CAAC;IAED,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,KAAK,CAAC,IAAI,GAAG,CAAC;IAEpD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,SAAS,CAAC,mCAAmC,KAAK,CAAC,IAAI,aAAa,CAAC,CAAC;IAClF,CAAC;IAED,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACjD,OAAO,IAAI,IAAI,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,GAAG,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,IAAmB;IACvC,IAAI,IAAI,YAAY,IAAI,EAAE,CAAC;QACzB,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,SAAS,CAAC,sCAAsC,CAAC,CAAC;QAC9D,CAAC;QACD,OAAO;YACL,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC;YACpD,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC;SACvD,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;QACvE,MAAM,IAAI,SAAS,CACjB,qDAAqD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAC5E,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAC7C,CAAC"}

package/dist/content/store.d.ts

@@ -0,0 +1,133 @@
+import type { Document, DocumentType } from './document.ts';
+/** File name of the derived index inside a site's data directory. */
+export declare const DATABASE_FILE = "geekity.db";
+/** Directory name that marks a document as thrown away but not yet deleted. */
+export declare const TRASH_DIRECTORY = "_trash";
+/** Where {@link openContentStore} puts the database. */
+export interface OpenContentStoreOptions {
+    /** Directory the database lives in. Created if it is missing. */
+    dataDir: string;
+}
+/**
+ * The derived index over the Markdown files.
+ *
+ * Files are the source of truth (decision-1); this is a queryable copy that
+ * answers the questions a directory walk cannot answer cheaply. Deleting the
+ * database is safe because the next boot rebuilds it.
+ */
+export interface ContentStore {
+    /** Absolute path of the SQLite file. */
+    readonly file: string;
+    /**
+     * Insert or replace the row for `document.path`, tags included.
+     *
+     * Throws {@link DuplicatePermalinkError} when another path already claims
+     * the same permalink.
+     */
+    upsert(document: Document): void;
+    /** {@link ContentStore.upsert} for many documents, in one transaction. */
+    upsertAll(documents: Iterable<Document>): void;
+    /** Drop a document by path. Returns `false` when there was nothing to drop. */
+    remove(path: string): boolean;
+    /** The document at a content-relative path, or `undefined`. */
+    getByPath(path: string): Document | undefined;
+    /** The document a URL resolves to, or `undefined`. Permalinks are unique. */
+    getByPermalink(permalink: string): Document | undefined;
+    /**
+     * The document with this slug, or `undefined`. Slugs are not unique across
+     * years, so the newest match wins.
+     */
+    getBySlug(slug: string): Document | undefined;
+    /** Published, untrashed posts, newest first. */
+    listPosts(options?: ListOptions): Document[];
+    /** Published, untrashed documents carrying a tag, newest first. */
+    listByTag(tag: string, options?: ListByTagOptions): Document[];
+    /** Everything the admin may see, trash and drafts included unless filtered. */
+    listAll(options?: ListAllOptions): Document[];
+    /** Every indexed path, sorted. What a sync compares the content tree against. */
+    listPaths(): string[];
+    /** How many documents there are of each kind. */
+    counts(): ContentCounts;
+    /** How many published, untrashed documents carry a tag. */
+    countByTag(tag: string, options?: ListByTagOptions): number;
+    /** Every tag in use on published, untrashed documents, with its count. */
+    listTags(): TagCount[];
+    /** Close the database. Safe to call twice. */
+    close(): void;
+}
+/** Paging for the public listings. */
+export interface ListOptions {
+    /** How many documents to return. Defaults to everything. */
+    limit?: number | undefined;
+    /** How many to skip first. Defaults to 0. */
+    offset?: number | undefined;
+}
+/** Paging plus the type filter the tag archives need. */
+export interface ListByTagOptions extends ListOptions {
+    /** Restrict to posts or pages. Defaults to both. */
+    type?: DocumentType | undefined;
+}
+/** Filters for the admin listing, which is the only view of the trash. */
+export interface ListAllOptions extends ListOptions {
+    /** Restrict to posts or pages. Defaults to both. */
+    type?: DocumentType | undefined;
+    /** `true` for drafts only, `false` for published only. Defaults to both. */
+    draft?: boolean | undefined;
+    /** `true` for trashed only, `false` for live only. Defaults to live only. */
+    trashed?: boolean | undefined;
+    /** Restrict to documents carrying this tag. */
+    tag?: string | undefined;
+}
+/** What {@link ContentStore.counts} reports. */
+export interface ContentCounts {
+    /** Every indexed document, trash included. */
+    total: number;
+    /** Published, untrashed posts: the size of the public archive. */
+    posts: number;
+    /** Published, untrashed pages. */
+    pages: number;
+    /** Untrashed drafts of either type. */
+    drafts: number;
+    /** Documents under `_trash/`. */
+    trashed: number;
+}
+/** One tag and how many published documents carry it. */
+export interface TagCount {
+    tag: string;
+    count: number;
+}
+/**
+ * Thrown when two files claim the same permalink. Two documents at one URL is
+ * a content mistake the site owner has to fix, so the index refuses it rather
+ * than picking a winner.
+ */
+export declare class DuplicatePermalinkError extends Error {
+    readonly name = "DuplicatePermalinkError";
+    /** The permalink both documents claim. */
+    readonly permalink: string;
+    /** The path that was being indexed. */
+    readonly path: string;
+    /** The path that already held the permalink, when it could be looked up. */
+    readonly conflictingPath: string | undefined;
+    constructor(permalink: string, path: string, conflictingPath: string | undefined);
+}
+/**
+ * Whether a content path is in the trash. Trashed documents stay indexed so
+ * the admin can restore them, and stay out of every public listing.
+ */
+export declare function isTrashedPath(contentPath: string): boolean;
+/**
+ * The value a document sorts by: its date as a UTC instant, so
+ * `2026-09-02T09:00:00-05:00` and `2026-09-02T14:00:00Z` compare equal.
+ *
+ * A document whose date is missing or unreadable sorts last, because SQLite
+ * orders NULL below every string.
+ */
+export declare function dateSortKey(date: string | undefined): string | null;
+/**
+ * Open (and if needed create) the index in `dataDir`, applying every migration
+ * the package ships. Applying them is idempotent, so reopening an up-to-date
+ * database does nothing.
+ */
+export declare function openContentStore(options: OpenContentStoreOptions): ContentStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/content/store.d.ts.map

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