@api-now/cli 1.0.4

package/dist/commands/catalog.js

@@ -0,0 +1,289 @@
+import { getSdkClient, handleApiError } from '../utils/api.js';
+import { config } from '../utils/config.js';
+import { Formatter, CliErrorCode } from '../utils/formatter.js';
+import { DomainFileKind } from '@api-now/core/models/kinds.js';
+import { askInput, askSelect } from '../utils/prompt.js';
+import { DataCatalogKind, DataCatalogVersion, } from '@api-now/core/models/index.js';
+/**
+ * Registers catalog management commands (publish, list) with the main Commander program.
+ *
+ * @param program - The root Commander program.
+ */
+export function registerCatalogCommands(program) {
+    const catalogCmd = program.command('catalog').description('Manage Data Catalog items');
+    catalogCmd
+        .command('publish')
+        .description('Publish a data domain file to the data catalog')
+        .option('--file <fid>', 'File ID of the data domain')
+        .option('--name <name>', 'Name for the catalog entry')
+        .option('--description <desc>', 'Description of the catalog entry')
+        .option('--scope <scope>', 'Publish scope: public, organization, private')
+        .option('-v, --catalog-version <ver>', 'Semantic version (e.g. 1.0.0)')
+        .option('--org <oid>', 'Organization ID (optional, defaults to configured default org)')
+        .option('--lifecycle <lifecycle>', 'Version lifecycle status (dev, beta, stable)', 'stable')
+        .option('--changelog <changelog>', 'Changelog description for this version')
+        .action(async (options) => {
+        const formatter = new Formatter({ format: config.resolved.format });
+        const resolved = config.resolved;
+        const orgId = options.org || resolved.org;
+        if (!orgId) {
+            formatter.error({
+                code: CliErrorCode.MISSING_REQUIRED,
+                message: 'Organization ID is required.',
+                detail: 'Pass --org <oid> or set a default organization using `apinow orgs set-default <oid>`.',
+            });
+            process.exit(1);
+        }
+        // Empathic interactive fallbacks
+        let fileId = options.file;
+        if (!fileId && process.stdout.isTTY) {
+            try {
+                const client = getSdkClient();
+                const res = await client.files.list(orgId, {
+                    filter: {
+                        field: 'kind',
+                        operator: 'eq',
+                        value: DomainFileKind,
+                    },
+                }, { token: client.token });
+                const files = res.data || [];
+                if (files.length > 0) {
+                    fileId = await askSelect('Select a data domain file to publish:', files.map((f) => ({
+                        name: `${f.info?.name || 'Unnamed'} (${f.key})`,
+                        value: f.key,
+                    })));
+                }
+            }
+            catch (_err) {
+                // Ignore list error and fail/prompt below
+            }
+        }
+        if (!fileId) {
+            formatter.error({
+                code: CliErrorCode.MISSING_REQUIRED,
+                message: 'File ID is required.',
+                detail: 'Specify --file <fid>.',
+            });
+            process.exit(1);
+        }
+        let name = options.name;
+        if (!name && process.stdout.isTTY) {
+            name = await askInput('Enter catalog entry name:');
+        }
+        if (!name) {
+            formatter.error({
+                code: CliErrorCode.MISSING_REQUIRED,
+                message: 'Name is required.',
+                detail: 'Specify --name <name>.',
+            });
+            process.exit(1);
+        }
+        let description = options.description;
+        if (!description && process.stdout.isTTY) {
+            description = await askInput('Enter catalog entry description:');
+        }
+        if (!description) {
+            formatter.error({
+                code: CliErrorCode.MISSING_REQUIRED,
+                message: 'Description is required.',
+                detail: 'Specify --description <desc>.',
+            });
+            process.exit(1);
+        }
+        let scope = options.scope;
+        if (!scope && process.stdout.isTTY) {
+            scope = await askSelect('Select publish scope:', [
+                { name: 'Public (public)', value: 'public' },
+                { name: 'Organization (organization)', value: 'organization' },
+                { name: 'Private (private)', value: 'private' },
+            ]);
+        }
+        if (!scope) {
+            formatter.error({
+                code: CliErrorCode.MISSING_REQUIRED,
+                message: 'Scope is required.',
+                detail: 'Specify --scope <scope> (allowed: public, organization, private).',
+            });
+            process.exit(1);
+        }
+        const allowedScopes = ['public', 'organization', 'private'];
+        if (!allowedScopes.includes(scope)) {
+            formatter.error({
+                code: CliErrorCode.INVALID_ARGUMENT,
+                message: `Invalid scope '${scope}'.`,
+                detail: `Allowed: ${allowedScopes.join(', ')}`,
+            });
+            process.exit(1);
+        }
+        let version = options.catalogVersion;
+        if (!version && process.stdout.isTTY) {
+            version = await askInput('Enter semantic version:', '1.0.0');
+        }
+        if (!version) {
+            formatter.error({
+                code: CliErrorCode.MISSING_REQUIRED,
+                message: 'Version is required.',
+                detail: 'Specify --catalog-version <ver> or -v <ver>.',
+            });
+            process.exit(1);
+        }
+        const allowedLifecycles = ['dev', 'beta', 'stable'];
+        if (!allowedLifecycles.includes(options.lifecycle)) {
+            formatter.error({
+                code: CliErrorCode.INVALID_ARGUMENT,
+                message: `Invalid lifecycle '${options.lifecycle}'.`,
+                detail: `Allowed: ${allowedLifecycles.join(', ')}`,
+            });
+            process.exit(1);
+        }
+        try {
+            const client = getSdkClient();
+            let catalogId = null;
+            try {
+                const status = await client.dataCatalog.checkPublicationStatus(fileId, orgId, {
+                    token: client.token,
+                });
+                catalogId = status.key;
+            }
+            catch (err) {
+                const apiErr = handleApiError(err);
+                if (apiErr.status !== 404) {
+                    throw err;
+                }
+            }
+            if (!catalogId) {
+                if (config.resolved.format !== 'json') {
+                    console.log('Catalog entry does not exist. Creating new catalog entry...');
+                }
+                const entry = {
+                    key: '',
+                    kind: DataCatalogKind,
+                    organization: orgId,
+                    file: fileId,
+                    scope: scope,
+                    name: name,
+                    description: description,
+                    publishedBy: '',
+                    publishedAt: 0,
+                    createdAt: 0,
+                    updatedAt: 0,
+                    tags: [],
+                };
+                const createdRecord = await client.dataCatalog.publish(entry, { token: client.token });
+                catalogId = createdRecord.key;
+            }
+            else {
+                if (config.resolved.format !== 'json') {
+                    console.log(`Catalog entry already exists (ID: ${catalogId}). Publishing new version...`);
+                }
+            }
+            const versionPayload = DataCatalogVersion.createSchema({
+                scope: scope,
+                lifecycle: options.lifecycle,
+                version: version,
+                changelog: options.changelog || undefined,
+            });
+            const versionData = await client.dataCatalog.publishVersion(catalogId, versionPayload, {
+                token: client.token,
+            });
+            formatter.success(`Successfully published version '${version}' to the data catalog!`, versionData);
+        }
+        catch (err) {
+            const apiErr = handleApiError(err);
+            formatter.error(apiErr);
+            process.exit(1);
+        }
+    });
+    catalogCmd
+        .command('list')
+        .description('List published data catalog items or versions of a specific catalog entry')
+        .option('--scope <scope>', 'Filter by scope: all, public, organization, private', 'all')
+        .option('--org <oid>', 'Organization ID (optional, defaults to configured default org)')
+        .option('--key <key>', 'Data catalog item key to list all versions of a specific data domain')
+        .action(async (options) => {
+        const formatter = new Formatter({ format: config.resolved.format });
+        const resolved = config.resolved;
+        const orgId = options.org || resolved.org;
+        const allowedScopes = ['all', 'public', 'organization', 'private'];
+        if (!allowedScopes.includes(options.scope)) {
+            formatter.error({
+                message: `Invalid scope '${options.scope}'. Allowed: ${allowedScopes.join(', ')}`,
+            });
+            process.exit(1);
+        }
+        if (['organization', 'private'].includes(options.scope) && !orgId) {
+            formatter.error({
+                message: `Organization ID (--org <oid>) is required when filtering by scope '${options.scope}'.`,
+            });
+            process.exit(1);
+        }
+        try {
+            const client = getSdkClient();
+            if (options.key) {
+                const res = await client.dataCatalog.listVersions(options.key, { token: client.token });
+                const versions = res.data || [];
+                const rows = versions.map((v) => ({
+                    key: v.key,
+                    version: v.version,
+                    published: new Date(v.published).toLocaleString(),
+                }));
+                formatter.list(rows, ['key', 'version', 'published'], {
+                    headers: ['VERSION KEY', 'VERSION', 'PUBLISHED AT'],
+                });
+            }
+            else {
+                const results = [];
+                if (options.scope === 'all') {
+                    const resPublic = await client.dataCatalog.list({ scope: 'public', oid: orgId }, { token: client.token });
+                    results.push(...(resPublic.data || []));
+                    if (orgId) {
+                        try {
+                            const resOrg = await client.dataCatalog.list({ scope: 'organization', oid: orgId }, { token: client.token });
+                            results.push(...(resOrg.data || []));
+                        }
+                        catch {
+                            // Ignore if organization query fails
+                        }
+                        try {
+                            const resPrivate = await client.dataCatalog.list({ scope: 'private', oid: orgId }, { token: client.token });
+                            results.push(...(resPrivate.data || []));
+                        }
+                        catch {
+                            // Ignore if private query fails
+                        }
+                    }
+                }
+                else {
+                    const res = await client.dataCatalog.list({ scope: options.scope, oid: orgId }, { token: client.token });
+                    results.push(...(res.data || []));
+                }
+                const seen = new Set();
+                const uniqueResults = results.filter((item) => {
+                    const key = item.key;
+                    if (seen.has(key))
+                        return false;
+                    seen.add(key);
+                    return true;
+                });
+                const rows = uniqueResults.map((item) => {
+                    const lastVersion = item.versions && item.versions[0] ? item.versions[0].version : 'N/A';
+                    return {
+                        key: item.key,
+                        name: item.name,
+                        scope: item.scope,
+                        lastVersion,
+                        organization: item.organization || 'N/A',
+                    };
+                });
+                formatter.list(rows, ['key', 'name', 'scope', 'lastVersion', 'organization'], {
+                    headers: ['KEY', 'NAME', 'SCOPE', 'LAST VERSION', 'ORGANIZATION'],
+                });
+            }
+        }
+        catch (err) {
+            const apiErr = handleApiError(err);
+            formatter.error(apiErr);
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/config.js

@@ -0,0 +1,59 @@
+import { config } from '../utils/config.js';
+import { Formatter, CliErrorCode } from '../utils/formatter.js';
+/**
+ * Registers configuration management commands with the main Commander program.
+ *
+ * @param program - The root Commander program.
+ */
+export function registerConfigCommands(program) {
+    const configCmd = program.command('config').description('Manage CLI configuration settings');
+    configCmd
+        .command('get <key>')
+        .description('Get a configuration value')
+        .action((key) => {
+        const formatter = new Formatter({ format: config.resolved.format });
+        const configObj = config.resolved;
+        if (key in configObj) {
+            const val = configObj[key];
+            if (config.resolved.format === 'json') {
+                formatter.object({ [key]: val });
+            }
+            else {
+                console.log(val);
+            }
+        }
+        else {
+            formatter.error({
+                code: CliErrorCode.INVALID_ARGUMENT,
+                message: `Configuration key '${key}' not found.`,
+                detail: `Run \`apinow config set ${key} <value>\` to define it.`,
+            });
+            process.exit(1);
+        }
+    });
+    configCmd
+        .command('set <key> <value>')
+        .description('Set a configuration value')
+        .action((key, value) => {
+        const formatter = new Formatter({ format: config.resolved.format });
+        const allowedKeys = ['apiUrl', 'token', 'org'];
+        if (!allowedKeys.includes(key)) {
+            formatter.error({
+                code: CliErrorCode.INVALID_ARGUMENT,
+                message: `Invalid configuration key '${key}'.`,
+                detail: `Allowed keys: ${allowedKeys.join(', ')}`,
+            });
+            process.exit(1);
+        }
+        config.writeProperty(key, value);
+        formatter.success(`Configuration '${key}' set to '${value}'.`);
+    });
+    configCmd
+        .command('reset')
+        .description('Reset all configuration settings and remove stored files')
+        .action(() => {
+        const formatter = new Formatter({ format: config.resolved.format });
+        config.reset();
+        formatter.success('Configuration has been reset successfully.');
+    });
+}

package/dist/commands/files.js

@@ -0,0 +1,293 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getSdkClient, handleApiError } from '../utils/api.js';
+import { config } from '../utils/config.js';
+import { Formatter, CliErrorCode } from '../utils/formatter.js';
+import { ApiFileKind, DomainFileKind, FolderKind } from '@api-now/core/models/kinds.js';
+import { File } from '@api-now/core/models/index.js';
+import { askInput, askSelect } from '../utils/prompt.js';
+/**
+ * Registers files management commands (list, create, read) with the main Commander program.
+ *
+ * @param program - The root Commander program.
+ */
+export function registerFilesCommands(program) {
+    const filesCmd = program.command('files').description('Manage files and metadata');
+    filesCmd
+        .command('list')
+        .description('List files in an organization')
+        .option('--org <oid>', 'Organization ID (optional, defaults to configured default org)')
+        .option('--kind <kind>', 'Filter by file kind (e.g. domain, api, folder)')
+        .option('--parent <parent>', 'Filter by parent folder ID')
+        .action(async (options) => {
+        const formatter = new Formatter({ format: config.resolved.format });
+        const resolved = config.resolved;
+        const orgId = options.org || resolved.org;
+        if (!orgId) {
+            formatter.error({
+                code: CliErrorCode.MISSING_REQUIRED,
+                message: 'Organization ID is required.',
+                detail: 'Pass --org <oid> or set a default organization using `apinow orgs set-default <oid>`.',
+            });
+            process.exit(1);
+        }
+        try {
+            const client = getSdkClient();
+            const listOpts = {};
+            if (options.parent) {
+                listOpts.parent = options.parent;
+            }
+            if (options.kind) {
+                const targetKind = getFileMetaKind(options.kind);
+                listOpts.filter = {
+                    field: 'kind',
+                    operator: 'eq',
+                    value: targetKind,
+                };
+            }
+            const res = await client.files.list(orgId, listOpts, { token: client.token });
+            const files = res.data || [];
+            const rows = files.map((f) => ({
+                id: f.key,
+                name: f.info?.name || '',
+                kind: f.kind,
+                isShortcut: f.isShortcut ? 'Yes' : 'No',
+            }));
+            formatter.list(rows, ['id', 'name', 'kind', 'isShortcut'], {
+                headers: ['ID', 'NAME', 'KIND', 'SHORTCUT'],
+            });
+        }
+        catch (err) {
+            const apiErr = handleApiError(err);
+            formatter.error(apiErr);
+            process.exit(1);
+        }
+    });
+    filesCmd
+        .command('create')
+        .description('Create a new file metadata record (and optionally upload media)')
+        .option('--name <name>', 'Name of the file')
+        .option('--kind <kind>', 'Kind of the file (e.g., domain, api)')
+        .option('--org <oid>', 'Organization ID (optional, defaults to configured default org)')
+        .option('--parent <parent>', 'Parent folder ID')
+        .option('--media <path>', 'Local path to the file content/media to upload')
+        .option('--stdin', 'Read media content from STDIN')
+        .action(async (options) => {
+        const formatter = new Formatter({ format: config.resolved.format });
+        const resolved = config.resolved;
+        const orgId = options.org || resolved.org;
+        if (!orgId) {
+            formatter.error({
+                code: CliErrorCode.MISSING_REQUIRED,
+                message: 'Organization ID is required.',
+                detail: 'Pass --org <oid> or set a default organization using `apinow orgs set-default <oid>`.',
+            });
+            process.exit(1);
+        }
+        if (options.media && options.stdin) {
+            formatter.error({
+                code: CliErrorCode.INVALID_ARGUMENT,
+                message: 'Cannot specify both --media <path> and --stdin',
+            });
+            process.exit(1);
+        }
+        // Empathic interactive fallbacks
+        let name = options.name;
+        if (!name && process.stdout.isTTY) {
+            name = await askInput('Enter file name:');
+        }
+        if (!name) {
+            formatter.error({
+                code: CliErrorCode.MISSING_REQUIRED,
+                message: 'Name is required.',
+                detail: 'Specify --name <name>.',
+            });
+            process.exit(1);
+        }
+        let kind = options.kind;
+        if (!kind && process.stdout.isTTY) {
+            kind = await askSelect('Select file kind:', [
+                { name: 'API Domain / Schema (domain)', value: 'domain' },
+                { name: 'API Schema (api)', value: 'api' },
+                { name: 'Folder (folder)', value: 'folder' },
+            ]);
+        }
+        if (!kind) {
+            formatter.error({
+                code: CliErrorCode.MISSING_REQUIRED,
+                message: 'Kind is required.',
+                detail: 'Specify --kind <kind> (allowed: api, domain, folder).',
+            });
+            process.exit(1);
+        }
+        try {
+            let mediaContent;
+            if (options.media) {
+                const filePath = path.resolve(options.media);
+                if (!fs.existsSync(filePath)) {
+                    formatter.error({
+                        code: CliErrorCode.INVALID_ARGUMENT,
+                        message: `Media file not found at path: ${filePath}`,
+                    });
+                    process.exit(1);
+                }
+                mediaContent = fs.readFileSync(filePath, 'utf8');
+            }
+            else if (options.stdin) {
+                mediaContent = await readStdin();
+            }
+            let fileKey;
+            let fileContent;
+            if (mediaContent !== undefined) {
+                try {
+                    fileContent = JSON.parse(mediaContent);
+                }
+                catch {
+                    throw new Error('invalid API now platform file');
+                }
+                if (!fileContent ||
+                    typeof fileContent !== 'object' ||
+                    Array.isArray(fileContent) ||
+                    !('key' in fileContent) ||
+                    typeof fileContent.key !== 'string' ||
+                    !fileContent.key.trim()) {
+                    throw new Error('invalid API now platform file');
+                }
+                fileKey = fileContent.key;
+            }
+            const client = getSdkClient();
+            const fileMeta = File.createSchema({
+                kind: getFileMetaKind(kind),
+                info: {
+                    name,
+                },
+                key: fileKey,
+            });
+            const createOpts = {};
+            if (options.parent) {
+                createOpts.parent = options.parent;
+            }
+            const file = await client.files.createMeta(fileMeta, orgId, createOpts, { token: client.token });
+            const fileId = file.key;
+            if (mediaContent !== undefined) {
+                await client.files.createMedia(fileContent, orgId, fileId, {}, { token: client.token });
+            }
+            formatter.success('File created successfully!', file);
+        }
+        catch (err) {
+            const apiErr = handleApiError(err);
+            formatter.error({
+                code: CliErrorCode.API_FAILURE,
+                ...apiErr,
+            });
+            process.exit(1);
+        }
+    });
+    filesCmd
+        .command('read')
+        .description('Read file metadata or media content')
+        .option('--id <fid>', 'File ID')
+        .option('--org <oid>', 'Organization ID (optional, defaults to configured default org)')
+        .option('--meta', 'Read file metadata (default)')
+        .option('--media', 'Read file media/content')
+        .action(async (options) => {
+        const formatter = new Formatter({ format: config.resolved.format });
+        const resolved = config.resolved;
+        const orgId = options.org || resolved.org;
+        if (!orgId) {
+            formatter.error({
+                code: CliErrorCode.MISSING_REQUIRED,
+                message: 'Organization ID is required.',
+                detail: 'Pass --org <oid> or set a default organization using `apinow orgs set-default <oid>`.',
+            });
+            process.exit(1);
+        }
+        let id = options.id;
+        if (!id && process.stdout.isTTY) {
+            try {
+                const client = getSdkClient();
+                const res = await client.files.list(orgId, {}, { token: client.token });
+                const files = res.data || [];
+                if (files.length > 0) {
+                    id = await askSelect('Select a file to read:', files.map((f) => ({
+                        name: `${f.info?.name || 'Unnamed'} (${f.kind})`,
+                        value: f.key,
+                    })));
+                }
+            }
+            catch (_err) {
+                // Ignore and let standard missing error handle below
+            }
+        }
+        if (!id) {
+            formatter.error({
+                code: CliErrorCode.MISSING_REQUIRED,
+                message: 'File ID is required.',
+                detail: 'Specify --id <fid>.',
+            });
+            process.exit(1);
+        }
+        try {
+            const client = getSdkClient();
+            if (options.media) {
+                const res = await client.files.readMedia(orgId, id, { token: client.token });
+                const content = res.media;
+                if (resolved.format === 'json') {
+                    console.log(JSON.stringify(content, null, 2));
+                }
+                else {
+                    if (typeof content === 'object' && content !== null) {
+                        console.log(JSON.stringify(content, null, 2));
+                    }
+                    else {
+                        console.log(content);
+                    }
+                }
+            }
+            else {
+                const meta = await client.files.read(orgId, id, { token: client.token });
+                formatter.object(meta);
+            }
+        }
+        catch (err) {
+            const apiErr = handleApiError(err);
+            formatter.error(apiErr);
+            process.exit(1);
+        }
+    });
+}
+/**
+ * Translates a user-friendly kind name (e.g. 'api', 'domain', 'folder')
+ * to the corresponding core platform file metadata Kind value.
+ */
+function getFileMetaKind(kind) {
+    const k = kind.toLowerCase();
+    if (k === 'api') {
+        return ApiFileKind;
+    }
+    if (k === 'domain') {
+        return DomainFileKind;
+    }
+    if (k === 'folder') {
+        return FolderKind;
+    }
+    throw new Error(`Unsupported file kind "${kind}". Allowed: api, domain, folder`);
+}
+/**
+ * Asynchronously reads all input from standard input (STDIN).
+ */
+async function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => {
+            resolve(data);
+        });
+        process.stdin.on('error', (err) => {
+            reject(err);
+        });
+    });
+}