@noego/captain 1.0.2 → 1.1.1

package/README.md

@@ -174,6 +174,37 @@ Each task supports the following options:
 - **Data processing**: Schedule batch processing of data at regular intervals
 - **Service coordination**: Trigger API calls or service interactions on a schedule
 
+## Using Captain as a Library
+
+Captain's scheduler can be embedded in your own application without starting the CLI. Import from the `@noego/captain/scheduler` entry point — it is side-effect free (no argument parsing, no `.env` loading, no CLI container) and ships with generated TypeScript declarations.
+
+```typescript
+import { Scheduler, type TaskDefinition } from '@noego/captain/scheduler';
+import * as winston from 'winston';
+
+const logger = winston.createLogger({ transports: [new winston.transports.Console()] });
+const scheduler = new Scheduler(logger);
+
+const task: TaskDefinition = { schedule: '*/5 * * * *', description: 'Every five minutes' };
+
+scheduler.scheduleTask('heartbeat', task, async () => {
+  console.log('tick');
+});
+
+// Later
+scheduler.stopTask('heartbeat');
+scheduler.stopAllTasks();
+```
+
+CommonJS works too: `const { Scheduler } = require('@noego/captain/scheduler')`.
+
+Exports: `Scheduler`, and the types `TaskDefinition` (alias `CaptainTaskDefinition`), `Config`, `TasksFile`.
+
+Do **not** import the package root (`@noego/captain`) as a library — it is the CLI entry and runs `main()` on load. Existing deep imports such as `@noego/captain/dist/components/scheduler` still resolve, but `@noego/captain/scheduler` is the supported path.
+
+If you bundle your application (Vite, esbuild, Rollup), externalize Captain including its subpaths, e.g. `/^@noego\/captain(?:\/|$)/`, rather than only the bare package name.
+
+
 ## Developing with Captain
 
 For developers who want to modify or extend Captain:

package/dist/components/cli.d.ts

@@ -0,0 +1,19 @@
+import * as winston from 'winston';
+import { Parser } from './parser';
+import { Scheduler } from './scheduler';
+import { Executor } from './executor';
+export declare class CLI {
+    private logger;
+    private parser;
+    private scheduler;
+    private executor;
+    private program;
+    private readonly trace;
+    constructor(logger: winston.Logger, parser: Parser, scheduler: Scheduler, executor: Executor);
+    setup(): void;
+    processFiles(files: string[], options: any): Promise<void>;
+    private listTasks;
+    private runSingleTask;
+    private scheduleTasks;
+    parse(argv: string[]): void;
+}

package/dist/components/executor.d.ts

@@ -0,0 +1,11 @@
+import { TaskDefinition } from '../models/task';
+import * as winston from 'winston';
+export declare class Executor {
+    private logger;
+    private runningTasks;
+    private readonly trace;
+    constructor(logger: winston.Logger);
+    executeTask(taskName: string, taskDef: TaskDefinition): Promise<boolean>;
+    private checkConcurrency;
+    private removeRunningTask;
+}

package/dist/components/parser.d.ts

@@ -0,0 +1,9 @@
+import { TasksFile } from '../models/task';
+import * as winston from 'winston';
+export declare class Parser {
+    private logger;
+    private readonly trace;
+    constructor(logger: winston.Logger);
+    parseFile(filePath: string): Promise<TasksFile>;
+    validateTask(taskName: string, task: any): boolean;
+}

package/dist/components/scheduler.d.ts

@@ -0,0 +1,15 @@
+import { TaskDefinition } from '../models/task';
+export interface SchedulerLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+export declare class Scheduler {
+    private logger;
+    private schedules;
+    private readonly trace;
+    constructor(logger: SchedulerLogger);
+    scheduleTask(taskName: string, taskDef: TaskDefinition, callback: () => Promise<void>): boolean;
+    stopTask(taskName: string): boolean;
+    stopAllTasks(): void;
+}

package/dist/container.d.ts

@@ -0,0 +1 @@
+export declare function initializeContainer(): import("@noego/ioc").IContainerClient & import("@noego/ioc").IContainerSetup;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/models/task.d.ts

@@ -0,0 +1,27 @@
+export interface TaskDefinition {
+    description?: string;
+    schedule: string;
+    file?: string;
+    command?: string;
+    timeout?: number;
+    concurrency?: {
+        max?: number;
+        allow_overlap?: boolean;
+    };
+    retry?: {
+        attempts?: number;
+        backoff?: "fixed" | "exponential";
+        delay?: number;
+    };
+    env?: Record<string, string>;
+}
+export interface Config {
+    default_timeout?: number;
+    max_concurrency?: number;
+    timezone?: string;
+    log_level?: "debug" | "info" | "warn" | "error";
+}
+export interface TasksFile {
+    tasks: Record<string, TaskDefinition>;
+    config?: Config;
+}

package/dist/scheduler.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Public, side-effect-free library entry point for the Captain scheduler.
+ *
+ * Importing this module never starts the CLI, parses process arguments,
+ * loads environment files, or initializes the CLI IoC container.
+ *
+ *   import { Scheduler } from '@noego/captain/scheduler';
+ */
+export { Scheduler } from './components/scheduler';
+export type { TaskDefinition, Config, TasksFile } from './models/task';
+/** Alias of {@link TaskDefinition} for consumers that prefer a namespaced name. */
+export type { TaskDefinition as CaptainTaskDefinition } from './models/task';

package/dist/scheduler.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Scheduler = void 0;
+/**
+ * Public, side-effect-free library entry point for the Captain scheduler.
+ *
+ * Importing this module never starts the CLI, parses process arguments,
+ * loads environment files, or initializes the CLI IoC container.
+ *
+ *   import { Scheduler } from '@noego/captain/scheduler';
+ */
+var scheduler_1 = require("./components/scheduler");
+Object.defineProperty(exports, "Scheduler", { enumerable: true, get: function () { return scheduler_1.Scheduler; } });

package/package.json

@@ -1,10 +1,24 @@
 {
   "name": "@noego/captain",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "YAML-driven task runner for TypeScript files",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./scheduler": {
+      "types": "./dist/scheduler.d.ts",
+      "default": "./dist/scheduler.js"
+    },
+    "./dist/*": "./dist/*.js",
+    "./package.json": "./package.json",
+    "./dist/*.js": "./dist/*.js"
+  },
   "bin": {
-    "captain": "./bin/captain.js"
+    "captain": "bin/captain.js"
   },
   "files": [
     "dist",
@@ -35,8 +49,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@noego/ioc": "^0.3.1",
-    "@noego/trace": "^0.0.4",
+    "@noego/ioc": "^0.8.0",
+    "@noego/trace": "^0.2.0",
     "commander": "^13.1.0",
     "dotenv": "^16.5.0",
     "js-yaml": "^4.1.0",