@servicenow/sdk 1.0.2

package/src/auth/index.ts

@@ -0,0 +1,238 @@
+import { logger } from '@servicenow/sdk-cli-core/dist/cli-util/logger'
+import { Creds } from '@servicenow/sdk-cli-core/dist/command/login'
+import { NowSDKError } from '@servicenow/sdk-cli-core/dist/cli-util/Error'
+import { KeyChain } from './keychain'
+import chalk from 'chalk'
+import { TEST_COMMAND } from '../command/test'
+
+export const SERVICE = 'fluent'
+const DEFAULT_ALIAS = 'fluent-default'
+
+const keychain = new KeyChain(SERVICE)
+
+export interface StoredCredential extends Creds {
+    isDefault: boolean
+    alias: string
+}
+
+type CredentialPreview = Omit<StoredCredential, 'password' | 'alias'>
+
+export async function getCredentials(args: any): Promise<Creds> {
+    const [command] = args._
+    let credentials: Creds | undefined
+    if (command === TEST_COMMAND) {
+        credentials = { username: args.username!, password: args.password!, host: args.host! }
+    } else {
+        credentials = await getStoredCredentials(args.auth)
+    }
+    return credentials
+}
+
+async function getStoredCredentials(alias: string = DEFAULT_ALIAS): Promise<Creds> {
+    if (alias === DEFAULT_ALIAS) {
+        const defaultCreds = await getDefaultCredentials()
+        if (!defaultCreds) {
+            throw new NowSDKError(
+                'Default Credential has not been set, Please provide the credential alias to use or set a default by using "$now-sdk auth set-default" command',
+                { command: 'login', type: 'credential_storage' }
+            )
+        }
+    }
+
+    const keyStore = await keychain.getPassword(alias)
+    if (!keyStore) {
+        throw new NowSDKError(
+            `Could not find stored credentials for alias: ${alias}, Please check the alias provided or save an alias using "$now-sdk auth save" command`,
+            { command: 'login', type: 'credential_storage' }
+        )
+    }
+
+    return JSON.parse(keyStore) as Creds
+}
+
+export async function storeCredentials(
+    alias: string,
+    host: string,
+    username: string,
+    password: string,
+    isDefault: boolean
+): Promise<void> {
+    host = getOrigin(host)
+
+    const defaultCreds = await getDefaultCredentials()
+
+    // if no default is set, set the current alias as default
+    if (!defaultCreds || defaultCreds.alias === alias) {
+        isDefault = true
+    }
+
+    const creds: StoredCredential = {
+        username,
+        password,
+        host,
+        isDefault,
+        alias,
+    }
+
+    await keychain.setPassword(alias, JSON.stringify(creds))
+
+    if (isDefault) {
+        await updateDefaultCredential(alias, defaultCreds)
+    }
+}
+
+export async function updateDefaultCredential(alias: string, defaultCreds?: StoredCredential) {
+    logger.info(`Setting alias ${alias} as default ...`)
+    const keyStore = await keychain.getPassword(alias)
+    if (!keyStore) {
+        throw new NowSDKError(
+            `No credentials found for alias ${alias}, Please check the alias provided or save an alias using "$now-sdk auth save" command`,
+            { command: 'auth', type: 'credential_storage' }
+        )
+    }
+
+    defaultCreds = defaultCreds ?? (await getDefaultCredentials())
+
+    if (defaultCreds) {
+        const { alias: defaultCredAlias } = defaultCreds
+
+        if (defaultCredAlias === alias) {
+            logger.info(`alias ${alias} is already set as default`)
+            return
+        }
+
+        defaultCreds.isDefault = false
+        keychain.setPassword(defaultCredAlias, JSON.stringify(defaultCreds))
+    }
+
+    const creds: StoredCredential = JSON.parse(keyStore as string)
+    creds.isDefault = true
+    keychain.setPassword(DEFAULT_ALIAS, JSON.stringify(creds))
+    keychain.setPassword(alias, JSON.stringify(creds))
+    logger.info(`Successfully set alias ${alias} as default`)
+}
+
+async function getDefaultCredentials(): Promise<StoredCredential | undefined> {
+    const keyStore = await keychain.getPassword(DEFAULT_ALIAS)
+    if (!keyStore) {
+        return
+    }
+
+    return JSON.parse(keyStore) as StoredCredential
+}
+
+export async function removeCredentials(alias: string): Promise<void> {
+    if (process.env['NODE_ENV'] === 'test') {
+        return
+    }
+
+    if (alias === 'all') {
+        logger.info(`Removing all stored credentials ...`)
+        const credentials = await keychain.findCredentials()
+        if (!credentials || credentials.length === 0) {
+            return
+        }
+
+        for (const credential of credentials) {
+            await keychain.deletePassword(credential.account)
+        }
+        logger.info(`Successfully removed all stored credentials`)
+        return
+    }
+
+    logger.info(`Removing credentials for alias: ${alias} ...`)
+
+    const keyStore = await keychain.getPassword(alias)
+
+    if (!keyStore) {
+        logger.info(`No credentials found for alias: ${alias}`)
+        return
+    }
+
+    const creds: StoredCredential = JSON.parse(keyStore as string)
+
+    if (creds.isDefault) {
+        logger.info(`alias ${alias} is set as default, removing default ...`)
+        await keychain.deletePassword(DEFAULT_ALIAS)
+    }
+    await keychain.deletePassword(alias)
+    logger.info(`Successfully removed credentials for alias ${alias}`)
+}
+
+export async function listCredentials(alias: string): Promise<void> {
+    if (process.env['NODE_ENV'] === 'test') {
+        return
+    }
+
+    const storedCreds = await fetchCredentials(alias)
+
+    if (storedCreds.size === 0) {
+        return
+    }
+
+    if (alias === 'all') {
+        logger.info(`Listing all credentials: `)
+
+        storedCreds.forEach((creds, alias) => {
+            prettyPrintCredentials(creds, alias)
+        })
+        return
+    }
+
+    logger.info(`Listing credentials for alias ${alias} ...`)
+    prettyPrintCredentials(storedCreds.get(alias) as CredentialPreview)
+}
+
+function prettyPrintCredentials(storedCreds: CredentialPreview, alias?: string): void {
+    const { host, username, isDefault } = storedCreds
+    if (alias) {
+        console.log(chalk.cyan.bold(`[${alias}]`))
+    }
+    console.log(`      host = ${host}`)
+    console.log(`      username = ${username}`)
+    console.log(`      ${isDefault ? chalk.green('default = Yes') : 'default = No'}`)
+}
+
+async function fetchCredentials(alias: string): Promise<Map<string, CredentialPreview>> {
+    const storedCreds: Map<string, CredentialPreview> = new Map()
+    if (alias === 'all') {
+        const credentials = await keychain.findCredentials()
+        if (!credentials || credentials.length === 0) {
+            logger.info(`No credentials found`)
+            return storedCreds
+        }
+
+        for (const credential of credentials) {
+            if (credential.account === DEFAULT_ALIAS) {
+                continue
+            }
+            const {
+                alias: storedAlias,
+                host,
+                username,
+                isDefault,
+            } = JSON.parse(credential.password as string) as StoredCredential
+            storedCreds.set(storedAlias, { host, username, isDefault })
+        }
+        return storedCreds
+    }
+
+    const keyStore = await keychain.getPassword(alias)
+
+    if (!keyStore) {
+        logger.info(`No credentials found for alias: ${alias}`)
+        return storedCreds
+    }
+
+    const { alias: storedAlias, host, username, isDefault } = JSON.parse(keyStore as string) as StoredCredential
+    storedCreds.set(storedAlias, { host, username, isDefault })
+
+    return storedCreds
+}
+
+function getOrigin(host?: string) {
+    if (!host) {
+        return ''
+    }
+    return new URL(host).origin
+}

package/src/auth/keychain/index.ts

@@ -0,0 +1,23 @@
+export class KeyChain {
+    constructor(private readonly service: string) {}
+
+    private async getSingleton() {
+        return (await import('keytar')).default
+    }
+
+    async getPassword(account: string): Promise<string | null> {
+        return this.getSingleton().then((k) => k.getPassword(this.service, account))
+    }
+
+    async setPassword(account: string, password: string): Promise<void> {
+        return this.getSingleton().then((k) => k.setPassword(this.service, account, password))
+    }
+
+    async deletePassword(account: string): Promise<boolean> {
+        return this.getSingleton().then((k) => k.deletePassword(this.service, account))
+    }
+
+    async findCredentials(): Promise<Array<{ account: string; password: string }>> {
+        return this.getSingleton().then((k) => k.findCredentials(this.service))
+    }
+}

package/src/command/auth/commands/clear.ts

@@ -0,0 +1,21 @@
+import { CommandModule, Argv, ArgumentsCamelCase } from 'yargs'
+import { removeCredentials } from '../../../auth'
+
+interface Arguments {
+    alias: string
+}
+
+export const clear: CommandModule<unknown, Arguments> = {
+    command: 'clear [alias]',
+    describe: 'Clear authentication credentials for an instance',
+    builder: async (yargs: Argv) => {
+        return yargs.positional('alias', {
+            describe: 'credential alias to clear',
+            type: 'string',
+            default: 'all',
+        })
+    },
+    handler: async function (args: ArgumentsCamelCase<Arguments>): Promise<void> {
+        await removeCredentials(args.alias)
+    },
+}

package/src/command/auth/commands/list.ts

@@ -0,0 +1,21 @@
+import { CommandModule, Argv, ArgumentsCamelCase } from 'yargs'
+import { listCredentials } from '../../../auth'
+
+interface Arguments {
+    alias: string
+}
+
+export const list: CommandModule<unknown, Arguments> = {
+    command: 'list [alias]',
+    describe: 'List all available authentication credentials',
+    builder: async (yargs: Argv) => {
+        return yargs.positional('alias', {
+            describe: 'credential alias to view',
+            type: 'string',
+            default: 'all',
+        })
+    },
+    handler: async function (args: ArgumentsCamelCase<Arguments>): Promise<void> {
+        await listCredentials(args.alias)
+    },
+}

package/src/command/auth/commands/save.ts

@@ -0,0 +1,100 @@
+import { CommandModule, Argv, ArgumentsCamelCase } from 'yargs'
+import { storeCredentials } from '../../../auth'
+import { input, password as passwordInput } from '@inquirer/prompts'
+export const DEFAULT_HOST = 'http://localhost:8080'
+
+interface Arguments {
+    host: string | undefined
+    username: string | undefined
+    alias: string
+    default: boolean
+}
+type Options = {
+    [K in keyof Arguments]: {
+        describe: string
+        defaultValue?: string
+    }
+}
+
+const options: Options = {
+    host: {
+        describe: 'Target host for application deployment',
+        defaultValue: DEFAULT_HOST,
+    },
+    username: {
+        describe: 'The username to authenticate with the instance',
+        defaultValue: 'admin',
+    },
+    alias: {
+        describe: 'The alias to use for the host and username combination',
+    },
+    default: {
+        describe: 'Set the alias as the default',
+    },
+}
+
+export const save: CommandModule<unknown, Arguments> = {
+    command: 'save <alias>',
+    describe: 'Store authentication credentials for an instance',
+    builder: async (yargs: Argv) => {
+        return yargs
+            .positional('alias', {
+                describe: options.alias.describe,
+                type: 'string',
+                demandOption: true,
+            })
+            .option('host', {
+                describe: options.host.describe,
+                type: 'string',
+            })
+            .option('username', {
+                describe: options.username.describe,
+                type: 'string',
+            })
+            .option('default', {
+                describe: options.default.describe,
+                type: 'boolean',
+                default: false,
+                alias: 'd',
+            })
+            .epilogue(`You will be prompted for a password to authenticate with the instance.`)
+    },
+    handler: async function (args: ArgumentsCamelCase<Arguments>): Promise<void> {
+        const { login: loginService } = await import('@servicenow/sdk-cli-core/dist/command/login/index.js')
+        const { logger } = await import('@servicenow/sdk-cli-core/dist/cli-util/logger/index.js')
+        try {
+            const host =
+                args.host ||
+                (await input({
+                    message: options.host.describe,
+                    default: options.host.defaultValue,
+                }))
+            logger.info(`Authenticating to instance "${host}".`)
+            const username =
+                args.username ||
+                (await input({
+                    message: options.username.describe,
+                    default: options.username.defaultValue,
+                }))
+            const password = await passwordInput({
+                message: 'The password to authenticate with the instance',
+                validate(val) {
+                    return val.length > 0
+                },
+            })
+            const session = await loginService({ host, username, password })
+
+            if (!session) {
+                return
+            }
+
+            const { instanceUrl } = session
+            logger.successful(`Successfully authenticated to instance ${instanceUrl}.`)
+            logger.info(`Storing credentials for instance "${instanceUrl}" with alias ${args.alias}.`)
+            await storeCredentials(args.alias, instanceUrl, username, password, args.default)
+            logger.successful(`Successfully stored credentials for instance "${instanceUrl}" with alias ${args.alias}.`)
+        } catch (error) {
+            logger.error(error instanceof Error ? error.message : (error as string), error)
+        }
+    },
+}

package/src/command/auth/commands/setDefault.ts

@@ -0,0 +1,21 @@
+import { CommandModule, Argv, ArgumentsCamelCase } from 'yargs'
+import { updateDefaultCredential } from '../../../auth'
+
+interface Arguments {
+    alias: string
+}
+
+export const setDefault: CommandModule<unknown, Arguments> = {
+    command: 'set-default <alias>',
+    describe: 'Set/Update the default credential alias',
+    builder: async (yargs: Argv) => {
+        return yargs.positional('alias', {
+            describe: 'credential alias to set as default option',
+            type: 'string',
+            demandOption: true,
+        })
+    },
+    handler: async function (args: ArgumentsCamelCase<Arguments>): Promise<void> {
+        await updateDefaultCredential(args.alias)
+    },
+}

package/src/command/auth/commands/validate.ts

@@ -0,0 +1,35 @@
+import { CommandModule, Argv, ArgumentsCamelCase } from 'yargs'
+import { getCredentials } from '../../../auth'
+
+interface Arguments {
+    alias: string
+}
+
+export const validate: CommandModule<unknown, Arguments> = {
+    describe: 'Validate authentication credentials for an instance',
+    builder: async (yargs: Argv) => {
+        return yargs.positional('alias', {
+            describe: 'credential alias to validate against the instance',
+            type: 'string',
+            demandOption: true,
+        })
+    },
+    handler: async function (args: ArgumentsCamelCase<Arguments>): Promise<void> {
+        const { login: loginService } = await import('@servicenow/sdk-cli-core/dist/command/login/index.js')
+        const { logger } = await import('@servicenow/sdk-cli-core/dist/cli-util/logger/index.js')
+        try {
+            args['auth'] = args.alias //getCredentials expects alias from args.auth
+            const creds = await getCredentials(args)
+
+            const session = await loginService(creds)
+
+            if (!session) {
+                return
+            }
+            const { instanceUrl } = session
+            logger.successful(`Successfully validated creds with instance ${instanceUrl}.`)
+        } catch (error) {
+            logger.error(error instanceof Error ? error.message : (error as string), error)
+        }
+    },
+}

package/src/command/auth/index.ts

@@ -0,0 +1,24 @@
+import { Argv, CommandModule } from 'yargs'
+import { save } from './commands/save'
+import { clear } from './commands/clear'
+import { setDefault } from './commands/setDefault'
+import { list } from './commands/list'
+import { validate } from './commands/validate'
+
+export const auth: CommandModule<unknown, any> = {
+    command: 'auth <command>',
+    describe: 'Configure authentication to instance',
+    builder: (yargs: Argv) => {
+        return yargs
+            .command(save)
+            .command(clear)
+            .command(setDefault)
+            .command(list)
+            .command('validate <alias>', false, validate)
+            .demandCommand(1)
+            .epilogue('Use $now-sdk auth <command> --help for more information on subcommands.')
+    },
+    handler: async () => {
+        // do nothing
+    },
+}

package/src/command/build/index.ts

@@ -0,0 +1,96 @@
+import { Argv, ArgumentsCamelCase, CommandModule } from 'yargs'
+import path from 'node:path'
+import { cwd } from '../../util'
+
+interface Arguments {
+    source: string
+    debug: boolean
+    'generate-deletes': boolean
+    lint: boolean
+    optimize: boolean
+    experimental: boolean
+}
+
+export const build: CommandModule<unknown, Arguments> = {
+    command: 'build [source]',
+    describe: 'Compile sources into app files and generate deployable package',
+    builder: (yargs: Argv) => {
+        return yargs
+            .positional('source', {
+                describe: `Path to "package.json"`,
+                default: cwd(),
+                type: 'string',
+            })
+            .option('debug', {
+                describe: 'Print debug output',
+                alias: 'd',
+                default: false,
+                type: 'boolean',
+            })
+            .option('generate-deletes', {
+                describe: 'Generate DELETE record updates for files removed between builds',
+                default: true,
+                type: 'boolean',
+            })
+            .option('lint', {
+                describe: 'Lint sources before building',
+                default: true,
+                type: 'boolean',
+            })
+            .option('optimize', {
+                describe: 'Optimize packaging by reusing unchanged dependency xmls',
+                default: true,
+                type: 'boolean',
+                alias: 'o',
+            })
+            .option('experimental', {
+                describe: 'Enables unstable experimental feature that may or may not be supported long term',
+                default: false,
+                type: 'boolean',
+                alias: 'e',
+                hidden: true,
+            })
+    },
+    handler: async function (args: ArgumentsCamelCase<Arguments>): Promise<void> {
+        const { logger } = await import('@servicenow/sdk-cli-core/dist/cli-util/logger/index.js')
+        logger.info('Initiating the build process...')
+
+        const { clean } = await import('@servicenow/sdk-cli-core/dist/command/clean/index.js')
+        const { pack } = await import('@servicenow/sdk-cli-core/dist/command/pack/index.js')
+        const { generateModules } = await import('@servicenow/sdk-cli-core/dist/command/generate-modules/index.js')
+        const { packageDependencies } = await import(
+            '@servicenow/sdk-cli-core/dist/command/package-dependencies/index.js'
+        )
+        const { compile } = await import('@servicenow/sdk-cli-core/dist/command/compile/index.js')
+        const { markFilesForDeployment, getFilesExcludedForDeployment } = await import(
+            '@servicenow/sdk-cli-core/dist/cli-util/DeployUtils.js'
+        )
+        const { moveDependencyXmls } = await import('@servicenow/sdk-cli-core/dist/cli-util/ModuleUtils.js')
+        try {
+            const workingDir = path.resolve(args.source)
+            const generateDeletes = args['generate-deletes']
+            const enableExperimental = args.experimental
+            await clean(workingDir)
+            const dependencies = await packageDependencies(workingDir, generateDeletes, args.optimize)
+            await generateModules(workingDir, generateDeletes, dependencies)
+            if (enableExperimental) {
+                await compile(workingDir, args.debug)
+            }
+            markFilesForDeployment(args.source)
+            await pack(workingDir, getFilesExcludedForDeployment(args.source))
+            moveDependencyXmls(workingDir)
+            writeMetrics(workingDir)
+        } catch (error) {
+            logger.error(error instanceof Error ? error.stack ?? error.message : (error as string), error)
+        }
+    },
+}
+
+async function writeMetrics(workingDir: string) {
+    const { writeCMDTimingMetric, writeCommandCountMetric } = await import(
+        '@servicenow/sdk-cli-core/dist/usage/Metrics.js'
+    )
+
+    writeCMDTimingMetric(['first_build_to_deploy_time', 'last_build_to_deploy_time'], workingDir)
+    writeCommandCountMetric('build_count', workingDir)
+}

package/src/command/clean/index.ts

@@ -0,0 +1,22 @@
+import { Argv, ArgumentsCamelCase, CommandModule } from 'yargs'
+import path from 'node:path'
+import { cwd } from '../../util'
+
+interface Arguments {
+    source: string
+}
+
+export const clean: CommandModule<unknown, Arguments> = {
+    describe: 'Clean output directory',
+    builder: (yargs: Argv) => {
+        return yargs.positional('source', {
+            describe: `Path to "package.json"`,
+            default: cwd(),
+            type: 'string',
+        })
+    },
+    handler: async function (args: ArgumentsCamelCase<Arguments>): Promise<void> {
+        const { clean: cleanService } = await import('@servicenow/sdk-cli-core/dist/command/clean/index.js')
+        await cleanService(path.resolve(args.source))
+    },
+}

package/src/command/compile/index.ts

@@ -0,0 +1,31 @@
+import { Argv, ArgumentsCamelCase, CommandModule } from 'yargs'
+import path from 'node:path'
+import { cwd } from '../../util'
+
+interface Arguments {
+    source: string
+    experimental: boolean
+}
+
+export const compile: CommandModule<unknown, Arguments> = {
+    describe: 'Generate metadata files',
+    builder: (yargs: Argv) => {
+        return yargs
+            .positional('source', {
+                describe: `Path to "package.json"`,
+                default: cwd(),
+                type: 'string',
+            })
+            .option('experimental', {
+                describe: 'Enables unstable experimental feature that may or may not be supported long term',
+                default: false,
+                type: 'boolean',
+                alias: 'e',
+                hidden: true,
+            })
+    },
+    handler: async function (args: ArgumentsCamelCase<Arguments>): Promise<void> {
+        const { compile: compileService } = await import('@servicenow/sdk-cli-core/dist/command/compile/index.js')
+        await compileService(path.resolve(args.source))
+    },
+}