@hotmeshio/long-tail 0.1.13 → 0.1.15

package/build/api/yaml-workflows/deploy.js

@@ -0,0 +1,223 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deployYamlWorkflow = deployYamlWorkflow;
+exports.activateYamlWorkflow = activateYamlWorkflow;
+exports.invokeYamlWorkflow = invokeYamlWorkflow;
+exports.archiveYamlWorkflow = archiveYamlWorkflow;
+exports.restoreYamlWorkflow = restoreYamlWorkflow;
+const yamlDb = __importStar(require("../../services/yaml-workflow/db"));
+const yamlDeployer = __importStar(require("../../services/yaml-workflow/deployer"));
+const yamlWorkers = __importStar(require("../../services/yaml-workflow/workers"));
+const invoke_1 = require("../../services/yaml-workflow/invoke");
+const helpers_1 = require("./helpers");
+/**
+ * Deploy a YAML workflow and all sibling workflows sharing its app_id namespace.
+ *
+ * Merges and deploys the full app_id YAML, registers HotMesh workers for every
+ * non-archived sibling, transitions draft/deployed siblings to active, and marks
+ * the app_id content as deployed. Uses the app_version declared in the workflow record.
+ *
+ * @param input.id — UUID of the workflow to deploy
+ * @returns `{ status: 200, data: YamlWorkflow }` the refreshed workflow record after deployment
+ */
+async function deployYamlWorkflow(input) {
+    try {
+        const wf = await yamlDb.getYamlWorkflow(input.id);
+        if (!wf) {
+            return { status: 404, error: 'YAML workflow not found' };
+        }
+        // Compute the next app-level version for the namespace.
+        // Each deploy increments regardless of individual tool versions —
+        // adding a second tool (v1 of itself) to an app already at v1 produces app v2.
+        const deployVersion = await yamlDb.getNextAppVersion(wf.app_id);
+        // Deploy + activate merged YAML for the full app_id
+        const siblings = await yamlDb.listYamlWorkflowsByAppId(wf.app_id);
+        await yamlDeployer.deployAppId(wf.app_id, deployVersion);
+        // Register workers and mark all non-archived siblings as active
+        for (const sibling of siblings) {
+            await yamlDb.updateYamlWorkflowVersion(sibling.id, deployVersion);
+            await yamlWorkers.registerWorkersForWorkflow(sibling);
+            if (sibling.status === 'draft' || sibling.status === 'deployed') {
+                await yamlDb.updateYamlWorkflowStatus(sibling.id, 'active');
+            }
+        }
+        // Mark content as deployed for the entire app_id
+        await yamlDb.markAppIdContentDeployed(wf.app_id);
+        const updated = await yamlDb.getYamlWorkflow(input.id);
+        return { status: 200, data: updated };
+    }
+    catch (err) {
+        if ((0, helpers_1.isNotFoundError)(err)) {
+            return { status: 404, error: 'YAML workflow not found' };
+        }
+        return {
+            status: 500,
+            error: err.message,
+        };
+    }
+}
+/**
+ * Activate a previously deployed YAML workflow and its app_id siblings.
+ *
+ * Calls the deployer to activate the app_id at its current version, then registers
+ * HotMesh workers for all sibling workflows. Siblings in "deployed" status are
+ * transitioned to "active". The workflow must already be in deployed or active status.
+ *
+ * @param input.id — UUID of the workflow to activate
+ * @returns `{ status: 200, data: YamlWorkflow }` the refreshed workflow record after activation
+ */
+async function activateYamlWorkflow(input) {
+    try {
+        const wf = await yamlDb.getYamlWorkflow(input.id);
+        if (!wf) {
+            return { status: 404, error: 'YAML workflow not found' };
+        }
+        if (wf.status !== 'deployed' && wf.status !== 'active') {
+            return { status: 400, error: 'Workflow must be deployed before activation' };
+        }
+        await yamlDeployer.activateYamlWorkflow(wf.app_id, wf.app_version);
+        // Register workers for ALL workflows sharing this app_id
+        const siblings = await yamlDb.listYamlWorkflowsByAppId(wf.app_id);
+        for (const sibling of siblings) {
+            await yamlWorkers.registerWorkersForWorkflow(sibling);
+            if (sibling.status === 'deployed') {
+                await yamlDb.updateYamlWorkflowStatus(sibling.id, 'active');
+            }
+        }
+        const updated = await yamlDb.getYamlWorkflow(input.id);
+        return { status: 200, data: updated };
+    }
+    catch (err) {
+        if ((0, helpers_1.isNotFoundError)(err)) {
+            return { status: 404, error: 'YAML workflow not found' };
+        }
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Invoke an active YAML workflow, executing its DAG pipeline.
+ *
+ * The workflow must be in "active" status. Delegates to the invoke service which
+ * starts the HotMesh execution. Supports both synchronous (wait for result) and
+ * asynchronous (fire-and-forget) invocation modes.
+ *
+ * @param input.id — UUID of the workflow to invoke
+ * @param input.data — input payload passed to the workflow's entry point
+ * @param input.sync — when true, block until the workflow completes and return its output
+ * @param input.timeout — max milliseconds to wait when sync is true
+ * @param input.execute_as — override identity for the execution context
+ * @param auth — authenticated user context; userId is forwarded to the invoke service
+ * @returns `{ status: 200, data: ... }` workflow execution result (sync) or job metadata (async)
+ */
+async function invokeYamlWorkflow(input, auth) {
+    try {
+        const wf = await yamlDb.getYamlWorkflow(input.id);
+        if (!wf) {
+            return { status: 404, error: 'YAML workflow not found' };
+        }
+        if (wf.status !== 'active') {
+            return { status: 400, error: 'Workflow must be active to invoke' };
+        }
+        const result = await (0, invoke_1.invokeYamlWorkflow)(wf, {
+            data: input.data,
+            sync: input.sync,
+            timeout: input.timeout,
+            execute_as: input.execute_as,
+            userId: auth?.userId,
+        });
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        if ((0, helpers_1.isNotFoundError)(err)) {
+            return { status: 404, error: 'YAML workflow not found' };
+        }
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Archive a YAML workflow, removing it from active service.
+ *
+ * If the workflow is currently active, its HotMesh engine is stopped before
+ * transitioning the status to "archived". Archived workflows cannot be invoked
+ * or regenerated but can still be viewed or deleted.
+ *
+ * @param input.id — UUID of the workflow to archive
+ * @returns `{ status: 200, data: YamlWorkflow }` the updated record with status "archived"
+ */
+async function archiveYamlWorkflow(input) {
+    try {
+        const wf = await yamlDb.getYamlWorkflow(input.id);
+        if (!wf) {
+            return { status: 404, error: 'YAML workflow not found' };
+        }
+        if (wf.status === 'active') {
+            await yamlDeployer.stopEngine(wf.app_id);
+        }
+        const updated = await yamlDb.updateYamlWorkflowStatus(wf.id, 'archived');
+        return { status: 200, data: updated };
+    }
+    catch (err) {
+        if ((0, helpers_1.isNotFoundError)(err)) {
+            return { status: 404, error: 'YAML workflow not found' };
+        }
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Restore an archived YAML workflow back to draft status.
+ *
+ * Transitions the workflow from "archived" to "draft" so it can be
+ * redeployed. The workflow must be in "archived" status.
+ */
+async function restoreYamlWorkflow(input) {
+    try {
+        const wf = await yamlDb.getYamlWorkflow(input.id);
+        if (!wf) {
+            return { status: 404, error: 'YAML workflow not found' };
+        }
+        if (wf.status !== 'archived') {
+            return { status: 400, error: 'Only archived workflows can be restored' };
+        }
+        const updated = await yamlDb.updateYamlWorkflowStatus(wf.id, 'draft');
+        return { status: 200, data: updated };
+    }
+    catch (err) {
+        if ((0, helpers_1.isNotFoundError)(err)) {
+            return { status: 404, error: 'YAML workflow not found' };
+        }
+        return { status: 500, error: err.message };
+    }
+}

package/build/api/yaml-workflows/helpers.d.ts

@@ -0,0 +1,2 @@
+/** Return true if a Postgres error indicates an invalid/missing ID */
+export declare function isNotFoundError(err: any): boolean;

package/build/api/yaml-workflows/helpers.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNotFoundError = isNotFoundError;
+/** Return true if a Postgres error indicates an invalid/missing ID */
+function isNotFoundError(err) {
+    const msg = err?.message ?? '';
+    return msg.includes('invalid input syntax for type uuid') || msg.includes('not found');
+}

package/build/api/yaml-workflows/index.d.ts

@@ -0,0 +1,4 @@
+export { listYamlWorkflows, createYamlWorkflow, createYamlWorkflowDirect, getAppIds, getYamlWorkflow, updateYamlWorkflow, regenerateYamlWorkflow, deleteYamlWorkflow, createYamlWorkflowFromDurable, } from './crud';
+export { deployYamlWorkflow, activateYamlWorkflow, invokeYamlWorkflow, archiveYamlWorkflow, restoreYamlWorkflow, } from './deploy';
+export { getVersionHistory, getVersionSnapshot, getYamlContent, } from './versions';
+export { setCronSchedule, clearCronSchedule, getCronStatus, } from './cron';

package/build/api/yaml-workflows/index.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCronStatus = exports.clearCronSchedule = exports.setCronSchedule = exports.getYamlContent = exports.getVersionSnapshot = exports.getVersionHistory = exports.restoreYamlWorkflow = exports.archiveYamlWorkflow = exports.invokeYamlWorkflow = exports.activateYamlWorkflow = exports.deployYamlWorkflow = exports.createYamlWorkflowFromDurable = exports.deleteYamlWorkflow = exports.regenerateYamlWorkflow = exports.updateYamlWorkflow = exports.getYamlWorkflow = exports.getAppIds = exports.createYamlWorkflowDirect = exports.createYamlWorkflow = exports.listYamlWorkflows = void 0;
+var crud_1 = require("./crud");
+Object.defineProperty(exports, "listYamlWorkflows", { enumerable: true, get: function () { return crud_1.listYamlWorkflows; } });
+Object.defineProperty(exports, "createYamlWorkflow", { enumerable: true, get: function () { return crud_1.createYamlWorkflow; } });
+Object.defineProperty(exports, "createYamlWorkflowDirect", { enumerable: true, get: function () { return crud_1.createYamlWorkflowDirect; } });
+Object.defineProperty(exports, "getAppIds", { enumerable: true, get: function () { return crud_1.getAppIds; } });
+Object.defineProperty(exports, "getYamlWorkflow", { enumerable: true, get: function () { return crud_1.getYamlWorkflow; } });
+Object.defineProperty(exports, "updateYamlWorkflow", { enumerable: true, get: function () { return crud_1.updateYamlWorkflow; } });
+Object.defineProperty(exports, "regenerateYamlWorkflow", { enumerable: true, get: function () { return crud_1.regenerateYamlWorkflow; } });
+Object.defineProperty(exports, "deleteYamlWorkflow", { enumerable: true, get: function () { return crud_1.deleteYamlWorkflow; } });
+Object.defineProperty(exports, "createYamlWorkflowFromDurable", { enumerable: true, get: function () { return crud_1.createYamlWorkflowFromDurable; } });
+var deploy_1 = require("./deploy");
+Object.defineProperty(exports, "deployYamlWorkflow", { enumerable: true, get: function () { return deploy_1.deployYamlWorkflow; } });
+Object.defineProperty(exports, "activateYamlWorkflow", { enumerable: true, get: function () { return deploy_1.activateYamlWorkflow; } });
+Object.defineProperty(exports, "invokeYamlWorkflow", { enumerable: true, get: function () { return deploy_1.invokeYamlWorkflow; } });
+Object.defineProperty(exports, "archiveYamlWorkflow", { enumerable: true, get: function () { return deploy_1.archiveYamlWorkflow; } });
+Object.defineProperty(exports, "restoreYamlWorkflow", { enumerable: true, get: function () { return deploy_1.restoreYamlWorkflow; } });
+var versions_1 = require("./versions");
+Object.defineProperty(exports, "getVersionHistory", { enumerable: true, get: function () { return versions_1.getVersionHistory; } });
+Object.defineProperty(exports, "getVersionSnapshot", { enumerable: true, get: function () { return versions_1.getVersionSnapshot; } });
+Object.defineProperty(exports, "getYamlContent", { enumerable: true, get: function () { return versions_1.getYamlContent; } });
+var cron_1 = require("./cron");
+Object.defineProperty(exports, "setCronSchedule", { enumerable: true, get: function () { return cron_1.setCronSchedule; } });
+Object.defineProperty(exports, "clearCronSchedule", { enumerable: true, get: function () { return cron_1.clearCronSchedule; } });
+Object.defineProperty(exports, "getCronStatus", { enumerable: true, get: function () { return cron_1.getCronStatus; } });

package/build/api/yaml-workflows/versions.d.ts

@@ -0,0 +1,43 @@
+import type { LTApiResult } from '../../types/sdk';
+/**
+ * Retrieve the version history for a YAML workflow.
+ *
+ * Returns a paginated list of version snapshots ordered by version number.
+ *
+ * @param input.id — UUID of the workflow
+ * @param input.limit — max versions to return (defaults to 20)
+ * @param input.offset — pagination offset (defaults to 0)
+ * @returns `{ status: 200, data: VersionSnapshot[] }` paginated version history
+ */
+export declare function getVersionHistory(input: {
+    id: string;
+    limit?: number;
+    offset?: number;
+}): Promise<LTApiResult>;
+/**
+ * Retrieve a specific version snapshot of a YAML workflow.
+ *
+ * Validates that the version number is a positive integer before querying.
+ *
+ * @param input.id — UUID of the workflow
+ * @param input.version — 1-based version number to retrieve
+ * @returns `{ status: 200, data: VersionSnapshot }` the snapshot at the requested version, or 404
+ */
+export declare function getVersionSnapshot(input: {
+    id: string;
+    version: number;
+}): Promise<LTApiResult>;
+/**
+ * Retrieve the raw YAML content for a workflow, optionally at a specific version.
+ *
+ * When a version is provided, fetches from the version snapshot table. Otherwise
+ * returns the current yaml_content from the live workflow record.
+ *
+ * @param input.id — UUID of the workflow
+ * @param input.version — optional version number; when omitted, returns the current content
+ * @returns `{ status: 200, data: string }` the raw YAML string
+ */
+export declare function getYamlContent(input: {
+    id: string;
+    version?: number;
+}): Promise<LTApiResult<string>>;

package/build/api/yaml-workflows/versions.js

@@ -0,0 +1,124 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getVersionHistory = getVersionHistory;
+exports.getVersionSnapshot = getVersionSnapshot;
+exports.getYamlContent = getYamlContent;
+const yamlDb = __importStar(require("../../services/yaml-workflow/db"));
+const helpers_1 = require("./helpers");
+/**
+ * Retrieve the version history for a YAML workflow.
+ *
+ * Returns a paginated list of version snapshots ordered by version number.
+ *
+ * @param input.id — UUID of the workflow
+ * @param input.limit — max versions to return (defaults to 20)
+ * @param input.offset — pagination offset (defaults to 0)
+ * @returns `{ status: 200, data: VersionSnapshot[] }` paginated version history
+ */
+async function getVersionHistory(input) {
+    try {
+        const limit = input.limit ?? 20;
+        const offset = input.offset ?? 0;
+        const result = await yamlDb.getVersionHistory(input.id, limit, offset);
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        if ((0, helpers_1.isNotFoundError)(err)) {
+            return { status: 404, error: 'YAML workflow not found' };
+        }
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Retrieve a specific version snapshot of a YAML workflow.
+ *
+ * Validates that the version number is a positive integer before querying.
+ *
+ * @param input.id — UUID of the workflow
+ * @param input.version — 1-based version number to retrieve
+ * @returns `{ status: 200, data: VersionSnapshot }` the snapshot at the requested version, or 404
+ */
+async function getVersionSnapshot(input) {
+    try {
+        const version = input.version;
+        if (isNaN(version) || version < 1) {
+            return { status: 400, error: 'Invalid version number' };
+        }
+        const snapshot = await yamlDb.getVersionSnapshot(input.id, version);
+        if (!snapshot) {
+            return { status: 404, error: `Version ${version} not found` };
+        }
+        return { status: 200, data: snapshot };
+    }
+    catch (err) {
+        if ((0, helpers_1.isNotFoundError)(err)) {
+            return { status: 404, error: 'YAML workflow not found' };
+        }
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Retrieve the raw YAML content for a workflow, optionally at a specific version.
+ *
+ * When a version is provided, fetches from the version snapshot table. Otherwise
+ * returns the current yaml_content from the live workflow record.
+ *
+ * @param input.id — UUID of the workflow
+ * @param input.version — optional version number; when omitted, returns the current content
+ * @returns `{ status: 200, data: string }` the raw YAML string
+ */
+async function getYamlContent(input) {
+    try {
+        if (input.version) {
+            const snapshot = await yamlDb.getVersionSnapshot(input.id, input.version);
+            if (!snapshot) {
+                return { status: 404, error: `Version ${input.version} not found` };
+            }
+            return { status: 200, data: snapshot.yaml_content };
+        }
+        const wf = await yamlDb.getYamlWorkflow(input.id);
+        if (!wf) {
+            return { status: 404, error: 'YAML workflow not found' };
+        }
+        return { status: 200, data: wf.yaml_content };
+    }
+    catch (err) {
+        if ((0, helpers_1.isNotFoundError)(err)) {
+            return { status: 404, error: 'YAML workflow not found' };
+        }
+        return { status: 500, error: err.message };
+    }
+}

package/build/bin/ltc.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import 'dotenv/config';

package/build/bin/ltc.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Suppress internal logger output in CLI mode
+process.env.LOG_LEVEL = process.env.LOG_LEVEL || 'error';
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+require("dotenv/config");
+const commander_1 = require("commander");
+const picocolors_1 = __importDefault(require("picocolors"));
+const compile_1 = require("../lib/cli/compile");
+const init_1 = require("../lib/cli/init");
+const auth_1 = require("../lib/cli/auth");
+const status_1 = require("../lib/cli/commands/status");
+const esc = __importStar(require("../lib/cli/commands/escalations"));
+const wf = __importStar(require("../lib/cli/commands/workflows"));
+const pip = __importStar(require("../lib/cli/commands/pipelines"));
+const kb = __importStar(require("../lib/cli/commands/knowledge"));
+const mcp = __importStar(require("../lib/cli/commands/mcp"));
+const usr = __importStar(require("../lib/cli/commands/users"));
+const pkg = require('../package.json');
+const envPath = path.resolve(process.cwd(), '.env');
+const envLoaded = fs.existsSync(envPath);
+// ── Error handler ────────────────────────────────────────────────────────
+function handleError(err) {
+    const msg = err.message || String(err);
+    console.error(`\n  ${picocolors_1.default.red('✗')} ${msg}\n`);
+    process.exit(1);
+}
+function wrap(fn) {
+    return (...args) => fn(...args).catch(handleError);
+}
+// ── Program ──────────────────────────────────────────────────────────────
+commander_1.program
+    .name('ltc')
+    .description('Long Tail CLI — workflows, escalations, knowledge, and more')
+    .version(pkg.version)
+    .hook('preAction', (thisCommand) => {
+    const cmd = thisCommand.args?.[0];
+    // Skip banner for quiet/json modes and version
+    if (process.argv.includes('-q') || process.argv.includes('--quiet') || process.argv.includes('--json'))
+        return;
+    if (cmd === '--version' || cmd === '-V')
+        return;
+    console.log();
+    console.log(`  ${picocolors_1.default.bold('ltc')} ${picocolors_1.default.dim(`v${pkg.version}`)}`);
+    if (envLoaded)
+        console.log(`  ${picocolors_1.default.dim('.env loaded')}`);
+});
+// ── Auth ─────────────────────────────────────────────────────────────────
+commander_1.program
+    .command('login')
+    .description('Authenticate with a Long Tail instance')
+    .option('-s, --server <url>', 'Server URL')
+    .option('-u, --username <name>', 'Username')
+    .option('-p, --password <pass>', 'Password')
+    .action(wrap(async (opts) => (0, auth_1.login)(opts)));
+commander_1.program
+    .command('logout')
+    .description('Clear stored credentials')
+    .action(() => (0, auth_1.logout)());
+commander_1.program
+    .command('status')
+    .description('Show instance health and summary counts')
+    .action(wrap(status_1.statusCommand));
+// ── Compile ──────────────────────────────────────────────────────────────
+commander_1.program
+    .command('compile [target]')
+    .description('Compile durable TypeScript workflows to YAML DAGs')
+    .option('--dry-run', 'Show discovered workflows without compiling')
+    .option('-o, --output <dir>', 'Output directory (default: adjacent to source)')
+    .option('--model <model>', 'LLM model to use')
+    .option('--function <name>', 'Workflow function name (auto-detected if omitted)')
+    .option('-q, --quiet', 'Minimal output (exit codes only)')
+    .action(compile_1.compileCommand);
+commander_1.program
+    .command('init')
+    .description('Create a .env file with API key template')
+    .action(init_1.initCommand);
+// ── Escalations ──────────────────────────────────────────────────────────
+const escCmd = commander_1.program.command('escalations').alias('esc').description('Manage escalations');
+escCmd.command('list')
+    .option('--status <status>', 'Filter by status (pending, resolved, cancelled)')
+    .option('--role <role>', 'Filter by role')
+    .option('--limit <n>', 'Max results')
+    .option('--json', 'JSON output')
+    .option('-q, --quiet', 'IDs only')
+    .action(wrap(esc.listEscalations));
+escCmd.command('get <id>')
+    .option('--json', 'JSON output')
+    .action(wrap(esc.getEscalation));
+escCmd.command('claim <id>')
+    .option('--duration <minutes>', 'Claim duration in minutes')
+    .action(wrap(esc.claimEscalation));
+escCmd.command('release <id>')
+    .action(wrap(esc.releaseEscalation));
+escCmd.command('resolve <id>')
+    .requiredOption('--data <json>', 'Resolver payload (JSON string)')
+    .action(wrap(esc.resolveEscalation));
+// ── Workflows ────────────────────────────────────────────────────────────
+const wfCmd = commander_1.program.command('workflows').alias('wf').description('Manage durable workflows');
+wfCmd.command('list')
+    .option('--include-system', 'Include system workflows')
+    .option('--json', 'JSON output')
+    .option('-q, --quiet', 'IDs only')
+    .action(wrap(wf.listWorkflows));
+wfCmd.command('invoke <type>')
+    .option('--data <json>', 'Input data (JSON string)')
+    .option('--json', 'JSON output')
+    .action(wrap(wf.invokeWorkflow));
+wfCmd.command('status <id>')
+    .option('--json', 'JSON output')
+    .action(wrap(wf.getWorkflowStatus));
+wfCmd.command('result <id>')
+    .option('--json', 'JSON output')
+    .action(wrap(wf.getWorkflowResult));
+wfCmd.command('terminate <id>')
+    .action(wrap(wf.terminateWorkflow));
+// ── Pipelines (YAML Workflows) ──────────────────────────────────────────
+const pipCmd = commander_1.program.command('pipelines').alias('pip').description('Manage YAML pipeline tools');
+pipCmd.command('list')
+    .option('--status <status>', 'Filter by status (active, draft, deployed, archived)')
+    .option('--limit <n>', 'Max results')
+    .option('--json', 'JSON output')
+    .option('-q, --quiet', 'IDs only')
+    .action(wrap(pip.listPipelines));
+pipCmd.command('get <id>')
+    .option('--json', 'JSON output')
+    .action(wrap(pip.getPipeline));
+pipCmd.command('deploy <id>')
+    .action(wrap(pip.deployPipeline));
+pipCmd.command('invoke <id>')
+    .option('--data <json>', 'Input data (JSON string)')
+    .option('--sync', 'Wait for result')
+    .option('--json', 'JSON output')
+    .action(wrap(pip.invokePipeline));
+pipCmd.command('archive <id>')
+    .action(wrap(pip.archivePipeline));
+// ── Knowledge ────────────────────────────────────────────────────────────
+const kbCmd = commander_1.program.command('knowledge').alias('kb').description('Manage knowledge store');
+kbCmd.command('domains')
+    .option('--json', 'JSON output')
+    .option('-q, --quiet', 'IDs only')
+    .action(wrap(kb.listDomains));
+kbCmd.command('list <domain>')
+    .option('--search <term>', 'Search by key or tag')
+    .option('--limit <n>', 'Max results')
+    .option('--json', 'JSON output')
+    .option('-q, --quiet', 'Keys only')
+    .action(wrap(kb.listEntries));
+kbCmd.command('get <domain> <key>')
+    .option('--json', 'JSON output')
+    .action(wrap(kb.getEntry));
+kbCmd.command('set <domain> <key> <path> <value>')
+    .option('--json', 'JSON output')
+    .description('Set a value at a dot-path (e.g., ltc kb set research screenshots google.holiday "Mother\'s Day")')
+    .action(wrap(kb.setField));
+kbCmd.command('remove <domain> <key> <path>')
+    .description('Remove a field at a dot-path')
+    .action(wrap(kb.removeField));
+kbCmd.command('delete <domain> <key>')
+    .description('Delete an entire entry')
+    .action(wrap(kb.deleteEntry));
+// ── MCP ──────────────────────────────────────────────────────────────────
+const mcpCmd = commander_1.program.command('mcp').description('MCP server and tool management');
+mcpCmd.command('servers')
+    .option('--json', 'JSON output')
+    .option('-q, --quiet', 'IDs only')
+    .action(wrap(mcp.listServers));
+mcpCmd.command('tools <serverId>')
+    .option('--json', 'JSON output')
+    .option('-q, --quiet', 'Names only')
+    .action(wrap(mcp.listTools));
+// ── Users ────────────────────────────────────────────────────────────────
+const usrCmd = commander_1.program.command('users').description('User management (admin)');
+usrCmd.command('list')
+    .option('--json', 'JSON output')
+    .option('-q, --quiet', 'IDs only')
+    .action(wrap(usr.listUsers));
+usrCmd.command('get <id>')
+    .option('--json', 'JSON output')
+    .action(wrap(usr.getUser));
+// ── Parse ────────────────────────────────────────────────────────────────
+commander_1.program.parse();