@theholocron/cli 3.63.0 → 3.65.0

package/dist/cli.mjs

@@ -22,6 +22,7 @@ import { createGitHubClient } from "@theholocron/github-client";
 import * as Sentry from "@sentry/node";
 import { PostHog } from "posthog-node";
 import { promisify } from "node:util";
+import { ConfigFileError, loadConfigFile } from "@theholocron/datapad";
 //#region src/env.ts
 /** Singleton env for simple global lookups throughout the CLI. */
 const env = createEnvLookup();
@@ -2035,12 +2036,13 @@ export class ${inputs.capabilityClass} {
 	readonly key = "${inputs.capability}" as const;
 	readonly providerName = "${inputs.slug}";
 
-	constructor(private readonly rest: ${clientClass}) {}
+	constructor(private readonly rest: () => ${clientClass}) {}
 
 	// TODO: implement the ${capabilityInterface} interface methods
 	// (see \`packages/cli/src/capabilities/index.ts\`). Each method
 	// should hit a specific ${inputs.vendorName} REST endpoint via
-	// \`this.rest.request(...)\`. Once methods are stubbed, add
+	// \`this.rest().request(...)\` — call the thunk so the token is
+	// resolved lazily. Once methods are stubbed, add
 	// \`implements ${capabilityInterface}\` to the class declaration
 	// above and remove the \`as unknown as\` cast in src/index.ts.
 }
@@ -2061,7 +2063,7 @@ import { stubFetch } from "./helpers.js";
 function makeCapability() {
 	const stub = stubFetch([]);
 	const rest = new ${clientClass}({ token: "t", fetch: stub.fetch });
-	return new ${inputs.capabilityClass}(rest);
+	return new ${inputs.capabilityClass}(() => rest);
 }
 
 describe("${inputs.capabilityClass}", () => {
@@ -2254,17 +2256,21 @@ export interface ${inputs.vendorName}PluginOptions extends ResolveTokenInput {
 
 export interface PluginContext {
 	options: ${inputs.vendorName}PluginOptions;
-	rest: ${clientClass};
+	/** Memoized client — the token is resolved on first use, not at plugin load. */
+	rest: () => ${clientClass};
 }
 
 export function createContext(options: ${inputs.vendorName}PluginOptions): PluginContext {
-	const token = resolveToken(options);
-	const restOpts: ConstructorParameters<typeof ${clientClass}>[0] = { token };
-	if (options.baseUrl !== undefined) restOpts.baseUrl = options.baseUrl;
-	if (options.fetch !== undefined) restOpts.fetch = options.fetch;
+	let rest: ${clientClass} | undefined;
 	return {
 		options,
-		rest: new ${clientClass}(restOpts),
+		rest: () => {
+			if (rest) return rest;
+			const restOpts: ConstructorParameters<typeof ${clientClass}>[0] = { token: resolveToken(options) };
+			if (options.baseUrl !== undefined) restOpts.baseUrl = options.baseUrl;
+			if (options.fetch !== undefined) restOpts.fetch = options.fetch;
+			return (rest = new ${clientClass}(restOpts));
+		},
 	};
 }
 
@@ -3751,7 +3757,7 @@ function deriveDeployPaths(raw) {
 * configured. Paths are gitignored and regenerated on every setup run so the
 * content always reflects the current CLI version.
 *
-* Source: .notes/ai-engineering-workflow.spec.md
+* Source: docs/wiki/specifications/ai-engineering-workflow.spec.md
 */
 const DECISIONS_TEMPLATE = "---\nid: ADR-XXXX\ntitle: \"\"\nstatus: proposed\ndate: YYYY-MM-DD\nowners: []\nspecs: []\ndiscussion:\n  github:\nsupersedes: []\nsuperseded-by: []\ntags: []\n---\n\n# [Short title of the decision]\n\n- Status: [proposed | accepted | rejected | deprecated | superseded by ADR-XXXX]\n- Date: YYYY-MM-DD\n\n## Context and Problem Statement\n\n2–3 sentences describing the situation that forced this decision.\n\n## Decision Drivers\n\n- [driver 1 — a constraint, goal, or value]\n- [driver 2]\n\n## Considered Options\n\n- [Option A]\n- [Option B]\n- [Option C — do nothing]\n\n## Decision Outcome\n\nChosen option: **[Option A]**, because [one-sentence justification].\n\n### Positive Consequences\n\n- …\n\n### Negative Consequences\n\n- …\n\n## Pros and Cons of the Options\n\n### [Option A]\n\n- Good, because [argument]\n- Bad, because [argument]\n\n### [Option B]\n\n- Good, because [argument]\n- Bad, because [argument]\n";
 const AGENT_PROMPTS = {
@@ -5203,12 +5209,17 @@ const REGISTRY_MAP = {
 	"@theholocron/themes": getThemes,
 	"@theholocron/utils": getUtils
 };
-function generateInstallBlock(pkg) {
+function generateInstallBlock(pkg, homepage = "") {
 	const { name = "", bin, peerDependencies = {} } = pkg;
 	const isCli = Boolean(bin);
 	const isReact = Boolean(peerDependencies["react"]);
+	const isConsumable = isCli || !pkg.private || Boolean(pkg.main) || pkg.exports !== void 0;
 	const lines = [];
 	lines.push("## Installation", "");
+	if (!isConsumable) {
+		lines.push("This repository is a workspace root — it is not published. See the", "packages under [`packages/`](./packages) for the tools it ships.");
+		return lines.join("\n");
+	}
 	if (isCli) lines.push("```bash", `npm install --global ${name}`, "```");
 	else lines.push("```bash", `pnpm install ${name}`, "```");
 	lines.push("", "## Usage", "");
@@ -5217,8 +5228,9 @@ function generateInstallBlock(pkg) {
 		lines.push("```bash");
 		for (const cmd of commands) lines.push(`${cmd} --help`);
 		lines.push("```");
-	} else if (isReact) lines.push("```tsx", `import { } from "${name}";`, "", "function App() {", `  return <></>;`, "}", "```");
-	else lines.push("```typescript", `import { } from "${name}";`, "```");
+	} else if (isReact) lines.push("```tsx", `import {} from "${name}";`, "", "function App() {", `  return <></>;`, "}", "```");
+	else if (homepage) lines.push(`See the [documentation](${homepage}) for the API.`);
+	else lines.push("See the package documentation for the API.");
 	return lines.join("\n");
 }
 /**
@@ -5300,9 +5312,10 @@ async function runSyncReadme(input) {
 		};
 	}
 	const description = loaded.resolved.description ?? "";
+	const homepage = loaded.resolved.homepage ?? pkg.homepage ?? "";
 	const sections = generateReadme({
 		description,
-		homepage: loaded.resolved.homepage ?? pkg.homepage ?? "",
+		homepage,
 		scripts: pkg.scripts ?? {},
 		packages: pkg.name ? REGISTRY_MAP[pkg.name]?.() : void 0
 	});
@@ -5311,7 +5324,7 @@ async function runSyncReadme(input) {
 		development: sections.development,
 		releases: sections.releases
 	};
-	const updated = await updateReadme(repoRoot, generateInstallBlock(pkg), markerSections, dryRun, readFileFn, writeFileFn);
+	const updated = await updateReadme(repoRoot, generateInstallBlock(pkg, homepage), markerSections, dryRun, readFileFn, writeFileFn);
 	if (!updated) {
 		print(style.warn("README.md not found or has no writable location for installation block"));
 		logger.warn({
@@ -6686,74 +6699,32 @@ async function runUpgradeNode(input) {
 //#endregion
 //#region src/config/load-config.ts
 /**
-* `holocron.config.{json,js,ts}` file loader.
+* `holocron.config.{ts,js,mjs,cjs,json}` loader.
 *
-* Search order: json → js → ts. JSON is parsed directly; JS is loaded
-* via native dynamic import; TS is loaded via `tsImport` from tsx (a
-* runtime dep) so operators can write typed configs with `defineConfig`
-* without needing a separate build step.
+* File discovery + module loading (typed configs via `tsx`, no build
+* step) is delegated to `@theholocron/datapad`. This module keeps the
+* holocron-specific parts: filling `name` / `repo.name` defaults and
+* running the config through `resolveConfig`.
 *
-* All three forms are validated through the same `resolveConfig` path.
-* Implements the lookup-order contract from issue #75 / #81.
+* Probe order is TS-first (`.ts` → `.js` → `.mjs` → `.cjs` → `.json`) —
+* see ADR-0010 / issue #75 / #81.
 */
 const execFileAsync = promisify(execFile);
-const CANDIDATE_FILENAMES = [
-	"holocron.config.json",
-	"holocron.config.js",
-	"holocron.config.ts"
-];
-var ConfigFileError = class extends Error {
-	name = "ConfigFileError";
-};
 /**
 * Read + parse + resolve `holocron.config.*` from the given directory.
-* Search order: json → js → ts. Throws `ConfigFileError` if nothing
-* found, or `ConfigError` if the config is malformed / invalid.
+* Throws {@link ConfigFileError} when nothing is found or a file cannot
+* be loaded, or `ConfigError` when the config is invalid.
 */
 async function loadConfig(cwd) {
-	for (const filename of CANDIDATE_FILENAMES) {
-		const fullPath = join(cwd, filename);
-		if (await fileExists(fullPath)) {
-			if (filename.endsWith(".json")) return {
-				resolved: await loadJson(fullPath),
-				filepath: fullPath
-			};
-			if (filename.endsWith(".ts")) return {
-				resolved: await loadTs(fullPath),
-				filepath: fullPath
-			};
-			return {
-				resolved: await loadJs(fullPath),
-				filepath: fullPath
-			};
-		}
-	}
-	throw new ConfigFileError(`no holocron.config.{json,js,ts} found in ${cwd}. Create one — see the README for the schema.`);
-}
-async function loadJson(filepath) {
-	const raw = await readFile(filepath, "utf8");
-	let parsed;
-	try {
-		parsed = JSON.parse(raw);
-	} catch (err) {
-		throw new ConfigError(`${filepath} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
-	}
-	return resolveConfig(await deriveDefaults(dirname(filepath), parsed));
-}
-async function loadJs(filepath) {
-	const mod = await import(pathToFileURL(filepath).href);
-	return resolveConfig(await deriveDefaults(dirname(filepath), extractRaw(filepath, mod)));
-}
-async function loadTs(filepath) {
-	const { tsImport } = await import("tsx/esm/api");
-	const mod = await tsImport(pathToFileURL(filepath).href, import.meta.url);
-	return resolveConfig(await deriveDefaults(dirname(filepath), extractRaw(filepath, mod)));
-}
-function extractRaw(filepath, mod) {
-	const outer = mod.default;
-	const raw = outer?.__esModule === true ? outer.default : outer;
-	if (raw === void 0 || raw === null) throw new ConfigFileError(`${filepath} must have a default export (use \`export default defineConfig({…})\`)`);
-	return raw;
+	const found = await loadConfigFile({
+		cwd,
+		name: "holocron"
+	});
+	if (!found) throw new ConfigFileError(`no holocron.config.{ts,js,mjs,cjs,json} found in ${cwd}. Create one — see the README for the schema.`);
+	return {
+		resolved: resolveConfig(await deriveDefaults(dirname(found.filepath), found.config)),
+		filepath: found.filepath
+	};
 }
 async function deriveDefaults(configDir, raw) {
 	const result = { ...raw };
@@ -6794,13 +6765,6 @@ function parseGitRemoteUrl(url) {
 	const sshMatch = url.match(/github\.com:([^/]+\/[^/]+?)(?:\.git)?$/);
 	if (sshMatch) return sshMatch[1];
 }
-async function fileExists(path) {
-	try {
-		return (await stat(path)).isFile();
-	} catch {
-		return false;
-	}
-}
 //#endregion
 //#region src/update-notifier.ts
 const PACKAGE_NAME = "@theholocron/cli";