@theholocron/holocron-plugin-fern 5.0.0-alpha.25 → 5.0.0-alpha.250

package/README.md

@@ -42,7 +42,7 @@ pnpm add -D @theholocron/holocron-plugin-fern
 | `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
+## What `holocron repo setup` does
 
 1. **Writes `fern/fern.config.json`** — Fern workspace org name and pinned
    CLI version. Always overwritten.
@@ -79,7 +79,7 @@ DNS: add one CNAME record — `wiki.theholocron.dev` →
 Password protection is configured in the **Fern Dashboard**
 (`dashboard.buildwithfern.com`) — it is not configurable via `docs.yml` or
 any CLI flag. Configure access control manually in the dashboard after
-running `holocron setup`.
+running `holocron repo setup`.
 
 ## CI secrets
 

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { AuthError, ResolveTokenInput, Wiki, WikiDnsRecord, WikiProvisionOpts, WikiProxyConfig } from "@theholocron/cli";
-//#region src/capabilities/wiki.d.ts
-declare const FERN_VERSION = "5.114.1";
-interface FernWikiOptions {
+import { AuthError, DnsRecordRequest, ResolveTokenInput, Wiki, WikiProvisionOpts, WikiProxyConfig } from "@theholocron/cli";
+export declare const resolveToken: (input?: ResolveTokenInput) => string;
+export declare const FERN_VERSION = "5.114.1";
+interface FernWikiOptions extends ResolveTokenInput {
   /** 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. */
@@ -36,36 +36,56 @@ interface FernWikiOptions {
   /**
    * One-line description shown on the global product switcher card.
    * Falls back to the top-level `description` field in `holocron.config.ts`
-   * when omitted. Only used by `holocron sync --steps wiki`.
+   * when omitted. Only used by `holocron repo sync --steps wiki`.
    */
   subtitle?: string;
   /**
    * Font Awesome icon class for the product switcher card (e.g. `"fa-duotone fa-gear"`).
-   * Only used by `holocron sync --steps wiki`.
+   * Only used by `holocron repo sync --steps wiki`.
    */
   icon?: string;
 }
-declare class FernWiki implements Wiki {
+export declare class FernWiki implements Wiki {
   private readonly opts;
   readonly key: "wiki";
   readonly providerName = "fern";
   constructor(opts: FernWikiOptions);
   provision(callOpts?: WikiProvisionOpts): Promise<string>;
   proxyConfig(): WikiProxyConfig | null;
-  dnsRecord(): WikiDnsRecord | null;
+  /**
+   * Confirms `HOLOCRON_FERN_TOKEN`/`FERN_TOKEN` resolves, or a Fern token
+   * is stored in the keyring — not a live check. Fern exposes no
+   * lightweight endpoint to verify a token actually works (the only
+   * token-consuming operation is a full `fern generate`, see
+   * holocron#1079); this only confirms one is configured, the same way
+   * CI's `fern generate --docs` step would find it.
+   *
+   * Deliberately ignores `cliToken` (`--token`): CI's step only ever sees
+   * the env var from a GitHub Actions secret, never a CLI flag — and a
+   * bare `--token <value>` meant for some OTHER provider is forwarded to
+   * every loaded plugin as a fallback (see AGENTS.md), so honoring it
+   * here would report "configured" even when no Fern-specific credential
+   * exists anywhere CI would actually look.
+   *
+   * Only `AuthError` (the specific "no token found" signal) is treated as
+   * `ok: false` — any other error (e.g. a real keyring failure) is a
+   * genuine problem and must surface as a failure, not get misreported as
+   * a missing token.
+   */
+  whoami(): Promise<{
+    ok: boolean;
+  }>;
+  dnsRecord(): DnsRecordRequest | 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): {
+export type FernPluginOptions = FernWikiOptions;
+export declare function wiki(opts: FernPluginOptions): Wiki;
+export declare function createPlugin(options?: FernPluginOptions): {
   name: string;
+  probes: {
+    connection: import("@theholocron/cli").Probe;
+  };
   capabilities: {
     wiki: () => Wiki;
   };
 };
-//#endregion
-export { AuthError, FERN_VERSION, FernPluginOptions, FernWiki, type FernWikiOptions, type ResolveTokenInput, createPlugin, resolveToken, wiki };
+export { AuthError, type FernWikiOptions, type ResolveTokenInput };

package/dist/index.mjs

@@ -1,7 +1,15 @@
+import { AuthError, connectionProbe, createResolveToken } from "@theholocron/cli";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { AuthError, createResolveToken } from "@theholocron/cli";
-//#region src/capabilities/wiki.ts
+import { stringifyJson } from "@theholocron/json-utils";
+// 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>"
+});
+// src/capabilities/wiki.ts
 const FERN_VERSION = "5.114.1";
 var FernWiki = class {
 	opts;
@@ -33,6 +41,38 @@ var FernWiki = class {
 			headers: { "X-Fern-Host": this.opts.domain.split("/")[0] }
 		};
 	}
+	/**
+	* Confirms `HOLOCRON_FERN_TOKEN`/`FERN_TOKEN` resolves, or a Fern token
+	* is stored in the keyring — not a live check. Fern exposes no
+	* lightweight endpoint to verify a token actually works (the only
+	* token-consuming operation is a full `fern generate`, see
+	* holocron#1079); this only confirms one is configured, the same way
+	* CI's `fern generate --docs` step would find it.
+	*
+	* Deliberately ignores `cliToken` (`--token`): CI's step only ever sees
+	* the env var from a GitHub Actions secret, never a CLI flag — and a
+	* bare `--token <value>` meant for some OTHER provider is forwarded to
+	* every loaded plugin as a fallback (see AGENTS.md), so honoring it
+	* here would report "configured" even when no Fern-specific credential
+	* exists anywhere CI would actually look.
+	*
+	* Only `AuthError` (the specific "no token found" signal) is treated as
+	* `ok: false` — any other error (e.g. a real keyring failure) is a
+	* genuine problem and must surface as a failure, not get misreported as
+	* a missing token.
+	*/
+	async whoami() {
+		try {
+			resolveToken({
+				...this.opts,
+				cliToken: void 0
+			});
+			return { ok: true };
+		} catch (err) {
+			if (err instanceof AuthError) return { ok: false };
+			throw err;
+		}
+	}
 	dnsRecord() {
 		const { org, domain, fernOrg } = this.opts;
 		if (!domain) return null;
@@ -40,8 +80,11 @@ var FernWiki = class {
 		const hostname = domain.split("/")[0];
 		return {
 			zone: hostname.split(".").slice(-2).join("."),
-			cname: hostname,
-			target: `${resolvedFernOrg}.docs.buildwithfern.com`
+			record: {
+				type: "CNAME",
+				name: hostname,
+				content: `${resolvedFernOrg}.docs.buildwithfern.com`
+			}
 		};
 	}
 };
@@ -49,10 +92,10 @@ async function writeFernConfig({ repoRoot, fernOrg }) {
 	const fernDir = join(repoRoot, "fern");
 	await mkdir(fernDir, { recursive: true });
 	const org = fernOrg ?? "holocron";
-	const content = JSON.stringify({
+	const content = stringifyJson({
 		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}`;
 }
@@ -127,24 +170,22 @@ function updateInstancesBlock(content, instanceUrl, customDomain, multiSource, r
 	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
+// src/index.ts
 function wiki(opts) {
 	return new FernWiki(opts);
 }
 function createPlugin(options = {}) {
 	return {
 		name: "@theholocron/holocron-plugin-fern",
+		probes: { connection: connectionProbe({
+			provider: "Fern",
+			token: () => resolveToken(options),
+			verify: async () => ({
+				ok: true,
+				subject: "a token is set (Fern cannot check it from here)"
+			})
+		}) },
 		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": "5.0.0-alpha.25",
+  "version": "5.0.0-alpha.250",
   "description": "Holocron plugin for Fern. Implements the wiki capability for engineering knowledge publishing.",
   "keywords": [
     "fern",
@@ -8,12 +8,12 @@
     "plugin",
     "wiki"
   ],
-  "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-fern#readme",
+  "homepage": "https://github.com/theholocron/holocron/tree/main/plugins/holocron-plugin-fern#readme",
   "bugs": "https://github.com/theholocron/holocron/issues",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/theholocron/holocron.git",
-    "directory": "packages/holocron-plugin-fern"
+    "directory": "plugins/holocron-plugin-fern"
   },
   "license": "MIT",
   "author": "Newton Koumantzelis",
@@ -29,25 +29,28 @@
   "files": [
     "dist"
   ],
+  "dependencies": {
+    "@theholocron/json-utils": "^1.16.0"
+  },
   "devDependencies": {
-    "@theholocron/eslint-config": "^8.0.0",
-    "@theholocron/tsconfig": "^8.0.0",
-    "@theholocron/tsdown-config": "^8.0.0",
-    "@theholocron/vitest-config": "^8.0.0",
+    "@theholocron/eslint-config": "^8.8.2",
+    "@theholocron/tsconfig": "^8.8.2",
+    "@theholocron/tsdown-config": "^8.8.2",
+    "@theholocron/vitest-config": "^8.8.2",
     "@types/node": "^26",
-    "@vitest/coverage-v8": "^4.1.11",
+    "@vitest/coverage-v8": "^5.0.5",
     "@vitest/eslint-plugin": "^1.6.27",
     "eslint": "^10.8.1",
     "eslint-plugin-n": "^18.3.0",
     "globals": "^17.11.0",
-    "tsdown": "^0.22.14",
-    "tsx": "4.23.12",
+    "tsdown": "^0.23.3",
+    "tsx": "4.23.15",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.11",
-    "@theholocron/cli": "5.0.0-alpha.25"
+    "vitest": "^5.0.5",
+    "@theholocron/cli": "5.0.0-alpha.250"
   },
   "peerDependencies": {
-    "@theholocron/cli": "5.0.0-alpha.25"
+    "@theholocron/cli": "5.0.0-alpha.250"
   },
   "engines": {
     "node": ">=22"