@theholocron/holocron-plugin-fern 5.0.0-alpha.43 → 5.0.0-alpha.430

package/README.md

@@ -1,3 +1,5 @@
+<!-- alex disable host-hostess -->
+
 <!-- editorconfig-checker-disable-file -->
 
 # `@theholocron/holocron-plugin-fern`
@@ -83,7 +85,7 @@ running `holocron 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 secrets --verify`, with the layers that hold it. */
+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,7 +35,7 @@ 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;
   /**
@@ -45,27 +50,54 @@ interface FernWikiOptions {
    */
   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` and `token` probes and the `wiki` capability. */
+export declare function createPlugin(options?: FernPluginOptions): {
   name: string;
+  probes: {
+    connection: import("@theholocron/cli").Probe;
+    token: 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,37 @@
+import { AuthError, connectionProbe, createResolveToken, tokenExpectations } 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/probes/token/expectations.ts
+/**
+* Where the Fern token is held: CI only (the `publish-wiki` workflow), so `ci` is the one layer declared. Fern has no
+* endpoint that reports a token's permissions, so none are declared and the probe says so instead of guessing. This is
+* the plugin's `tokens` declaration, read through `tokenExpectations()`; change it and the Fern note in
+* `docs/src/content/docs/tokens.mdx` together.
+*/
+const EXPECTED = { layers: ["ci"] };
+// 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 new token fern <token>"
+});
+/** Every token this plugin takes, for `holocron doctor secrets --verify`, with the layers that hold it. */
+const tokens = [{
+	...resolveToken.token,
+	expect: EXPECTED
+}];
+// 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 +59,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 +110,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 +188,76 @@ 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/probes/token/parse-layer.ts
+/** Reads `--layer <word>` (or `--layer=<word>`) from the words after the probe name, which the CLI passes when `--environment` named a layer. */
+function parseLayer(args) {
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--layer") return args[i + 1];
+		if (arg.startsWith("--layer=")) return arg.slice(8);
+	}
+}
+// src/probes/token/token.ts
+/**
+* The `token` probe for Fern. Fern has no endpoint that reports who a token is or what it may do, so the probe cannot
+* judge permissions: it checks that a token is set, says whether the layer holds it when `--layer` is passed (because
+* `--environment` named one) against the plugin's `tokens` declaration, and states plainly that permissions are not
+* checked. It makes no request and never prints the token.
+*/
+function tokenProbe(ctx) {
+	return {
+		summary: "Check that a Fern token is set, and for a layer that it is one that should hold it. Fern cannot report a token's permissions, so those are not checked. Read-only, no request.",
+		writes: false,
+		acceptsToken: true,
+		async run(probe) {
+			probe.secret(ctx.token());
+			probe.say({
+				status: "ok",
+				label: "token",
+				detail: "set"
+			});
+			const layer = parseLayer(probe.args ?? []);
+			if (layer) {
+				const declared = tokenExpectations(tokens, { layer }).length > 0;
+				probe.say(declared ? {
+					status: "ok",
+					label: layer,
+					detail: "a layer that should hold this token"
+				} : {
+					status: "info",
+					label: layer,
+					detail: "not a layer this token is declared for, so it is only described"
+				});
+			}
+			probe.say({
+				status: "info",
+				label: "permissions",
+				detail: "Fern cannot report a token's permissions, so they are not checked"
+			});
+		}
+	};
+}
+// src/index.ts
+/** Builds the `wiki` capability from the plugin options. */
 function wiki(opts) {
 	return new FernWiki(opts);
 }
+/** Creates the Fern plugin: its `connection` and `token` probes 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)"
+				})
+			}),
+			token: tokenProbe({ token: () => resolveToken(options) })
+		},
 		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.43",
+  "version": "5.0.0-alpha.430",
   "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.4.5",
-    "@theholocron/tsconfig": "^8.4.5",
-    "@theholocron/tsdown-config": "^8.4.5",
-    "@theholocron/vitest-config": "^8.4.5",
     "@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.43"
+    "vitest": "^5.1.0",
+    "@theholocron/cli": "5.0.0-alpha.430",
+    "@theholocron/eslint-config": "^8.9.0-alpha.17",
+    "@theholocron/tsconfig": "^8.9.0-alpha.17",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.17",
+    "@theholocron/vitest-config": "^8.9.0-alpha.17"
   },
   "peerDependencies": {
-    "@theholocron/cli": "5.0.0-alpha.43"
+    "@theholocron/cli": "5.0.0-alpha.430"
   },
   "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"
   }
 }