@theholocron/cli 2.0.0-alpha.18 → 2.0.0-alpha.19

package/README.md

@@ -10,11 +10,79 @@ npm i -g @theholocron/cli@alpha
 holocron --help
 ```
 
+## Config file
+
+Holocron reads `holocron.config.{json,js,ts}` from the project root
+(priority: json → js → ts).
+
+**JSON** (simplest):
+```jsonc
+// holocron.config.json
+{
+  "project": { "name": "my-app" },
+  "providers": {
+    "vault": ["1password", { "vault": "my-app" }],
+    "source": "github"
+  }
+}
+```
+
+**JS/TS** — use `defineConfig` for autocomplete and type-checking:
+```ts
+// holocron.config.ts
+import { defineConfig } from '@theholocron/cli'
+
+export default defineConfig({
+  project: { name: 'my-app' },
+  providers: {
+    vault: ['1password', { vault: 'my-app' }],
+    source: 'github',
+  },
+})
+```
+
+### Shareable configs
+
+**Level 1 — per-capability config packages.** Reference a published
+package in any provider slot and Holocron resolves its bundled
+`{ provider, options }` automatically. Per-project options merge on
+top (project wins):
+
+```ts
+providers: {
+  vault: '@acme/holocron-vault',                     // preset only
+  source: ['@acme/holocron-github', { repo: 'x' }], // preset + override
+}
+```
+
+A capability config package exports a `CapabilityConfigPackage` default:
+```ts
+import type { CapabilityConfigPackage } from '@theholocron/cli'
+export default {
+  provider: '1password',
+  options: { vault: 'acme-app' },
+} satisfies CapabilityConfigPackage
+```
+
+**Level 2 — whole-config presets.** Because the config file can be
+JS/TS, a shared base is just an import:
+
+```ts
+// holocron.config.ts
+import { acmeConfig } from '@acme/holocron-config'
+export default acmeConfig
+```
+
 ## What's in here
 
 - `src/capabilities/` — the 14 capability interfaces that providers
 	implement
-- `src/config.ts` — `holocron.config.json` parser + plugin resolution
+- `src/config.ts` — config schema, `defineConfig`, `resolveConfig`,
+	`CapabilityConfigPackage`
+- `src/load-config.ts` — `loadConfig` — reads JSON/JS/TS config files
+- `src/define-config.ts` — `defineConfig` typed pass-through
+- `src/loader.ts` — `PluginLoader` — dynamic-imports plugins, resolves
+	capability config packages, builds the capability registry
 - `src/cli.ts` — yargs entry, dispatches subcommands
 - `src/commands/` — `setup`, `doctor`, `deploy`, `secret set`,
 	`secrets sync`, `npm publish-initial`

package/dist/cli.mjs

@@ -7,6 +7,7 @@ import path, { dirname, join } from "node:path";
 import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { readFile, stat } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
 //#region src/capabilities/index.ts
 const CARDINALITY = {
 	source: "single",
@@ -446,17 +447,30 @@ var PluginLoader = class {
 	}
 	/** Internal — invoke a plugin's capability factory and return the impl. */
 	async loadOne(key, tuple) {
-		const module = await this.importer(tuple.packageName).catch((err) => {
+		const mod = await this.importer(tuple.packageName).catch((err) => {
 			throw new LoaderError(`failed to import \`${tuple.packageName}\` for capability \`${key}\`: ${err instanceof Error ? err.message : String(err)}`);
 		});
-		if (typeof module.createPlugin !== "function") throw new LoaderError(`\`${tuple.packageName}\` does not export \`createPlugin(options)\``);
-		const factory = module.createPlugin({
-			...this.projectDefaults(),
-			...this.context,
-			...tuple.options
-		}).capabilities[key];
-		if (typeof factory !== "function") throw new LoaderError(`\`${tuple.packageName}\` does not implement the \`${key}\` capability`);
-		return factory();
+		if (isPluginModule(mod)) {
+			const factory = mod.createPlugin({
+				...this.projectDefaults(),
+				...this.context,
+				...tuple.options
+			}).capabilities[key];
+			if (typeof factory !== "function") throw new LoaderError(`\`${tuple.packageName}\` does not implement the \`${key}\` capability`);
+			return factory();
+		}
+		if (isCapabilityConfigModule(mod)) {
+			const cap = mod.default;
+			return this.loadOne(key, {
+				provider: cap.provider,
+				packageName: resolvePluginPackage(cap.provider),
+				options: {
+					...cap.options,
+					...tuple.options
+				}
+			});
+		}
+		throw new LoaderError(`\`${tuple.packageName}\` does not export \`createPlugin(options)\` or a capability config ({ provider, options? })`);
 	}
 	/**
 	* Project-level defaults that get merged into every plugin's options
@@ -471,8 +485,14 @@ var PluginLoader = class {
 };
 /** Default importer — native dynamic import. */
 const defaultImporter = async (pkg) => {
-	return await import(pkg);
+	return import(pkg);
 };
+function isPluginModule(mod) {
+	return typeof mod.createPlugin === "function";
+}
+function isCapabilityConfigModule(mod) {
+	return typeof mod.default?.provider === "string";
+}
 //#endregion
 //#region src/commands/deploy.ts
 async function runDeploy(input) {
@@ -745,13 +765,13 @@ on: # yamllint disable-line rule:truthy
   workflow_call:
     inputs:
       build-script:
-        description: Script to build before analyzing bundle size
+        description: Script to build and upload bundle stats to Codecov
         type: string
         required: false
         default: pnpm build
     secrets:
-      BUNDLEWATCH_GITHUB_TOKEN:
-        required: true
+      CODECOV_TOKEN:
+        required: false
 
 jobs:
   bundle-size:
@@ -764,7 +784,7 @@ jobs:
       group: audit-\${{ github.ref }}
       cancel-in-progress: true
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         name: Checkout repository
         with:
           fetch-depth: 0
@@ -772,11 +792,10 @@ jobs:
       - uses: theholocron/.github/.github/actions/setup@main
         name: Setup
 
-      - uses: jackyef/bundlewatch-gh-action@01f51133d3580a6daa046ca83eb233d79735e1c1 # 0.3.0
-        name: Analyze using BundleWatch
-        with:
-          build-script: \${{ inputs.build-script }}
-          bundlewatch-github-token: \${{ secrets.BUNDLEWATCH_GITHUB_TOKEN }}
+      - run: \${{ inputs.build-script }}
+        name: Build and upload bundle stats
+        env:
+          CODECOV_TOKEN: \${{ secrets.CODECOV_TOKEN }}
 `,
 	"bookkeeping-pr": `\
 name: PR Bookkeeping
@@ -802,7 +821,7 @@ jobs:
       group: bookkeeping-pr-\${{ github.event.pull_request.number }}
       cancel-in-progress: true
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           sparse-checkout: \${{ inputs.configuration-path || '.github/labeler.yml' }}
           sparse-checkout-cone-mode: false
@@ -845,18 +864,18 @@ jobs:
       group: codeql-\${{ github.ref }}
       cancel-in-progress: false
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         name: Checkout repository
 
-      - uses: github/codeql-action/init@411c4c9a36b3fca4d674f06b6396b2c6d23522c6 # v3
+      - uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
         name: Initialize CodeQL
         with:
           languages: \${{ inputs.language }}
 
-      - uses: github/codeql-action/autobuild@411c4c9a36b3fca4d674f06b6396b2c6d23522c6 # v3
+      - uses: github/codeql-action/autobuild@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
         name: Autobuild
 
-      - uses: github/codeql-action/analyze@411c4c9a36b3fca4d674f06b6396b2c6d23522c6 # v3
+      - uses: github/codeql-action/analyze@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
         name: Analyze
         with:
           category: /language:\${{ inputs.language }}
@@ -887,7 +906,7 @@ jobs:
       cancel-in-progress: true
     if: github.event.pull_request.user.login == 'dependabot[bot]'
     steps:
-      - uses: dependabot/fetch-metadata@21025c705c08248db411dc16f3619e6b5f9ea21a # v2
+      - uses: dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98 # v3.1.0
         name: Fetch Dependabot metadata
         id: metadata
 
@@ -919,7 +938,7 @@ jobs:
       group: greetings-\${{ github.event.issue.number || github.event.pull_request.number }}
       cancel-in-progress: false
     steps:
-      - uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         name: Greet on first contribution
         with:
           script: |
@@ -995,7 +1014,7 @@ jobs:
     env:
       GPG_KEY_SET: \${{ secrets.SUPER_LINTER_GPG_PRIVATE_KEY != '' }}
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         name: Checkout repository
         with:
           fetch-depth: 0
@@ -1004,7 +1023,7 @@ jobs:
       - uses: theholocron/.github/.github/actions/setup@main
         name: Setup
 
-      - uses: super-linter/super-linter/slim@b92721f792f381cedc002ecdbb9847a15ece5bb8 # v7.1.0
+      - uses: super-linter/super-linter/slim@4ce20838b8ab83717e78138c5b3a1407148e0918 # v8.7.0
         name: Run Super Linter
         env:
           GITHUB_TOKEN: \${{ github.token }}
@@ -1039,7 +1058,7 @@ jobs:
           VALIDATE_YAML: true
           YAML_CONFIG_FILE: \${{ inputs.yaml-config }}
 
-      - uses: crazy-max/ghaction-import-gpg@e89d40939c28e39f97cf32126055eeae86ba74ec # v6
+      - uses: crazy-max/ghaction-import-gpg@2dc316deee8e90f13e1a351ab510b4d5bc0c82cd # v7.0.0
         name: Import GPG Key
         # Conditions mirror auto-commit exactly — no point importing GPG if the
         # commit step will be skipped (fork PR, default branch, or secret unset).
@@ -1055,7 +1074,7 @@ jobs:
           GPG_PRIVATE_KEY: \${{ secrets.SUPER_LINTER_GPG_PRIVATE_KEY }}
           PASSPHRASE: \${{ secrets.SUPER_LINTER_GPG_PASSPHRASE }}
 
-      - uses: stefanzweifel/git-auto-commit-action@b863ae1933cb653a53c021fe36dbb774e1fb9403 # v5
+      - uses: stefanzweifel/git-auto-commit-action@4a55954c782fc1ea30b9056cd3e7a2b40ca8887d # v7.2.0
         name: Commit and push linting fixes
         if: >
           inputs.enable-auto-commit == true &&
@@ -1108,7 +1127,7 @@ jobs:
       group: release-\${{ github.ref }}
       cancel-in-progress: false
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         name: Checkout repository
         with:
           fetch-depth: 0
@@ -1180,7 +1199,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Setup
         if: \${{ hashFiles('pnpm-lock.yaml') != '' }}
@@ -1283,7 +1302,7 @@ jobs:
 
       - name: dotenv-linter
         if: steps.detect.outputs.dotenv == 'true'
-        uses: dotenv-linter/action-dotenv-linter@21287e2624aaf2dc8da5dd8ccfe8e49c63501116 # v2
+        uses: dotenv-linter/action-dotenv-linter@afde61cfda2ecffe7bea35837b6f20b956c88689 # v3.0.0
         with:
           reporter: github-code-suggestions
 
@@ -1324,7 +1343,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/stale@5bef64f19d7facfb25b37b414482c7164d639639 # v9
+      - uses: actions/stale@1e223db275d687790206a7acac4d1a11bd6fe629 # v10.4.0
         name: Run Stale
         with:
           close-issue-message: >
@@ -1361,7 +1380,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         name: Checkout repository
         with:
           fetch-depth: 0
@@ -1372,8 +1391,14 @@ jobs:
       - run: pnpm test -- --coverage
         name: Run tests with coverage
 
-      - uses: codecov/codecov-action@b9fd7d16f6d7d1b5d2bec1a2887e65ceed900238 # v4
-        name: Upload results to Codecov
+      - uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        name: Upload coverage to Codecov
+        with:
+          token: \${{ secrets.CODECOV_TOKEN }}
+
+      - uses: codecov/test-results-action@0fa95f0e1eeaafde2c782583b36b28ad0d8c77d3 # v1
+        name: Upload test results to Codecov
+        if: \${{ !cancelled() }}
         with:
           token: \${{ secrets.CODECOV_TOKEN }}
 `,
@@ -1424,7 +1449,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         name: Checkout repository
 
       - uses: theholocron/.github/.github/actions/setup@main
@@ -1485,7 +1510,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         name: Checkout repository
 
       - uses: theholocron/.github/.github/actions/setup@main
@@ -3857,15 +3882,13 @@ function formatStep(step) {
 /**
 * `holocron.config.{json,js,ts}` file loader.
 *
-* v2.0 only documents the JSON form, but the loader looks up all three
-* extensions in priority order (json → js → ts) — that's the schema
-* commitment captured in [`.notes/tech-architecture.spec.md` → Roadmap
-* → Shareable configs] so the JS/TS preset story (issue #75) can land
-* later without a breaking change.
+* 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.
 *
-* The JS/TS forms aren't actually parsed today; they trigger a clear
-* error telling the operator to use JSON for v2.0. The contract is the
-* lookup order, not the interpretation.
+* All three forms are validated through the same `resolveConfig` path.
+* Implements the lookup-order contract from issue #75 / #81.
 */
 const CANDIDATE_FILENAMES = [
 	"holocron.config.json",
@@ -3878,7 +3901,7 @@ var ConfigFileError = class extends Error {
 /**
 * Read + parse + resolve `holocron.config.*` from the given directory.
 * Search order: json → js → ts. Throws `ConfigFileError` if nothing
-* found, or `ConfigError` if the JSON is malformed / invalid.
+* found, or `ConfigError` if the config is malformed / invalid.
 */
 async function loadConfig(cwd) {
 	for (const filename of CANDIDATE_FILENAMES) {
@@ -3888,7 +3911,14 @@ async function loadConfig(cwd) {
 				resolved: await loadJson(fullPath),
 				filepath: fullPath
 			};
-			throw new ConfigFileError(`${filename} found, but v2.0 only supports the JSON form. Rename to holocron.config.json. The JS/TS form lands with the preset feature (see issue #75).`);
+			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.`);
@@ -3903,6 +3933,19 @@ async function loadJson(filepath) {
 	}
 	return resolveConfig(parsed);
 }
+async function loadJs(filepath) {
+	return extractAndResolve(filepath, await import(pathToFileURL(filepath).href));
+}
+async function loadTs(filepath) {
+	const { tsImport } = await import("tsx/esm/api");
+	const outer = await tsImport(pathToFileURL(filepath).href, import.meta.url);
+	return extractAndResolve(filepath, outer.default ?? outer);
+}
+function extractAndResolve(filepath, mod) {
+	const raw = mod.default;
+	if (raw === void 0 || raw === null) throw new ConfigFileError(`${filepath} must have a default export (use \`export default defineConfig({…})\`)`);
+	return resolveConfig(raw);
+}
 async function fileExists(path) {
 	try {
 		return (await stat(path)).isFile();

package/dist/index.d.mts

@@ -2,6 +2,23 @@ import { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentit
 
 //#region src/config.d.ts
 type ProviderOptions = Record<string, unknown>;
+/**
+ * The shape a capability config package's default export must satisfy.
+ * Config packages let teams share a pre-bundled provider + options across
+ * repos (Level 1 of the shareable-configs story, issue #75).
+ *
+ * @example
+ * // @acme/holocron-vault/index.ts
+ * import type { CapabilityConfigPackage } from '@theholocron/cli'
+ * export default {
+ *   provider: '1password',
+ *   options: { vault: 'acme-app' },
+ * } satisfies CapabilityConfigPackage
+ */
+interface CapabilityConfigPackage {
+  provider: string;
+  options?: ProviderOptions;
+}
 type SingleEntry = string | [provider: string, options: ProviderOptions];
 type MultiEntry = Array<string | [provider: string, options: ProviderOptions]>;
 type RawProviderEntry = SingleEntry | MultiEntry;
@@ -103,6 +120,9 @@ declare function resolvePluginPackage(provider: string): string;
 declare function resolveEntry(key: CapabilityKey, raw: RawProviderEntry): ResolvedProviderEntry;
 declare function resolveConfig(raw: HolocronConfig): ResolvedHolocronConfig;
 //#endregion
+//#region src/define-config.d.ts
+declare function defineConfig(config: HolocronConfig): HolocronConfig;
+//#endregion
 //#region src/keyring.d.ts
 /**
  * Keyring-backed bootstrap credential store.
@@ -147,4 +167,20 @@ declare function deleteToken(provider: string): boolean;
  */
 declare function listStoredProviders(): string[];
 //#endregion
-export { Analytics, AppConfig, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConfigError, ConnectionStringOptions, CreateAuthUserInput, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordType, DoctorConfig, EnsureResult, Environment, EnvironmentReviewer, Environments, HolocronConfig, Issue, IssueSearchFilter, Issues, LifecycleResult, LifecycleSlot, MultiEntry, NormalizedAuthUser, Notifications, Observability, ParseWebhookInput, ProviderApiError, ProviderIdentity, ProviderOptions, REQUIRED_CAPABILITIES, RawProviderEntry, RawProvidersConfig, RepoPolicyConfig, RepoRef, RepoSettings, ResolvedCapability, ResolvedHolocronConfig, ResolvedProviderEntry, ResolvedProvidersConfig, ResolvedTuple, Ruleset, SecretScope, Secrets, SingleEntry, Source, StatusCategory, Storage, StorageBranch, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, deleteToken, getToken, isMulti, listStoredProviders, resolveConfig, resolveEntry, resolvePluginPackage, setToken };
+//#region src/load-config.d.ts
+declare class ConfigFileError extends Error {
+  name: string;
+}
+interface LoadedConfig {
+  resolved: ResolvedHolocronConfig;
+  /** Absolute path to the file the config was read from. */
+  filepath: string;
+}
+/**
+ * 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.
+ */
+declare function loadConfig(cwd: string): Promise<LoadedConfig>;
+//#endregion
+export { Analytics, AppConfig, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityConfigPackage, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConfigError, ConfigFileError, ConnectionStringOptions, CreateAuthUserInput, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordType, DoctorConfig, EnsureResult, Environment, EnvironmentReviewer, Environments, HolocronConfig, Issue, IssueSearchFilter, Issues, LifecycleResult, LifecycleSlot, LoadedConfig, MultiEntry, NormalizedAuthUser, Notifications, Observability, ParseWebhookInput, ProviderApiError, ProviderIdentity, ProviderOptions, REQUIRED_CAPABILITIES, RawProviderEntry, RawProvidersConfig, RepoPolicyConfig, RepoRef, RepoSettings, ResolvedCapability, ResolvedHolocronConfig, ResolvedProviderEntry, ResolvedProvidersConfig, ResolvedTuple, Ruleset, SecretScope, Secrets, SingleEntry, Source, StatusCategory, Storage, StorageBranch, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, defineConfig, deleteToken, getToken, isMulti, listStoredProviders, loadConfig, resolveConfig, resolveEntry, resolvePluginPackage, setToken };

package/dist/index.mjs

@@ -1,5 +1,8 @@
 import { CARDINALITY, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, isMulti } from "./capabilities/index.mjs";
 import { Entry, findCredentials } from "@napi-rs/keyring";
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
 //#region src/config.ts
 /**
 * `holocron.config.json` schema, parser, and provider resolution.
@@ -111,6 +114,11 @@ function resolveConfig(raw) {
 	};
 }
 //#endregion
+//#region src/define-config.ts
+function defineConfig(config) {
+	return config;
+}
+//#endregion
 //#region src/keyring.ts
 /**
 * Keyring-backed bootstrap credential store.
@@ -181,4 +189,80 @@ function listStoredProviders() {
 	}
 }
 //#endregion
-export { CARDINALITY, ConfigError, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, deleteToken, getToken, isMulti, listStoredProviders, resolveConfig, resolveEntry, resolvePluginPackage, setToken };
+//#region src/load-config.ts
+/**
+* `holocron.config.{json,js,ts}` file 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.
+*
+* All three forms are validated through the same `resolveConfig` path.
+* Implements the lookup-order contract from issue #75 / #81.
+*/
+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.
+*/
+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(parsed);
+}
+async function loadJs(filepath) {
+	return extractAndResolve(filepath, await import(pathToFileURL(filepath).href));
+}
+async function loadTs(filepath) {
+	const { tsImport } = await import("tsx/esm/api");
+	const outer = await tsImport(pathToFileURL(filepath).href, import.meta.url);
+	return extractAndResolve(filepath, outer.default ?? outer);
+}
+function extractAndResolve(filepath, mod) {
+	const raw = mod.default;
+	if (raw === void 0 || raw === null) throw new ConfigFileError(`${filepath} must have a default export (use \`export default defineConfig({…})\`)`);
+	return resolveConfig(raw);
+}
+async function fileExists(path) {
+	try {
+		return (await stat(path)).isFile();
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { CARDINALITY, ConfigError, ConfigFileError, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, defineConfig, deleteToken, getToken, isMulti, listStoredProviders, loadConfig, resolveConfig, resolveEntry, resolvePluginPackage, setToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/cli",
-  "version": "2.0.0-alpha.18",
+  "version": "2.0.0-alpha.19",
   "description": "The Holocron CLI — a pluggable, capability-based orchestrator for spinning up and operating software projects.",
   "homepage": "https://github.com/theholocron/holocron/tree/main/packages/cli#readme",
   "bugs": "https://github.com/theholocron/holocron/issues",
@@ -34,16 +34,19 @@
   ],
   "dependencies": {
     "@napi-rs/keyring": "^1.3.0",
+    "tsx": "^4.22.4",
     "yargs": "^18.0.0"
   },
   "devDependencies": {
-    "@theholocron/eslint-config": "^4.1.0",
+    "@theholocron/eslint-config": "^5.1.1",
     "@theholocron/tsconfig": "^4.1.0",
     "@tsconfig/node-lts": "^24.0.0",
     "@types/yargs": "^17.0.35",
     "@vitest/coverage-v8": "^3.2.6",
-    "eslint": "^9.36.0",
-    "globals": "^16.5.0",
+    "@vitest/eslint-plugin": "^1.6.23",
+    "eslint": "^10.7.0",
+    "eslint-plugin-n": "^18.2.2",
+    "globals": "^17.7.0",
     "tsdown": "^0.22.3",
     "typescript": "^5.9.3",
     "vitest": "^3.2.6",