@orkify/cli 1.0.0-beta.5

package/dist/types/index.d.ts

@@ -0,0 +1,373 @@
+import type { ExecModeType, IPCMessageTypeType, ProcessStatusType } from '../constants.js';
+export interface CronJob {
+    schedule: string;
+    path: string;
+    method?: string;
+    timeout?: number;
+}
+export interface ProcessConfig {
+    name: string;
+    script: string;
+    cwd: string;
+    workerCount: number;
+    execMode: ExecModeType;
+    watch: boolean;
+    watchPaths?: string[];
+    env: Record<string, string>;
+    nodeArgs: string[];
+    args: string[];
+    killTimeout: number;
+    maxRestarts: number;
+    minUptime: number;
+    restartDelay: number;
+    sticky: boolean;
+    port?: number;
+    reloadRetries?: number;
+    healthCheck?: string;
+    logMaxSize: number;
+    logMaxFiles: number;
+    logMaxAge: number;
+    restartOnMemory?: number;
+    cron?: CronJob[];
+    framework?: string;
+}
+export interface WorkerInfo {
+    id: number;
+    pid: number;
+    status: ProcessStatusType;
+    restarts: number;
+    crashes: number;
+    uptime: number;
+    memory: number;
+    cpu: number;
+    createdAt: number;
+    stale?: boolean;
+    heapUsed?: number;
+    heapTotal?: number;
+    external?: number;
+    arrayBuffers?: number;
+    eventLoopLag?: number;
+    eventLoopLagP95?: number;
+    activeHandles?: number;
+    cacheSize?: number;
+    cacheTotalBytes?: number;
+    cacheHits?: number;
+    cacheMisses?: number;
+    cacheHitRate?: number;
+}
+export interface ProcessInfo {
+    id: number;
+    name: string;
+    script: string;
+    cwd: string;
+    execMode: ExecModeType;
+    workerCount: number;
+    status: ProcessStatusType;
+    workers: WorkerInfo[];
+    pid?: number;
+    createdAt: number;
+    restartedAt?: number;
+    watch: boolean;
+    sticky: boolean;
+    port?: number;
+}
+export interface IPCMessage {
+    type: IPCMessageTypeType;
+    id: string;
+    payload?: unknown;
+}
+export interface IPCRequest extends IPCMessage {
+    payload?: DeployRestorePayload | KillPayload | LogsPayload | McpStartPayload | ProcessConfig[] | RestorePayload | SnapPayload | TargetPayload | TelemetryConfig | UpPayload;
+}
+export interface IPCResponse extends IPCMessage {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+}
+export interface UpPayload {
+    script: string;
+    name?: string;
+    workers?: number;
+    watch?: boolean;
+    watchPaths?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    nodeArgs?: string[];
+    args?: string[];
+    killTimeout?: number;
+    maxRestarts?: number;
+    minUptime?: number;
+    restartDelay?: number;
+    sticky?: boolean;
+    port?: number;
+    reloadRetries?: number;
+    healthCheck?: string;
+    logMaxSize?: number;
+    logMaxFiles?: number;
+    logMaxAge?: number;
+    restartOnMemory?: number;
+    cron?: CronJob[];
+    framework?: string;
+}
+export interface KillPayload {
+    force?: boolean;
+}
+export interface TargetPayload {
+    target: 'all' | number | string;
+}
+export interface LogsPayload {
+    target?: number | string;
+    lines?: number;
+    follow?: boolean;
+}
+export interface SnapPayload {
+    noEnv?: boolean;
+    file?: string;
+}
+export interface RestorePayload {
+    file?: string;
+}
+export interface DeployRestorePayload {
+    secrets: Record<string, string>;
+    downloadUrl: string;
+    sha256: string;
+    version: number;
+    artifactId: string;
+    sizeBytes: number;
+    deployConfig: DeploySettings;
+}
+export interface SavedState {
+    version?: number;
+    deploy?: DeploySettings;
+    processes: ProcessConfig[];
+    mcp?: McpStartPayload;
+}
+export type McpTransport = 'advanced-http' | 'simple-http';
+export interface McpStartPayload {
+    transport: McpTransport;
+    port: number;
+    bind: string;
+    cors?: string;
+}
+export interface McpStatusResponse {
+    running: boolean;
+    transport?: McpTransport;
+    port?: number;
+    bind?: string;
+    cors?: string;
+}
+export interface DaemonStatus {
+    pid: number;
+    uptime: number;
+    processCount: number;
+    workerCount: number;
+}
+export type TelemetryEventType = 'error:uncaughtException' | 'error:unhandledRejection' | 'process:deploy-failed' | 'process:deploy-finished' | 'process:deploy-started' | 'process:reload' | 'process:reloaded' | 'process:start' | 'process:stop' | 'worker:crash' | 'worker:exit' | 'worker:maxRestarts' | 'worker:memoryRestart' | 'worker:ready';
+export interface TelemetryEvent {
+    type: TelemetryEventType;
+    processName: string;
+    timestamp: number;
+    [key: string]: unknown;
+}
+export interface TelemetryMetricsSnapshot {
+    processName: string;
+    processId: number;
+    execMode: ExecModeType;
+    status: ProcessStatusType;
+    workers: Array<{
+        id: number;
+        pid: number;
+        cpu: number;
+        memory: number;
+        uptime: number;
+        restarts: number;
+        crashes: number;
+        status: ProcessStatusType;
+        stale?: boolean;
+        heapUsed?: number;
+        heapTotal?: number;
+        external?: number;
+        arrayBuffers?: number;
+        eventLoopLag?: number;
+        eventLoopLagP95?: number;
+        activeHandles?: number;
+        cacheSize?: number;
+        cacheTotalBytes?: number;
+        cacheHits?: number;
+        cacheMisses?: number;
+        cacheHitRate?: number;
+    }>;
+    timestamp: number;
+}
+export interface TelemetryHostInfo {
+    os: string;
+    arch: string;
+    nodeVersion: string;
+    cpuCount: number;
+    totalMemory: number;
+}
+export interface SourceContextFrame {
+    file: string;
+    line: number;
+    column: number;
+    pre: string[];
+    target: string;
+    post: string[];
+}
+export interface CrashDiagnostics {
+    memoryUsage: {
+        rss: number;
+        heapTotal: number;
+        heapUsed: number;
+        external: number;
+        arrayBuffers: number;
+    };
+    processUptime: number;
+    heapStatistics: {
+        totalHeapSize: number;
+        usedHeapSize: number;
+        heapSizeLimit: number;
+        totalAvailableSize: number;
+        totalPhysicalSize: number;
+    };
+    osFreeMemory: number;
+    osLoadAvg: number[];
+    activeResources: string[];
+}
+export interface TelemetryErrorEvent {
+    processName: string;
+    workerId: number;
+    timestamp: number;
+    errorType: 'browser:error' | 'browser:unhandledRejection' | 'uncaughtException' | 'unhandledRejection';
+    name: string;
+    message: string;
+    stack: string;
+    fingerprint: string;
+    sourceContext: null | SourceContextFrame[];
+    topFrame: null | {
+        file: string;
+        line: number;
+        column: number;
+    };
+    diagnostics: CrashDiagnostics | null;
+    nodeVersion: string;
+    pid: number;
+    lastLogs: string[];
+    resolved?: boolean;
+    url?: string;
+    userAgent?: string;
+}
+export interface TelemetryLogEntry {
+    processName: string;
+    workerId: number;
+    timestamp: number;
+    level: 'error' | 'info' | 'warn';
+    message: string;
+}
+export interface DeployStatus {
+    deployId: string;
+    targetId: string;
+    phase: 'building' | 'downloading' | 'extracting' | 'failed' | 'installing' | 'monitoring' | 'reloading' | 'rolled_back' | 'success';
+    buildLog?: string;
+    error?: string;
+}
+export interface DeploySettings {
+    install: string;
+    build?: string;
+    buildEnv?: Record<string, string>;
+    crashWindow?: number;
+    sourcemaps?: boolean;
+}
+/** @deprecated Use DeploySettings instead */
+export type DeployConfig = DeploySettings;
+export interface DeployCommand {
+    type: 'deploy';
+    deployId: string;
+    targetId: string;
+    artifactId: string;
+    version: number;
+    sha256: string;
+    sizeBytes: number;
+    downloadToken: string;
+    downloadUrl: string;
+    deployConfig: DeploySettings;
+}
+export interface DeployLocalPayload {
+    tarballPath: string;
+    deployConfig: DeploySettings;
+    env?: Record<string, string>;
+}
+export interface DeployOptions {
+    localTarball?: string;
+    secrets?: Record<string, string>;
+    skipInstall?: boolean;
+    skipBuild?: boolean;
+    skipMonitor?: boolean;
+    skipTelemetry?: boolean;
+    deploysDir?: string;
+}
+export interface ReconcileResult {
+    started: string[];
+    reloaded: string[];
+    deleted: string[];
+}
+export interface TelemetryPayload {
+    daemonPid: number;
+    daemonUptime: number;
+    hostname: string;
+    agentName?: string;
+    machineId?: null | string;
+    host: TelemetryHostInfo;
+    events: TelemetryEvent[];
+    metrics: TelemetryMetricsSnapshot[];
+    errors: TelemetryErrorEvent[];
+    logs: TelemetryLogEntry[];
+    alerts?: TelemetryAlertEvent[];
+    configHash?: null | string;
+    mcpCapable?: boolean;
+    deployStatus?: DeployStatus;
+    sentAt: number;
+}
+export interface TelemetryConfig {
+    apiKey: string;
+    apiHost: string;
+}
+export interface AlertRuleCondition {
+    metric: 'cpu' | 'heartbeat' | 'memory';
+    operator: 'gt';
+    threshold: number;
+    duration: number;
+}
+export interface AlertRuleConfig {
+    id: string;
+    name: string;
+    condition: AlertRuleCondition;
+    is_enabled: boolean;
+}
+export interface McpRemoteKeyConfig {
+    name: string;
+    key_hash: string;
+    tools: string[];
+    allowed_ips: string[];
+}
+export interface McpRemoteConfig {
+    enabled: boolean;
+    keys: McpRemoteKeyConfig[];
+}
+export interface ProjectConfig {
+    alert_rules: AlertRuleConfig[];
+    mcp: McpRemoteConfig;
+}
+export interface TelemetryAlertEvent {
+    type: 'alert:resolved' | 'alert:triggered';
+    rule_id: string;
+    rule_name: string;
+    metric: 'cpu' | 'heartbeat' | 'memory';
+    value: number;
+    threshold: number;
+    process_name: string;
+    worker_id: number;
+    hostname: string;
+    timestamp: number;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,148 @@
+{
+  "name": "@orkify/cli",
+  "version": "1.0.0-beta.5",
+  "description": "Modern JS process orchestration and deployment for your own infrastructure",
+  "type": "module",
+  "main": "dist/cli/index.js",
+  "exports": {
+    ".": "./dist/cli/index.js",
+    "./cache": {
+      "types": "./packages/cache/src/index.ts",
+      "import": "./packages/cache/dist/index.js",
+      "default": "./packages/cache/dist/index.js"
+    },
+    "./next/use-cache": {
+      "types": "./packages/next/src/use-cache.ts",
+      "import": "./packages/next/dist/use-cache.js",
+      "default": "./packages/next/dist/use-cache.js"
+    },
+    "./next/isr-cache": {
+      "types": "./packages/next/src/isr-cache.ts",
+      "import": "./packages/next/dist/isr-cache.js",
+      "default": "./packages/next/dist/isr-cache.js"
+    },
+    "./next/error-capture": {
+      "types": "./packages/next/src/error-capture.ts",
+      "import": "./packages/next/dist/error-capture.js",
+      "default": "./packages/next/dist/error-capture.js"
+    },
+    "./next/error-handler": {
+      "types": "./packages/next/src/error-handler.ts",
+      "import": "./packages/next/dist/error-handler.js",
+      "default": "./packages/next/dist/error-handler.js"
+    }
+  },
+  "bin": {
+    "orkify": "./bin/orkify"
+  },
+  "files": [
+    "bin/",
+    "boot/",
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "packages/"
+  ],
+  "scripts": {
+    "build": "tsc -p packages/cache/tsconfig.json && tsc -p packages/next/tsconfig.json && tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli/index.js",
+    "clean": "rm -rf dist coverage packages/cache/dist packages/next/dist",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run --exclude 'tests/integration/**'",
+    "test:watch": "vitest --exclude 'tests/integration/**'",
+    "test:coverage": "vitest run --coverage --exclude 'tests/integration/**'",
+    "test:e2e": "vitest run tests/integration",
+    "typecheck": "tsc --noEmit",
+    "knip": "knip",
+    "check": "npm run build && npm run typecheck && npm run lint && npm run knip && npm run format:check && npm run test:coverage",
+    "audit": "npm audit --audit-level=moderate",
+    "prepack": "npm run audit && npm run check && npm run build",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "*.{ts,js}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md,yml,yaml}": [
+      "prettier --write"
+    ]
+  },
+  "keywords": [
+    "process-manager",
+    "cluster",
+    "socket.io",
+    "sticky-sessions",
+    "zero-downtime",
+    "graceful-reload",
+    "node",
+    "daemon"
+  ],
+  "author": "orkify <ahoy@orkify.com>",
+  "license": "Apache-2.0",
+  "homepage": "https://orkify.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/orkify/orkify.git"
+  },
+  "bugs": {
+    "url": "https://github.com/orkify/orkify/issues"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "@orkify/cache": "file:./packages/cache",
+    "@orkify/next": "file:./packages/next",
+    "@socket.io/cluster-adapter": "^0.3.0",
+    "@socket.io/sticky": "^1.0.4",
+    "chalk": "^5.3.0",
+    "chokidar": "^3.5.3",
+    "cli-table3": "^0.6.3",
+    "commander": "^12.0.0",
+    "cron-parser": "^5.5.0",
+    "express": "^5.2.1",
+    "ignore": "^7.0.5",
+    "pidusage": "^3.0.2",
+    "socket.io": "^4.8.3",
+    "source-map-js": "^1.2.1",
+    "tar-stream": "^3.1.7",
+    "yaml": "^2.8.2",
+    "zod": "^3.22.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.3.1",
+    "@commitlint/config-conventional": "^20.3.1",
+    "@eslint/js": "^10.0.1",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "@types/pidusage": "^2.0.5",
+    "@types/react": "^19.2.14",
+    "@types/tar-stream": "^3.1.4",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^10.0.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-perfectionist": "^5.6.0",
+    "husky": "^9.1.7",
+    "knip": "^5.82.1",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.3.0",
+    "react": "^19.2.4",
+    "socket.io-client": "^4.8.3",
+    "typescript": "^5.9.0",
+    "typescript-eslint": "^8.56.0",
+    "vitest": "^4.0.18"
+  }
+}

package/packages/cache/README.md

@@ -0,0 +1,114 @@
+# @orkify/cache
+
+[![npm](https://img.shields.io/npm/v/@orkify/cache)](https://www.npmjs.com/package/@orkify/cache)
+[![Node](https://img.shields.io/node/v/orkify)](https://nodejs.org/)
+[![License](https://img.shields.io/npm/l/orkify)](https://github.com/orkify/orkify/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-%E2%89%A55.9-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
+Framework-agnostic shared cache for [orkify](https://orkify.com)-managed Node.js processes.
+
+## Installation
+
+```bash
+npm install @orkify/cache
+```
+
+## Usage
+
+```typescript
+import { cache } from '@orkify/cache';
+
+// Set a value
+cache.set('user:123', { name: 'Alice', role: 'admin' });
+
+// Set with TTL (seconds) and tags
+cache.set('post:456', postData, { ttl: 300, tags: ['posts', 'user:123'] });
+
+// Get a value (synchronous, local memory)
+const user = cache.get<User>('user:123');
+
+// Get with async fallback (checks file-backed cold layer)
+const post = await cache.getAsync<Post>('post:456');
+
+// Check existence
+cache.has('user:123');
+
+// Delete + broadcast to all workers
+cache.delete('user:123');
+
+// Clear all entries + broadcast
+cache.clear();
+
+// Invalidate all entries with a tag + record timestamp
+cache.invalidateTag('posts');
+
+// Query when a tag was last invalidated
+cache.getTagExpiration(['posts']);
+
+// Record a timestamp without deleting entries (stale-while-revalidate)
+cache.updateTagTimestamp('posts');
+
+// Cache stats
+const stats = cache.stats();
+// { size, hits, misses, hitRate, totalBytes, diskSize }
+```
+
+`get()` reads from memory only — always sync, zero overhead. `getAsync()` checks memory first, then falls back to disk if file-backed mode is enabled.
+
+## Configuration
+
+Optional — call `cache.configure()` before the first use, or defaults apply:
+
+```typescript
+import { cache } from '@orkify/cache';
+
+cache.configure({
+  maxEntries: 50_000, // Default: 10,000
+  defaultTtl: 300, // Default: undefined (no expiry, seconds)
+  maxMemorySize: 128 * 1024 * 1024, // Default: 64 MB per worker
+  maxValueSize: 2 << 20, // Default: 1 MB
+  fileBacked: true, // Default: true — evicted entries spill to disk
+});
+```
+
+| Option          | Default                 | Description                                                              |
+| --------------- | ----------------------- | ------------------------------------------------------------------------ |
+| `maxEntries`    | `10,000`                | Maximum entries before LRU eviction kicks in                             |
+| `defaultTtl`    | `undefined` (no expiry) | Default TTL in seconds for entries without an explicit `ttl`             |
+| `maxMemorySize` | `64 MB`                 | Maximum memory per worker before byte-based LRU eviction                 |
+| `maxValueSize`  | `1 MB`                  | Maximum byte size of a single value (rejects larger with an error)       |
+| `fileBacked`    | `true`                  | Persist evicted entries to disk, survive restarts, read via `getAsync()` |
+
+## How It Works
+
+| Mode                       | Behavior                                                |
+| -------------------------- | ------------------------------------------------------- |
+| `npm run dev` (standalone) | Local cache + disk cold layer, no IPC                   |
+| `orkify up -w 1` (fork)    | Local cache + disk cold layer, no IPC                   |
+| `orkify up -w 4` (cluster) | Broadcast cache — writes sync via IPC, reads stay local |
+| `orkify run` (foreground)  | Local cache + disk cold layer, no IPC                   |
+
+The API is identical in every mode. In standalone or fork mode, it degrades gracefully to a plain local cache — no errors, no code changes needed. Deploy with `orkify up -w 4` and the same code syncs across workers automatically.
+
+## Features
+
+- LRU eviction (entry-count and byte-based)
+- TTL expiration
+- Tag-based group invalidation with timestamps
+- V8 serialization (supports Map, Set, Date, RegExp, Error, ArrayBuffer, TypedArray)
+- Value validation — rejects functions, symbols, and oversized values with descriptive errors
+- Two-tier architecture: hot memory layer + cold file-backed layer
+- Cluster-safe: automatic IPC synchronization across workers
+- Snapshots sent to new workers on spawn
+- Eventual consistency: other workers may read stale values for one IPC round trip after a write
+
+For full details on eviction, persistence lifecycle, and cluster behavior, see the [main orkify README](https://github.com/orkify/orkify#shared-cluster-cache).
+
+## Requirements
+
+- Node.js 22+
+- Must run under [orkify](https://github.com/orkify/orkify) for cluster mode features
+
+## License
+
+Apache-2.0

package/packages/cache/dist/CacheClient.d.ts

@@ -0,0 +1,26 @@
+import type { CacheConfig, CacheSetOptions, CacheStats } from './types.js';
+export declare class CacheClient {
+    private clusterMode;
+    private defaultTtl;
+    private maxValueSize;
+    private messageHandler;
+    private store;
+    constructor(config?: CacheConfig, bufferedMessages?: unknown[]);
+    /** Configure cache options. Must be called before any other method. Intercepted by the proxy in `cache/index.ts`. */
+    configure(_config: CacheConfig): void;
+    get<T>(key: string): T | undefined;
+    getAsync<T>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown, opts?: CacheSetOptions): void;
+    delete(key: string): void;
+    clear(): void;
+    has(key: string): boolean;
+    stats(): CacheStats;
+    getTagExpiration(tags: string[]): number;
+    invalidateTag(tag: string): void;
+    updateTagTimestamp(tag: string, timestamp?: number): void;
+    destroy(): void;
+    /** Send an IPC message to the cluster primary, silently ignoring failures (e.g. closed channel). */
+    private trySend;
+    private handleMessage;
+}
+//# sourceMappingURL=CacheClient.d.ts.map

package/packages/cache/dist/CacheClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheClient.d.ts","sourceRoot":"","sources":["../src/CacheClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAMV,WAAW,EACX,eAAe,EAEf,UAAU,EAEX,MAAM,YAAY,CAAC;AAcpB,qBAAa,WAAW;IACtB,OAAO,CAAC,WAAW,CAAU;IAC7B,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,cAAc,CAAuC;IAC7D,OAAO,CAAC,KAAK,CAAc;gBAEf,MAAM,CAAC,EAAE,WAAW,EAAE,gBAAgB,CAAC,EAAE,OAAO,EAAE;IAiE9D,qHAAqH;IACrH,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAIrC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAI5B,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAItD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,IAAI;IAwB9D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAQzB,KAAK,IAAI,IAAI;IAQb,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,KAAK,IAAI,UAAU;IAInB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM;IAIxC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAQhC,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IASzD,OAAO,IAAI,IAAI;IAQf,oGAAoG;IACpG,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,aAAa;CA8BtB"}