@opum-ai/lore 0.1.0 → 0.1.1

package/src/core/consumer-scaffold.ts

@@ -1,433 +0,0 @@
-/**
- * core/consumer-scaffold.ts — the **pure** content builders behind `lore scaffold <target>`
- * (LORE-39/40; cli-surface §"Consumer scaffolding", ADR-0010).
- *
- * Each target's config is generated **additively, outside `docs/`** so the OKF bundle stays
- * the single source of truth (ADR-0010 §2) — with one intentional exception: {@link buildObsidianScaffold}
- * writes `docs/.obsidian/app.json` and `docs/.obsidian/.gitignore` *inside* `docs/`, because
- * Obsidian's vault-scoping requirement (consumer-compatibility.md §3.2) needs `docs/` itself to be
- * the vault root. Every other target's output, and everything else under `docs/`, is never mutated
- * to satisfy a consumer.
- * Like {@link buildScaffold} (`lore init`'s pure plan builder), these functions touch no
- * filesystem and read no clock; the side effects (never-clobber vs. `--force` overwrite) live
- * in `commands/scaffold.ts`.
- *
- * `mkdocs.yml`'s exact settings (§3.3 of
- * [consumer-compatibility.md](../../docs/reference/consumer-compatibility.md)) and the
- * `docs/tags.md` tag-index page were verified against a real `mkdocs build` of this repo's own
- * bundle before being pinned here — `plugins: [tags]` alone builds cleanly, but a dedicated
- * `<!-- material/tags -->` page is what actually renders the tag index (an empty/absent one
- * leaves the plugin silently inert). `docs/tags.md` is a normal, appendable OKF concept once
- * scaffolded — not a `RESERVED_STEMS` entry like `index`/`log` — because nothing regenerates it
- * wholesale afterward; a user may rename or supersede it like any other doc.
- *
- * `docs/tags.md` is serialized against the **structural default profile**, never the active
- * one, via the shared {@link serializeStructuralConcept} (`scaffold.ts`) — the same helper
- * `rootIndexDocument` uses for `docs/index.md`, and for the identical reason: it is lore's own
- * fixed-shape utility page, so a custom profile that adds a required field to `Reference` must not
- * make `lore scaffold mkdocs` fail to write it.
- *
- * `website/`'s three files (`docusaurus.config.js`, `sidebars.js`, `package.json`) were verified
- * against a real `docusaurus build` (v3.10.2) of this repo's own bundle before being pinned here.
- * `docusaurus.config.js`/`sidebars.js` MUST be CommonJS (`module.exports = {...}`), not the ESM
- * `export default` shown in consumer-compatibility.md's superseded snippet — that form crashes
- * the production build (`TypeError: require.resolveWeak is not a function`, an ESM/webpack-SSR
- * interaction), not a config-content bug; the exact same settings succeed once the file is CJS.
- * Unlike MkDocs (a standalone pip-installed tool), Docusaurus's CLI is a project-local
- * devDependency that resolves its preset/theme from the site's own `node_modules`, so `website/`
- * needs its own `package.json` — `@docusaurus/core` and `@docusaurus/preset-classic` pinned to
- * the same exact version (Docusaurus packages must stay in lockstep) and no `"type": "module"`.
- * `website/` carries no OKF concept file (unlike mkdocs's `docs/tags.md`) — the sidebar is fully
- * autogenerated from `docs/`, so nothing needs `serializeStructuralConcept` here.
- */
-
-import type { Concept } from "./concept";
-import { idFromPath } from "./concept";
-import { defaultProfile, type Profile } from "./profile";
-import { DOCS_DIR, serializeStructuralConcept } from "./scaffold";
-
-/** The repo-root-relative path of the scaffolded MkDocs config, sibling to `docs/` (ADR-0010 §2). */
-export const MKDOCS_CONFIG_REL_PATH = "mkdocs.yml";
-
-/** The repo-relative path of the scaffolded MkDocs Material tag-index page. */
-export const TAGS_INDEX_REL_PATH = `${DOCS_DIR}/tags.md`;
-
-/** The repo-root-relative directory of the scaffolded Docusaurus site, sibling to `docs/` (ADR-0010 §2). */
-export const WEBSITE_DIR = "website";
-
-/** The repo-relative path of the scaffolded Docusaurus config. */
-export const DOCUSAURUS_CONFIG_REL_PATH = `${WEBSITE_DIR}/docusaurus.config.js`;
-
-/** The repo-relative path of the scaffolded, fully-autogenerated Docusaurus sidebar. */
-export const SIDEBARS_REL_PATH = `${WEBSITE_DIR}/sidebars.js`;
-
-/** The repo-relative path of the scaffolded Docusaurus site's own package manifest. */
-export const WEBSITE_PACKAGE_JSON_REL_PATH = `${WEBSITE_DIR}/package.json`;
-
-/**
- * The repo-relative directory of the scaffolded Obsidian vault config — inside `docs/`, unlike
- * `website/`/`mkdocs.yml`, since the recommended setup opens `docs/` itself as the vault
- * (consumer-compatibility.md §3.2).
- */
-export const OBSIDIAN_DIR = `${DOCS_DIR}/.obsidian`;
-
-/**
- * The repo-relative path of the scaffolded Obsidian vault config. Only this file (plus
- * {@link OBSIDIAN_GITIGNORE_REL_PATH} itself) is meant to be committed — the scaffolded
- * `.gitignore` excludes everything under `docs/.obsidian/` *except* the two of them
- * (`*` plus `!app.json`/`!.gitignore` negations), rather than enumerating the rest of Obsidian's
- * per-user vault state file by file, since Obsidian creates more of those than any fixed list can
- * keep up with. A future file scaffolded under `docs/.obsidian/` needs its own negation line to
- * be committed.
- */
-export const OBSIDIAN_APP_JSON_REL_PATH = `${OBSIDIAN_DIR}/app.json`;
-
-/**
- * The repo-relative path of the scaffolded, self-contained Obsidian `.gitignore`
- * (consumer-compatibility.md §3.2: "A `.gitignore` entry for `docs/.obsidian/workspace*.json` and
- * the cache (commit `app.json` only)"). Scoped *inside* `docs/.obsidian/` rather than appended to
- * a repo-root `.gitignore` — every pattern below is relative to this file's own directory — so
- * scaffolding it never has to read, merge into, or risk clobbering a consumer's pre-existing
- * root `.gitignore`; it fits the same create-fresh/`--force`-to-overwrite model every other
- * scaffolded file already uses. Its exclude-all-except pattern is a strict superset of the doc's
- * literal `workspace*.json`/cache wording — see {@link OBSIDIAN_APP_JSON_REL_PATH}'s own doc for why.
- */
-export const OBSIDIAN_GITIGNORE_REL_PATH = `${OBSIDIAN_DIR}/.gitignore`;
-
-/** The exact, lockstep-pinned Docusaurus version this scaffold was verified against. */
-const DOCUSAURUS_VERSION = "3.10.2";
-
-/** A single file a consumer scaffold wants to exist, with the exact bytes to write. */
-export interface ConsumerScaffoldFile {
-  /** Repo-relative POSIX path. */
-  readonly path: string;
-  /** The exact bytes to write — pinned by golden tests, applied verbatim by the command. */
-  readonly contents: string;
-}
-
-/** The complete, filesystem-free description of one consumer's scaffolded config. */
-export interface ConsumerScaffoldPlan {
-  /** Directories to ensure exist first, parents before children (mirrors `ScaffoldPlan.dirs`). */
-  readonly dirs: readonly string[];
-  /** Files to create (or, under `--force`, overwrite), in a stable order. */
-  readonly files: readonly ConsumerScaffoldFile[];
-  /**
-   * Extra guidance lines the command prints after the file summary, for a target whose scaffolded
-   * file cannot fully guarantee the desired behavior on its own (e.g. Obsidian's `app.json`, which
-   * some Obsidian builds do not read at all — the Settings UI is the real guarantee). Omitted by
-   * targets with nothing to add (mkdocs, docusaurus).
-   */
-  readonly notes?: readonly string[];
-}
-
-/** Options for {@link buildMkdocsScaffold}, {@link buildDocusaurusScaffold}, and {@link buildObsidianScaffold}. */
-export interface ConsumerScaffoldOptions {
-  /**
-   * ISO-8601 datetime stamped on `docs/tags.md`'s frontmatter, mirroring `buildScaffold`'s
-   * injected-clock seam (lore-design §8) so the plan stays deterministic and golden-testable.
-   * Unused by {@link buildDocusaurusScaffold} and {@link buildObsidianScaffold}, neither of which
-   * emits an OKF concept file; kept here so all three builders share one options shape and the
-   * command layer calls them uniformly.
-   */
-  readonly timestamp: string;
-  /**
-   * The MkDocs `site_name` / Docusaurus `title` (required by both; there is no sane
-   * zero-config default). The command layer derives this from the repo directory name — the
-   * one filesystem read these otherwise-pure builders need, kept at the boundary rather than
-   * smuggled in here. Unused by {@link buildObsidianScaffold}, whose `app.json` carries no
-   * site-name-equivalent setting.
-   */
-  readonly siteName: string;
-  /**
-   * The active profile, used only to decide whether `docs/tags.md` carries the
-   * `$schema` editor modeline (only when the profile actually defines `Reference`).
-   * Defaults to the built-in {@link defaultProfile}. Unused by {@link buildDocusaurusScaffold}
-   * and {@link buildObsidianScaffold}, for the same reason as `timestamp`.
-   */
-  readonly profile?: Profile;
-}
-
-/**
- * Build the {@link ConsumerScaffoldPlan} for `lore scaffold mkdocs`: a repo-root `mkdocs.yml`
- * and a `docs/tags.md` tag-index page. Pure — identical `options` always produce identical bytes.
- */
-export function buildMkdocsScaffold(options: ConsumerScaffoldOptions): ConsumerScaffoldPlan {
-  const profile = options.profile ?? defaultProfile();
-  return {
-    dirs: [DOCS_DIR],
-    files: [
-      { path: MKDOCS_CONFIG_REL_PATH, contents: mkdocsConfigYaml(options.siteName) },
-      { path: TAGS_INDEX_REL_PATH, contents: tagsIndexDocument(options.timestamp, profile) },
-    ],
-  };
-}
-
-/**
- * Build the {@link ConsumerScaffoldPlan} for `lore scaffold docusaurus`: a `website/` directory
- * with `package.json`, `docusaurus.config.js`, and `sidebars.js`. Pure — identical `options`
- * always produce identical bytes.
- */
-export function buildDocusaurusScaffold(options: ConsumerScaffoldOptions): ConsumerScaffoldPlan {
-  return {
-    dirs: [WEBSITE_DIR],
-    files: [
-      { path: WEBSITE_PACKAGE_JSON_REL_PATH, contents: websitePackageJson() },
-      { path: DOCUSAURUS_CONFIG_REL_PATH, contents: docusaurusConfigJs(options.siteName) },
-      { path: SIDEBARS_REL_PATH, contents: sidebarsJs() },
-    ],
-  };
-}
-
-/**
- * Build the {@link ConsumerScaffoldPlan} for `lore scaffold obsidian` (LORE-41): the
- * `docs/.obsidian/app.json` preset plus the scoped `docs/.obsidian/.gitignore` that keeps
- * Obsidian's per-user vault state (workspace layout, cache, plugins/, ...) untracked while still
- * committing the two of them (consumer-compatibility.md §3.2), plus {@link OBSIDIAN_GUIDANCE_NOTES}.
- * Pure — identical `options` always produce identical bytes; unlike {@link buildMkdocsScaffold}, no
- * OKF concept file is emitted, so every `options` field goes unused here, the same reason
- * {@link buildDocusaurusScaffold} ignores `timestamp`/`profile`.
- */
-export function buildObsidianScaffold(_options: ConsumerScaffoldOptions): ConsumerScaffoldPlan {
-  return {
-    dirs: [DOCS_DIR, OBSIDIAN_DIR],
-    files: [
-      { path: OBSIDIAN_APP_JSON_REL_PATH, contents: obsidianAppJson() },
-      { path: OBSIDIAN_GITIGNORE_REL_PATH, contents: obsidianGitignore() },
-    ],
-    notes: OBSIDIAN_GUIDANCE_NOTES,
-  };
-}
-
-/** The reserved tag-index page's `type` — a plain `Reference`, like the bundle root index. */
-const TAGS_INDEX_TYPE = "Reference";
-
-/**
- * The `docs/tags.md` bytes: a valid OKF `Reference` concept (so it stays lint-clean and
- * OKF-legal) whose body carries the `<!-- material/tags -->` marker the MkDocs Material `tags`
- * plugin scans to render the tag index. Serialized via the shared {@link serializeStructuralConcept}
- * — see the module docstring for why — which conditionally carries the `$schema` modeline only
- * when the *active* profile defines `Reference`.
- */
-function tagsIndexDocument(timestamp: string, profile: Profile): string {
-  const concept: Concept = {
-    id: idFromPath(TAGS_INDEX_REL_PATH),
-    path: TAGS_INDEX_REL_PATH,
-    type: TAGS_INDEX_TYPE,
-    frontmatter: {
-      type: TAGS_INDEX_TYPE,
-      title: "Tags",
-      summary: "Autogenerated tag index for this OKF bundle, rendered by the MkDocs Material `tags` plugin.",
-      timestamp,
-    },
-    body: TAGS_INDEX_BODY,
-  };
-  return serializeStructuralConcept(concept, profile);
-}
-
-/** The body of the scaffolded tag-index page (after the frontmatter fence). */
-const TAGS_INDEX_BODY = `
-# Tags
-
-<!-- material/tags -->
-`;
-
-/**
- * The shared "generated once, user-owned" disclaimer every scaffolded config's header comment
- * carries, so the wording and `--force` phrasing live in one place instead of being copy-pasted
- * per target. `commentPrefix` is `#` (YAML) or `//` (JS); `target`/`docSection` name the specific
- * `lore scaffold <target>` invocation and the consumer-compatibility.md section to cite.
- */
-function generatedHeader(commentPrefix: string, target: string, docSection: string): string {
-  return `${commentPrefix} Generated once by \`lore scaffold ${target}\` — user-owned; re-run with --force to regenerate.
-${commentPrefix} See docs/reference/consumer-compatibility.md ${docSection} and ADR-0010 for the rationale.`;
-}
-
-/**
- * The scaffolded `mkdocs.yml` bytes (consumer-compatibility.md §3.3; ADR-0010 §2). Every setting
- * mirrors that documented rationale — repeated here as inline comments since this is the file a
- * team actually reads and edits, not the doc:
- *
- * - `navigation.indexes` — `index.md` becomes each section's landing page (not just a sibling link).
- * - `plugins: [search, tags]` — the built-in search plus the frontmatter `tags` → chips/tag-index plugin.
- * - `strict: false` plus `not_found: warn` (links, nav, anchors) — honors OKF's broken-link
- *   tolerance so an in-progress or cross-tree (`backlog/`) link never fails the build.
- * - `absolute_links: relative_to_docs` (MkDocs >= 1.6) — the safety net for any `/`-absolute
- *   link that survives the portability lint.
- * - `not_in_nav: /log.md` — the machine-regenerated log stays out of the autogenerated nav tree.
- */
-function mkdocsConfigYaml(siteName: string): string {
-  return `${generatedHeader("#", "mkdocs", "§3.3")}
-site_name: ${JSON.stringify(siteName)}
-docs_dir: docs
-theme:
-  name: material
-  features:
-    - navigation.indexes
-plugins:
-  - search
-  - tags
-strict: false
-validation:
-  links:
-    absolute_links: relative_to_docs
-    not_found: warn
-    anchors: warn
-  nav:
-    omitted_files: ignore
-    not_found: warn
-not_in_nav: |
-  /log.md
-`;
-}
-
-/**
- * The exact React version this scaffold was verified against — within `@docusaurus/preset-classic@3.10.2`'s
- * verified peer range (`^18.0.0 || ^19.0.0`). `react`/`react-dom` are pinned exactly, like
- * `@docusaurus/core`/`@docusaurus/preset-classic`, rather than left on a caret range: no
- * lockfile is scaffolded (matching MkDocs's own floor-not-exact CI precedent, which has no
- * requirements file at all), so an exact pin on every *direct* dependency is the cheapest
- * available guard against a fresh `npm install` silently resolving a different, unverified
- * top-level React on a later run — it cannot pin transitive dependencies, which is the
- * inherent tradeoff of not committing a lockfile.
- */
-const REACT_VERSION = "19.2.7";
-
-/**
- * The scaffolded `website/package.json` bytes. Docusaurus's CLI is a project-local
- * devDependency (unlike MkDocs, which is pip-installed and standalone) — `@docusaurus/core`
- * and `@docusaurus/preset-classic` are pinned to the exact same {@link DOCUSAURUS_VERSION}
- * (Docusaurus packages must stay in lockstep; a caret range on one but not the other can
- * resolve mismatched minors). Deliberately no `"type": "module"` — see the module docstring
- * for why the config files must load as CommonJS.
- */
-function websitePackageJson(): string {
-  const pkg = {
-    name: "website",
-    private: true,
-    scripts: {
-      build: "docusaurus build",
-    },
-    dependencies: {
-      "@docusaurus/core": DOCUSAURUS_VERSION,
-      "@docusaurus/preset-classic": DOCUSAURUS_VERSION,
-      react: REACT_VERSION,
-      "react-dom": REACT_VERSION,
-    },
-  };
-  return `${JSON.stringify(pkg, null, 2)}\n`;
-}
-
-/**
- * The scaffolded `docusaurus.config.js` bytes (consumer-compatibility.md §3.4; ADR-0010 §2).
- * Every setting mirrors that documented rationale — repeated here as inline comments since
- * this is the file a team actually reads and edits, not the doc:
- *
- * - `markdown.format: 'detect'` — the load-bearing flip: without it, raw `<`/`{` in
- *   hand-written OKF prose (and `<!-- lore:tasks:begin -->`-style comments) is parsed as
- *   MDX/JSX and breaks the build.
- * - `markdown.hooks.onBrokenMarkdownLinks: 'warn'` (moved here in Docusaurus v3.9) plus
- *   `onBrokenLinks: 'warn'` / `onBrokenAnchors: 'warn'` — the default `onBrokenLinks: 'throw'`
- *   would fail the build on OKF's tolerated broken links (cross-tree `backlog/` links, in-progress docs).
- * - `docs.path: '../docs'` / `routeBasePath: '/'` — points the site at the existing bundle
- *   without copying or mutating it (ADR-0010 §2: scaffolding is additive, outside `docs/`).
- * - `blog: false` — avoids parent-folder MDX-loader conflicts; OKF bundles have no blog.
- * - `trailingSlash: false` — pinned to avoid relative-link drift.
- * - `url` / `baseUrl` are placeholders sufficient for `docusaurus build` (which requires both);
- *   only a real deploy needs `organizationName`/`projectName`, which this scaffold does not set.
- */
-function docusaurusConfigJs(siteName: string): string {
-  return `${generatedHeader("//", "docusaurus", "§3.4")}
-//
-// CommonJS, not ESM: an \`export default\` form here crashes the production build
-// (require.resolveWeak is not a function, an ESM/webpack-SSR interaction) — verified against
-// a real \`docusaurus build\`. Do not add "type": "module" to this site's package.json.
-module.exports = {
-  title: ${JSON.stringify(siteName)},
-  url: "https://example.com",
-  baseUrl: "/",
-  trailingSlash: false,
-  onBrokenLinks: "warn",
-  onBrokenAnchors: "warn",
-  markdown: {
-    format: "detect",
-    hooks: {
-      onBrokenMarkdownLinks: "warn",
-    },
-  },
-  presets: [
-    [
-      "classic",
-      {
-        docs: {
-          path: "../docs",
-          routeBasePath: "/",
-          sidebarPath: "./sidebars.js",
-        },
-        blog: false,
-      },
-    ],
-  ],
-};
-`;
-}
-
-/**
- * The scaffolded `sidebars.js` bytes: a single fully-autogenerated sidebar built from the
- * bundle tree (consumer-compatibility.md §3.4) — no per-page sidebar maintenance.
- */
-function sidebarsJs(): string {
-  return `${generatedHeader("//", "docusaurus", "§3.4")}
-module.exports = {
-  docs: [{ type: "autogenerated", dirName: "." }],
-};
-`;
-}
-
-/**
- * Guidance printed after a `lore scaffold obsidian` run. `app.json`'s keys mirror the Settings →
- * Files & Links values below, but Obsidian only reads `app.json` on startup and some builds
- * (mobile in particular) do not honor it at all — the UI is the real guarantee
- * (consumer-compatibility.md §3.2), so the command surfaces it instead of leaving it undocumented.
- */
-export const OBSIDIAN_GUIDANCE_NOTES: readonly string[] = Object.freeze([
-  "Open docs/ itself as the vault (not the repo root), so only the OKF bundle is indexed.",
-  "app.json is a best-effort preset — confirm Settings → Files & Links matches:",
-  "  New link format = Relative path to file",
-  "  Use [[Wikilinks]] = OFF",
-  "  Automatically update internal links = ON",
-]);
-
-/**
- * The scaffolded `docs/.obsidian/app.json` bytes (consumer-compatibility.md §3.2): plain JSON, no
- * header comment (unlike `mkdocs.yml`/`docusaurus.config.js`) since Obsidian owns this file and
- * JSON has no comment syntax to carry one in. `useMarkdownLinks`/`newLinkFormat: "relative"` make
- * new links GitHub-compatible (`[text](path.md)`, not `[[wikilinks]]`); `alwaysUpdateLinks` keeps
- * them correct across renames — the same three settings consumer-compatibility.md's manual
- * Files & Links walkthrough recommends.
- */
-function obsidianAppJson(): string {
-  const config = {
-    useMarkdownLinks: true,
-    newLinkFormat: "relative",
-    alwaysUpdateLinks: true,
-  };
-  return `${JSON.stringify(config, null, 2)}\n`;
-}
-
-/**
- * The scaffolded `docs/.obsidian/.gitignore` bytes ({@link OBSIDIAN_GITIGNORE_REL_PATH}):
- * exclude-all-except, scoped to `docs/.obsidian/` itself so every pattern below is relative to
- * that directory rather than the repo root. `*` ignores everything Obsidian writes there
- * (`workspace.json`, `workspace-mobile.json`, `cache/`, `plugins/`, `snippets/`, ...) — a strict
- * superset of consumer-compatibility.md §3.2's literal `workspace*.json`/cache wording, chosen for
- * the same reason this repo's own root `.gitignore` uses it for its own `docs/.obsidian/`: Obsidian
- * creates more per-user state files than any fixed list can keep up with. `!.gitignore` and
- * `!app.json` re-include the two files this scaffold actually wants committed.
- */
-function obsidianGitignore(): string {
-  return `${generatedHeader("#", "obsidian", "§3.2")}
-*
-!.gitignore
-!app.json
-`;
-}