@wolfstar/schema 0.2.0

package/dist/esm/config.js

@@ -0,0 +1,21 @@
+//#region src/config.ts
+/**
+* Typed helper for `stars.config.{ts,mts,cts,js,mjs,cjs}` files.
+*
+* @example
+* ```ts
+* import { defineConfig } from '@wolfstar/http-framework/config';
+*
+* export default defineConfig({
+* 	entry: 'src/main.ts',
+* 	build: { tool: 'tsdown' }
+* });
+* ```
+*/
+function defineConfig(config) {
+	return config;
+}
+
+//#endregion
+export { defineConfig };
+//# sourceMappingURL=config.js.map

package/dist/esm/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","names":[],"sources":["../../src/config.ts"],"sourcesContent":["import type { StarsConfig } from './types/config.js';\n\nexport type * from './types/config.js';\n\n/**\n * Typed helper for `stars.config.{ts,mts,cts,js,mjs,cjs}` files.\n *\n * @example\n * ```ts\n * import { defineConfig } from '@wolfstar/http-framework/config';\n *\n * export default defineConfig({\n * \tentry: 'src/main.ts',\n * \tbuild: { tool: 'tsdown' }\n * });\n * ```\n */\nexport function defineConfig(config: StarsConfig): StarsConfig {\n\treturn config;\n}\n"],"mappings":";;;;;;;;;;;;;;AAiBA,SAAgB,aAAa,QAAkC;CAC9D,OAAO;AACR"}

package/dist/esm/index.d.ts

@@ -0,0 +1,472 @@
+import { StarsBuildConfig, StarsBuildTool, StarsCodegenConfig, StarsCompatibilityVersion, StarsConfig, StarsDevConfig, StarsExperimentalConfig, StarsFutureConfig, StarsI18nCodegenConfig, StarsImportsConfig, StarsNitroConfig, StarsTsdownConfig, StarsTunnelConfig, StarsTypecheckConfig, StarsTypechecker, StarsViteConfig, defineConfig } from "./config.js";
+import { EventEmitter } from "node:events";
+//#region src/config/resolve.d.ts
+interface PackageJsonLike {
+  name?: string;
+  /** `tsdown` reads its options from here as well as from a `tsdown.config.*`. */
+  tsdown?: unknown;
+  version?: string;
+  main?: string;
+  type?: string;
+  scripts?: Record<string, string>;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}
+interface ResolvedBuildConfig {
+  readonly tool: StarsBuildTool;
+  /** Absolute output directory. */
+  readonly outDir: string;
+  /** Absolute `tsconfig.json` used by `tsc`, `null` for the other tools. */
+  readonly tsconfig: string | null;
+  /** Absolute path of the file `node` runs, i.e. the built entry (or the entry itself when `tool` is `none`). */
+  readonly output: string;
+  /**
+   * Absolute path of the build tool's own configuration file (`tsdown.config.*`, `vite.config.*`), `null` when the
+   * tool has none — which is always the case for `tsdown` with `future.compatibilityVersion` 4, where the build is
+   * configured from `stars.config` alone.
+   */
+  readonly configFile: string | null;
+}
+interface ResolvedTypecheckConfig {
+  readonly enabled: boolean;
+  /** Absolute `tsconfig.json` the type checker runs against, `null` when it could not be found. */
+  readonly tsconfig: string | null;
+  /** The type checker to run, with `'auto'` already resolved. */
+  readonly checker: StarsTypechecker;
+}
+type ResolvedTunnelConfig = {
+  readonly mode: 'off';
+} |
+/** A `cloudflared` quick tunnel, whose hostname is only known once it is up. */
+{
+  readonly mode: 'quick';
+  readonly path: string;
+  readonly updateEndpoint: boolean;
+} |
+/** An https URL the user already serves. */
+{
+  readonly mode: 'url';
+  readonly url: string;
+  readonly path: string;
+  readonly updateEndpoint: boolean;
+};
+interface ResolvedDevConfig {
+  readonly banner: readonly string[] | false | null;
+  readonly watch: readonly string[];
+  readonly ignore: readonly string[];
+  readonly debounce: number;
+  readonly env: Readonly<Record<string, string>>;
+  readonly nodeArgs: readonly string[];
+  readonly args: readonly string[];
+  readonly url: string | null;
+  readonly health: string | null;
+  readonly killTimeout: number;
+  readonly typecheck: ResolvedTypecheckConfig;
+  readonly tunnel: ResolvedTunnelConfig;
+  /** Absolute path of the file the dev session's logs are mirrored into, `null` when disabled. */
+  readonly logFile: string | null;
+}
+interface ResolvedNitroConfig {
+  readonly [option: string]: unknown;
+  readonly preset: string;
+}
+interface ResolvedExperimentalConfig {
+  readonly enableVite: boolean;
+  readonly enableExternalVite: boolean;
+  readonly enableNitro: boolean;
+  readonly nitro: ResolvedNitroConfig;
+}
+interface ResolvedFutureConfig {
+  readonly compatibilityVersion: StarsCompatibilityVersion;
+}
+interface ResolvedImportsConfig {
+  readonly enabled: boolean;
+  /** Directory glob patterns, relative to the project root (the way `unimport` scans them). */
+  readonly dirs: readonly string[];
+  readonly presets: readonly string[];
+  readonly exclude: readonly string[];
+  /** Absolute path of the generated declaration file. */
+  readonly dts: string;
+}
+interface ResolvedI18nCodegenConfig {
+  readonly locales: string;
+  readonly output: string;
+}
+interface ResolvedCodegenConfig {
+  readonly i18n: ResolvedI18nCodegenConfig | null;
+}
+interface ResolvedStarsConfig {
+  /** Absolute path of the configuration file, `null` when running on defaults. */
+  readonly configFile: string | null;
+  /** The directory the CLI was invoked from. */
+  readonly cwd: string;
+  /** Absolute project root. */
+  readonly root: string;
+  readonly packageJson: PackageJsonLike | null;
+  /** Absolute source entry. */
+  readonly entry: string;
+  readonly build: ResolvedBuildConfig;
+  readonly dev: ResolvedDevConfig;
+  readonly codegen: ResolvedCodegenConfig;
+  readonly imports: ResolvedImportsConfig;
+  readonly experimental: ResolvedExperimentalConfig;
+  readonly future: ResolvedFutureConfig;
+  /** Raw options merged into `vite.config.*`. */
+  readonly vite: Readonly<Record<string, unknown>>;
+  /** The `tsdown` build's options: merged over `tsdown.config.*` at compatibility version 3, the whole build at 4. */
+  readonly tsdown: Readonly<Record<string, unknown>>;
+}
+interface ResolveConfigOptions {
+  cwd: string;
+  configFile: string | null;
+  config: StarsConfig;
+  env?: NodeJS.ProcessEnv;
+}
+/**
+ * Applies defaults, validates every option and resolves all paths to absolute ones.
+ *
+ * @throws {Diagnostic} (from `nostics`, via {@link configDiagnostics}) with an actionable `fix` on the first invalid option.
+ */
+export declare function resolveStarsConfig(options: ResolveConfigOptions): ResolvedStarsConfig;
+/**
+ * Presents an absolute path relative to `root` when possible, for display purposes.
+ */
+export declare function displayPath(root: string, path: string): string;
+/**
+ * Reads the project's environment layers from `src/.env*` and `.env*` into a plain object, the way `stars dev` and
+ * `stars commands` need it:
+ * these files are only loaded into `process.env` by the bot itself once it starts (see `@wolfstar/env-utilities`),
+ * so by the time the CLI runs they are not there yet. This is a minimal line reader, not a full dotenv
+ * implementation — quoting is stripped, but expansion (`dotenv-expand`) is not. Earlier files win, matching
+ * dotenv's own precedence.
+ */
+export declare function readProjectEnvFiles(root: string, environment?: string): Record<string, string>;
+//#endregion
+//#region src/config/load.d.ts
+export declare const CONFIG_EXTENSIONS: readonly ['ts', 'mts', 'cts', 'js', 'mjs', 'cjs'];
+export declare const CONFIG_FILE_NAMES: string[];
+interface LoadConfigFileOptions {
+  /** The directory to discover the configuration file from. */
+  cwd: string;
+  /** An explicit configuration file (`--config`), resolved from `cwd`. */
+  configFile?: string | null;
+}
+interface LoadedConfigFile {
+  /** The absolute path of the loaded file, `null` when running on defaults. */
+  configFile: string | null;
+  config: StarsConfig;
+}
+/**
+ * Finds the first `stars.config.*` file in `cwd`, in {@link CONFIG_FILE_NAMES} order.
+ */
+export declare function discoverConfigFile(cwd: string): string | null;
+/**
+ * Loads the raw configuration object. The loader (`c12`) is imported lazily so
+ * commands that never touch the configuration stay fast.
+ */
+export declare function loadConfigFile(options: LoadConfigFileOptions): Promise<LoadedConfigFile>;
+//#endregion
+//#region src/config/errors.d.ts
+/**
+ * Structured, stable diagnostic codes for every way a `stars.config.*` can fail to load or validate.
+ *
+ * This is a plain data error (no exit code or terminal formatting), so nothing here reports anywhere on its own —
+ * `reporters` stays empty and each call only builds and returns a `Diagnostic`. That keeps it meaningful outside a
+ * CLI, e.g. for a dashboard or test that calls {@link loadStarsConfig} directly; `@wolfstar/cli` is what renders it
+ * and picks an exit code (`exitCodeOf`).
+ *
+ * The `sources` field (populated with the configuration file, when there is one) carries the "which file" grounding
+ * `ConfigError` used to expose as `.file`; the "which option" grounding it exposed as `.path` is folded directly into
+ * every `why`/`fix` message instead, the way every other diagnostic code already reads.
+ *
+ * `why` and `fix` are always given the same, fully-typed params object (even when one of them ignores part of it):
+ * a bare `() => value` loses nostics' param-type inference (a zero-arg function widens to `unknown` params), so every
+ * entry here spells out its shape on both sides instead.
+ */
+export declare const configDiagnostics: import("nostics").Diagnostics<{
+  readonly ROOT_NOT_FOUND: {
+    why: (p: {
+      root: string;
+    }) => string;
+    fix: (_p: {
+      root: string;
+    }) => string;
+  };
+  readonly PACKAGE_JSON_INVALID: {
+    why: (p: {
+      file: string;
+      message: string;
+    }) => string;
+    fix: (_p: {
+      file: string;
+      message: string;
+    }) => string;
+  };
+  readonly ENTRY_NOT_FOUND: {
+    why: (p: {
+      entry: string;
+    }) => string;
+    fix: (_p: {
+      entry: string;
+    }) => string;
+  };
+  readonly ENTRY_DEFAULT_NOT_FOUND: {
+    why: (p: {
+      root: string;
+      defaults: string;
+    }) => string;
+    fix: (p: {
+      root: string;
+      defaults: string;
+    }) => string;
+  };
+  readonly INVALID_BUILD_TOOL: {
+    why: (p: {
+      tool: string;
+    }) => string;
+    fix: (_p: {
+      tool: string;
+    }) => string;
+  };
+  readonly EXPERIMENTAL_BUILD_TOOL: {
+    why: (p: {
+      tool: string;
+      flag: string;
+    }) => string;
+    fix: (p: {
+      tool: string;
+      flag: string;
+    }) => string;
+  };
+  readonly BUILD_TOOL_REQUIRED: {
+    why: (p: {
+      entry: string;
+    }) => string;
+    fix: (_p: {
+      entry: string;
+    }) => string;
+  };
+  readonly TSCONFIG_EXPLICIT_NOT_FOUND: {
+    why: (p: {
+      tsconfig: string;
+      path: string;
+    }) => string;
+    fix: (p: {
+      tsconfig: string;
+      path: string;
+    }) => string;
+  };
+  readonly TSCONFIG_NOT_FOUND: {
+    why: (p: {
+      root: string;
+      suggestion: string;
+    }) => string;
+    fix: (p: {
+      root: string;
+      suggestion: string;
+    }) => string;
+  };
+  readonly TSDOWN_OPTIONS_REQUIRE_TSDOWN: {
+    why: (_p: {
+      tool: string;
+    }) => string;
+    fix: (p: {
+      tool: string;
+    }) => string;
+  };
+  readonly VITE_OPTIONS_REQUIRE_VITE: {
+    why: (_p: {
+      tool: string;
+    }) => string;
+    fix: (p: {
+      tool: string;
+    }) => string;
+  };
+  readonly TSDOWN_CONFIG_FILE_UNSUPPORTED: {
+    why: (p: {
+      file: string;
+      version: number;
+      legacyVersion: number;
+    }) => string;
+    fix: (p: {
+      file: string;
+      version: number;
+      legacyVersion: number;
+    }) => string;
+  };
+  readonly INVALID_TYPE: {
+    why: (p: {
+      path: string;
+      expected: string;
+      value: unknown;
+      fix: string;
+    }) => string;
+    fix: (p: {
+      path: string;
+      expected: string;
+      value: unknown;
+      fix: string;
+    }) => string;
+  };
+  readonly INVALID_COMPATIBILITY_VERSION: {
+    why: (p: {
+      value: unknown;
+      legacyVersion: number;
+      latestVersion: number;
+    }) => string;
+    fix: (p: {
+      value: unknown;
+      legacyVersion: number;
+      latestVersion: number;
+    }) => string;
+  };
+  readonly UNKNOWN_OPTION: {
+    why: (p: {
+      path: string;
+      parent: string;
+      known: string;
+    }) => string;
+    fix: (p: {
+      path: string;
+      parent: string;
+      known: string;
+    }) => string;
+  };
+  readonly EXPERIMENT_REQUIRED: {
+    why: (p: {
+      path: string;
+      requires: string;
+      drop: string;
+    }) => string;
+    fix: (p: {
+      path: string;
+      requires: string;
+      drop: string;
+    }) => string;
+  };
+  readonly IMPORTS_REQUIRE_TSDOWN: {
+    why: (_p: {}) => string;
+    fix: (_p: {}) => string;
+  };
+  readonly LOCALES_NOT_FOUND: {
+    why: (p: {
+      locales: string;
+    }) => string;
+    fix: (_p: {
+      locales: string;
+    }) => string;
+  };
+  readonly INVALID_URL: {
+    why: (p: {
+      url: string;
+      fix: string;
+    }) => string;
+    fix: (p: {
+      url: string;
+      fix: string;
+    }) => string;
+  };
+  readonly TUNNEL_URL_NOT_HTTPS: {
+    why: (p: {
+      url: string;
+    }) => string;
+    fix: (_p: {
+      url: string;
+    }) => string;
+  };
+  readonly INVALID_TYPECHECKER: {
+    why: (p: {
+      checker: string;
+    }) => string;
+    fix: (_p: {
+      checker: string;
+    }) => string;
+  };
+  readonly CONFIG_NOT_FOUND: {
+    why: (p: {
+      file: string;
+      cwd: string;
+      names: string;
+    }) => string;
+    fix: (p: {
+      file: string;
+      cwd: string;
+      names: string;
+    }) => string;
+  };
+  readonly CONFIG_LOAD_FAILED: {
+    why: (p: {
+      message: string;
+    }) => string;
+    fix: (_p: {
+      message: string;
+    }) => string;
+  };
+  readonly CONFIG_NOT_OBJECT: {
+    why: (_p: {}) => string;
+    fix: (_p: {}) => string;
+  };
+}, readonly []>;
+type ConfigDiagnosticCode = keyof typeof configDiagnostics;
+//#endregion
+//#region src/config/index.d.ts
+export interface LoadStarsConfigOptions {
+  /**
+   * The directory to discover `stars.config.*` from.
+   * @default process.cwd()
+   */
+  cwd?: string;
+  /** An explicit configuration file, resolved from `cwd`. */
+  configFile?: string | null;
+  /**
+   * Environment used for defaults such as `HTTP_PORT`.
+   * @default process.env
+   */
+  env?: NodeJS.ProcessEnv;
+}
+/**
+ * Loads, validates and resolves a project's `stars.config.*`.
+ *
+ * @throws {Diagnostic} (from `nostics`, via {@link configDiagnostics}) when the configuration file cannot be loaded or contains an invalid option.
+ */
+export declare function loadStarsConfig(options?: LoadStarsConfigOptions): Promise<ResolvedStarsConfig>;
+//#endregion
+//#region src/types/builder.d.ts
+type BuilderLogLevel = 'debug' | 'info' | 'success' | 'warn' | 'error';
+interface BuildOutcome {
+  ok: boolean;
+  durationMs: number;
+  /** A one-line summary, e.g. the first error. */
+  message: string | null;
+}
+interface BuilderEvents {
+  start: [];
+  /** Coarse, real lifecycle milestones, not an estimate of compiler work remaining. */
+  progress: [fraction: number, message: string];
+  success: [outcome: BuildOutcome];
+  failure: [outcome: BuildOutcome];
+  log: [level: BuilderLogLevel, text: string];
+}
+/**
+ * Turns project sources into the runnable output, once or continuously.
+ * Implementations report progress through {@link BuilderEvents}.
+ */
+interface Builder extends EventEmitter<BuilderEvents> {
+  readonly tool: StarsBuildTool;
+  /** Runs a single build. Compilation failures are reported in the outcome; dependency loading may throw. */
+  build(): Promise<BuildOutcome>;
+  /** Starts watching. Resolves once the watcher is set up; builds are reported through events. */
+  watch(): Promise<void>;
+  /** Stops watching. */
+  close(): Promise<void>;
+}
+/** Services supplied by the host; server integrations never import the CLI. */
+interface BuilderContext {
+  /** Resolve build dependencies from the consuming project and report missing dependencies. */
+  importFromProject<T>(root: string, id: string, hint: string): Promise<T>;
+  /** Create the host's entry transformation for installed plugin registrations. */
+  pluginRegistrations(config: ResolvedStarsConfig): object;
+}
+//#endregion
+export { type BuildOutcome, type Builder, type BuilderContext, type BuilderEvents, type BuilderLogLevel, type ConfigDiagnosticCode, type LoadConfigFileOptions, type LoadedConfigFile, type PackageJsonLike, type ResolveConfigOptions, type ResolvedBuildConfig, type ResolvedCodegenConfig, type ResolvedDevConfig, type ResolvedExperimentalConfig, type ResolvedFutureConfig, type ResolvedI18nCodegenConfig, type ResolvedImportsConfig, type ResolvedNitroConfig, type ResolvedStarsConfig, type ResolvedTunnelConfig, type ResolvedTypecheckConfig, type StarsBuildConfig, type StarsBuildTool, type StarsCodegenConfig, type StarsCompatibilityVersion, type StarsConfig, type StarsDevConfig, type StarsExperimentalConfig, type StarsFutureConfig, type StarsI18nCodegenConfig, type StarsImportsConfig, type StarsNitroConfig, type StarsTsdownConfig, type StarsTunnelConfig, type StarsTypecheckConfig, type StarsTypechecker, type StarsViteConfig, defineConfig };
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/config/resolve.ts","../../src/config/load.ts","../../src/config/errors.ts","../../src/config/index.ts","../../src/types/builder.ts"],"mappings":"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"}