@mudah-cli/core 0.1.0

package/dist/application.d.ts

@@ -0,0 +1,80 @@
+import { ConfigRepository } from '@mudah-cli/config';
+import { Container, type Abstract, type Constructor } from '@mudah-cli/container';
+import { EventBus } from './events.js';
+import { type MudahManifest } from './manifest.js';
+import { ServiceProvider } from './service-provider.js';
+export type ProviderClass = new (app: Application) => ServiceProvider;
+export interface LazyProviderOptions {
+    /** Boot this provider when one of these commands is invoked. */
+    commands?: string[];
+    /** Boot this provider when one of these bindings is resolved. */
+    bindings?: readonly Abstract[];
+    /** Boot this provider when the predicate returns true (checked on demand). */
+    bootWhen?: (app: Application) => boolean;
+}
+/** A command module: a module whose default export is a command class. */
+export interface CommandModule {
+    default: CommandClass;
+}
+export type CommandClass = Constructor<CommandShape>;
+export interface CommandShape {
+    signature?: string;
+    description?: string;
+    handle: (...args: unknown[]) => unknown;
+}
+/** True when the value is a class with a `handle` prototype method. */
+export declare function isCommandExport(value: unknown): value is CommandClass;
+/**
+ * The Mudah application kernel.
+ *
+ * An IoC container with a service-provider boot lifecycle:
+ * two-phase provider boot (register → boot), lazy providers keyed on
+ * commands/bindings, and auto-discovery of `src/providers` and `src/commands`.
+ */
+export declare class Application extends Container {
+    readonly basePath: string;
+    readonly manifest: MudahManifest;
+    private readonly providers;
+    private readonly lazyProviders;
+    private readonly bootedLazy;
+    private booted;
+    constructor(basePath?: string, manifest?: MudahManifest);
+    config(): ConfigRepository;
+    events(): EventBus;
+    /** Register a provider that always boots. */
+    register(provider: ProviderClass): this;
+    /**
+     * Register a provider that boots lazily — only when a matching command is
+     * invoked, a matching binding is resolved, or `bootWhen` returns true.
+     */
+    registerLazy(provider: ProviderClass, options?: LazyProviderOptions): this;
+    /**
+     * Boot all registered providers in two phases, each in registration order:
+     * 1. `register()` — container bindings
+     * 2. `boot()` — everything else
+     *
+     * Set `MUDAH_BOOT_PROFILE=1` to print per-hook timings on stderr.
+     */
+    boot(): Promise<void>;
+    /** Boot lazy providers that declared an interest in `command`. */
+    bootLazyForCommand(command: string): Promise<void>;
+    /** Boot lazy providers that declared an interest in `abstract`. */
+    bootLazyForBinding(abstract: Abstract): Promise<void>;
+    /** Boot lazy providers whose `bootWhen` predicate currently returns true. */
+    evaluateLazy(): Promise<void>;
+    private bootLazy;
+    /**
+     * Discover and register every `*.provider.{ts,js}` in the given directory
+     * (sorted for determinism). Exports whose name ends in `Provider` win.
+     */
+    discoverProviders(dir?: string): Promise<this>;
+    /**
+     * Discover command modules in the given directory (sorted). A command
+     * module is any file whose default export is a class with `handle`.
+     */
+    discoverCommandModules(dir?: string): Promise<CommandModule[]>;
+    /** Load an app-root-relative (or absolute) file as an ES module. */
+    importModule(path: string): Promise<Record<string, unknown>>;
+    private listFiles;
+    private importFile;
+}

package/dist/application.js

@@ -0,0 +1,180 @@
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ConfigRepository } from '@mudah-cli/config';
+import { Container, isClassLike } from '@mudah-cli/container';
+import { EventBus } from './events.js';
+import { loadManifest } from './manifest.js';
+import { ServiceProvider } from './service-provider.js';
+/** True when the value is a class with a `handle` prototype method. */
+export function isCommandExport(value) {
+    if (typeof value !== 'function' || !isClassLike(value))
+        return false;
+    return typeof value.prototype?.handle === 'function';
+}
+/**
+ * The Mudah application kernel.
+ *
+ * An IoC container with a service-provider boot lifecycle:
+ * two-phase provider boot (register → boot), lazy providers keyed on
+ * commands/bindings, and auto-discovery of `src/providers` and `src/commands`.
+ */
+export class Application extends Container {
+    basePath;
+    manifest;
+    providers = [];
+    lazyProviders = [];
+    bootedLazy = new Set();
+    booted = false;
+    constructor(basePath = process.cwd(), manifest) {
+        super();
+        this.basePath = basePath;
+        this.manifest = manifest ?? loadManifest(basePath);
+        this.singleton('app', () => this);
+        this.singleton('config', () => new ConfigRepository());
+        this.singleton('events', () => new EventBus());
+    }
+    config() {
+        return this.make('config');
+    }
+    events() {
+        return this.make('events');
+    }
+    /** Register a provider that always boots. */
+    register(provider) {
+        this.providers.push(provider);
+        return this;
+    }
+    /**
+     * Register a provider that boots lazily — only when a matching command is
+     * invoked, a matching binding is resolved, or `bootWhen` returns true.
+     */
+    registerLazy(provider, options = {}) {
+        this.lazyProviders.push({ provider, options });
+        return this;
+    }
+    /**
+     * Boot all registered providers in two phases, each in registration order:
+     * 1. `register()` — container bindings
+     * 2. `boot()` — everything else
+     *
+     * Set `MUDAH_BOOT_PROFILE=1` to print per-hook timings on stderr.
+     */
+    async boot() {
+        if (this.booted)
+            return;
+        const profile = process.env['MUDAH_BOOT_PROFILE'] === '1';
+        const timings = [];
+        const started = performance.now();
+        for (const Provider of this.providers) {
+            const provider = new Provider(this);
+            const t0 = profile ? performance.now() : 0;
+            await provider.register?.();
+            if (profile)
+                timings.push(`${Provider.name}.register=${Math.round(performance.now() - t0)}ms`);
+        }
+        for (const Provider of this.providers) {
+            const provider = new Provider(this);
+            const t0 = profile ? performance.now() : 0;
+            await provider.boot?.();
+            if (profile)
+                timings.push(`${Provider.name}.boot=${Math.round(performance.now() - t0)}ms`);
+        }
+        if (profile) {
+            console.error(`[boot-profile] total=${Math.round(performance.now() - started)}ms ${timings.join(' ')}`);
+        }
+        this.booted = true;
+        await this.events().emit('app.booted', { app: this });
+    }
+    /** Boot lazy providers that declared an interest in `command`. */
+    async bootLazyForCommand(command) {
+        for (const entry of this.lazyProviders) {
+            if (this.bootedLazy.has(entry.provider))
+                continue;
+            if (entry.options.commands?.includes(command)) {
+                await this.bootLazy(entry.provider);
+            }
+        }
+    }
+    /** Boot lazy providers that declared an interest in `abstract`. */
+    async bootLazyForBinding(abstract) {
+        for (const entry of this.lazyProviders) {
+            if (this.bootedLazy.has(entry.provider))
+                continue;
+            if (entry.options.bindings?.some((binding) => binding === abstract)) {
+                await this.bootLazy(entry.provider);
+            }
+        }
+    }
+    /** Boot lazy providers whose `bootWhen` predicate currently returns true. */
+    async evaluateLazy() {
+        for (const entry of this.lazyProviders) {
+            if (this.bootedLazy.has(entry.provider))
+                continue;
+            if (entry.options.bootWhen?.(this)) {
+                await this.bootLazy(entry.provider);
+            }
+        }
+    }
+    async bootLazy(provider) {
+        if (this.bootedLazy.has(provider))
+            return;
+        this.bootedLazy.add(provider);
+        const instance = new provider(this);
+        await instance.register?.();
+        await instance.boot?.();
+    }
+    /**
+     * Discover and register every `*.provider.{ts,js}` in the given directory
+     * (sorted for determinism). Exports whose name ends in `Provider` win.
+     */
+    async discoverProviders(dir = join(this.basePath, 'src', 'providers')) {
+        for (const file of await this.listFiles(dir)) {
+            const mod = await this.importFile(file);
+            for (const value of Object.values(mod)) {
+                if (typeof value === 'function' && /Provider$/.test(value.name ?? '')) {
+                    this.register(value);
+                    break;
+                }
+            }
+        }
+        return this;
+    }
+    /**
+     * Discover command modules in the given directory (sorted). A command
+     * module is any file whose default export is a class with `handle`.
+     */
+    async discoverCommandModules(dir = join(this.basePath, 'src', 'commands')) {
+        const modules = [];
+        for (const file of await this.listFiles(dir)) {
+            const mod = await this.importFile(file);
+            if (isCommandExport(mod.default)) {
+                modules.push(mod);
+            }
+        }
+        return modules;
+    }
+    /** Load an app-root-relative (or absolute) file as an ES module. */
+    async importModule(path) {
+        const resolved = path.startsWith('/') ? path : join(this.basePath, path);
+        return this.importFile(resolved);
+    }
+    async listFiles(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        return entries
+            .filter((entry) => entry.isFile() && /\.(ts|mts|js|mjs)$/.test(entry.name))
+            .map((entry) => join(dir, entry.name))
+            .sort();
+    }
+    async importFile(file) {
+        const mod = await import(pathToFileURL(file).href);
+        return mod;
+    }
+}
+//# sourceMappingURL=application.js.map

package/dist/application.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"application.js","sourceRoot":"","sources":["../src/application.ts"],"names":[],"mappings":"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"}

package/dist/events.d.ts

@@ -0,0 +1,33 @@
+import type { Application } from './application.js';
+/** Typed application lifecycle events. */
+export interface AppEvents {
+    'app.booted': {
+        app: Application;
+    };
+    'command.before': {
+        command: string;
+        argv: string[];
+    };
+    'command.after': {
+        command: string;
+        exitCode: number;
+        durationMs: number;
+    };
+    'command.error': {
+        command: string;
+        error: unknown;
+    };
+}
+export type EventHandler<E> = (payload: E) => void | Promise<void>;
+/**
+ * Minimal typed event bus. Listeners run sequentially in registration order
+ * and are awaited, so a listener may do async work (notifications, telemetry).
+ */
+export declare class EventBus {
+    private readonly listeners;
+    /** Subscribe. Returns an unsubscribe function. */
+    on<K extends keyof AppEvents>(event: K, handler: EventHandler<AppEvents[K]>): () => void;
+    off<K extends keyof AppEvents>(event: K, handler: EventHandler<AppEvents[K]>): void;
+    /** Emit to all subscribers, awaiting each in order. */
+    emit<K extends keyof AppEvents>(event: K, payload: AppEvents[K]): Promise<void>;
+}

package/dist/events.js

@@ -0,0 +1,30 @@
+/**
+ * Minimal typed event bus. Listeners run sequentially in registration order
+ * and are awaited, so a listener may do async work (notifications, telemetry).
+ */
+export class EventBus {
+    listeners = new Map();
+    /** Subscribe. Returns an unsubscribe function. */
+    on(event, handler) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(handler);
+        return () => this.off(event, handler);
+    }
+    off(event, handler) {
+        this.listeners.get(event)?.delete(handler);
+    }
+    /** Emit to all subscribers, awaiting each in order. */
+    async emit(event, payload) {
+        const set = this.listeners.get(event);
+        if (!set)
+            return;
+        for (const handler of [...set]) {
+            await handler(payload);
+        }
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,MAAM,OAAO,QAAQ;IACF,SAAS,GAAG,IAAI,GAAG,EAA6C,CAAC;IAElF,kDAAkD;IAClD,EAAE,CAA4B,KAAQ,EAAE,OAAmC;QACzE,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACjC,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,OAA8B,CAAC,CAAC;QACxC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;IAED,GAAG,CAA4B,KAAQ,EAAE,OAAmC;QAC1E,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,OAA8B,CAAC,CAAC;IACpE,CAAC;IAED,uDAAuD;IACvD,KAAK,CAAC,IAAI,CAA4B,KAAQ,EAAE,OAAqB;QACnE,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,CAAC,GAAG;YAAE,OAAO;QACjB,KAAK,MAAM,OAAO,IAAI,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC;YAC/B,MAAO,OAAsC,CAAC,OAAO,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;CACF"}

package/dist/exceptions.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A usage error: bad arguments, missing flags, unknown command.
+ * Rendered with usage + hint, exits with code 2.
+ */
+export declare class UsageError extends Error {
+    readonly hint?: string;
+    readonly usage?: string;
+    constructor(message: string, options?: {
+        hint?: string;
+        usage?: string;
+    });
+}
+/** Explicit exit with a chosen code (optionally with a message). */
+export declare class ExitError extends Error {
+    readonly code: number;
+    constructor(code: number, message?: string);
+}
+/** The user interrupted a prompt (escape, ctrl+c). Exits with 130. */
+export declare class CommandCancelled extends Error {
+    constructor();
+}

package/dist/exceptions.js

@@ -0,0 +1,31 @@
+/**
+ * A usage error: bad arguments, missing flags, unknown command.
+ * Rendered with usage + hint, exits with code 2.
+ */
+export class UsageError extends Error {
+    hint;
+    usage;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = 'UsageError';
+        this.hint = options.hint;
+        this.usage = options.usage;
+    }
+}
+/** Explicit exit with a chosen code (optionally with a message). */
+export class ExitError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ExitError';
+    }
+}
+/** The user interrupted a prompt (escape, ctrl+c). Exits with 130. */
+export class CommandCancelled extends Error {
+    constructor() {
+        super('Command cancelled');
+        this.name = 'CommandCancelled';
+    }
+}
+//# sourceMappingURL=exceptions.js.map

package/dist/exceptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.js","sourceRoot":"","sources":["../src/exceptions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IAC1B,IAAI,CAAU;IACd,KAAK,CAAU;IAExB,YAAY,OAAe,EAAE,OAAO,GAAsC,EAAE;QAC1E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC7B,CAAC;CACF;AAED,oEAAoE;AACpE,MAAM,OAAO,SAAU,SAAQ,KAAK;IAEvB,IAAI;IADf,YACW,IAAY,EACrB,OAAgB;QAEhB,KAAK,CAAC,OAAO,CAAC,CAAC;oBAHN,IAAI;QAIb,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED,sEAAsE;AACtE,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC;QACE,KAAK,CAAC,mBAAmB,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { Application, isCommandExport, type CommandClass, type CommandModule, type CommandShape, type LazyProviderOptions, type ProviderClass, } from './application.js';
+export { EventBus, type AppEvents, type EventHandler } from './events.js';
+export { CommandCancelled, ExitError, UsageError } from './exceptions.js';
+export { loadManifest, MudahManifestError, type MudahManifest, type MudahUiOptions } from './manifest.js';
+export { ServiceProvider } from './service-provider.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { Application, isCommandExport, } from './application.js';
+export { EventBus } from './events.js';
+export { CommandCancelled, ExitError, UsageError } from './exceptions.js';
+export { loadManifest, MudahManifestError } from './manifest.js';
+export { ServiceProvider } from './service-provider.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,eAAe,GAMhB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAqC,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAA2C,MAAM,eAAe,CAAC;AAC1G,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/manifest.d.ts

@@ -0,0 +1,29 @@
+export interface MudahUiOptions {
+    /** Theme name (default `sleek`) or `auto` for dark/light detection. */
+    theme?: string;
+    /** Force reduced-motion rendering regardless of terminal detection. */
+    reducedMotion?: boolean;
+    /** Force color on (or off) regardless of TTY detection. */
+    color?: boolean;
+}
+export interface MudahManifest {
+    /** Application name (shown in help headers and notifications). */
+    name: string;
+    /** Application version (semver). */
+    version: string;
+    /** Binary name (`bin/<name>` in the published package). */
+    bin: string;
+    description?: string;
+    ui?: MudahUiOptions;
+    /** Set false to disable the update nudge. Default true. */
+    updates?: boolean;
+    /** Extra command file paths (relative to the app root) beyond src/commands. */
+    commands?: string[];
+    /** Extra provider file paths (relative to the app root) beyond src/providers. */
+    providers?: string[];
+}
+export declare class MudahManifestError extends Error {
+    constructor(message: string);
+}
+/** Read and validate `mudah.json` from the application root. */
+export declare function loadManifest(basePath: string): MudahManifest;

package/dist/manifest.js

@@ -0,0 +1,49 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export class MudahManifestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MudahManifestError';
+    }
+}
+/** Read and validate `mudah.json` from the application root. */
+export function loadManifest(basePath) {
+    const file = join(basePath, 'mudah.json');
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new MudahManifestError(`No valid manifest at ${file} (${reason}). Scaffold an app with \`npm create @mudah-cli/mudah\` or add a mudah.json with "name", "version", and "bin".`);
+    }
+    if (typeof raw !== 'object' || raw === null) {
+        throw new MudahManifestError('mudah.json must contain a JSON object.');
+    }
+    const data = raw;
+    const rawName = data.name;
+    const rawVersion = data.version;
+    const rawBin = data.bin;
+    if (typeof rawName !== 'string' || rawName.length === 0) {
+        throw new MudahManifestError('mudah.json field "name" must be a non-empty string.');
+    }
+    if (typeof rawVersion !== 'string' || rawVersion.length === 0) {
+        throw new MudahManifestError('mudah.json field "version" must be a non-empty string.');
+    }
+    if (typeof rawBin !== 'string' || rawBin.length === 0) {
+        throw new MudahManifestError('mudah.json field "bin" must be a non-empty string.');
+    }
+    const manifest = { name: rawName, version: rawVersion, bin: rawBin };
+    if (typeof data.description === 'string')
+        manifest.description = data.description;
+    if (typeof data.updates === 'boolean')
+        manifest.updates = data.updates;
+    if (data.ui && typeof data.ui === 'object')
+        manifest.ui = data.ui;
+    if (Array.isArray(data.commands))
+        manifest.commands = data.commands.filter((c) => typeof c === 'string');
+    if (Array.isArray(data.providers))
+        manifest.providers = data.providers.filter((p) => typeof p === 'string');
+    return manifest;
+}
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"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"}

package/dist/service-provider.d.ts

@@ -0,0 +1,23 @@
+import type { Application } from './application.js';
+/**
+ * Base class for Mudah service providers.
+ *
+ * - Override {@link register} to bind services into the container. Runs for
+ *   every provider before any `boot()`.
+ * - Override {@link boot} for work that depends on other providers having
+ *   registered (subscribing events, registering commands, …).
+ *
+ * Both hooks are async-first: use `async register()` when doing I/O — the
+ * kernel always awaits each hook in registration order.
+ */
+export declare abstract class ServiceProvider {
+    protected readonly app: Application;
+    constructor(app: Application);
+    register(): void | Promise<void>;
+    boot(): void | Promise<void>;
+    /**
+     * Import a config file and merge it as defaults under `key`
+     * (existing values win).
+     */
+    protected mergeConfigFrom(path: string, key: string): Promise<void>;
+}

package/dist/service-provider.js

@@ -0,0 +1,32 @@
+import { isAbsolute, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * Base class for Mudah service providers.
+ *
+ * - Override {@link register} to bind services into the container. Runs for
+ *   every provider before any `boot()`.
+ * - Override {@link boot} for work that depends on other providers having
+ *   registered (subscribing events, registering commands, …).
+ *
+ * Both hooks are async-first: use `async register()` when doing I/O — the
+ * kernel always awaits each hook in registration order.
+ */
+export class ServiceProvider {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    register() { }
+    boot() { }
+    /**
+     * Import a config file and merge it as defaults under `key`
+     * (existing values win).
+     */
+    async mergeConfigFrom(path, key) {
+        const resolved = isAbsolute(path) ? path : join(this.app.basePath, path);
+        const mod = await import(pathToFileURL(resolved).href);
+        const defaults = mod.default ?? mod;
+        this.app.config().merge(key, defaults);
+    }
+}
+//# sourceMappingURL=service-provider.js.map

package/dist/service-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-provider.js","sourceRoot":"","sources":["../src/service-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC;;;;;;;;;;GAUG;AACH,MAAM,OAAgB,eAAe;IACJ,GAAG;IAAlC,YAA+B,GAAgB;mBAAhB,GAAG;IAAgB,CAAC;IAEnD,QAAQ,KAA0B,CAAC;IAEnC,IAAI,KAA0B,CAAC;IAE/B;;;OAGG;IACO,KAAK,CAAC,eAAe,CAAC,IAAY,EAAE,GAAW;QACvD,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACzE,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC;QACvD,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC;QACpC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,QAAmC,CAAC,CAAC;IACpE,CAAC;CACF"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@mudah-cli/core",
+  "version": "0.1.0",
+  "description": "Mudah application kernel: service providers, two-phase boot, events, and discovery.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=26"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@mudah-cli/config": "^0.1.0",
+    "@mudah-cli/container": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}