@lightdash/cli 2.472.0 → 2.473.0

package/dist/handlers/agentAccess.d.ts

@@ -0,0 +1,8 @@
+import { type AiAccessForUser } from '@lightdash/common';
+export type AgentOptions = {
+    project?: string;
+    verbose: boolean;
+};
+export declare const resolveAgentProject: (project?: string) => Promise<string>;
+export declare const getAgentAccess: (projectUuid: string) => Promise<AiAccessForUser>;
+//# sourceMappingURL=agentAccess.d.ts.map

package/dist/handlers/agentAccess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentAccess.d.ts","sourceRoot":"","sources":["../../src/handlers/agentAccess.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAKzE,MAAM,MAAM,YAAY,GAAG;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,eAAO,MAAM,mBAAmB,aAClB,MAAM,KACjB,OAAO,CAAC,MAAM,CAShB,CAAC;AAEF,eAAO,MAAM,cAAc,gBAAiB,MAAM,KAAG,OAAO,CAAC,eAAe,CAKtE,CAAC"}

package/dist/handlers/agentAccess.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAgentAccess = exports.resolveAgentProject = void 0;
+const common_1 = require("@lightdash/common");
+const config_1 = require("../config");
+const apiClient_1 = require("./dbt/apiClient");
+const resolveProjectFlag_1 = require("./resolveProjectFlag");
+const resolveAgentProject = async (project) => {
+    if (project !== undefined)
+        return (0, resolveProjectFlag_1.resolveProjectFlag)(project);
+    const config = await (0, config_1.getConfig)();
+    if (!config.context?.project) {
+        throw new common_1.ParameterError('No project selected. Run `lightdash config set-project` or pass --project <uuid or slug>.');
+    }
+    return config.context.project;
+};
+exports.resolveAgentProject = resolveAgentProject;
+const getAgentAccess = (projectUuid) => (0, apiClient_1.lightdashApi)({
+    method: 'GET',
+    url: `/api/v2/projects/${projectUuid}/ai-access/me`,
+    body: undefined,
+});
+exports.getAgentAccess = getAgentAccess;

package/dist/handlers/agentAccess.mock.d.ts

@@ -0,0 +1,6 @@
+import { type AiAccessForUser } from '@lightdash/common';
+export declare const agentProjectUuid = "00000000-0000-0000-0000-000000000001";
+export declare const agentConnectUrl = "https://example.com/agent/connect?project=00000000-0000-0000-0000-000000000001&redirect=/agent-connected";
+export declare const agentAccess: AiAccessForUser;
+export declare const connectedAgentAccess: AiAccessForUser;
+//# sourceMappingURL=agentAccess.mock.d.ts.map

package/dist/handlers/agentAccess.mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentAccess.mock.d.ts","sourceRoot":"","sources":["../../src/handlers/agentAccess.mock.ts"],"names":[],"mappings":"AAAA,OAAO,EAGH,KAAK,eAAe,EACvB,MAAM,mBAAmB,CAAC;AAE3B,eAAO,MAAM,gBAAgB,yCAAyC,CAAC;AACvE,eAAO,MAAM,eAAe,6GAA4F,CAAC;AACzH,eAAO,MAAM,WAAW,EAAE,eAkBzB,CAAC;AACF,eAAO,MAAM,oBAAoB,EAAE,eAKlC,CAAC"}

package/dist/handlers/agentAccess.mock.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connectedAgentAccess = exports.agentAccess = exports.agentConnectUrl = exports.agentProjectUuid = void 0;
+const common_1 = require("@lightdash/common");
+exports.agentProjectUuid = '00000000-0000-0000-0000-000000000001';
+exports.agentConnectUrl = `https://example.com/agent/connect?project=${exports.agentProjectUuid}&redirect=/agent-connected`;
+exports.agentAccess = {
+    projectUuid: exports.agentProjectUuid,
+    expiresAt: null,
+    requirementSource: 'organization',
+    identity: null,
+    marker: null,
+    warehouseConnectionUuid: null,
+    enabled: false,
+    principalKind: 'person',
+    refusal: {
+        code: 'ai_access_refused',
+        reason: common_1.AiAccessRefusalReason.NEEDS_SIGN_IN,
+        action: common_1.AiAccessRefusalAction.SIGN_IN,
+        message: 'Connect your agent to the warehouse once so it can run as you.',
+        settingsUrl: null,
+        connectUrl: exports.agentConnectUrl,
+    },
+};
+exports.connectedAgentAccess = {
+    ...exports.agentAccess,
+    identity: 'connected_person',
+    enabled: true,
+    refusal: null,
+};

package/dist/handlers/agentConnect.d.ts

@@ -0,0 +1,8 @@
+import { type AgentOptions } from './agentAccess';
+type AgentConnectOptions = AgentOptions & {
+    oauthPort?: number;
+    timeout?: number;
+};
+export declare const agentConnectHandler: (options: AgentConnectOptions) => Promise<void>;
+export {};
+//# sourceMappingURL=agentConnect.d.ts.map

package/dist/handlers/agentConnect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentConnect.d.ts","sourceRoot":"","sources":["../../src/handlers/agentConnect.ts"],"names":[],"mappings":"AAQA,OAAO,EAGH,KAAK,YAAY,EACpB,MAAM,eAAe,CAAC;AAGvB,KAAK,mBAAmB,GAAG,YAAY,GAAG;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAyCF,eAAO,MAAM,mBAAmB,YACnB,mBAAmB,KAC7B,OAAO,CAAC,IAAI,CA4Id,CAAC"}

package/dist/handlers/agentConnect.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentConnectHandler = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@lightdash/common");
+const http = tslib_1.__importStar(require("http"));
+const globalState_1 = tslib_1.__importDefault(require("../globalState"));
+const styles = tslib_1.__importStar(require("../styles"));
+const agentAccess_1 = require("./agentAccess");
+const oauth_1 = require("./login/oauth");
+const getFailureReason = (error) => {
+    switch (error) {
+        case 'not_agent_session':
+            return 'Your Snowflake sign-in is not an agent session. Ask your Snowflake admin to set IS_AGENTIC = TRUE on the security integration used for AI.';
+        case 'no_refresh_token':
+            return 'Snowflake did not return a refresh token. Try again.';
+        case 'license_required':
+            return 'An enterprise licence is required.';
+        default:
+            return 'The sign-in did not complete. Try again.';
+    }
+};
+const pollForConnection = async (projectUuid) => {
+    const deadline = Date.now() + 120_000;
+    const poll = async () => {
+        await new Promise((resolve) => {
+            setTimeout(resolve, Math.min(3000, deadline - Date.now()));
+        });
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return false;
+        let timer;
+        try {
+            const access = await Promise.race([
+                (0, agentAccess_1.getAgentAccess)(projectUuid),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(undefined), remaining);
+                }),
+            ]);
+            if (access === undefined)
+                return false;
+            if (access.refusal === null)
+                return true;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        return poll();
+    };
+    return poll();
+};
+const agentConnectHandler = async (options) => {
+    globalState_1.default.setVerbose(options.verbose);
+    const projectUuid = await (0, agentAccess_1.resolveAgentProject)(options.project);
+    const access = await (0, agentAccess_1.getAgentAccess)(projectUuid);
+    if (access.refusal === null && access.identity === 'connected_person') {
+        console.error('Agent already connected');
+        return;
+    }
+    if (access.requirementSource === null) {
+        console.error('Agent connection is not required for this project');
+        return;
+    }
+    if (access.refusal?.action !== 'sign_in' || !access.refusal.connectUrl) {
+        console.error(access.refusal?.message ?? 'Agent not connected');
+        process.exitCode = 1;
+        return;
+    }
+    const timeout = options.timeout ?? 180;
+    if (!Number.isFinite(timeout) ||
+        timeout <= 0 ||
+        timeout * 1000 > 2_147_483_647) {
+        throw new common_1.ParameterError('Timeout must be a positive number of seconds no greater than 2147483.647');
+    }
+    const port = options.oauthPort ??
+        (process.env.LIGHTDASH_OAUTH_PORT
+            ? Number(process.env.LIGHTDASH_OAUTH_PORT)
+            : 0);
+    if (!Number.isInteger(port) ||
+        port < 0 ||
+        port > 65535 ||
+        (port === 0 &&
+            (options.oauthPort !== undefined ||
+                process.env.LIGHTDASH_OAUTH_PORT))) {
+        throw new common_1.ParameterError('OAuth port must be a number between 1 and 65535');
+    }
+    let resolveCallback;
+    let rejectCallback;
+    const callback = new Promise((resolve, reject) => {
+        resolveCallback = resolve;
+        rejectCallback = reject;
+    }).then(() => ({ status: 'connected' }), (error) => ({ status: 'failed', code: error.message }));
+    const server = http.createServer((req, res) => {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        if (req.method !== 'GET' || url.pathname !== '/done') {
+            res.writeHead(404, { 'Content-Type': 'text/plain' });
+            res.end('Not Found');
+            return;
+        }
+        const error = url.searchParams.get('error');
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        if (error !== null) {
+            res.writeHead(400);
+            res.end((0, common_1.generateOAuthErrorResponse)('Agent connection failed', [
+                getFailureReason(error),
+            ]));
+            rejectCallback(new Error(error));
+        }
+        else {
+            res.writeHead(200);
+            res.end((0, common_1.generateOAuthSuccessResponse)('Agent connected.', [
+                'You can close this tab.',
+            ]));
+            resolveCallback();
+        }
+    });
+    let timer;
+    try {
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(port, 'localhost', resolve);
+        });
+        const address = server.address();
+        if (!address || typeof address === 'string') {
+            throw new common_1.ParameterError('Could not start the agent callback server');
+        }
+        const redirect = `http://localhost:${address.port}/done`;
+        globalState_1.default.debug(`> Agent callback server listening on ${redirect}`);
+        const connectUrl = new URL(access.refusal.connectUrl);
+        connectUrl.searchParams.set('redirect', redirect);
+        const result = Promise.race([
+            callback,
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve({ status: 'timeout' }), timeout * 1000);
+            }),
+        ]);
+        console.error(`\n${styles.title('🔐 Agent connection')}`);
+        console.error('Opening browser for authentication...');
+        console.error("If the browser doesn't open automatically, please visit:");
+        console.error(`${styles.secondary(connectUrl.href)}\n`);
+        await (0, oauth_1.openBrowser)(connectUrl.href);
+        const outcome = await result;
+        if (outcome.status === 'failed') {
+            console.error(`Agent connection failed: ${getFailureReason(outcome.code)}`);
+            process.exitCode = 1;
+            return;
+        }
+        if (outcome.status === 'connected' ||
+            (await pollForConnection(projectUuid))) {
+            console.error('Agent connected');
+            return;
+        }
+        console.error('Agent connection did not complete. Run `lightdash agent status` after you approve in the browser.');
+        process.exitCode = 1;
+    }
+    finally {
+        clearTimeout(timer);
+        await new Promise((resolve) => {
+            server.close(() => resolve());
+            server.closeAllConnections();
+        });
+    }
+};
+exports.agentConnectHandler = agentConnectHandler;

package/dist/handlers/agentStatus.d.ts

@@ -0,0 +1,3 @@
+import { type AgentOptions } from './agentAccess';
+export declare const agentStatusHandler: (options: AgentOptions) => Promise<void>;
+//# sourceMappingURL=agentStatus.d.ts.map

package/dist/handlers/agentStatus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentStatus.d.ts","sourceRoot":"","sources":["../../src/handlers/agentStatus.ts"],"names":[],"mappings":"AACA,OAAO,EAGH,KAAK,YAAY,EACpB,MAAM,eAAe,CAAC;AAEvB,eAAO,MAAM,kBAAkB,YAClB,YAAY,KACtB,OAAO,CAAC,IAAI,CAsBd,CAAC"}

package/dist/handlers/agentStatus.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentStatusHandler = void 0;
+const tslib_1 = require("tslib");
+const globalState_1 = tslib_1.__importDefault(require("../globalState"));
+const agentAccess_1 = require("./agentAccess");
+const agentStatusHandler = async (options) => {
+    globalState_1.default.setVerbose(options.verbose);
+    const access = await (0, agentAccess_1.getAgentAccess)(await (0, agentAccess_1.resolveAgentProject)(options.project));
+    if (access.refusal === null && access.identity === 'connected_person') {
+        console.error(`Agent connected${access.expiresAt ? `, expires ${new Date(access.expiresAt).toISOString()}` : ''}`);
+        return;
+    }
+    if (access.requirementSource === null) {
+        console.error('Agent connection not required for this project');
+        return;
+    }
+    if (access.refusal?.action === 'sign_in') {
+        console.error(`Agent not connected: ${access.refusal.message}`);
+        if (access.refusal.connectUrl)
+            console.error(access.refusal.connectUrl);
+    }
+    else {
+        console.error(access.refusal?.message ?? 'Agent not connected');
+    }
+    process.exitCode = 1;
+};
+exports.agentStatusHandler = agentStatusHandler;

package/dist/index.js

@@ -7,6 +7,8 @@ const commander_1 = require("commander");
 const env_1 = require("./env");
 const error_1 = require("./error");
 const globalState_1 = tslib_1.__importDefault(require("./globalState"));
+const agentConnect_1 = require("./handlers/agentConnect");
+const agentStatus_1 = require("./handlers/agentStatus");
 const build_1 = require("./handlers/apps/build");
 const createApp_1 = require("./handlers/apps/createApp");
 const preview_1 = require("./handlers/apps/preview");
@@ -52,6 +54,13 @@ function parseIntArgument(value) {
     }
     return parsedValue;
 }
+function parseOAuthPortArgument(value) {
+    const port = parseInt(value, 10);
+    if (Number.isNaN(port) || port < 1 || port > 65535) {
+        throw new Error('Port must be a number between 1 and 65535');
+    }
+    return port;
+}
 function parseStartOfWeekArgument(value) {
     const number = parseIntArgument(value);
     if (number < 0 || number > 6) {
@@ -142,15 +151,36 @@ ${styles.bold('Examples:')}
     .argParser(parseProjectArgument)
     .conflicts('skipProjectSelection'))
     .option('--email <email>', 'Login with email and password', undefined)
-    .option('--oauth-port <port>', 'Port for the local OAuth callback server (default: random available port)', (value) => {
-    const port = parseInt(value, 10);
-    if (Number.isNaN(port) || port < 1 || port > 65535) {
-        throw new Error('Port must be a number between 1 and 65535');
-    }
-    return port;
-}, undefined)
+    .option('--oauth-port <port>', 'Port for the local OAuth callback server (default: random available port)', parseOAuthPortArgument, undefined)
     .option('--verbose', undefined, false)
     .action(login_1.login);
+const agentProgram = commander_1.program
+    .command('agent')
+    .description('Connect your agent to the warehouse and check its status');
+agentProgram
+    .command('connect')
+    .description('Connects your agent to the warehouse using browser sign-in')
+    .option('--project <project uuid or slug>', 'Specify the project', parseProjectArgument)
+    .option('--oauth-port <port>', 'Port for the local callback server (default: LIGHTDASH_OAUTH_PORT or a random available port)', parseOAuthPortArgument)
+    .option('--timeout <seconds>', 'Seconds to wait for the browser callback before polling for another 120 seconds', Number, 180)
+    .option('--verbose', undefined, false)
+    .addHelpText('after', `
+${styles.bold('Examples:')}
+  lightdash agent connect
+  lightdash agent connect --project my-project --oauth-port 4321 --timeout 180
+`)
+    .action(agentConnect_1.agentConnectHandler);
+agentProgram
+    .command('status')
+    .description('Shows your agent connection status for a project')
+    .option('--project <project uuid or slug>', 'Specify the project', parseProjectArgument)
+    .option('--verbose', undefined, false)
+    .addHelpText('after', `
+${styles.bold('Examples:')}
+  lightdash agent status
+  lightdash agent status --project my-project
+`)
+    .action(agentStatus_1.agentStatusHandler);
 // CONFIG
 const configProgram = commander_1.program
     .command('config')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/cli",
-  "version": "2.472.0",
+  "version": "2.473.0",
   "description": "Lightdash CLI tool",
   "license": "MIT",
   "repository": {
@@ -22,8 +22,8 @@
     "@actions/core": "1.11.1",
     "@aws-sdk/credential-providers": "3.995.0",
     "@casl/ability": "6.8.0",
-    "@lightdash/common": "2.472.0",
-    "@lightdash/warehouses": "2.472.0",
+    "@lightdash/common": "2.473.0",
+    "@lightdash/warehouses": "2.473.0",
     "@sidvind/better-ajv-errors": "7.0.0",
     "@types/columnify": "1.5.1",
     "ajv": "8.18.0",