@kici-dev/orchestrator 0.0.0 → 0.1.2

package/dist/cli/commands/source.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Source management commands for kici-admin.
+ *
+ * Provides subcommands for webhook source CRUD:
+ *   source add github         Add a new GitHub App source
+ *   source add generic        Add a new generic webhook source
+ *   source list               List all configured sources
+ *   source get <id>           Get details of a specific generic source
+ *   source update <routingKey> Update a GitHub source
+ *   source update-generic <id> Update a generic source
+ *   source remove <routingKey> Remove a source (GitHub or generic with --generic flag)
+ *   source enable <id>        Enable a generic source
+ *   source disable <id>       Disable a generic source
+ *
+ * Supports multiple secret input modes:
+ *   --private-key <value>      Direct value
+ *   --private-key @/path/file  Read from file (@ prefix)
+ *   --from-env <VAR_NAME>      Read from environment variable
+ *   --stdin                    Read from stdin
+ */
+import type { Command } from 'commander';
+import type { AdminApiClient } from '../api-client.js';
+export declare function registerSourceCommands(program: Command, getClient: () => AdminApiClient): void;
+//# sourceMappingURL=source.d.ts.map

package/dist/cli/commands/token.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Token management commands for kici-admin.
+ *
+ * Provides CRUD operations for admin API tokens:
+ *   token create, list, revoke
+ */
+import type { Command } from 'commander';
+import type { AdminApiClient } from '../api-client.js';
+export declare function registerTokenCommands(program: Command, getClient: () => AdminApiClient): void;
+//# sourceMappingURL=token.d.ts.map

package/dist/cli/commands/workflow.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Workflow registration commands for kici-admin.
+ *
+ * Provides operator-facing read access to the workflow_registrations table
+ * via the orchestrator's admin HTTP API. This is the dogfooded replacement
+ * for "let me just psql the registration table" — every CLI subcommand here
+ * goes through AdminApiClient and the existing /api/v1/admin/registrations
+ * route.
+ *
+ *   workflow list                List registered workflows (table or JSON)
+ *
+ * Filter flags map 1:1 to the route's query string params:
+ *   --org              -> ?customerId=<id>
+ *   --routing-key      -> ?routingKey=<key>
+ *   --repo             -> ?repoIdentifier=<owner/repo>
+ *   --trigger-type     -> ?triggerType=<type>
+ *   --event            -> ?event=<eventName>
+ *
+ * Output:
+ *   default            Aligned ASCII table with id, repo_identifier,
+ *                      workflow_name, trigger_types, events, disabled
+ *                      (plus org_id when --org is omitted)
+ *   --json             Raw JSON.stringify of the full response
+ */
+import type { Command } from 'commander';
+import type { AdminApiClient } from '../api-client.js';
+/**
+ * Register the `workflow` command group with kici-admin.
+ */
+export declare function registerWorkflowCommands(program: Command, getClient: () => AdminApiClient): void;
+//# sourceMappingURL=workflow.d.ts.map

package/dist/cli/join.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `kici-admin join` command.
+ *
+ * Bootstraps a new orchestrator by connecting to an existing cluster via
+ * Platform relay or direct peer, receiving an encrypted config bundle, and
+ * writing the local YAML config.
+ *
+ * Usage:
+ *   kici-admin join --token kici_join_v1.xxx.yyy --platform wss://platform.kici.dev/ws --api-key KEY
+ *   kici-admin join --token kici_join_v1.xxx.yyy --peer https://orch-1:8080
+ */
+import type { Command } from 'commander';
+export declare function registerJoinCommand(program: Command): void;
+//# sourceMappingURL=join.d.ts.map

package/dist/cli/kici-admin.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * kici-admin CLI binary.
+ *
+ * Manages secrets, tokens, key rotation, and audit logs
+ * through the orchestrator's admin HTTP API.
+ *
+ * Global options:
+ *   --url / -u    Orchestrator URL (env: KICI_ADMIN_URL, default: http://localhost:8080)
+ *   --token / -t  Admin API token (env: KICI_ADMIN_TOKEN, required)
+ */
+export {};
+//# sourceMappingURL=kici-admin.d.ts.map

package/dist/cli/lazy-deps/cache.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Cache directory management for lazy dependencies.
+ *
+ * Provides cache path resolution and cleanup.
+ */
+/**
+ * Get the base cache directory path for lazy dependencies.
+ * Delegates to platform-detect's getCacheDir() for platform-appropriate paths.
+ */
+export declare function getCacheBasePath(): string;
+/**
+ * Remove all cached dependencies.
+ *
+ * @param cacheDir - Cache directory to clean (from getCacheBasePath())
+ */
+export declare function cleanCache(cacheDir: string): void;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cli/lazy-deps/downloader.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Lazy dependency downloader with integrity verification.
+ *
+ * Downloads, verifies SHA-256 integrity, extracts archives, and caches
+ * dependencies for offline use. Uses atomic rename to prevent partial
+ * downloads from polluting the cache.
+ */
+import type { LazyDep } from './registry.js';
+/**
+ * Verify SHA-256 integrity of downloaded content.
+ *
+ * @param content - Downloaded file contents as a Buffer
+ * @param expectedHash - Expected SHA-256 hex digest
+ * @throws If the hash does not match
+ */
+export declare function verifyIntegrity(content: Buffer, expectedHash: string): void;
+/**
+ * Ensure a lazy dependency is available in the cache.
+ *
+ * Flow:
+ * 1. Check if already cached -> return path immediately
+ * 2. Download from URL to temp directory
+ * 3. Verify SHA-256 integrity
+ * 4. Extract archive
+ * 5. Atomic rename to final cache location
+ * 6. Return path to cached dependency
+ *
+ * @param dep - Dependency metadata from the registry
+ * @param cacheDir - Base cache directory
+ * @returns Path to the cached dependency
+ */
+export declare function ensureDep(dep: LazyDep, cacheDir: string): Promise<string>;
+//# sourceMappingURL=downloader.d.ts.map

package/dist/cli/lazy-deps/registry.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Metadata registry for lazy dependencies.
+ *
+ * Each entry describes a downloadable dependency with platform/arch variants,
+ * URLs, SHA-256 integrity hashes, and extraction details.
+ */
+/** Metadata for a single lazy dependency variant. */
+export interface LazyDep {
+    /** Dependency name (e.g., "rolldown", "shawl"). */
+    name: string;
+    /** Version string. */
+    version: string;
+    /** Target Node.js platform. */
+    platform: NodeJS.Platform;
+    /** Target architecture (x64, arm64). */
+    arch: string;
+    /** Download URL. */
+    url: string;
+    /** Expected SHA-256 hash of the downloaded archive. */
+    sha256: string;
+    /** Relative path inside the archive to the binary/directory. */
+    extractPath: string;
+    /** Archive type for extraction. */
+    archiveType: 'tar.gz' | 'zip' | 'binary';
+}
+/**
+ * Platform+arch key used for variant lookup.
+ * Format: `${platform}-${arch}` (e.g., "linux-x64", "darwin-arm64").
+ */
+type VariantKey = `${NodeJS.Platform}-${string}`;
+/** Registry of all lazy dependencies keyed by name, then platform-arch. */
+export declare const LAZY_DEPS: Record<string, Record<VariantKey, LazyDep>>;
+/**
+ * Get dependency metadata for the current (or specified) platform and architecture.
+ *
+ * @param name - Dependency name (e.g., "rolldown", "shawl")
+ * @param platform - Override platform (default: os.platform())
+ * @param arch - Override arch (default: process.arch)
+ * @throws If the dependency or variant is not found in the registry
+ */
+export declare function getDepMetadata(name: string, platform?: NodeJS.Platform, arch?: string): LazyDep;
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/cli/service/compose.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Docker/Podman Compose service manager.
+ *
+ * Generates compose YAML files and manages service lifecycle via
+ * `docker compose` or `podman compose` (auto-detected). Provides
+ * a container-based service management backend that works on any
+ * platform with Docker or Podman installed.
+ */
+import type { ServiceManager, ServiceConfig, ServiceStatus, LogOptions } from './types.js';
+export declare class ComposeServiceManager implements ServiceManager {
+    private runtime;
+    /** Get the runtime command, detecting it if not already done. */
+    private getRuntime;
+    /** Run a compose command for the given service config. */
+    private runCompose;
+    install(config: ServiceConfig): Promise<void>;
+    uninstall(config: ServiceConfig): Promise<void>;
+    start(config: ServiceConfig): Promise<void>;
+    stop(config: ServiceConfig): Promise<void>;
+    restart(config: ServiceConfig): Promise<void>;
+    status(config: ServiceConfig): Promise<ServiceStatus>;
+    logs(config: ServiceConfig, options: LogOptions): Promise<void>;
+    isInstalled(config: ServiceConfig): Promise<boolean>;
+}
+//# sourceMappingURL=compose.d.ts.map

package/dist/cli/service/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Service management entry point.
+ *
+ * Re-exports all types and provides a factory function that returns
+ * the correct ServiceManager implementation for the detected (or
+ * specified) platform. Uses dynamic imports to avoid loading all
+ * platform-specific code on every platform.
+ */
+export type { ServiceManager, ServiceConfig, ServiceStatus, ServiceState, ServicePlatform, RestartPolicy, LogOptions, } from './types.js';
+export { DEFAULT_RESTART_POLICY } from './types.js';
+export { detectPlatform, isRoot, getConfigDir, getLogDir, getCacheDir } from './platform-detect.js';
+import type { ServiceManager, ServicePlatform } from './types.js';
+/**
+ * Create a ServiceManager for the given platform.
+ *
+ * Uses dynamic imports so only the relevant platform code is loaded.
+ * For example, on Linux only the systemd module is imported, not
+ * Windows or launchd code.
+ *
+ * @param platform - Target platform (from detectPlatform() or --platform flag)
+ * @returns The appropriate ServiceManager implementation
+ */
+export declare function createServiceManager(platform: ServicePlatform): Promise<ServiceManager>;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/service/launchd.d.ts

@@ -0,0 +1,34 @@
+/**
+ * launchd service manager implementation.
+ *
+ * Generates plist files and manages service lifecycle via launchctl.
+ * Supports both system-level (/Library/LaunchDaemons/) and
+ * user-level (~/Library/LaunchAgents/) agents.
+ */
+import type { ServiceConfig, ServiceManager, ServiceStatus, LogOptions } from './types.js';
+export declare class LaunchdServiceManager implements ServiceManager {
+    /** Build the launchd label for a service. */
+    private label;
+    /** Resolve the log directory based on service level. */
+    private logDir;
+    /** Resolve the plist file path based on service level. */
+    private plistPath;
+    /** Parse a .env file into key-value pairs. */
+    private parseEnvFile;
+    /** Escape XML special characters. */
+    private escapeXml;
+    /**
+     * Generate a launchd plist XML string from a service config.
+     * Visible for testing.
+     */
+    generatePlist(config: ServiceConfig): string;
+    install(config: ServiceConfig): Promise<void>;
+    uninstall(config: ServiceConfig): Promise<void>;
+    start(config: ServiceConfig): Promise<void>;
+    stop(config: ServiceConfig): Promise<void>;
+    restart(config: ServiceConfig): Promise<void>;
+    status(config: ServiceConfig): Promise<ServiceStatus>;
+    logs(config: ServiceConfig, options: LogOptions): Promise<void>;
+    isInstalled(config: ServiceConfig): Promise<boolean>;
+}
+//# sourceMappingURL=launchd.d.ts.map

package/dist/cli/service/platform-detect.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Platform detection and directory resolution for KiCI service management.
+ *
+ * Detects the init system (systemd, launchd, Windows Services, or Compose fallback)
+ * and resolves platform-appropriate directories for config, logs, and cache.
+ */
+import type { ServicePlatform } from './types.js';
+/**
+ * Detect the service management platform.
+ *
+ * Auto-detection order:
+ * - win32 -> 'windows'
+ * - darwin -> 'launchd'
+ * - linux with /run/systemd/system or /sys/fs/cgroup/systemd -> 'systemd'
+ * - linux without systemd -> 'compose' (Docker/Podman Compose fallback)
+ *
+ * @param override - Force a specific platform (e.g., from --platform flag)
+ */
+export declare function detectPlatform(override?: ServicePlatform): ServicePlatform;
+/**
+ * Check if the current process has root/admin privileges.
+ *
+ * - Unix: UID === 0
+ * - Windows: attempts `net session` (succeeds only as admin)
+ */
+export declare function isRoot(): boolean;
+/**
+ * Get the configuration directory for a KiCI service.
+ *
+ * Paths follow platform conventions:
+ * - System Linux/macOS: /etc/kici/
+ * - User Linux: ~/.config/kici/
+ * - User macOS: ~/Library/Application Support/kici/
+ * - System Windows: C:\ProgramData\kici\
+ * - User Windows: %LOCALAPPDATA%\kici\
+ */
+export declare function getConfigDir(_serviceName: string, isUserLevel: boolean): string;
+/**
+ * Get the log directory for a KiCI service.
+ *
+ * Paths follow platform conventions:
+ * - System Linux/macOS: /var/log/kici/
+ * - User Linux: ~/.local/share/kici/logs/
+ * - User macOS: ~/Library/Logs/kici/
+ * - Windows: C:\ProgramData\kici\logs\
+ */
+export declare function getLogDir(_serviceName: string, isUserLevel: boolean): string;
+/**
+ * Get the cache directory for lazy dependency downloads.
+ *
+ * Resolution order:
+ * 1. $XDG_CACHE_HOME/kici/deps/ (if set)
+ * 2. Platform default:
+ *    - Linux: ~/.cache/kici/deps/
+ *    - macOS: ~/Library/Caches/kici/deps/
+ *    - Windows: %LOCALAPPDATA%\kici\deps\
+ */
+export declare function getCacheDir(): string;
+//# sourceMappingURL=platform-detect.d.ts.map

package/dist/cli/service/systemd.d.ts

@@ -0,0 +1,41 @@
+/**
+ * systemd service manager implementation.
+ *
+ * Generates unit files and manages service lifecycle via systemctl,
+ * journalctl, and loginctl commands. Supports both system-level
+ * (/etc/systemd/system/) and user-level (~/.config/systemd/user/) services.
+ */
+import type { ServiceConfig, ServiceManager, ServiceStatus, LogOptions } from './types.js';
+/**
+ * Check whether linger is already enabled for a user.
+ *
+ * Uses `loginctl show-user <user>` which is readable by any user. Returns
+ * true if the user's `Linger` property reads `yes`. Returns false on any
+ * parse failure, missing binary, or unknown user — the caller is expected
+ * to attempt `enable-linger` in that case.
+ *
+ * Exported (package-private) for testing.
+ */
+export declare function isLingerEnabled(user: string): boolean;
+export declare class SystemdServiceManager implements ServiceManager {
+    /**
+     * Generate a systemd unit file from a service config.
+     * Visible for testing.
+     */
+    generateUnitFile(config: ServiceConfig): string;
+    /** Resolve the unit file path based on service level. */
+    private unitFilePath;
+    /** Build systemctl command args, inserting --user for user-level services. */
+    private systemctlArgs;
+    /** Run a systemctl command. */
+    private systemctl;
+    install(config: ServiceConfig): Promise<void>;
+    uninstall(config: ServiceConfig): Promise<void>;
+    start(config: ServiceConfig): Promise<void>;
+    stop(config: ServiceConfig): Promise<void>;
+    restart(config: ServiceConfig): Promise<void>;
+    status(config: ServiceConfig): Promise<ServiceStatus>;
+    logs(config: ServiceConfig, options: LogOptions): Promise<void>;
+    isInstalled(config: ServiceConfig): Promise<boolean>;
+}
+//# sourceMappingURL=systemd.d.ts.map

package/dist/cli/service/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared types for the service management system.
+ *
+ * Defines the ServiceManager interface contract and supporting types
+ * used by all platform-specific service managers (systemd, launchd,
+ * Windows Services, Docker/Podman Compose).
+ */
+/** Supported service platforms. */
+export type ServicePlatform = 'systemd' | 'launchd' | 'windows' | 'compose';
+/** Restart behavior on service failure. */
+export interface RestartPolicy {
+    /** Whether to restart on failure. */
+    enabled: boolean;
+    /** Backoff delays in seconds between restart attempts. */
+    delays: number[];
+    /** Maximum consecutive failures before giving up. */
+    maxRetries: number;
+    /** Window in seconds for counting consecutive failures. */
+    windowSeconds: number;
+}
+/** Default restart policy: backoff 1s, 5s, 15s, 30s; max 5 failures in 5 minutes. */
+export declare const DEFAULT_RESTART_POLICY: RestartPolicy;
+/** Configuration for installing a service. */
+export interface ServiceConfig {
+    /** Service identifier (e.g., "kici-orchestrator"). */
+    name: string;
+    /** Human-readable display name. */
+    displayName: string;
+    /** Service description. */
+    description: string;
+    /** Path to the executable binary. */
+    executablePath: string;
+    /** Path to the environment file (.env). */
+    envFilePath: string;
+    /** Working directory for the service process. */
+    workingDirectory: string;
+    /** User to run the service as (Unix only). */
+    user?: string;
+    /** Whether this is a user-level (non-root) service. */
+    isUserLevel: boolean;
+    /** Restart policy configuration. */
+    restartPolicy: RestartPolicy;
+}
+/** Current state of a service. */
+export type ServiceState = 'running' | 'stopped' | 'failed' | 'unknown';
+/** Runtime status information for a service. */
+export interface ServiceStatus {
+    /** Current service state. */
+    state: ServiceState;
+    /** Process ID if running. */
+    pid?: number;
+    /** Uptime in seconds if running. */
+    uptime?: number;
+    /** ISO timestamp when the service last started. */
+    startedAt?: string;
+}
+/** Options for the logs command. */
+export interface LogOptions {
+    /** Show logs since this duration (e.g., "1h", "30m"). */
+    since?: string;
+    /** Filter by log level. */
+    level?: 'error' | 'warn' | 'info';
+    /** Output as JSON lines. */
+    json?: boolean;
+    /** Follow (tail -f) mode. */
+    follow?: boolean;
+}
+/**
+ * Interface that all platform-specific service managers must implement.
+ *
+ * Each method operates on a service identified by the ServiceConfig.
+ */
+export interface ServiceManager {
+    /** Install and register the service with the init system. */
+    install(config: ServiceConfig): Promise<void>;
+    /** Remove the service registration (preserves config/data). */
+    uninstall(config: ServiceConfig): Promise<void>;
+    /** Start the service. */
+    start(config: ServiceConfig): Promise<void>;
+    /** Stop the service. */
+    stop(config: ServiceConfig): Promise<void>;
+    /** Restart the service (stop + start). */
+    restart(config: ServiceConfig): Promise<void>;
+    /** Get the current service status. */
+    status(config: ServiceConfig): Promise<ServiceStatus>;
+    /** Stream or display service logs. */
+    logs(config: ServiceConfig, options: LogOptions): Promise<void>;
+    /** Check if the service is currently installed/registered. */
+    isInstalled(config: ServiceConfig): Promise<boolean>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cli/service/windows.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Windows service manager using shawl + sc.exe.
+ *
+ * Uses shawl (https://github.com/mtkennerly/shawl) to wrap the KiCI
+ * executable as a Windows service. Shawl is downloaded as a lazy
+ * dependency on first use. Service configuration (auto-start, recovery)
+ * is handled via sc.exe.
+ */
+import type { ServiceManager, ServiceConfig, ServiceStatus, LogOptions } from './types.js';
+export declare class WindowsServiceManager implements ServiceManager {
+    install(config: ServiceConfig): Promise<void>;
+    uninstall(config: ServiceConfig): Promise<void>;
+    start(config: ServiceConfig): Promise<void>;
+    stop(config: ServiceConfig): Promise<void>;
+    restart(config: ServiceConfig): Promise<void>;
+    status(config: ServiceConfig): Promise<ServiceStatus>;
+    logs(config: ServiceConfig, _options: LogOptions): Promise<void>;
+    isInstalled(config: ServiceConfig): Promise<boolean>;
+}
+//# sourceMappingURL=windows.d.ts.map

package/dist/cli/wizard/agent-wizard.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Interactive wizard for agent service setup.
+ *
+ * Walks the user through essential agent configuration
+ * (orchestrator URL, token, labels). Returns a config object
+ * that the install command uses to write the env file.
+ */
+/** Config produced by the agent wizard. */
+interface AgentInstallConfig {
+    orchestratorUrl: string;
+    agentToken: string;
+    labels: string[];
+}
+/**
+ * Run the interactive agent setup wizard.
+ *
+ * Asks only essential questions:
+ * 1. Orchestrator URL
+ * 2. Agent authentication token
+ * 3. Labels (optional, comma-separated)
+ */
+export declare function runAgentWizard(): Promise<AgentInstallConfig>;
+export {};
+//# sourceMappingURL=agent-wizard.d.ts.map

package/dist/cli/wizard/orchestrator-wizard.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Interactive wizard for orchestrator service setup.
+ *
+ * Walks the user through essential configuration (mode, DB URL,
+ * port, secrets key) with sensible defaults. Returns a config
+ * object that the install command uses to write the env file.
+ */
+/** Config produced by the orchestrator wizard. */
+interface OrchestratorInstallConfig {
+    mode: 'platform' | 'hybrid' | 'independent';
+    databaseUrl: string;
+    port: number;
+    secretsKey: string;
+    platformUrl?: string;
+    platformToken?: string;
+    /** Source to add after orchestrator is running. */
+    source?: {
+        provider: string;
+        name: string;
+        appId: string;
+        privateKey: string;
+        webhookSecret?: string;
+    };
+}
+/**
+ * Run the interactive orchestrator setup wizard.
+ *
+ * Asks only essential questions per the user decision:
+ * 1. Mode (platform/hybrid/independent)
+ * 2. Database URL
+ * 3. Port
+ * 4. Secrets encryption key
+ * 5. Platform URL + token (if platform/hybrid mode)
+ * 6. Webhook secret (if hybrid/independent mode)
+ */
+export declare function runOrchestratorWizard(): Promise<OrchestratorInstallConfig>;
+export {};
+//# sourceMappingURL=orchestrator-wizard.d.ts.map

package/dist/cli/wizard/prompts.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared prompt utilities for the setup wizards.
+ *
+ * Wraps @inquirer/prompts with consistent formatting and
+ * validation for common input types (DB URLs, ports, etc.).
+ */
+/** Prompt for a PostgreSQL database URL with validation. */
+export declare function promptDbUrl(): Promise<string>;
+/** Prompt for a port number with validation. */
+export declare function promptPort(defaultPort: number): Promise<number>;
+/** Prompt for a yes/no confirmation. */
+export declare function promptConfirm(message: string, defaultValue?: boolean): Promise<boolean>;
+/** Prompt for a URL with http(s):// validation. */
+export declare function promptUrl(message: string, defaultValue?: string): Promise<string>;
+/** Prompt for a secret/password (masked input). */
+export declare function promptSecret(message: string): Promise<string>;
+/** Prompt for a selection from a list of options. */
+export declare function promptSelect<T extends string>(message: string, choices: {
+    name: string;
+    value: T;
+    description?: string;
+}[], defaultValue?: T): Promise<T>;
+//# sourceMappingURL=prompts.d.ts.map