@servicenow/sdk 1.0.2

package/src/command/convert/index.ts

@@ -0,0 +1,76 @@
+import { ArgumentsCamelCase, Argv, CommandModule } from 'yargs'
+import { Creds } from '@servicenow/sdk-cli-core/dist/command/login'
+import { getCredentials } from '../../auth'
+import path from 'path'
+
+interface Arguments extends Partial<Creds> {
+    scopeName: string
+    packageName: string
+    directory: string | undefined
+    auth: string | undefined
+    scopeId: string | undefined
+    experimental: boolean
+}
+
+export const convert: CommandModule<unknown, Arguments> = {
+    command: 'convert <scopeName> <packageName> [directory]',
+    describe: 'Convert a legacy ServiceNow App on instance to a nowSDK App',
+    builder: (yargs: Argv) => {
+        return yargs
+            .positional('scopeName', {
+                describe: 'Scope of the app to convert. For global apps, use app name',
+                type: 'string',
+                demandOption: true,
+            })
+            .positional('packageName', {
+                describe: 'Package Name of the App to use in the package.json',
+                type: 'string',
+                demandOption: true,
+            })
+            .positional('directory', {
+                describe: 'Directory to setup the application',
+                type: 'string',
+            })
+            .option('auth', {
+                describe: 'Credential alias to use for authentication with instance',
+                type: 'string',
+                alias: 'a',
+            })
+            .option('scopeId', {
+                describe: 'Scope ID of application.',
+                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 { logger } = await import('@servicenow/sdk-cli-core/dist/cli-util/logger/index.js')
+
+        try {
+            const credentials: Creds = await getCredentials(args)
+
+            const directory = args.directory ? path.resolve(args.directory) : path.join(process.cwd(), args.packageName)
+
+            logger.info(
+                `Converting application ${args.scopeName} from instance ${credentials.host} to local application package...`
+            )
+
+            const { convert: convertService } = await import('@servicenow/sdk-cli-core/dist/command/convert/index.js')
+            await convertService({
+                scope: args.scopeName,
+                packageName: args.packageName,
+                directory,
+                credentials,
+                scopeId: args.scopeId,
+                experimental: args.experimental,
+            })
+        } catch (error) {
+            logger.error(error instanceof Error ? error.message : (error as string), error)
+        }
+    },
+}

package/src/command/create/index.ts

@@ -0,0 +1,97 @@
+import { ArgumentsCamelCase, Argv, CommandModule } from 'yargs'
+import { Creds } from '@servicenow/sdk-cli-core/dist/command/login'
+import { getCredentials } from '../../auth'
+
+interface Arguments extends Partial<Creds> {
+    projectName: string | undefined
+    description: string | undefined
+    scopeName: string | undefined
+    sampleTable: boolean | undefined
+    directory: string | undefined
+    offline: boolean | undefined
+    interactive: boolean | undefined
+    auth: string | undefined
+    'open-browser': boolean
+}
+
+export const create: CommandModule<unknown, Arguments> = {
+    command: 'create <projectName> <scopeName> [directory]',
+    describe: 'Scaffold new ServiceNow custom application',
+    builder: (yargs: Argv) => {
+        return yargs
+            .positional('projectName', {
+                describe: 'Name of ServiceNow App project',
+                type: 'string',
+            })
+            .positional('scopeName', {
+                describe:
+                    'Scope name (Must start with vendor prefix if applicable and cannot be greater than 12 characters)',
+                type: 'string',
+            })
+            .positional('directory', {
+                describe: 'Directory to setup the application',
+                type: 'string',
+            })
+            .option('description', {
+                describe: 'Description associated with sys_app',
+                type: 'string',
+            })
+            .option('sampleTable', {
+                describe: 'Add a sample table to the application?',
+                type: 'boolean',
+            })
+            .option('offline', {
+                describe: 'Build and register application on instance?',
+                type: 'boolean',
+                alias: 'o',
+            })
+            .option('auth', {
+                describe: 'Target host for application deployment',
+                type: 'string',
+                alias: 'a',
+            })
+            .option('interactive', {
+                describe: 'Provide create options via interactive UI',
+                type: 'boolean',
+                alias: 'i',
+            })
+            .option('open-browser', {
+                describe: 'Open sys_app page in the default browser on successful deploy',
+                default: false,
+                type: 'boolean',
+                alias: 'b',
+            })
+            .middleware(async (args: ArgumentsCamelCase<Arguments>) => {
+                if (args.auth) {
+                    args.offline = false
+                }
+
+                if (!args.interactive && !args.offline) {
+                    args.offline = false
+                }
+            })
+    },
+    handler: async function (args: ArgumentsCamelCase<Arguments>): Promise<void> {
+        const { logger } = await import('@servicenow/sdk-cli-core/dist/cli-util/logger/index.js')
+        logger.info(`Bootstrapping a new ServiceNow application project...`)
+
+        const { create: createService } = await import('@servicenow/sdk-cli-core/dist/command/create/index.js')
+        try {
+            let credentials: Creds | undefined
+            if (!args.offline) {
+                try {
+                    credentials = await getCredentials(args)
+                } catch (error) {
+                    // Ignore
+                }
+            }
+
+            await createService({
+                ...args,
+                ...(credentials && { ...credentials }),
+            })
+        } catch (error) {
+            logger.error(error instanceof Error ? error.message : (error as string), error)
+        }
+    },
+}

package/src/command/deploy/index.ts

@@ -0,0 +1,84 @@
+import { Argv, ArgumentsCamelCase, CommandModule } from 'yargs'
+import { Creds } from '@servicenow/sdk-cli-core/dist/command/login'
+import { DeploymentMode } from '@servicenow/sdk-cli-core/dist/cli-util/Enums'
+import { getCredentials } from '../../auth'
+import { cwd } from '../../util'
+
+interface Arguments extends Partial<Creds> {
+    source: string
+    mode: DeploymentMode
+    'open-browser': boolean
+    auth: string | undefined
+    info: boolean
+}
+
+export const deploy: CommandModule<unknown, Arguments> = {
+    command: 'deploy',
+    describe: 'Install or update application on instance',
+    builder: async (yargs: Argv) => {
+        return yargs
+            .option('source', {
+                describe: 'Path to the nowSDK project',
+                default: cwd(),
+                type: 'string',
+            })
+            .option('mode', {
+                describe:
+                    'Mode of application deployment, \n\n Reinstall:\n' +
+                    'Uninstall and reinstall the application on the instance to ensure metadata on instance matches deployment package.\n' +
+                    'Warning: Metadata created on-instance that is not present locally will be lost\n\n' +
+                    'Complete:\n Deploy entire application.\n\nIncremental:\n Deploy changes since last deployment.',
+                choices: [DeploymentMode.REINSTALL, DeploymentMode.COMPLETE, DeploymentMode.INCREMENTAL],
+                type: 'string',
+                default: DeploymentMode.INCREMENTAL,
+                coerce: (arg) => arg.toLowerCase(),
+                alias: 'm',
+            })
+            .option('auth', {
+                describe: 'Credential alias to use for authentication with instance',
+                type: 'string',
+                alias: 'a',
+            })
+            .option('open-browser', {
+                describe: 'Open sys_app page in the default browser on successful deploy',
+                default: false,
+                type: 'boolean',
+                alias: 'b',
+            })
+            .option('info', {
+                describe: 'Get information from instance for most recent install of this app',
+                default: false,
+                type: 'boolean',
+                alias: 'i',
+            })
+    },
+    handler: async function (args: ArgumentsCamelCase<Arguments>): Promise<void> {
+        const { logger } = await import('@servicenow/sdk-cli-core/dist/cli-util/logger/index.js')
+
+        try {
+            const credentials: Creds = await getCredentials(args)
+
+            if (args.info) {
+                logger.info('Fetching most recent installation details for application.')
+                const { info: infoService } = await import('@servicenow/sdk-cli-core/dist/command/deploy/index.js')
+                await infoService({ ...credentials, ...args })
+                return
+            }
+            logger.info('Starting deployment...')
+            const { updateDeployManifest } = await import('@servicenow/sdk-cli-core/dist/cli-util/DeployUtils.js')
+
+            const { deploy: deployService } = await import('@servicenow/sdk-cli-core/dist/command/deploy/index.js')
+            const isDeployed = await deployService({
+                source: args.source,
+                mode: args.mode,
+                'open-browser': args['open-browser'],
+                ...credentials,
+            })
+            if (isDeployed) {
+                updateDeployManifest(args.source)
+            }
+        } catch (error) {
+            logger.error(error instanceof Error ? error.message : (error as string), error)
+        }
+    },
+}

package/src/command/fetch/index.ts

@@ -0,0 +1,78 @@
+import { Argv, ArgumentsCamelCase, CommandModule } from 'yargs'
+import { Creds } from '@servicenow/sdk-cli-core/dist/command/login'
+import { FetchMode } from '@servicenow/sdk-cli-core/dist/cli-util/Enums'
+import { getCredentials } from '../../auth'
+import { cwd } from '../../util'
+
+interface Arguments extends Partial<Creds> {
+    directory: string
+    mode: FetchMode
+    auth: string | undefined
+    debug: boolean
+    experimental: boolean
+}
+
+export const fetch: CommandModule<unknown, Arguments> = {
+    command: 'fetch',
+    describe: 'Download application metadata from instance and update local metadata folder.',
+    builder: (yargs: Argv) => {
+        return yargs
+            .option('directory', {
+                describe: `Path to expand application`,
+                default: cwd(),
+                type: 'string',
+            })
+            .option('mode', {
+                describe:
+                    'Application fetch mode,\n\n' +
+                    'complete:\n Download and extract the complete application\n\n' +
+                    'incremental:\n Download changes since last fetch.',
+                choices: [FetchMode.COMPLETE, FetchMode.INCREMENTAL],
+                type: 'string',
+                default: FetchMode.INCREMENTAL,
+                coerce: (arg) => arg.toLowerCase(),
+                alias: 'm',
+            })
+            .option('auth', {
+                describe: 'Credential alias to use for authentication with instance',
+                type: 'string',
+                alias: 'a',
+            })
+            .option('debug', {
+                describe: 'Enable debug output',
+                type: 'boolean',
+                alias: 'd',
+                default: false,
+            })
+            .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('Fetching application metadata from instance...')
+
+        const { fetch: fetchService } = await import('@servicenow/sdk-cli-core/dist/command/fetch/index.js')
+        try {
+            const credentials: Creds = await getCredentials(args)
+
+            logger.warn(
+                'WARN: Updates to JavaScript modules are not included when fetching application metadata from your instance.'
+            )
+            await fetchService({
+                directory: args.directory,
+                credentials,
+                mode: args.mode,
+                debug: args.debug,
+                experimental: args.experimental,
+            })
+        } catch (error) {
+            logger.error('Failed to fetch application: ')
+            logger.error(error instanceof Error ? error.message : (error as string), error)
+        }
+    },
+}

package/src/command/generate-modules/index.ts

@@ -0,0 +1,36 @@
+import { Argv, ArgumentsCamelCase, CommandModule } from 'yargs'
+import path from 'node:path'
+import { cwd } from '../../util'
+
+interface Arguments {
+    source: string
+    'generate-deletes': boolean
+}
+
+export const generateModules: CommandModule<unknown, Arguments> = {
+    describe: 'Wrap modular JS source files into sys_module XMLs',
+    builder: (yargs: Argv) => {
+        return yargs
+            .positional('source', {
+                describe: `Path to "package.json"`,
+                default: cwd(),
+                type: 'string',
+            })
+            .option('generate-deletes', {
+                describe: 'Generate DELETE record updates for modules removed between builds',
+                default: true,
+                type: 'boolean',
+            })
+    },
+    handler: async function (args: ArgumentsCamelCase<Arguments>): Promise<void> {
+        const { logger } = await import('@servicenow/sdk-cli-core/dist/cli-util/logger/index.js')
+        const { generateModules: generateModulesService } = await import(
+            '@servicenow/sdk-cli-core/dist/command/generate-modules/index.js'
+        )
+        try {
+            await generateModulesService(path.resolve(args.source), args['generate-deletes'])
+        } catch (error) {
+            logger.error(error instanceof Error ? error.message : (error as string), error)
+        }
+    },
+}

package/src/command/pack/index.ts

@@ -0,0 +1,27 @@
+import { Argv, ArgumentsCamelCase, CommandModule } from 'yargs'
+import path from 'node:path'
+import { cwd } from '../../util'
+
+interface Arguments {
+    source: string
+}
+
+export const pack: CommandModule<unknown, Arguments> = {
+    describe: 'Zip built app into deployable artifact',
+    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 { pack: packService } = await import('@servicenow/sdk-cli-core/dist/command/pack/index.js')
+        const { logger } = await import('@servicenow/sdk-cli-core/dist/cli-util/logger/index.js')
+        try {
+            await packService(path.resolve(args.source))
+        } catch (error) {
+            logger.error(error instanceof Error ? error.message : (error as string), error)
+        }
+    },
+}

package/src/command/package-dependencies/index.ts

@@ -0,0 +1,43 @@
+import { Argv, ArgumentsCamelCase, CommandModule } from 'yargs'
+import path from 'node:path'
+import { cwd } from '../../util'
+
+interface Arguments {
+    source: string
+    'generate-deletes': boolean
+    optimize: boolean
+}
+
+export const packageDependencies: CommandModule<unknown, Arguments> = {
+    describe: 'Wrap 3rd Party dependencies into sys_module XMLs',
+    builder: (yargs: Argv) => {
+        return yargs
+            .positional('source', {
+                describe: `Path to "package.json"`,
+                default: cwd(),
+                type: 'string',
+            })
+            .option('generate-deletes', {
+                describe: 'Generate DELETE record updates for dependencies removed between builds',
+                default: true,
+                type: 'boolean',
+            })
+            .option('optimize', {
+                describe: 'Optimize dependency packaging by reusing unchanged dependency xmls',
+                default: true,
+                type: 'boolean',
+                alias: 'o',
+            })
+    },
+    handler: async function (args: ArgumentsCamelCase<Arguments>): Promise<void> {
+        const { logger } = await import('@servicenow/sdk-cli-core/dist/cli-util/logger/index.js')
+        const { packageDependencies: packageDependenciesService } = await import(
+            '@servicenow/sdk-cli-core/dist/command/package-dependencies/index.js'
+        )
+        try {
+            await packageDependenciesService(path.resolve(args.source), args['generate-deletes'], args.optimize)
+        } catch (error) {
+            logger.error(error instanceof Error ? error.message : (error as string), error)
+        }
+    },
+}

package/src/command/test/index.ts

@@ -0,0 +1,40 @@
+import { Argv, CommandModule } from 'yargs'
+import { deploy } from '../deploy'
+import { fetch } from '../fetch'
+import { convert } from '../convert'
+import { create } from '../create'
+import { NowSDKError } from '@servicenow/sdk-cli-core/dist/cli-util/Error'
+
+export const TEST_COMMAND = 'test'
+
+export const test: CommandModule<unknown, any> = {
+    describe: 'Test command for development and testing purposes',
+    builder: (yargs: Argv) => {
+        return yargs
+            .option('host', {
+                describe: 'Target host for application deployment',
+                type: 'string',
+            })
+            .option('username', {
+                describe: 'The username to authenticate with host',
+                type: 'string',
+            })
+            .option('password', {
+                describe: 'The password to authenticate with host',
+                type: 'string',
+            })
+            .command(deploy)
+            .command(fetch)
+            .command(convert)
+            .command(create)
+            .demandCommand(1)
+            .check((args) => {
+                const { username, password, host } = args
+                if (!username || !password || !host) {
+                    throw new NowSDKError('Missing required arguments, please provide username, password and host')
+                }
+                return true
+            })
+    },
+    handler: async function (): Promise<void> {},
+}

package/src/command/transform/index.ts

@@ -0,0 +1,45 @@
+import { Argv, CommandModule } from 'yargs'
+import { transform as transformService, TransformArguments } from '@servicenow/sdk-cli-core/dist/command/transform'
+import path from 'path'
+
+export const transform: CommandModule<unknown, TransformArguments> = {
+    describe: 'Parse XML data from a directory and use it to transform source code for bi-directional sync',
+    builder: (yargs: Argv) => {
+        return yargs
+            .option('directory', {
+                describe: 'Directory from which to parse XML files',
+                type: 'string',
+                requiresArg: true,
+                alias: ['D', 'dir'],
+                default: path.resolve(process.cwd(), 'incoming'),
+            })
+            .option('clean', {
+                describe: 'Delete parsed XML files when finished',
+                type: 'boolean',
+                alias: 'c',
+                default: false,
+            })
+            .option('debug', {
+                describe: 'Enable debug output',
+                type: 'boolean',
+                alias: 'd',
+                default: false,
+            })
+            .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: TransformArguments) {
+        const { logger } = await import('@servicenow/sdk-cli-core/dist/cli-util/logger/index.js')
+        try {
+            await transformService(args)
+        } catch (error) {
+            logger.error('Transform failed:')
+            logger.error((error as Error).stack ?? error)
+        }
+    },
+}

package/src/epilogue/index.ts

@@ -0,0 +1,5 @@
+export const epilogue = `
+Use $now-sdk <command> --help for usage information.
+
+For more information, please visit https://docs.servicenow.com/bundle/washingtondc-api-reference/page/script/sdk/reference/servicenow-sdk-cli-commands.html.
+`

package/src/index.ts

@@ -0,0 +1,50 @@
+import yargs from 'yargs'
+import { usage } from './usage'
+import { epilogue } from './epilogue'
+import { clean } from './command/clean'
+import { create } from './command/create'
+import { convert } from './command/convert'
+import { build } from './command/build'
+import { compile } from './command/compile'
+import { generateModules } from './command/generate-modules'
+import { packageDependencies } from './command/package-dependencies'
+import { pack } from './command/pack'
+import { deploy } from './command/deploy'
+import { fetch } from './command/fetch'
+import { transform } from './command/transform'
+import { auth } from './command/auth'
+import { TEST_COMMAND, test } from './command/test'
+import { lt } from 'semver'
+import { logger } from '@servicenow/sdk-cli-core/dist/cli-util/logger'
+
+yargs
+    .check(() => {
+        if (lt(process.version, '16.16.0')) {
+            logger.error('now-sdk requires node version to be >= 16.16.0')
+            process.exit(1)
+        }
+        return true
+    })
+    .usage(usage)
+    .command(auth)
+    .command(create)
+    .command(convert)
+    .command(fetch)
+    .command(build)
+    .command(deploy)
+    .command('transform', false, transform)
+    .command('clean [source]', false, clean)
+    .command('compile [source]', false, compile)
+    .command('generate-modules [source]', false, generateModules)
+    .command('package-dependencies [source]', false, packageDependencies)
+    .command('pack [source]', false, pack)
+    .command(`${TEST_COMMAND} <command>`, false, test)
+    .demandCommand()
+    .epilogue(epilogue)
+    .strictCommands()
+    .help()
+    .updateStrings({
+        'Positionals:': 'Parameters:',
+    })
+    .alias('h', 'help')
+    .scriptName('now-sdk').argv

package/src/usage/index.ts

@@ -0,0 +1,13 @@
+/* eslint-disable no-useless-escape */
+
+// TODO: Prepending underscores for now, because yargs removes
+//       leading whitespace from the usage() argument
+export const usage = `
+_____   ______ _       __  _____ ____  __ \u2009__
+___/ | / / __  /|     / / / ___// __ / /\u2009/_/
+__/  |/ / / / / | /| / / \\__ \// / / / <   
+_/ /|  / /_/ /| |/ |/ / ___/ / /_/ / /| |  
+/_/ |_/\_____/ |__/|__/ /____/_____/_/ |_|  
+
+Source-driven applications by writing actual code, and using modern, industry-standard development paradigms.
+`

package/src/util.ts

@@ -0,0 +1,21 @@
+import { NowSDKError } from '@servicenow/sdk-cli-core/dist/cli-util/Error'
+import path from 'path'
+import fs from 'fs'
+
+export function cwd(): string {
+    try {
+        const dir = process.cwd()
+        if (fs.existsSync(path.join(dir, 'package.json'))) {
+            return dir
+        }
+
+        throw new NowSDKError(
+            'Could not find package.json. Please ensure you are running command in the intended directory or specify source as an argument.',
+            { type: 'missing_package_json' }
+        )
+    } catch (error) {
+        const { logger } = require('@servicenow/sdk-cli-core/dist/cli-util/logger')
+        logger.error(error instanceof Error ? error.message : (error as string), error)
+        process.exit()
+    }
+}