@theholocron/holocron-plugin-fern 3.43.0 → 3.45.0

package/README.md

@@ -27,6 +27,9 @@ pnpm add -D @theholocron/holocron-plugin-fern
 
     // With an explicit basepath
     "wiki": ["fern", { "domain": "wiki.theholocron.dev/myrepo" }],
+
+    // When the Fern workspace slug differs from config.org
+    "wiki": ["fern", { "domain": "wiki.theholocron.dev", "fernOrg": "holocron" }],
   },
 }
 
@@ -34,20 +37,25 @@ pnpm add -D @theholocron/holocron-plugin-fern
 
 ### Options
 
-| Option   | Required | Description                                                                                                                                                                |
-| -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `domain` | No       | Base domain (`"wiki.theholocron.dev"`) or full path (`"wiki.theholocron.dev/myrepo"`). When a base domain is given, the repo name is appended automatically as a basepath. |
+| Option    | Required | Description                                                                                                                                                                |
+| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `domain`  | No       | Base domain (`"wiki.theholocron.dev"`) or full path (`"wiki.theholocron.dev/myrepo"`). When a base domain is given, the repo name is appended automatically as a basepath. |
+| `fernOrg` | No       | Fern workspace slug. Defaults to `config.org`. Set this when the Fern workspace name differs from the GitHub org (e.g. workspace `"holocron"`, org `"theholocron"`).       |
 
 ## What `holocron setup` does
 
 1. **Writes `fern/fern.config.json`** — Fern workspace org name and pinned
    CLI version. Always overwritten.
-2. **Scaffolds `fern/docs.yml`** — Instance URL, optional custom domain with
-   `multi-source: true`, and navigation pointing at `docs/decisions/` and
-   `docs/engineering/`. Skipped if the file already exists so hand-edited
-   navigation entries are preserved.
-
-Both files must be committed — the CI workflow reads them at deploy time.
+2. **Updates `fern/docs.yml`** — On first run, scaffolds the file with
+   instance URL, optional custom domain, and navigation stubs. On subsequent
+   runs, updates only the `instances:` block (URL, `custom-domain`,
+   `multi-source`) while leaving hand-edited navigation, colors, and layout
+   untouched.
+3. **Provisions DNS** — When a `domain` is set and a `dns` provider is
+   configured, upserts a CNAME record pointing the hostname at
+   `<fernOrg>.docs.buildwithfern.com`.
+
+Both `fern/` files must be committed — the CI workflow reads them at deploy time.
 
 ## Custom domain and multi-source routing
 

package/dist/index.d.mts

@@ -0,0 +1,59 @@
+import { AuthError, ResolveTokenInput, Wiki, WikiDnsRecord, WikiProvisionOpts } from "@theholocron/cli";
+//#region src/capabilities/wiki.d.ts
+declare const FERN_VERSION = "5.35.4";
+interface FernWikiOptions {
+  /** Absolute path to the working repo root. Injected by the loader from RuntimeContext. */
+  repoRoot?: string;
+  /** Active org name (e.g. "theholocron"). Injected by the loader from RuntimeContext. */
+  org?: string;
+  /**
+   * "owner/name" repo coordinate. Injected by the loader from RuntimeContext.
+   * Used to derive the per-repo basepath when multi-source custom domain is configured.
+   */
+  repo?: string;
+  /**
+   * Base domain for the Fern docs site (e.g. "wiki.theholocron.dev").
+   *
+   * When provided without a path, the repo name is appended automatically:
+   *   domain "wiki.theholocron.dev" + repo "owner/holocron"
+   *   → custom-domain: wiki.theholocron.dev/holocron
+   *   → multi-source: true
+   *
+   * You can also supply the full path explicitly:
+   *   domain "wiki.theholocron.dev/holocron"
+   *
+   * Note: password protection is configured in the Fern Dashboard
+   * (https://dashboard.buildwithfern.com) — it is not configurable via docs.yml.
+   */
+  domain?: string;
+  /**
+   * Fern workspace org slug. Defaults to `org` (the GitHub org name).
+   * Set this explicitly when the Fern workspace name differs from the
+   * GitHub org — e.g. the workspace was registered as "holocron" while
+   * the GitHub org is "theholocron".
+   */
+  fernOrg?: string;
+}
+declare class FernWiki implements Wiki {
+  private readonly opts;
+  readonly key: "wiki";
+  readonly providerName = "fern";
+  constructor(opts: FernWikiOptions);
+  provision(callOpts?: WikiProvisionOpts): Promise<string>;
+  dnsRecord(): WikiDnsRecord | null;
+}
+//#endregion
+//#region src/auth.d.ts
+declare const resolveToken: (input?: ResolveTokenInput) => string;
+//#endregion
+//#region src/index.d.ts
+type FernPluginOptions = FernWikiOptions;
+declare function wiki(opts: FernPluginOptions): Wiki;
+declare function createPlugin(options?: FernPluginOptions): {
+  name: string;
+  capabilities: {
+    wiki: () => Wiki;
+  };
+};
+//#endregion
+export { AuthError, FERN_VERSION, FernPluginOptions, FernWiki, type FernWikiOptions, type ResolveTokenInput, createPlugin, resolveToken, wiki };

package/dist/index.mjs

@@ -0,0 +1,141 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { AuthError, createResolveToken } from "@theholocron/cli";
+//#region src/capabilities/wiki.ts
+const FERN_VERSION = "5.35.4";
+var FernWiki = class {
+	opts;
+	key = "wiki";
+	providerName = "fern";
+	constructor(opts) {
+		this.opts = opts;
+	}
+	async provision(callOpts) {
+		const repoRoot = this.opts.repoRoot ?? process.cwd();
+		const { org, repo, domain, fernOrg } = this.opts;
+		const name = callOpts?.name;
+		const resolvedFernOrg = fernOrg ?? org;
+		return `${await writeFernConfig({
+			repoRoot,
+			fernOrg: resolvedFernOrg
+		})}; ${await writeFernDocsYml({
+			repoRoot,
+			fernOrg: resolvedFernOrg,
+			repo,
+			name,
+			domain
+		})}`;
+	}
+	dnsRecord() {
+		const { org, domain, fernOrg } = this.opts;
+		if (!domain) return null;
+		const resolvedFernOrg = fernOrg ?? org ?? "holocron";
+		const hostname = domain.split("/")[0];
+		return {
+			zone: hostname.split(".").slice(-2).join("."),
+			cname: hostname,
+			target: `${resolvedFernOrg}.docs.buildwithfern.com`
+		};
+	}
+};
+async function writeFernConfig({ repoRoot, fernOrg }) {
+	const fernDir = join(repoRoot, "fern");
+	await mkdir(fernDir, { recursive: true });
+	const org = fernOrg ?? "holocron";
+	const content = JSON.stringify({
+		organization: org,
+		version: FERN_VERSION
+	}, null, 2) + "\n";
+	await writeFile(join(fernDir, "fern.config.json"), content, "utf8");
+	return `fern.config.json: org=${org}, version=${FERN_VERSION}`;
+}
+async function writeFernDocsYml({ repoRoot, fernOrg, repo, name, domain }) {
+	const fernDir = join(repoRoot, "fern");
+	await mkdir(fernDir, { recursive: true });
+	const docsPath = join(fernDir, "docs.yml");
+	const resolvedFernOrg = fernOrg ?? "holocron";
+	const repoName = repo?.split("/").pop();
+	let instanceUrl;
+	let customDomain;
+	let multiSource = false;
+	if (domain) {
+		const slashIdx = domain.indexOf("/");
+		if (slashIdx !== -1) {
+			instanceUrl = `${resolvedFernOrg}.docs.buildwithfern.com/${domain.slice(slashIdx + 1)}`;
+			customDomain = domain;
+			multiSource = true;
+		} else if (repoName) {
+			instanceUrl = `${resolvedFernOrg}.docs.buildwithfern.com/${repoName}`;
+			customDomain = `${domain}/${repoName}`;
+			multiSource = true;
+		} else {
+			instanceUrl = `${resolvedFernOrg}.docs.buildwithfern.com`;
+			customDomain = domain;
+		}
+	} else instanceUrl = `${resolvedFernOrg}.docs.buildwithfern.com`;
+	let existing = null;
+	try {
+		existing = await readFile(docsPath, "utf8");
+	} catch {}
+	if (existing !== null) {
+		const updated = updateInstancesBlock(existing, instanceUrl, customDomain, multiSource);
+		if (updated !== existing) {
+			await writeFile(docsPath, updated, "utf8");
+			const domainPart = customDomain ? `, domain=${customDomain}${multiSource ? " (multi-source)" : ""}` : "";
+			return `docs.yml: updated instances (url=${instanceUrl}${domainPart})`;
+		}
+		return "docs.yml: instances block already up to date";
+	}
+	const lines = [
+		`# yaml-language-server: $schema=https://schema.buildwithfern.dev/docs-yml.json`,
+		``,
+		`instances:`,
+		`  - url: ${instanceUrl}`
+	];
+	if (customDomain) lines.push(`    custom-domain: ${customDomain}`);
+	if (multiSource) lines.push(`    multi-source: true`);
+	lines.push(``, `title: ${name ?? resolvedFernOrg} Engineering`, ``, `layout:`, `  page-width: full`, `  tabs-placement: header`, `  searchbar-placement: header`, ``, `tabs:`, `  decisions:`, `    display-name: Decisions`, `    icon: fa-duotone fa-scale-balanced`, `  engineering:`, `    display-name: Engineering`, `    icon: fa-duotone fa-gear`, ``, `navigation:`, `  - tab: decisions`, `    layout:`, `      - section: Architecture Decision Records`, `        contents:`, `          - page: Index`, `            path: ../docs/decisions/README.md`, `  - tab: engineering`, `    layout:`, `      - section: Overview`, `        contents:`, `          - page: Engineering Home`, `            path: ../docs/engineering/README.md`, ``, `colors:`, `  accent-primary:`, `    dark: "#70E155"`, `    light: "#008700"`, ``, `logo:`, `  height: 20`, ``, `metadata:`, `  og:dynamic: true`, ``);
+	await writeFile(docsPath, lines.join("\n"), "utf8");
+	const domainSummary = customDomain ? `, domain=${customDomain}${multiSource ? " (multi-source)" : ""}` : "";
+	return `docs.yml: url=${instanceUrl}${domainSummary}`;
+}
+/**
+* Replace the `instances:` block in an existing docs.yml, preserving
+* everything else (navigation, colors, layout, title, etc.).
+*
+* Uses a regex to match the block (the `instances:` key and all following
+* indented / list lines) and replaces it in-place. Returns the original
+* string unchanged when the block already matches.
+*/
+function updateInstancesBlock(content, instanceUrl, customDomain, multiSource) {
+	const blockRe = /^instances:(?:\n[ \t][^\n]*)*/m;
+	const match = content.match(blockRe);
+	if (!match) return content;
+	const newLines = [`instances:`, `  - url: ${instanceUrl}`];
+	if (customDomain) newLines.push(`    custom-domain: ${customDomain}`);
+	if (multiSource) newLines.push(`    multi-source: true`);
+	const newBlock = newLines.join("\n");
+	if (match[0] === newBlock) return content;
+	return content.replace(blockRe, newBlock);
+}
+//#endregion
+//#region src/auth.ts
+const resolveToken = createResolveToken({
+	envName: "HOLOCRON_FERN_TOKEN",
+	vendorEnvName: "FERN_TOKEN",
+	keyringService: "fern",
+	errorMessage: "no Fern token found. Set HOLOCRON_FERN_TOKEN / FERN_TOKEN, or run: holocron auth set fern <token>"
+});
+//#endregion
+//#region src/index.ts
+function wiki(opts) {
+	return new FernWiki(opts);
+}
+function createPlugin(options = {}) {
+	return {
+		name: "@theholocron/holocron-plugin-fern",
+		capabilities: { wiki: () => wiki(options) }
+	};
+}
+//#endregion
+export { AuthError, FERN_VERSION, FernWiki, createPlugin, resolveToken, wiki };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-fern",
-  "version": "3.43.0",
+  "version": "3.45.0",
   "description": "Holocron plugin for Fern. Implements the wiki capability for engineering knowledge publishing.",
   "keywords": [
     "fern",
@@ -44,10 +44,10 @@
     "tsx": "4.23.12",
     "typescript": "^5.9.3",
     "vitest": "^4.1.10",
-    "@theholocron/cli": "3.43.0"
+    "@theholocron/cli": "3.45.0"
   },
   "peerDependencies": {
-    "@theholocron/cli": "3.43.0"
+    "@theholocron/cli": "3.45.0"
   },
   "engines": {
     "node": ">=22"