@theholocron/holocron-plugin-fern 5.0.0-alpha.42 → 5.0.0-alpha.420

package/README.md

@@ -1,3 +1,5 @@
+<!-- alex disable host-hostess -->
+
 <!-- editorconfig-checker-disable-file -->
 
 # `@theholocron/holocron-plugin-fern`
@@ -42,7 +44,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,11 +81,11 @@ 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
 
-Add `HOLOCRON_FERN_TOKEN` to your repo's GitHub Secrets. The `wiki.yml` thin caller
+Add `HOLOCRON_FERN_TOKEN` to your repo's GitHub Secrets. The `publish-wiki` thin caller
 passes it to the Fern CLI during `fern generate --docs`.
 
 | Secret                | Purpose                                      |

package/dist/index.d.mts

@@ -1,10 +1,15 @@
-import { AuthError, DnsRecordRequest, ResolveTokenInput, Wiki, WikiProvisionOpts, WikiProxyConfig } from "@theholocron/cli";
-//#region src/capabilities/wiki.d.ts
-declare const FERN_VERSION = "5.114.1";
-interface FernWikiOptions {
+import { AuthError, DnsRecordRequest, PluginToken, ResolveTokenInput, Wiki, WikiProvisionOpts, WikiProxyConfig } from "@theholocron/cli";
+/** Resolves the Fern token from `--token`, `HOLOCRON_FERN_TOKEN`, `FERN_TOKEN` or the keyring entry for `fern`, and throws `AuthError` when none is set. */
+export declare const resolveToken: import("@theholocron/cli").TokenResolver;
+/** Every token this plugin takes, for `holocron doctor tokens`. */
+export declare const tokens: PluginToken[];
+/** The Fern CLI version written into `fern/fern.config.json`. */
+export declare const FERN_VERSION = "5.114.1";
+/** Options for the Fern `wiki` capability. */
+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. */
+  /** Active org name (e.g. "acme"). Injected by the loader from RuntimeContext. */
   org?: string;
   /**
    * "owner/name" repo coordinate. Injected by the loader from RuntimeContext.
@@ -12,15 +17,15 @@ interface FernWikiOptions {
    */
   repo?: string;
   /**
-   * Base domain for the Fern docs site (e.g. "wiki.theholocron.dev").
+   * Base domain for the Fern docs site (e.g. "wiki.example.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
+   *   domain "wiki.example.dev" + repo "owner/holocron"
+   *   → custom-domain: wiki.example.dev/holocron
    *   → multi-source: true
    *
    * You can also supply the full path explicitly:
-   *   domain "wiki.theholocron.dev/holocron"
+   *   domain "wiki.example.dev/holocron"
    *
    * Note: password protection is configured in the Fern Dashboard
    * (https://dashboard.buildwithfern.com) — it is not configurable via docs.yml.
@@ -30,42 +35,68 @@ interface FernWikiOptions {
    * 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".
+   * the GitHub org is "acme".
    */
   fernOrg?: string;
   /**
    * 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 {
+/** `wiki` capability for Fern: writes the Fern config and docs scaffold for a repo. */
+export declare class FernWiki implements Wiki {
   private readonly opts;
+  /** Capability key; always `"wiki"`. */
   readonly key: "wiki";
+  /** Provider name; always `"fern"`. */
   readonly providerName = "fern";
   constructor(opts: FernWikiOptions);
   provision(callOpts?: WikiProvisionOpts): Promise<string>;
   proxyConfig(): WikiProxyConfig | 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): {
+/** Options for the Fern plugin; the same as the `wiki` capability's. */
+export type FernPluginOptions = FernWikiOptions;
+/** Builds the `wiki` capability from the plugin options. */
+export declare function wiki(opts: FernPluginOptions): Wiki;
+/** Creates the Fern plugin: its `connection` probe and the `wiki` capability. */
+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,11 +1,26 @@
+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
+/** Resolves the Fern token from `--token`, `HOLOCRON_FERN_TOKEN`, `FERN_TOKEN` or the keyring entry for `fern`, and throws `AuthError` when none is set. */
+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>"
+});
+/** Every token this plugin takes, for `holocron doctor tokens`. */
+const tokens = [resolveToken.token];
+// src/capabilities/wiki.ts
+/** The Fern CLI version written into `fern/fern.config.json`. */
 const FERN_VERSION = "5.114.1";
+/** `wiki` capability for Fern: writes the Fern config and docs scaffold for a repo. */
 var FernWiki = class {
 	opts;
+	/** Capability key; always `"wiki"`. */
 	key = "wiki";
+	/** Provider name; always `"fern"`. */
 	providerName = "fern";
 	constructor(opts) {
 		this.opts = opts;
@@ -33,6 +48,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;
@@ -52,10 +99,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}`;
 }
@@ -130,24 +177,24 @@ 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
+/** Builds the `wiki` capability from the plugin options. */
 function wiki(opts) {
 	return new FernWiki(opts);
 }
+/** Creates the Fern plugin: its `connection` probe and the `wiki` capability. */
 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 };
+export { AuthError, FERN_VERSION, FernWiki, createPlugin, resolveToken, tokens, wiki };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-fern",
-  "version": "5.0.0-alpha.42",
+  "version": "5.0.0-alpha.420",
   "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://docs.theholocron.dev/holocron/plugins/fern/",
   "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.17.0-alpha.4"
+  },
   "devDependencies": {
-    "@theholocron/eslint-config": "^8.0.0",
-    "@theholocron/tsconfig": "^8.0.0",
-    "@theholocron/tsdown-config": "^8.0.0",
-    "@theholocron/vitest-config": "^8.0.0",
     "@types/node": "^26",
-    "@vitest/coverage-v8": "^4.1.11",
-    "@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",
+    "@vitest/coverage-v8": "^5.1.0",
+    "@vitest/eslint-plugin": "^1.6.28",
+    "eslint": "^10.14.0",
+    "eslint-plugin-n": "^18.5.0",
+    "globals": "^17.14.0",
+    "tsdown": "^0.23.5",
+    "tsx": "4.23.15",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.11",
-    "@theholocron/cli": "5.0.0-alpha.42"
+    "vitest": "^5.1.0",
+    "@theholocron/cli": "5.0.0-alpha.420",
+    "@theholocron/tsconfig": "^8.9.0-alpha.16",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.16",
+    "@theholocron/vitest-config": "^8.9.0-alpha.16",
+    "@theholocron/eslint-config": "^8.9.0-alpha.16"
   },
   "peerDependencies": {
-    "@theholocron/cli": "5.0.0-alpha.42"
+    "@theholocron/cli": "5.0.0-alpha.420"
   },
   "engines": {
     "node": ">=22"
@@ -56,10 +59,10 @@
     "access": "public"
   },
   "scripts": {
-    "delivery.build": "tsdown",
-    "sourceQuality.staticAnalysis": "holocron run sourceQuality.staticAnalysis --",
+    "build": "tsdown",
+    "lint:code": "eslint .",
+    "test:unit": "vitest run --coverage",
     "test:watch": "vitest",
-    "verification.typeSafety": "holocron run verification.typeSafety --",
-    "verification.unitTests": "holocron run verification.unitTests --"
+    "typecheck": "tsc --noEmit"
   }
 }