@newcms/core 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,569 @@
+/**
+ * Generic hook callback. Used for both actions and filters.
+ * Actions ignore the return value; filters chain it.
+ */
+type HookCallback = (...args: any[]) => any;
+/**
+ * A registered hook handler with its metadata.
+ */
+interface HookHandler {
+    /** The callback function */
+    callback: HookCallback;
+    /** Execution priority (lower = earlier). Default: 10 */
+    priority: number;
+    /** Number of arguments the callback accepts */
+    acceptedArgs: number;
+    /** Unique identifier for this handler */
+    id: string;
+}
+/**
+ * Represents a hook currently being executed in the stack.
+ */
+interface HookStackEntry {
+    /** The hook name being executed */
+    name: string;
+    /** Current iteration index within the priority groups */
+    currentIndex: number;
+}
+/**
+ * Options for adding a hook.
+ */
+interface AddHookOptions {
+    /** Execution priority. Default: 10 */
+    priority?: number;
+    /** Number of arguments the callback accepts. Default: 1 */
+    acceptedArgs?: number;
+}
+/**
+ * Result of checking if a hook has handlers.
+ * Returns false if no handlers, or the priority of the first matching handler.
+ */
+type HasHookResult = false | number;
+/**
+ * Registered post type definition.
+ */
+interface PostTypeDefinition {
+    name: string;
+    label: string;
+    labels?: Record<string, string>;
+    public?: boolean;
+    hierarchical?: boolean;
+    showInRest?: boolean;
+    restBase?: string;
+    supports?: string[];
+    taxonomies?: string[];
+    hasArchive?: boolean;
+    rewrite?: {
+        slug: string;
+        withFront?: boolean;
+    } | false;
+    menuPosition?: number;
+    menuIcon?: string;
+    capability_type?: string;
+    capabilities?: Record<string, string>;
+}
+/**
+ * Registered taxonomy definition.
+ */
+interface TaxonomyDefinition {
+    name: string;
+    objectTypes: string[];
+    label: string;
+    labels?: Record<string, string>;
+    public?: boolean;
+    hierarchical?: boolean;
+    showInRest?: boolean;
+    restBase?: string;
+    rewrite?: {
+        slug: string;
+        withFront?: boolean;
+        hierarchical?: boolean;
+    } | false;
+}
+/**
+ * User capability check context.
+ */
+interface CapabilityContext {
+    userId: number;
+    capability: string;
+    objectId?: number;
+}
+/**
+ * Standard post statuses.
+ */
+declare const POST_STATUS: {
+    readonly PUBLISH: "publish";
+    readonly DRAFT: "draft";
+    readonly PENDING: "pending";
+    readonly PRIVATE: "private";
+    readonly TRASH: "trash";
+    readonly AUTO_DRAFT: "auto-draft";
+    readonly INHERIT: "inherit";
+    readonly FUTURE: "future";
+};
+/**
+ * Default user roles.
+ */
+declare const USER_ROLES: {
+    readonly ADMINISTRATOR: "administrator";
+    readonly EDITOR: "editor";
+    readonly AUTHOR: "author";
+    readonly CONTRIBUTOR: "contributor";
+    readonly SUBSCRIBER: "subscriber";
+};
+/**
+ * Default hook priorities.
+ */
+declare const HOOK_PRIORITY: {
+    readonly EARLIEST: 1;
+    readonly EARLY: 5;
+    readonly DEFAULT: 10;
+    readonly LATE: 15;
+    readonly LATEST: 20;
+};
+
+/**
+ * HookEngine — the backbone of the CMS extensibility system.
+ *
+ * Implements a WordPress-compatible hook system with actions and filters.
+ * Actions are hooks that perform side effects. Filters are hooks that
+ * transform a value through a pipeline of callbacks.
+ *
+ * Features:
+ * - Priority-based execution (lower number = earlier execution)
+ * - Recursive hook execution support
+ * - Universal "all" hook that fires for every hook
+ * - Execution stack tracking
+ * - Fire counters per hook
+ * - Precise removal by callback + priority
+ */
+declare class HookEngine {
+    /**
+     * Map of hook name → array of handlers, kept sorted by priority.
+     */
+    private hooks;
+    /**
+     * Stack of hooks currently being executed (supports recursion).
+     */
+    private currentStack;
+    /**
+     * Counter of how many times each hook has been fired.
+     */
+    private fireCount;
+    /**
+     * Register a callback for a hook.
+     *
+     * @param hookName - The hook identifier
+     * @param callback - The function to execute
+     * @param options - Priority and accepted args configuration
+     * @returns The generated handler ID
+     */
+    addHook(hookName: string, callback: HookCallback, options?: AddHookOptions): string;
+    /**
+     * Remove a specific callback from a hook.
+     *
+     * Both the callback reference AND priority must match for removal.
+     *
+     * @param hookName - The hook identifier
+     * @param callback - The callback to remove
+     * @param priority - The priority it was registered with (default: 10)
+     * @returns true if a handler was removed
+     */
+    removeHook(hookName: string, callback: HookCallback, priority?: number): boolean;
+    /**
+     * Remove all callbacks from a hook, optionally only for a specific priority.
+     *
+     * @param hookName - The hook identifier
+     * @param priority - If provided, only remove handlers at this priority
+     * @returns true if any handlers were removed
+     */
+    removeAllHooks(hookName: string, priority?: number): boolean;
+    /**
+     * Check if a hook has registered handlers.
+     *
+     * @param hookName - The hook identifier
+     * @param callback - If provided, check for this specific callback
+     * @returns false if no handlers, or the priority of the matching handler
+     */
+    hasHook(hookName: string, callback?: HookCallback): HasHookResult;
+    /**
+     * Execute an action hook. All registered callbacks are called in priority order.
+     * The "all" universal hook fires before the specific hook.
+     *
+     * @param hookName - The hook identifier
+     * @param args - Arguments to pass to callbacks
+     */
+    doAction(hookName: string, ...args: unknown[]): Promise<void>;
+    /**
+     * Execute an action hook synchronously.
+     */
+    doActionSync(hookName: string, ...args: unknown[]): void;
+    /**
+     * Execute a filter hook. The first argument is the value being filtered.
+     * Each callback receives the (possibly modified) value and returns a new value.
+     * The "all" universal hook fires before the specific hook.
+     *
+     * @param hookName - The hook identifier
+     * @param value - The initial value to filter
+     * @param args - Additional arguments passed to each callback
+     * @returns The filtered value after all callbacks have processed it
+     */
+    applyFilters(hookName: string, value: unknown, ...args: unknown[]): Promise<unknown>;
+    /**
+     * Execute a filter hook synchronously.
+     */
+    applyFiltersSync(hookName: string, value: unknown, ...args: unknown[]): unknown;
+    /**
+     * Get how many times a hook has been fired.
+     */
+    getFireCount(hookName: string): number;
+    /**
+     * Check if a specific hook is currently being executed.
+     */
+    isDoingHook(hookName?: string): boolean;
+    /**
+     * Get the name of the hook currently being executed (top of stack).
+     * Returns undefined if no hook is executing.
+     */
+    currentHook(): string | undefined;
+    /**
+     * Get a snapshot of the current execution stack.
+     */
+    getExecutionStack(): readonly HookStackEntry[];
+    /**
+     * Check if a hook has ever been fired (fire count > 0).
+     */
+    didHook(hookName: string): boolean;
+    /**
+     * Get the number of handlers registered for a hook.
+     */
+    getHandlerCount(hookName: string): number;
+    /**
+     * Reset the engine — useful for testing.
+     */
+    reset(): void;
+    addAction(hookName: string, callback: HookCallback, options?: AddHookOptions): string;
+    addFilter(hookName: string, callback: HookCallback, options?: AddHookOptions): string;
+    removeAction(hookName: string, callback: HookCallback, priority?: number): boolean;
+    removeFilter(hookName: string, callback: HookCallback, priority?: number): boolean;
+    hasAction(hookName: string, callback?: HookCallback): HasHookResult;
+    hasFilter(hookName: string, callback?: HookCallback): HasHookResult;
+    didAction(hookName: string): boolean;
+    didFilter(hookName: string): boolean;
+    private incrementFireCount;
+    private fireUniversalHook;
+    private fireUniversalHookSync;
+}
+
+/**
+ * Registry for content types (post types).
+ *
+ * Manages registration and lookup of all content types in the system.
+ * Built-in types (post, page, attachment, revision, nav_menu_item) are
+ * registered during bootstrap; custom types are registered by extensions.
+ */
+declare class PostTypeRegistry {
+    private types;
+    /**
+     * Register a new post type.
+     *
+     * @throws If a type with the same name is already registered
+     */
+    register(definition: PostTypeDefinition): void;
+    /**
+     * Get a post type definition by name.
+     */
+    get(name: string): PostTypeDefinition | undefined;
+    /**
+     * Check if a post type is registered.
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered post types.
+     */
+    getAll(): PostTypeDefinition[];
+    /**
+     * Get only public post types (for REST API, search, etc).
+     */
+    getPublic(): PostTypeDefinition[];
+    /**
+     * Get post types that are exposed via REST API.
+     */
+    getRestVisible(): PostTypeDefinition[];
+    /**
+     * Unregister a post type. Only custom types can be unregistered.
+     */
+    unregister(name: string): boolean;
+    /**
+     * Reset registry — for testing only.
+     */
+    reset(): void;
+}
+/**
+ * Built-in post type definitions, registered during bootstrap.
+ */
+declare const BUILTIN_POST_TYPES: PostTypeDefinition[];
+
+/**
+ * Registry for taxonomies (categories, tags, custom taxonomies).
+ */
+declare class TaxonomyRegistry {
+    private taxonomies;
+    register(definition: TaxonomyDefinition): void;
+    get(name: string): TaxonomyDefinition | undefined;
+    has(name: string): boolean;
+    getAll(): TaxonomyDefinition[];
+    /**
+     * Get taxonomies assigned to a specific object type (e.g., 'post').
+     */
+    getForObjectType(objectType: string): TaxonomyDefinition[];
+    getRestVisible(): TaxonomyDefinition[];
+    unregister(name: string): boolean;
+    reset(): void;
+}
+declare const BUILTIN_TAXONOMIES: TaxonomyDefinition[];
+
+/**
+ * Extension manifest — equivalent to plugin headers in the spec.
+ * Found in the extension's manifest.json file.
+ */
+interface ExtensionManifest {
+    /** Unique slug identifier */
+    slug: string;
+    /** Display name */
+    name: string;
+    /** Semantic version */
+    version: string;
+    /** Short description */
+    description?: string;
+    /** Author name */
+    author?: string;
+    /** Author URL */
+    authorUri?: string;
+    /** Minimum CMS version required */
+    minCmsVersion?: string;
+    /** Minimum Node.js version required */
+    minNodeVersion?: string;
+    /** Dependencies (slugs of other extensions) */
+    dependencies?: string[];
+    /** Text domain for i18n */
+    textDomain?: string;
+    /** Whether this is a network-wide extension (multisite) */
+    network?: boolean;
+    /** Entry point file (relative to extension dir). Default: index.ts */
+    main?: string;
+}
+type ExtensionStatus = 'active' | 'inactive' | 'paused' | 'must-use';
+interface ExtensionEntry {
+    manifest: ExtensionManifest;
+    status: ExtensionStatus;
+    /** Absolute path to the extension directory */
+    path: string;
+    /** Error that caused the extension to be paused */
+    pauseReason?: string;
+    /** When the extension was activated */
+    activatedAt?: Date;
+}
+/**
+ * Registry that tracks all discovered and active extensions.
+ *
+ * Extensions go through these states:
+ *   discovered → activated → loaded → running
+ *   activated → paused (on fatal error, via recovery mode)
+ *   running → deactivated → inactive
+ */
+declare class ExtensionRegistry {
+    private extensions;
+    /**
+     * Register an extension manifest (discovery phase).
+     */
+    register(manifest: ExtensionManifest, path: string, status: ExtensionStatus): void;
+    get(slug: string): ExtensionEntry | undefined;
+    has(slug: string): boolean;
+    /**
+     * Get all extensions by status.
+     */
+    getByStatus(status: ExtensionStatus): ExtensionEntry[];
+    getAll(): ExtensionEntry[];
+    getActive(): ExtensionEntry[];
+    getMustUse(): ExtensionEntry[];
+    getPaused(): ExtensionEntry[];
+    /**
+     * Activate an extension. Checks dependencies first.
+     *
+     * @throws If dependencies are not met
+     */
+    activate(slug: string): void;
+    /**
+     * Deactivate an extension. Checks if other extensions depend on it.
+     *
+     * @throws If other active extensions depend on this one
+     */
+    deactivate(slug: string): void;
+    /**
+     * Pause an extension due to a fatal error (recovery mode).
+     */
+    pause(slug: string, reason: string): void;
+    /**
+     * Unpause an extension (resume from recovery mode).
+     */
+    unpause(slug: string): void;
+    /**
+     * Remove an extension from the registry entirely.
+     */
+    unregister(slug: string): boolean;
+    /**
+     * Get dependencies that are not active.
+     */
+    getUnmetDependencies(slug: string): string[];
+    /**
+     * Get active extensions that depend on the given extension.
+     */
+    getDependents(slug: string): ExtensionEntry[];
+    /**
+     * Check for circular dependencies starting from a slug.
+     */
+    hasCircularDependency(slug: string, visited?: Set<string>): boolean;
+    reset(): void;
+}
+
+/**
+ * Theme manifest — found in the theme's theme.json file.
+ */
+interface ThemeManifest {
+    slug: string;
+    name: string;
+    version: string;
+    description?: string;
+    author?: string;
+    authorUri?: string;
+    /** Parent theme slug (for child themes) */
+    parent?: string;
+    /** Supported features */
+    supports?: ThemeSupports;
+    /** Menu locations */
+    menuLocations?: Record<string, string>;
+    /** Design tokens / settings */
+    settings?: Record<string, unknown>;
+}
+interface ThemeSupports {
+    thumbnails?: boolean;
+    postFormats?: string[];
+    html5?: string[];
+    customLogo?: {
+        width?: number;
+        height?: number;
+        flexWidth?: boolean;
+        flexHeight?: boolean;
+    };
+    customHeader?: {
+        width?: number;
+        height?: number;
+        flexWidth?: boolean;
+        flexHeight?: boolean;
+    };
+    customBackground?: boolean;
+    menus?: boolean;
+    feedLinks?: boolean;
+    responsiveEmbeds?: boolean;
+    blockTemplates?: boolean;
+}
+interface ThemeEntry {
+    manifest: ThemeManifest;
+    path: string;
+    active: boolean;
+    parentTheme?: ThemeEntry;
+}
+/**
+ * Registry for installed themes.
+ */
+declare class ThemeRegistry {
+    private themes;
+    private activeSlug;
+    register(manifest: ThemeManifest, path: string): void;
+    get(slug: string): ThemeEntry | undefined;
+    getAll(): ThemeEntry[];
+    getActive(): ThemeEntry | undefined;
+    /**
+     * Activate a theme. Resolves parent theme for child themes.
+     */
+    activate(slug: string): void;
+    /**
+     * Check if the active theme supports a feature.
+     */
+    supports(feature: keyof ThemeSupports): boolean;
+    reset(): void;
+}
+/**
+ * Template hierarchy resolver.
+ *
+ * Given query flags and context, returns an ordered list of template
+ * names to search for (most specific first).
+ */
+interface TemplateContext {
+    type: 'single' | 'page' | 'category' | 'tag' | 'taxonomy' | 'author' | 'date' | 'search' | '404' | 'home' | 'archive' | 'attachment';
+    slug?: string;
+    id?: number;
+    postType?: string;
+    taxonomy?: string;
+    term?: string;
+    mimeType?: string;
+    mimeSubtype?: string;
+    nicename?: string;
+    customTemplate?: string;
+}
+declare function resolveTemplateHierarchy(ctx: TemplateContext): string[];
+
+/**
+ * The 17 bootstrap phases as defined in the spec.
+ * Each phase is a named step executed in strict order during startup.
+ */
+declare const BOOTSTRAP_PHASES: readonly ["entry_point", "configuration", "initial_constants", "environment_check", "error_handling", "core_functions", "database_connect", "object_cache", "default_filters", "must_use_extensions", "regular_extensions", "overridable_functions", "extensions_loaded", "global_objects", "theme", "init", "system_loaded"];
+type BootstrapPhase = (typeof BOOTSTRAP_PHASES)[number];
+/**
+ * Callback for a bootstrap phase.
+ */
+type PhaseHandler = () => void | Promise<void>;
+/**
+ * Orchestrates the CMS bootstrap process through 17 ordered phases.
+ *
+ * Each phase can have multiple handlers registered. Handlers within a phase
+ * run in registration order. Phases are always executed in the order defined
+ * by BOOTSTRAP_PHASES.
+ *
+ * The HookEngine fires a hook for each phase, allowing extensions to tap in.
+ */
+declare class BootstrapManager {
+    private hooks;
+    private phaseHandlers;
+    private completedPhases;
+    private currentPhase;
+    constructor(hooks: HookEngine);
+    /**
+     * Register a handler for a bootstrap phase.
+     */
+    on(phase: BootstrapPhase, handler: PhaseHandler): void;
+    /**
+     * Execute all 17 bootstrap phases in order.
+     * For short-init mode, pass a phase to stop at.
+     */
+    run(stopAfter?: BootstrapPhase): Promise<void>;
+    /**
+     * Check if a phase has been completed.
+     */
+    isPhaseComplete(phase: BootstrapPhase): boolean;
+    /**
+     * Get the phase currently being executed.
+     */
+    getCurrentPhase(): BootstrapPhase | null;
+    /**
+     * Get all completed phases.
+     */
+    getCompletedPhases(): BootstrapPhase[];
+    /**
+     * Reset — for testing.
+     */
+    reset(): void;
+}
+
+export { type AddHookOptions, BOOTSTRAP_PHASES, BUILTIN_POST_TYPES, BUILTIN_TAXONOMIES, BootstrapManager, type BootstrapPhase, type CapabilityContext, type ExtensionEntry, type ExtensionManifest, ExtensionRegistry, type ExtensionStatus, HOOK_PRIORITY, type HasHookResult, type HookCallback, HookEngine, type HookHandler, type HookStackEntry, POST_STATUS, type PhaseHandler, type PostTypeDefinition, PostTypeRegistry, type TaxonomyDefinition, TaxonomyRegistry, type TemplateContext, type ThemeEntry, type ThemeManifest, ThemeRegistry, type ThemeSupports, USER_ROLES, resolveTemplateHierarchy };