@theholocron/holocron-plugin-fern 5.0.0-alpha.428 → 5.0.0-alpha.429

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 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`. */
+/** Every token this plugin takes, for `holocron doctor tokens`, 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";
@@ -89,11 +89,12 @@ export declare class FernWiki implements Wiki {
 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. */
+/** 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;

package/dist/index.mjs

@@ -1,7 +1,15 @@
-import { AuthError, connectionProbe, createResolveToken } from "@theholocron/cli";
+import { AuthError, connectionProbe, createResolveToken, tokenExpectations } from "@theholocron/cli";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 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({
@@ -10,8 +18,11 @@ const resolveToken = createResolveToken({
 	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 tokens`. */
-const tokens = [resolveToken.token];
+/** Every token this plugin takes, for `holocron doctor tokens`, 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";
@@ -177,23 +188,75 @@ function updateInstancesBlock(content, instanceUrl, customDomain, multiSource, r
 	if (match[0] === newBlock) return content;
 	return content.replace(blockRe, newBlock);
 }
+// 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` probe and the `wiki` capability. */
+/** 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)"
-			})
-		}) },
+		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) }
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-fern",
-  "version": "5.0.0-alpha.428",
+  "version": "5.0.0-alpha.429",
   "description": "Holocron plugin for Fern. Implements the wiki capability for engineering knowledge publishing.",
   "keywords": [
     "fern",
@@ -43,14 +43,14 @@
     "tsx": "4.23.15",
     "typescript": "^5.9.3",
     "vitest": "^5.1.0",
-    "@theholocron/cli": "5.0.0-alpha.428",
     "@theholocron/eslint-config": "^8.9.0-alpha.17",
-    "@theholocron/vitest-config": "^8.9.0-alpha.17",
+    "@theholocron/tsconfig": "^8.9.0-alpha.17",
     "@theholocron/tsdown-config": "^8.9.0-alpha.17",
-    "@theholocron/tsconfig": "^8.9.0-alpha.17"
+    "@theholocron/vitest-config": "^8.9.0-alpha.17",
+    "@theholocron/cli": "5.0.0-alpha.429"
   },
   "peerDependencies": {
-    "@theholocron/cli": "5.0.0-alpha.428"
+    "@theholocron/cli": "5.0.0-alpha.429"
   },
   "engines": {
     "node": ">=22"