knarr 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,434 @@
+interface PublishOptions {
+    allowPrivate?: boolean;
+    /** Whether to run prepack/postpack lifecycle hooks (default: true) */
+    runScripts?: boolean;
+    /** Force publish, bypassing hash comparison */
+    force?: boolean;
+    /** Max historical builds to keep (default: 3). Set to 0 to disable. */
+    historyLimit?: number;
+}
+interface PublishResult {
+    name: string;
+    version: string;
+    fileCount: number;
+    /** True if content was unchanged and publish was skipped */
+    skipped: boolean;
+    contentHash: string;
+    /** 8-char hex identifier generated on each successful publish */
+    buildId: string;
+}
+/**
+ * Publish a package from a directory to the Knarr store.
+ *
+ * 1. Read package.json, validate name and version
+ * 2. Resolve publishable files
+ * 3. Compute content hash
+ * 4. Skip if hash matches existing store entry
+ * 5. Copy files to temp dir, then atomic rename to store
+ * 6. Write .knarr-meta.json
+ */
+declare function publish(packageDir: string, options?: PublishOptions): Promise<PublishResult>;
+
+/** Metadata stored alongside each package in the Knarr store */
+interface KnarrMeta {
+    schemaVersion?: number;
+    contentHash: string;
+    publishedAt: string;
+    sourcePath: string;
+    /** 8-char hex ID derived from content hash. Missing in pre-buildId store entries. */
+    buildId?: string;
+}
+/** A store entry representing a published package */
+interface StoreEntry {
+    name: string;
+    version: string;
+    packageDir: string;
+    meta: KnarrMeta;
+}
+/** Tracks a single linked package in a consumer project */
+interface LinkEntry {
+    version: string;
+    contentHash: string;
+    linkedAt: string;
+    sourcePath: string;
+    backupExists: boolean;
+    packageManager: PackageManager;
+    /** 8-char hex ID. Missing in pre-buildId state files. */
+    buildId?: string;
+}
+/** Consumer project state file (.knarr/state.json) */
+interface ConsumerState {
+    version: "1";
+    packageManager?: PackageManager;
+    role?: "consumer" | "library";
+    links: Record<string, LinkEntry>;
+}
+/** Global consumers registry (~/.knarr/consumers.json) */
+interface ConsumersRegistry {
+    /** Maps package name → array of consumer project paths */
+    [packageName: string]: string[];
+}
+type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
+/** A historical build stored in the store's history directory */
+interface HistoryEntry {
+    buildId: string;
+    contentHash: string;
+    publishedAt: string;
+    sourcePath: string;
+    /** Path to the history entry's package directory */
+    packageDir: string;
+}
+/** Options for the watch mode */
+interface WatchOptions {
+    /** Glob patterns to watch (default: src, lib, dist) */
+    patterns?: string[];
+    /** Build command to run before publishing */
+    buildCmd?: string;
+    /** Debounce delay in ms (default: 500) */
+    debounce?: number;
+    /** Minimum time between builds in ms (default: 500) */
+    cooldown?: number;
+    /** Ring terminal bell on push success/failure */
+    notify?: boolean;
+    /** Enable awaitWriteFinish for large/slow writes (auto-enabled when no buildCmd) */
+    awaitWriteFinish?: boolean | {
+        stabilityThreshold: number;
+        pollInterval: number;
+    };
+}
+/** Package.json fields we care about */
+interface PackageJson {
+    name: string;
+    version: string;
+    files?: string[];
+    bin?: string | Record<string, string>;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+    peerDependenciesMeta?: Record<string, {
+        optional?: boolean;
+    }>;
+    main?: string;
+    module?: string;
+    exports?: unknown;
+    type?: string;
+    private?: boolean;
+    scripts?: Record<string, string>;
+    types?: string;
+    typings?: string;
+    browser?: string | Record<string, string>;
+    /** Corepack packageManager field, e.g. "pnpm@9.0.0" */
+    packageManager?: string;
+    publishConfig?: {
+        main?: string;
+        module?: string;
+        exports?: unknown;
+        types?: string;
+        typings?: string;
+        browser?: string | Record<string, string>;
+        bin?: string | Record<string, string>;
+        directory?: string;
+    };
+}
+
+interface InjectResult {
+    copied: number;
+    removed: number;
+    skipped: number;
+    binLinks: number;
+}
+interface InjectOptions {
+    /** Force copy all files, bypassing hash comparison */
+    force?: boolean;
+}
+/**
+ * Inject a package from the store into a consumer's node_modules.
+ * Strategy depends on the package manager:
+ * - npm/yarn/bun: direct node_modules/<pkg>/
+ * - pnpm: follow .pnpm/ structure
+ */
+declare function inject(storeEntry: StoreEntry, consumerPath: string, pm: PackageManager, options?: InjectOptions): Promise<InjectResult>;
+/**
+ * Back up the existing installed version of a package before overwriting.
+ */
+declare function backupExisting(consumerPath: string, packageName: string, pm: PackageManager): Promise<boolean>;
+/**
+ * Restore a backed-up package to node_modules.
+ */
+declare function restoreBackup(consumerPath: string, packageName: string, pm: PackageManager): Promise<boolean>;
+/**
+ * Remove an injected package from node_modules.
+ */
+declare function removeInjected(consumerPath: string, packageName: string, pm: PackageManager): Promise<void>;
+/**
+ * Check for missing transitive dependencies.
+ * Returns a list of dependency names that are in the linked package's
+ * dependencies but not installed in the consumer's node_modules.
+ */
+declare function checkMissingDeps(storeEntry: StoreEntry, consumerPath: string): Promise<string[]>;
+
+/** Get a store entry if it exists */
+declare function getStoreEntry(name: string, version: string): Promise<StoreEntry | null>;
+/** Find a store entry by name (any version). Returns the latest by publishedAt. */
+declare function findStoreEntry(name: string): Promise<StoreEntry | null>;
+/** List all entries in the store */
+declare function listStoreEntries(): Promise<StoreEntry[]>;
+
+/** Read the consumer state file, or return an empty state if not found */
+declare function readConsumerState(consumerPath: string): Promise<ConsumerState>;
+/**
+ * Read consumer state with reliability information.
+ * Returns `reliable: true` when the state is trustworthy (valid file or ENOENT).
+ * Returns `reliable: false` when the file exists but is corrupt/unreadable,
+ * meaning the consumer might have links we can't see.
+ */
+declare function readConsumerStateSafe(consumerPath: string): Promise<{
+    state: ConsumerState;
+    reliable: boolean;
+}>;
+/** Add or update a link entry in the consumer state */
+declare function addLink(consumerPath: string, packageName: string, entry: LinkEntry): Promise<void>;
+/** Remove a link entry from the consumer state */
+declare function removeLink(consumerPath: string, packageName: string): Promise<void>;
+/** Get a specific link entry */
+declare function getLink(consumerPath: string, packageName: string): Promise<LinkEntry | null>;
+/** Register a consumer for a package */
+declare function registerConsumer(packageName: string, consumerPath: string): Promise<void>;
+/** Unregister a consumer for a package */
+declare function unregisterConsumer(packageName: string, consumerPath: string): Promise<void>;
+/** Get all consumers for a package */
+declare function getConsumers(packageName: string): Promise<string[]>;
+/**
+ * Clean stale consumers — remove registrations for directories that no longer exist.
+ * Returns the number of stale entries removed.
+ */
+declare function cleanStaleConsumers(): Promise<{
+    removedConsumers: number;
+    removedPackages: number;
+}>;
+
+/**
+ * knarr configuration stored in package.json under the "knarr" key.
+ * Provides persistent defaults for watch/build/dev behavior.
+ */
+interface KnarrConfig {
+    buildCmd?: string;
+    watchPatterns?: string[];
+    debounce?: number;
+    cooldown?: number;
+    historyLimit?: number;
+    notify?: boolean;
+}
+/**
+ * Load knarr configuration from package.json#knarr.
+ */
+declare function loadKnarrConfig(projectDir: string): Promise<KnarrConfig>;
+
+interface PushOptions {
+    runScripts?: boolean;
+    /** Force copy all files, bypassing hash comparison */
+    force?: boolean;
+    /** Max historical builds to keep per package */
+    historyLimit?: number;
+}
+/**
+ * Publish a package to the store, then inject into all registered consumers.
+ * Shared by both `push` and `dev` commands.
+ */
+declare function doPush(packageDir: string, options?: PushOptions): Promise<void>;
+/** Common CLI args shared by push --watch and dev */
+interface WatchArgs {
+    build?: string;
+    "skip-build"?: boolean;
+    debounce?: string;
+    cooldown?: string;
+    notify?: boolean;
+    "no-cascade"?: boolean;
+}
+
+/**
+ * Push all workspace packages in topological (dependency-first) order.
+ * Each package is published and injected sequentially to ensure
+ * dependencies are available before dependents.
+ */
+declare function doPushAll(startDir: string, options?: PushOptions): Promise<void>;
+
+/**
+ * Capture the current store entry as a history entry before it gets replaced.
+ * Moves the old package/ and .knarr-meta.json into history/<buildId>/.
+ */
+declare function captureHistory(name: string, version: string, oldEntryDir: string, historyLimit?: number): Promise<void>;
+/**
+ * List all history entries for a package, sorted by publishedAt (newest first).
+ */
+declare function listHistory(name: string, version: string): Promise<HistoryEntry[]>;
+/**
+ * Get a specific history entry by buildId.
+ */
+declare function getHistoryEntry(name: string, version: string, buildId: string): Promise<HistoryEntry | null>;
+/**
+ * Restore a history entry as the current store entry.
+ * Moves the history entry back to the main store position.
+ */
+declare function restoreHistoryEntry(name: string, version: string, buildId: string, historyLimit?: number): Promise<HistoryEntry | null>;
+/**
+ * Prune history entries to keep only the most recent `limit` entries.
+ */
+declare function pruneHistory(name: string, version: string, limit: number): Promise<number>;
+/**
+ * Remove all history for a package.
+ */
+declare function clearHistory(name: string, version: string): Promise<void>;
+/** Resolve the effective history limit from config or default */
+declare function resolveHistoryLimit(configValue?: number): number;
+
+/** Kill the active build process if one is running */
+declare function killActiveBuild(): void;
+/**
+ * Start watching a directory for changes and trigger a callback.
+ *
+ * Uses a "debounce effects, not detection" strategy (inspired by Vite):
+ * - File changes are detected immediately
+ * - The push callback is coalesced: rapid changes within `debounceMs` are batched
+ * - If a push is already running when new changes arrive, a re-push is queued
+ *   so the final state is always pushed
+ */
+declare function startWatcher(watchDir: string, options: WatchOptions, onChange: () => Promise<void>): Promise<{
+    close: () => Promise<void>;
+}>;
+/**
+ * Run a build command and return true if it succeeds.
+ */
+declare function runBuildCommand(cmd: string, cwd: string): Promise<boolean>;
+
+/**
+ * Orchestrates watch mode for all workspace packages with optional
+ * cascading rebuilds. When a package is pushed, its dependents in
+ * the workspace are automatically rebuilt and pushed.
+ *
+ * State machine per package prevents infinite loops:
+ *   idle → building → idle (normal)
+ *   building + trigger → queued → building (coalesced)
+ *   queued + trigger → queued (no-op)
+ */
+declare class WatchOrchestrator {
+    private packages;
+    private dependents;
+    private cascade;
+    private pushOptions;
+    constructor(cascade: boolean);
+    start(startDir: string, args: WatchArgs, pushOptions: PushOptions): Promise<void>;
+    private onPackagePushed;
+    private requestRebuild;
+    close(): Promise<void>;
+}
+
+/**
+ * Detect the package manager used in a project directory.
+ * Checks `packageManager` field in package.json first (Corepack convention),
+ * then falls back to lockfile presence, walking up to the filesystem root.
+ * Closest match wins. Within the same directory, priority order is maintained.
+ * Falls back to "npm" if nothing is found.
+ */
+declare function detectPackageManager(projectDir: string): Promise<PackageManager>;
+
+/**
+ * Topological sort using Kahn's algorithm.
+ * Used to order workspace packages so dependencies are processed first.
+ */
+declare class CycleError extends Error {
+    readonly cycle: string[];
+    constructor(cycle: string[]);
+}
+/**
+ * Sort nodes topologically (dependency-first order).
+ * @param graph Map of node → Set of its dependencies (nodes it depends on)
+ * @returns Nodes in dependency-first order
+ * @throws CycleError if a cycle is detected
+ */
+declare function topoSort(graph: Map<string, Set<string>>): string[];
+
+interface WorkspacePackage {
+    name: string;
+    version: string;
+    dir: string;
+    pkg: PackageJson;
+}
+interface WorkspaceGraph {
+    packages: WorkspacePackage[];
+    /** Map of package name → Set of in-workspace dependency names */
+    adjacency: Map<string, Set<string>>;
+}
+/**
+ * Build a workspace dependency graph for topological sorting.
+ * Reads all workspace packages and builds an adjacency map of
+ * in-workspace dependencies (both dependencies and devDependencies).
+ */
+declare function buildWorkspaceGraph(startDir: string): Promise<WorkspaceGraph>;
+/**
+ * Build a reverse adjacency map: for each package, which packages depend on it.
+ * Used by WatchOrchestrator to trigger cascading rebuilds.
+ */
+declare function buildReverseAdjacency(adjacency: Map<string, Set<string>>): Map<string, Set<string>>;
+
+type PreflightSeverity = "warn" | "error";
+interface PreflightIssue {
+    code: string;
+    severity: PreflightSeverity;
+    message: string;
+}
+/**
+ * Run pre-flight validation checks on a package before publishing.
+ * Checks entry points, exports, types, and bin paths exist on disk.
+ * Returns an array of issues found (empty = all good).
+ */
+declare function runPreflightChecks(packageDir: string): Promise<PreflightIssue[]>;
+
+/**
+ * Ring the terminal bell (BEL character).
+ * Writes to stderr so it doesn't interfere with --json output on stdout.
+ */
+declare function ringBell(enabled: boolean): void;
+
+/**
+ * Simple timer for measuring command execution time.
+ */
+declare class Timer {
+    private start;
+    /** Return elapsed time in ms */
+    elapsedMs(): number;
+    /** Return human-readable elapsed time (e.g., "1.2s" or "150ms") */
+    elapsed(): string;
+}
+
+/** Type guard for Node.js system errors with an error code */
+declare function isNodeError(err: unknown): err is NodeJS.ErrnoException;
+
+/** Normalize a file path to use forward slashes (for cross-platform consistency). */
+declare function normalizePath(p: string): string;
+
+type MutationType = "copy" | "remove" | "move" | "mkdir" | "write" | "bin-link" | "bin-unlink" | "cache-invalidate" | "lock-skip" | "lifecycle-skip";
+interface DryRunMutation {
+    type: MutationType;
+    path: string;
+    dest?: string;
+    detail?: string;
+}
+/** Record a mutation that was skipped due to --dry-run */
+declare function recordMutation(mutation: DryRunMutation): void;
+/** Print a summary of all recorded dry-run mutations */
+declare function printDryRunReport(): void;
+/** Reset recorded mutations (for testing) */
+declare function resetMutations(): void;
+
+/**
+ * Heuristic to detect configs that are too complex for automatic rewriting.
+ * Returns null if safe to rewrite, or a reason string if too complex.
+ */
+declare function isComplexConfig(content: string): {
+    complex: boolean;
+    reason?: string;
+};
+
+export { type ConsumerState, type ConsumersRegistry, CycleError, type DryRunMutation, type HistoryEntry, type InjectOptions, type InjectResult, type KnarrConfig, type KnarrMeta, type LinkEntry, type MutationType, type PackageJson, type PackageManager, type PreflightIssue, type PreflightSeverity, type PublishOptions, type PublishResult, type PushOptions, type StoreEntry, Timer, type WatchOptions, WatchOrchestrator, type WorkspaceGraph, type WorkspacePackage, addLink, backupExisting, buildReverseAdjacency, buildWorkspaceGraph, captureHistory, checkMissingDeps, cleanStaleConsumers, clearHistory, detectPackageManager, doPush, doPushAll, findStoreEntry, getConsumers, getHistoryEntry, getLink, getStoreEntry, inject, isComplexConfig, isNodeError, killActiveBuild, listHistory, listStoreEntries, loadKnarrConfig, normalizePath, printDryRunReport, pruneHistory, publish, readConsumerState, readConsumerStateSafe, recordMutation, registerConsumer, removeInjected, removeLink, resetMutations, resolveHistoryLimit, restoreBackup, restoreHistoryEntry, ringBell, runBuildCommand, runPreflightChecks, startWatcher, topoSort, unregisterConsumer };