@zvndev/darkmown 0.8.1 → 0.9.0

package/types/compiler.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Compile a page source file into a full HTML document plus its assets.
+ * @param {string} file Absolute path to the source `.md`/`.wd` file.
+ * @param {Paths} context Resolved project paths.
+ * @returns {CompiledPage}
+ */
+export function compilePage(file: string, context: Paths): CompiledPage;
+/**
+ * Compile a source file into its body HTML, frontmatter, and assets (no page shell).
+ * @param {string} file Absolute path to the source file.
+ * @param {Paths} context Resolved project paths.
+ * @param {string[]} [stack] Include stack for cycle detection.
+ * @param {Record<string, unknown>} [vars] Initial static scope variables.
+ * @returns {CompiledDocument}
+ */
+export function compileDocument(file: string, context: Paths, stack?: string[], vars?: Record<string, unknown>): CompiledDocument;
+/**
+ * Split a raw file into its frontmatter `meta` and `body`.
+ * @param {string} raw Full file contents.
+ * @param {string} [file] Source path, used only for error messages.
+ * @returns {{ meta: Meta, body: string }}
+ */
+export function parseFrontmatter(raw: string, file?: string): {
+    meta: Meta;
+    body: string;
+};
+/**
+ * Stable per-render key for a loop row, disambiguating duplicates with `#n`.
+ * @param {unknown} item
+ * @param {Map<string, number>} counts Mutable seen-count accumulator.
+ * @returns {string}
+ */
+export function loopKeyOf(item: unknown, counts: Map<string, number>): string;
+/**
+ * Escape a value for safe inclusion in HTML text and attribute contexts.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function escapeHtml(value: unknown): string;
+/**
+ * A compiled `@loop … where` predicate.
+ */
+export type Predicate = {
+    /**
+     * Safe JS boolean expression over `I()`/`S()`/`C()`.
+     */
+    body: string;
+    /**
+     * Whether the predicate reads declared state.
+     */
+    refsState: boolean;
+};
+/**
+ * A parsed `:button` action.
+ */
+export type Action = {
+    /**
+     * Runtime operation (inc/dec/add/append/set/remove/append-row).
+     */
+    op: string;
+    /**
+     * State key the action mutates.
+     */
+    target: string;
+    /**
+     * Literal value for value-carrying ops.
+     */
+    value?: unknown;
+};
+export type Paths = import("./config.js").Paths;
+/**
+ * Frontmatter values are scalars or inline arrays of scalars.
+ */
+export type FrontmatterValue = string | number | boolean | null | Array<string | number | boolean | null>;
+/**
+ * Parsed page frontmatter, keyed by field name.
+ */
+export type Meta = Record<string, FrontmatterValue>;
+/**
+ * Collected output assets for a compiled document.
+ */
+export type Assets = {
+    /**
+     * Public hrefs of compiled skin stylesheets.
+     */
+    skins: Set<string>;
+    /**
+     * Public hrefs of colocated page scripts.
+     */
+    scripts: Set<string>;
+    /**
+     * Source path → public href for emitted assets.
+     */
+    files: Map<string, string>;
+    /**
+     * Whether the reactive runtime is required.
+     */
+    runtime: boolean;
+};
+/**
+ * Per-document compilation accumulator shared across includes/sections.
+ */
+export type Compilation = {
+    assets: Assets;
+    /**
+     * Declared state keys → initial values.
+     */
+    state: Map<string, unknown>;
+    /**
+     * Non-fatal authoring hints.
+     */
+    warnings: string[];
+    /**
+     * Counter for auto-generated section ids.
+     */
+    sectionCounter: number;
+};
+/**
+ * A lexical scope chain for static interpolation values (include args, loop vars).
+ */
+export type Scope = {
+    parent: Scope | null;
+    vars: Record<string, unknown>;
+};
+/**
+ * Per-file compile context threaded through the directive handlers.
+ */
+export type Ctx = {
+    /**
+     * Absolute path to the file being compiled.
+     */
+    file: string;
+    /**
+     * Resolved project paths.
+     */
+    context: Paths;
+    /**
+     * Include stack (real paths) for cycle detection.
+     */
+    stack: string[];
+    /**
+     * Static value scope chain.
+     */
+    scope: Scope;
+    /**
+     * Shared compilation accumulator.
+     */
+    comp: Compilation;
+    /**
+     * Active section-id scope chain.
+     */
+    sections: string[];
+    /**
+     * Name of the current reactive loop item, if any.
+     */
+    loopItem: string | null;
+    /**
+     * State key of the list being looped, if any.
+     */
+    loopKey?: string | undefined;
+    /**
+     * Markdown-it instance selected for this file.
+     */
+    md?: MarkdownIt | undefined;
+};
+/**
+ * A compiled page document.
+ */
+export type CompiledDocument = {
+    meta: Meta;
+    html: string;
+    assets: Assets;
+    warnings: string[];
+};
+/**
+ * A compiled page: the document plus its full HTML shell.
+ */
+export type CompiledPage = {
+    meta: Meta;
+    html: string;
+    assets: Assets;
+    warnings: string[];
+};
+import MarkdownIt from "markdown-it";

package/types/config.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Resolved project paths used across the build pipeline.
+ * @typedef {object} Paths
+ * @property {string} cwd Project working directory.
+ * @property {string} routesRoot Absolute path to `site/pages`.
+ * @property {string} shelfRoot Absolute path to the include shelf `site/_`.
+ * @property {string} distRoot Absolute path to the build output `dist`.
+ */
+/**
+ * Build the absolute project paths for a given working directory.
+ * @param {string} [cwd] Project working directory (defaults to `process.cwd()`).
+ * @returns {Paths}
+ */
+export function createPaths(cwd?: string): Paths;
+/**
+ * Whether a file or directory name is hidden from routing (starts with `.`, `-`, or `_`).
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isHiddenName(name: string): boolean;
+export const routesDir: "site/pages";
+export const shelfDir: "site/_";
+export const distDir: "dist";
+export const pageExtensions: Set<string>;
+/**
+ * Resolved project paths used across the build pipeline.
+ */
+export type Paths = {
+    /**
+     * Project working directory.
+     */
+    cwd: string;
+    /**
+     * Absolute path to `site/pages`.
+     */
+    routesRoot: string;
+    /**
+     * Absolute path to the include shelf `site/_`.
+     */
+    shelfRoot: string;
+    /**
+     * Absolute path to the build output `dist`.
+     */
+    distRoot: string;
+};

package/types/dev.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Inject the dev-client `<script>` before `</body>` (or append it if absent).
+ * @param {string} html Page HTML to augment.
+ * @returns {string}
+ */
+export function injectDevClient(html: string): string;
+/**
+ * The dev-client browser script that opens the SSE channel for live reload.
+ * @returns {string}
+ */
+export function devClientScript(): string;
+export const devClientPath: "/__wd/dev-client.js";
+export const devEventsPath: "/__wd/dev-events";

package/types/index.d.ts

@@ -0,0 +1,33 @@
+// Public type surface for @zvndev/darkmown.
+// Generated declarations live alongside this file (see `npm run types`).
+// This entry re-exports the functions and shapes a consumer is expected to use.
+
+export { buildSite } from "./builder.js";
+export type { RouteManifestEntry, Paths, Assets } from "./builder.js";
+
+export {
+  compilePage,
+  compileDocument,
+  parseFrontmatter,
+  escapeHtml,
+  loopKeyOf
+} from "./compiler.js";
+export type {
+  Meta,
+  FrontmatterValue,
+  CompiledPage,
+  CompiledDocument
+} from "./compiler.js";
+
+export { createPaths, isHiddenName, pageExtensions } from "./config.js";
+
+export { discoverRoutes, routeFromFile, outputPathForRoute } from "./router.js";
+export type { Route } from "./router.js";
+
+export { compileSkin } from "./skin.js";
+
+export { initProject } from "./scaffold.js";
+
+export { serve, resolvePublicFile, contentType } from "./statics.js";
+
+export { injectDevClient, devClientScript } from "./dev.js";

package/types/router.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A discovered page route: the source file and its public route path.
+ * @typedef {object} Route
+ * @property {string} file Absolute path to the source `.md`/`.wd` file.
+ * @property {string} route Public route path (always trailing-slashed, e.g. `/about/`).
+ */
+/**
+ * Walk `routesRoot` and collect page routes, sorted and de-duplicated.
+ * @param {string} routesRoot Absolute path to `site/pages`.
+ * @returns {Route[]}
+ */
+export function discoverRoutes(routesRoot: string): Route[];
+/**
+ * Derive a public route path from a source file path.
+ * @param {string} routesRoot Absolute path to `site/pages`.
+ * @param {string} file Absolute path to the source file.
+ * @returns {string}
+ */
+export function routeFromFile(routesRoot: string, file: string): string;
+/**
+ * Map a public route to the `index.html` output path under `distRoot`.
+ * @param {string} distRoot Absolute path to the build output directory.
+ * @param {string} route Public route path.
+ * @returns {string}
+ */
+export function outputPathForRoute(distRoot: string, route: string): string;
+/**
+ * A discovered page route: the source file and its public route path.
+ */
+export type Route = {
+    /**
+     * Absolute path to the source `.md`/`.wd` file.
+     */
+    file: string;
+    /**
+     * Public route path (always trailing-slashed, e.g. `/about/`).
+     */
+    route: string;
+};

package/types/scaffold.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Scaffold a new Darkmown project into `root`, creating files that don't exist.
+ * @param {string} root Absolute path to the target project directory.
+ * @returns {{ root: string }}
+ */
+export function initProject(root: string): {
+    root: string;
+};

package/types/skin.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A nesting frame in the indentation stack.
+ * @typedef {object} SkinFrame
+ * @property {number} indent
+ * @property {string | null} selector
+ * @property {string} [media]
+ */
+/**
+ * Compile indentation-based `.skin` source into CSS.
+ * @param {string} source
+ * @returns {string}
+ */
+export function compileSkin(source: string): string;
+/**
+ * A nesting frame in the indentation stack.
+ */
+export type SkinFrame = {
+    indent: number;
+    selector: string | null;
+    media?: string | undefined;
+};

package/types/statics.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Serve a built file for a request URL out of `distRoot`, or a 404 page.
+ * @param {string} distRoot Absolute path to the build output directory.
+ * @param {string} url Request URL (may include a query string).
+ * @param {http.ServerResponse} res Response to write to.
+ * @returns {void}
+ */
+export function serve(distRoot: string, url: string, res: http.ServerResponse): void;
+/**
+ * Resolve a request URL to an absolute file inside `distRoot`, guarding against
+ * path traversal. Returns null when the resolved path escapes the root.
+ * @param {string} distRoot Absolute path to the build output directory.
+ * @param {string} url Request URL (may include a query string).
+ * @returns {string | null}
+ */
+export function resolvePublicFile(distRoot: string, url: string): string | null;
+/**
+ * Map a file path to a response content-type, defaulting to `text/html`.
+ * @param {string} file File path or name.
+ * @returns {string}
+ */
+export function contentType(file: string): string;
+import http from "node:http";

package/docs/okf-integration.md

@@ -1,120 +0,0 @@
-# OKF integration — plan & options
-
-Status: **parked / decision pending** (2026-06-14). Research-verified; revisit when
-we decide how far to take it. v0.8.0 (array frontmatter + readable `meta`) already
-shipped the enabling groundwork.
-
-## What OKF is (verified)
-
-**Open Knowledge Format (OKF)** is real. Published **2026-06-12** by the Google Cloud
-Data Analytics team (Sam McVeety, Amir Hormati).
-
-- Announcement: <https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/>
-- Spec: <https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md>
-- Repo (Apache-2.0, `okf/` subdir): <https://github.com/GoogleCloudPlatform/knowledge-catalog>
-- **Not** the Open Knowledge Foundation (unrelated nonprofit — do not conflate).
-
-It is a **file format**, not a service: a directory of markdown "concept" files for
-feeding organizational knowledge to AI agents. Each concept file has YAML frontmatter
-where **`type` is the only required field**; `title`, `description`, `resource` (a URI
-for the underlying asset), `tags` (a YAML list), and `timestamp` (ISO 8601) are
-optional. Producers may add arbitrary keys; consumers must preserve unknown keys.
-
-- **Cross-links** are ordinary markdown links between concept files (bundle-relative
-  absolute like `/tables/customers.md` recommended). They are treated as **directed,
-  untyped graph edges** — the relationship's meaning lives in surrounding prose.
-- **Reserved files:** `index.md` (a directory listing for *progressive disclosure* — an
-  agent navigates one level at a time) and `log.md` (chronological history). The root
-  `index.md` frontmatter may declare `okf_version: "0.1"`.
-- **Conformance is permissive:** consumers MUST tolerate broken links, unknown `type`
-  values, unknown keys, and missing optional fields (so agent-generated, partial bundles
-  still work).
-- **Reference tooling (both labeled proof-of-concept):** a BigQuery *enrichment agent*
-  that drafts OKF docs per table, and a *visualizer* — a `visualize` command that emits a
-  single self-contained interactive HTML file (Cytoscape.js force-graph + marked.js body,
-  no backend).
-- **Sample bundles:** GA4 e-commerce, Stack Overflow, Bitcoin. ("BigQuery Table /
-  Dataset / Metric" are concept *types inside* bundles, not separate samples.)
-
-## Why it's interesting for Darkmown
-
-OKF's entire surface — YAML frontmatter + a folder tree + relative markdown links →
-static HTML — **is what Darkmown already does**. A `.md` tree with a `type:` field and
-cross-links is *nearly an OKF bundle by accident*. Two directions:
-
-1. **Darkmown as an OKF renderer.** Darkmown renders markdown bundles to static, zero-JS
-   HTML — directly competitive with OKF's reference visualizer, which is OKF's weakest
-   surface (a single JS-heavy HTML file).
-2. **Every Darkmown site emits an OKF bundle.** Any docs/content site also becomes
-   machine-readable agent context. No other markdown framework offers this.
-
-## Why to be cautious
-
-- **v0.1 "Draft," explicitly evolving.** Google's own blog: "a starting point, not a
-  finished standard." Field names and required fields may change (minor versions promise
-  backward-compatible additions only; breaking changes need a major bump).
-- **Thin traction.** ~1.2k GitHub stars but ~8 issues, ~13 PRs, ~27 commits at launch.
-  **No third-party adopters** — only Google's own Cloud Knowledge Catalog consumes it.
-- **Governance unclear.** Lives under Google's repo with no foundation/working group.
-- **Thin convention.** Net-new over "a markdown vault + Obsidian/Dataview" is small: one
-  required field, two reserved filenames, link-as-edge semantics. Easy for others to
-  ignore or fork.
-
-## Decision (Kirby, 2026-06-14)
-
-**Support OKF naturally; do not tie ourselves to it.** Treat it as a cheap, additive
-interop convention, not a strategic bet or a core-model change.
-
-## Options (revisit later)
-
-### Option A — Do nothing more (status quo)
-v0.8.0 array frontmatter already makes Darkmown frontmatter able to carry `tags` lists
-and a `type` field. A Darkmown content tree with `type:` in frontmatter is already
-~conformant. Cost: zero. Keep tracking adoption.
-
-### Option B — Thin OKF emit (recommended first step if we act) — increment #3
-A flag-gated export from a built site: `okf: true` in config or `--emit-okf`.
-- During `buildSite` (`src/builder.js`), alongside `routes.json`, write `dist/okf/`.
-- For each page, emit an OKF doc: frontmatter (`type` defaulting to `page`, `title` from
-  meta, `tags` from meta, `timestamp` from file mtime/git) + the page's markdown body.
-- Derive edges from internal links + `@include` edges (`resolveInclude`/`compileFile`
-  already know these). Emit per-directory `index.md` for progressive disclosure.
-- **Map at emit time** — do not restructure Darkmown's internal model around OKF.
-- Effort: low; it hooks the existing route loop. Largely free.
-
-### Option C — OKF render mode ("best OKF renderer") — increment #2
-`darkmown build --okf ./bundle [--out dist-okf]`: walk an arbitrary bundle root, render
-each doc (type-aware templates, generic fallback), rewrite `.md` cross-links to routes,
-emit a static index/graph view. Reuse `parseFrontmatter`, markdown-it, `compileFile` —
-do not fork the pipeline. Must stay `runtime: false`.
-- **Gate this on OKF showing real external adoption.** Today you'd build a renderer for a
-  format only Google uses. Higher effort, higher coupling risk.
-
-### Sequencing if we proceed
-1. (done) Array frontmatter + readable `meta` — v0.8.0.
-2. Option B (emit) — additive, low-regret.
-3. Option C (render) — only if the format gets stickier.
-
-## Hard "avoid" list
-
-- Don't hardcode Google/BigQuery `type` vocabularies (`BigQuery Table`, etc.) — `type` is
-  uncentralized and producer-defined.
-- Don't bet on v0.1 field names / required-field stability — map our frontmatter → OKF at
-  emit time.
-- Don't depend on OKF's reference enrichment agent or visualizer — both are proofs of
-  concept. If we want a graph view, build our own; the format is trivial.
-- Don't market "OKF-native" as a moat — it's a thin convention with thin adoption. A
-  cheap interoperability checkbox, not a strategic bet.
-
-## Invariants to respect (if/when we build)
-
-- `.md` never gains directive behavior; OKF docs are content, rendered as content.
-- No eval of bundle content; the `constructor`/`prototype`/`__proto__` rejection in
-  `getPath` still applies.
-- OKF render/emit are pure content transforms — `runtime: false` always.
-- Compile/render errors include the offending file path and a corrective suggestion.
-
-## Source
-
-Full research briefing (cited): the research-investigator memory
-`reference_okf_open_knowledge_format.md`, and `docs/spec-alignment.md` Stage 7.