@constructive-io/cli 0.0.3 → 5.1.0

package/esm/commands/codegen.js

@@ -0,0 +1,126 @@
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import yaml from 'js-yaml';
+import { runCodegen, defaultGraphQLCodegenOptions, mergeGraphQLCodegenOptions } from '@constructive-io/graphql-codegen';
+import { fetchEndpointSchemaSDL } from '@constructive-io/graphql-server';
+const usage = `
+Constructive GraphQL Codegen:
+
+  cnc codegen [OPTIONS]
+
+Options:
+  --help, -h                 Show this help message
+  --config <path>            Config file (json|yaml)
+  --schema <path>            Schema SDL file path
+  --endpoint <url>           GraphQL endpoint to fetch schema via introspection
+  --headerHost <host>        Optional Host header to send with endpoint requests
+  --auth <token>             Optional Authorization header value (e.g., "Bearer 123")
+  --header "Name: Value"    Optional HTTP header; repeat to add multiple headers
+  --out <dir>                Output root directory (default: graphql/codegen/dist)
+  --format <gql|ts>          Document format (default: gql)
+  --convention <style>       Filename convention (dashed|underscore|camelcase|camelUpper)
+  --emitTypes <bool>         Emit types (default: true)
+  --emitOperations <bool>    Emit operations (default: true)
+  --emitSdk <bool>           Emit sdk (default: true)
+  --allowQuery <name>        Only generate for this root field (repeatable)
+  --excludeQuery <name>      Exclude this root field (repeatable)
+  --excludePattern <regex>   Exclude fields matching regex (repeatable)
+`;
+function parseBool(v, d) {
+    if (v === undefined)
+        return d;
+    if (typeof v === 'boolean')
+        return v;
+    const s = String(v).toLowerCase();
+    if (s === 'true')
+        return true;
+    if (s === 'false')
+        return false;
+    return d;
+}
+async function loadConfig(path) {
+    const content = await fs.readFile(path, 'utf8');
+    if (/\.ya?ml$/i.test(path))
+        return yaml.load(content);
+    if (/\.json$/i.test(path))
+        return JSON.parse(content);
+    return {};
+}
+export default async (argv, _prompter, _options) => {
+    if (argv.help || argv.h) {
+        console.log(usage);
+        process.exit(0);
+    }
+    const cwd = argv.cwd || process.cwd();
+    const configPath = argv.config || '';
+    let fileOpts = {};
+    if (configPath)
+        fileOpts = await loadConfig(configPath);
+    const overrides = {};
+    if (argv.schema)
+        overrides.input = { ...(overrides.input || {}), schema: String(argv.schema) };
+    if (argv.endpoint)
+        overrides.input = { ...(overrides.input || {}), endpoint: String(argv.endpoint) };
+    const headerHost = argv.headerHost ?? '';
+    const auth = argv.auth ?? '';
+    const headerArg = argv.header;
+    const headerList = Array.isArray(headerArg) ? headerArg : headerArg ? [headerArg] : [];
+    const headers = {};
+    if (auth)
+        headers['Authorization'] = auth;
+    for (const h of headerList) {
+        const idx = typeof h === 'string' ? h.indexOf(':') : -1;
+        if (idx <= 0)
+            continue;
+        const name = h.slice(0, idx).trim();
+        const value = h.slice(idx + 1).trim();
+        if (!name)
+            continue;
+        headers[name] = value;
+    }
+    if (Object.keys(headers).length)
+        overrides.input = { ...(overrides.input || {}), headers };
+    if (argv.out)
+        overrides.output = { ...(overrides.output || {}), root: String(argv.out) };
+    if (argv.format)
+        overrides.documents = { ...(overrides.documents || {}), format: String(argv.format) };
+    if (argv.convention)
+        overrides.documents = { ...(overrides.documents || {}), convention: String(argv.convention) };
+    const allowQueryArg = argv.allowQuery;
+    const excludeQueryArg = argv.excludeQuery;
+    const excludePatternArg = argv.excludePattern;
+    const allowQueries = Array.isArray(allowQueryArg) ? allowQueryArg : allowQueryArg ? [String(allowQueryArg)] : [];
+    const excludeQueries = Array.isArray(excludeQueryArg) ? excludeQueryArg : excludeQueryArg ? [String(excludeQueryArg)] : [];
+    const excludePatterns = Array.isArray(excludePatternArg) ? excludePatternArg : excludePatternArg ? [String(excludePatternArg)] : [];
+    if (allowQueries.length || excludeQueries.length || excludePatterns.length) {
+        overrides.documents = { ...(overrides.documents || {}), allowQueries, excludeQueries, excludePatterns };
+    }
+    const emitTypes = parseBool(argv.emitTypes, true);
+    const emitOperations = parseBool(argv.emitOperations, true);
+    const emitSdk = parseBool(argv.emitSdk, true);
+    overrides.features = { emitTypes, emitOperations, emitSdk };
+    const merged = mergeGraphQLCodegenOptions(defaultGraphQLCodegenOptions, fileOpts);
+    const finalOptions = mergeGraphQLCodegenOptions(merged, overrides);
+    if (finalOptions.input.endpoint && headerHost) {
+        const opts = {};
+        if (headerHost)
+            opts.headerHost = headerHost;
+        if (auth)
+            opts.auth = auth;
+        if (Object.keys(headers).length)
+            opts.headers = headers;
+        const sdl = await fetchEndpointSchemaSDL(String(finalOptions.input.endpoint), opts);
+        const tmpSchemaPath = join(cwd, '.constructive-codegen-schema.graphql');
+        await fs.writeFile(tmpSchemaPath, sdl, 'utf8');
+        finalOptions.input.schema = tmpSchemaPath;
+        finalOptions.input.endpoint = '';
+    }
+    const hasSchema = !!finalOptions.input.schema && String(finalOptions.input.schema).trim() !== '';
+    const hasEndpoint = !!finalOptions.input.endpoint && String(finalOptions.input.endpoint).trim() !== '';
+    if (!hasSchema && !hasEndpoint) {
+        console.error('Missing --schema or --endpoint or config.input');
+        process.exit(1);
+    }
+    const result = await runCodegen(finalOptions, cwd);
+    console.log(`Generated at ${join(result.root)}`);
+};

package/esm/commands/explorer.js

@@ -0,0 +1,92 @@
+import { getEnvOptions } from '@constructive-io/graphql-env';
+import { GraphQLExplorer as explorer } from '@constructive-io/graphql-explorer';
+import { Logger } from '@pgpmjs/logger';
+const log = new Logger('explorer');
+const explorerUsageText = `
+Constructive GraphQL Explorer:
+
+  cnc explorer [OPTIONS]
+
+  Launch GraphiQL explorer interface.
+
+Options:
+  --help, -h              Show this help message
+  --port <number>         Server port (default: 5555)
+  --origin <url>          CORS origin URL (default: http://localhost:3000)
+  --simpleInflection      Use simple inflection (default: true)
+  --oppositeBaseNames     Use opposite base names (default: false)
+  --postgis               Enable PostGIS extension (default: true)
+  --cwd <directory>       Working directory (default: current directory)
+
+Examples:
+  cnc explorer                        Launch explorer with defaults
+  cnc explorer --origin http://localhost:4000  Launch explorer with custom origin
+`;
+const questions = [
+    {
+        name: 'simpleInflection',
+        message: 'Use simple inflection?',
+        type: 'confirm',
+        required: false,
+        default: true,
+        useDefault: true
+    },
+    {
+        name: 'oppositeBaseNames',
+        message: 'Use opposite base names?',
+        type: 'confirm',
+        required: false,
+        default: false,
+        useDefault: true
+    },
+    {
+        name: 'postgis',
+        message: 'Enable PostGIS extension?',
+        type: 'confirm',
+        required: false,
+        default: true,
+        useDefault: true
+    },
+    {
+        name: 'port',
+        message: 'Development server port',
+        type: 'number',
+        required: false,
+        default: 5555,
+        useDefault: true
+    },
+    {
+        name: 'origin',
+        message: 'CORS origin URL',
+        type: 'text',
+        required: false,
+        default: 'http://localhost:3000',
+        useDefault: true
+    }
+];
+export default async (argv, prompter, _options) => {
+    // Show usage if explicitly requested
+    if (argv.help || argv.h) {
+        console.log(explorerUsageText);
+        process.exit(0);
+    }
+    log.info('🔧 Constructive GraphQL Explorer Configuration:\n');
+    const { oppositeBaseNames, origin, port, postgis, simpleInflection } = await prompter.prompt(argv, questions);
+    const options = getEnvOptions({
+        features: {
+            oppositeBaseNames,
+            simpleInflection,
+            postgis
+        },
+        server: {
+            origin,
+            port
+        }
+    });
+    log.success('✅ Selected Configuration:');
+    for (const [key, value] of Object.entries(options)) {
+        log.debug(`${key}: ${JSON.stringify(value)}`);
+    }
+    log.success('🚀 Launching Explorer...\n');
+    explorer(options);
+};

package/esm/commands/get-graphql-schema.js

@@ -0,0 +1,71 @@
+import { promises as fs } from 'fs';
+import { buildSchemaSDL, fetchEndpointSchemaSDL } from '@constructive-io/graphql-server';
+const usage = `
+Constructive Get GraphQL Schema:
+
+  cnc get-graphql-schema [OPTIONS]
+
+Options:
+  --help, -h              Show this help message
+  --database <name>       Database name (default: constructive)
+  --schemas <list>        Comma-separated schemas to include
+  --endpoint <url>        GraphQL endpoint to fetch schema via introspection
+  --headerHost <host>     Optional Host header to send with endpoint requests
+  --auth <token>          Optional Authorization header value (e.g., "Bearer 123")
+  --header "Name: Value"  Optional HTTP header; repeat to add multiple headers
+  --out <path>            Output file path (default: print to stdout)
+`;
+const defaultSchemas = [
+    'collections_public',
+    'dashboard_public'
+];
+export default async (argv, prompter, _options) => {
+    if (argv.help || argv.h) {
+        console.log(usage);
+        process.exit(0);
+    }
+    const endpoint = argv.endpoint ?? '';
+    const headerHost = argv.headerHost ?? '';
+    const auth = argv.auth ?? '';
+    const database = argv.database ?? 'constructive';
+    const schemasArg = argv.schemas ?? defaultSchemas.join(',');
+    const out = argv.out ?? '';
+    const headerArg = argv.header;
+    const headerList = Array.isArray(headerArg) ? headerArg : headerArg ? [headerArg] : [];
+    const headers = {};
+    for (const h of headerList) {
+        const idx = typeof h === 'string' ? h.indexOf(':') : -1;
+        if (idx <= 0)
+            continue;
+        const name = h.slice(0, idx).trim();
+        const value = h.slice(idx + 1).trim();
+        if (!name)
+            continue;
+        headers[name] = value;
+    }
+    const schemas = schemasArg.split(',').map(s => s.trim()).filter(Boolean);
+    let sdl;
+    if (endpoint) {
+        const opts = {};
+        if (headerHost)
+            opts.headerHost = headerHost;
+        if (auth)
+            opts.auth = auth;
+        if (Object.keys(headers).length)
+            opts.headers = headers;
+        sdl = await fetchEndpointSchemaSDL(endpoint, opts);
+    }
+    else {
+        // The server package already depends on postgraphile and graphql,
+        // and exporting a reusable programmatic builder from there
+        // avoids adding new dependencies to cli and prevents duplication.
+        sdl = await buildSchemaSDL({ database, schemas });
+    }
+    if (out) {
+        await fs.writeFile(out, sdl, 'utf8');
+        console.log(`Wrote schema SDL to ${out}`);
+    }
+    else {
+        process.stdout.write(sdl + '\n');
+    }
+};

package/esm/commands/server.js

@@ -0,0 +1,185 @@
+import { getEnvOptions } from '@constructive-io/graphql-env';
+import { Logger } from '@pgpmjs/logger';
+import { GraphQLServer as server } from '@constructive-io/graphql-server';
+import { getPgPool } from 'pg-cache';
+const log = new Logger('server');
+const serverUsageText = `
+Constructive GraphQL Server:
+
+  cnc server [OPTIONS]
+
+  Start Constructive GraphQL development server.
+
+Options:
+  --help, -h              Show this help message
+  --port <number>         Server port (default: 5555)
+  --simpleInflection      Use simple inflection (default: true)
+  --oppositeBaseNames     Use opposite base names (default: false)
+  --postgis               Enable PostGIS extension (default: true)
+  --metaApi               Enable Meta API (default: true)
+  --cwd <directory>       Working directory (default: current directory)
+
+Examples:
+  cnc server                    Start server with defaults
+  cnc server --port 8080        Start server on custom port
+  cnc server --no-postgis       Start server without PostGIS
+`;
+const questions = [
+    {
+        name: 'simpleInflection',
+        message: 'Use simple inflection?',
+        type: 'confirm',
+        required: false,
+        default: true,
+        useDefault: true
+    },
+    {
+        name: 'oppositeBaseNames',
+        message: 'Use opposite base names?',
+        type: 'confirm',
+        required: false,
+        default: false,
+        useDefault: true
+    },
+    {
+        name: 'postgis',
+        message: 'Enable PostGIS extension?',
+        type: 'confirm',
+        required: false,
+        default: true,
+        useDefault: true
+    },
+    {
+        name: 'metaApi',
+        message: 'Enable Meta API?',
+        type: 'confirm',
+        required: false,
+        default: true,
+        useDefault: true
+    },
+    {
+        name: 'origin',
+        message: 'CORS origin (exact URL or *)',
+        type: 'text',
+        required: false,
+        // no default to avoid accidentally opening up CORS; pass explicitly or via env
+    },
+    {
+        name: 'port',
+        message: 'Development server port',
+        type: 'number',
+        required: false,
+        default: 5555,
+        useDefault: true
+    }
+];
+export default async (argv, prompter, _options) => {
+    // Show usage if explicitly requested
+    if (argv.help || argv.h) {
+        console.log(serverUsageText);
+        process.exit(0);
+    }
+    log.info('🔧 Constructive GraphQL Server Configuration:\n');
+    let selectedDb = process.env.PGDATABASE;
+    if (!selectedDb) {
+        const db = await getPgPool({ database: 'postgres' });
+        const result = await db.query(`
+      SELECT datname FROM pg_database
+      WHERE datistemplate = false AND datname NOT IN ('postgres')
+        AND datname !~ '^pg_'
+      ORDER BY datname;
+    `);
+        const dbChoices = result.rows.map(row => row.datname);
+        const { database } = await prompter.prompt(argv, [
+            {
+                type: 'autocomplete',
+                name: 'database',
+                message: 'Select the database to use',
+                options: dbChoices,
+                required: true
+            }
+        ]);
+        selectedDb = database;
+        log.info(`📌 Using database: "${selectedDb}"`);
+    }
+    const { oppositeBaseNames, port, postgis, simpleInflection, metaApi, origin } = await prompter.prompt(argv, questions);
+    // Warn when passing CORS override via CLI, especially in production
+    if (origin && origin.trim().length) {
+        const env = (process.env.NODE_ENV || 'development').toLowerCase();
+        if (env === 'production') {
+            if (origin.trim() === '*') {
+                log.warn('CORS wildcard ("*") provided via --origin in production: this effectively disables CORS and is not recommended. Prefer per-API CORS via meta schema.');
+            }
+            else {
+                log.warn(`CORS override (origin=${origin.trim()}) provided via --origin in production. Prefer per-API CORS via meta schema.`);
+            }
+        }
+    }
+    let selectedSchemas = [];
+    let authRole;
+    let roleName;
+    if (!metaApi) {
+        const db = await getPgPool({ database: selectedDb });
+        const result = await db.query(`
+      SELECT nspname 
+      FROM pg_namespace 
+      WHERE nspname NOT IN ('pg_catalog', 'information_schema')
+      ORDER BY nspname;
+    `);
+        const schemaChoices = result.rows.map(row => ({
+            name: row.nspname,
+            value: row.nspname,
+            selected: true
+        }));
+        const { schemas } = await prompter.prompt(argv, [
+            {
+                type: 'checkbox',
+                name: 'schemas',
+                message: 'Select schemas to expose',
+                options: schemaChoices,
+                required: true
+            }
+        ]);
+        selectedSchemas = schemas.filter(s => s.selected).map(s => s.value);
+        const { authRole: selectedAuthRole, roleName: selectedRoleName } = await prompter.prompt(argv, [
+            {
+                type: 'autocomplete',
+                name: 'authRole',
+                message: 'Select the authentication role',
+                options: ['postgres', 'authenticated', 'anonymous'],
+                required: true
+            },
+            {
+                type: 'autocomplete',
+                name: 'roleName',
+                message: 'Enter the default role name:',
+                options: ['postgres', 'authenticated', 'anonymous'],
+                required: true
+            }
+        ]);
+        authRole = selectedAuthRole;
+        roleName = selectedRoleName;
+    }
+    const options = getEnvOptions({
+        pg: { database: selectedDb },
+        features: {
+            oppositeBaseNames,
+            simpleInflection,
+            postgis
+        },
+        api: {
+            enableMetaApi: metaApi,
+            ...(metaApi === false && { exposedSchemas: selectedSchemas, authRole, roleName })
+        },
+        server: {
+            port,
+            ...(origin ? { origin } : {})
+        }
+    });
+    log.success('✅ Selected Configuration:');
+    for (const [key, value] of Object.entries(options)) {
+        log.debug(`${key}: ${JSON.stringify(value)}`);
+    }
+    log.success('🚀 Launching Server...\n');
+    server(options);
+};

package/esm/commands.js

@@ -1,78 +1,59 @@
-import { teardownPgPools } from 'pg-cache';
-import add from './commands/add';
-import adminUsers from './commands/admin-users';
-import analyze from './commands/analyze';
-import clear from './commands/clear';
-import deploy from './commands/deploy';
-import docker from './commands/docker';
-import env from './commands/env';
-import _export from './commands/export';
-import extension from './commands/extension';
-import init from './commands/init';
-import install from './commands/install';
-import kill from './commands/kill';
-import migrate from './commands/migrate';
-import _package from './commands/package';
-import plan from './commands/plan';
-import remove from './commands/remove';
-import renameCmd from './commands/rename';
-import revert from './commands/revert';
-import tag from './commands/tag';
-import verify from './commands/verify';
-import { readAndParsePackageJson } from './package';
-import { extractFirst, usageText } from './utils';
-import { cliExitWithError } from './utils/cli-error';
-const withPgTeardown = (fn, skipTeardown = false) => async (...args) => {
-    try {
-        await fn(...args);
-    }
-    finally {
-        if (!skipTeardown) {
-            await teardownPgPools();
-        }
-    }
-};
-export const createConstructiveCommandMap = (skipPgTeardown = false) => {
-    const pgt = (fn) => withPgTeardown(fn, skipPgTeardown);
+import { findAndRequirePackageJson } from 'find-and-require-package-json';
+import { checkForUpdates, createInitUsageText, createPgpmCommandMap } from 'pgpm';
+import codegen from './commands/codegen';
+import explorer from './commands/explorer';
+import getGraphqlSchema from './commands/get-graphql-schema';
+import server from './commands/server';
+import { cliExitWithError, extractFirst, usageText } from './utils';
+const createCommandMap = (skipPgTeardown = false) => {
+    const pgpmCommands = createPgpmCommandMap(skipPgTeardown);
     return {
-        add,
-        'admin-users': pgt(adminUsers),
-        clear: pgt(clear),
-        deploy: pgt(deploy),
-        docker,
-        env,
-        verify: pgt(verify),
-        revert: pgt(revert),
-        remove: pgt(remove),
-        init: pgt(init),
-        extension: pgt(extension),
-        plan: pgt(plan),
-        export: pgt(_export),
-        package: pgt(_package),
-        tag: pgt(tag),
-        kill: pgt(kill),
-        install: pgt(install),
-        migrate: pgt(migrate),
-        analyze: pgt(analyze),
-        rename: pgt(renameCmd)
+        ...pgpmCommands,
+        server,
+        explorer,
+        'get-graphql-schema': getGraphqlSchema,
+        codegen
     };
 };
 export const commands = async (argv, prompter, options) => {
+    let { first: command, newArgv } = extractFirst(argv);
+    // Run update check early so it shows on help/version paths too
+    try {
+        const pkg = findAndRequirePackageJson(__dirname);
+        await checkForUpdates({
+            command: command || 'help',
+            pkgName: pkg.name,
+            pkgVersion: pkg.version,
+            toolName: 'constructive',
+            key: pkg.name,
+            updateCommand: `Run npm i -g ${pkg.name}@latest to upgrade.`
+        });
+    }
+    catch {
+        // ignore update check failures
+    }
     if (argv.version || argv.v) {
-        const pkg = readAndParsePackageJson();
+        const pkg = findAndRequirePackageJson(__dirname);
         console.log(pkg.version);
         process.exit(0);
     }
-    let { first: command, newArgv } = extractFirst(argv);
+    // Show usage if explicitly requested but no command specified
     if ((argv.help || argv.h || command === 'help') && !command) {
         console.log(usageText);
         process.exit(0);
     }
+    // Show usage for help command specifically
     if (command === 'help') {
         console.log(usageText);
         process.exit(0);
     }
-    const commandMap = createConstructiveCommandMap(options?.skipPgTeardown);
+    // Command-specific help for init
+    if (command === 'init' && (argv.help || argv.h)) {
+        console.log(createInitUsageText('constructive', 'Constructive'));
+        process.exit(0);
+    }
+    const commandMap = createCommandMap(options?.skipPgTeardown);
+    // Prompt if no command provided
     if (!command) {
         const answer = await prompter.prompt(argv, [
             {
@@ -84,6 +65,7 @@ export const commands = async (argv, prompter, options) => {
         ]);
         command = answer.command;
     }
+    // Prompt for working directory
     newArgv = await prompter.prompt(newArgv, [
         {
             type: 'text',

package/esm/index.js

@@ -2,28 +2,13 @@
 import { readFileSync } from 'fs';
 import { CLI } from 'inquirerer';
 import { join } from 'path';
-import { commands, createConstructiveCommandMap } from './commands';
-export { createConstructiveCommandMap };
-export { default as add } from './commands/add';
-export { default as adminUsers } from './commands/admin-users';
-export { default as analyze } from './commands/analyze';
-export { default as clear } from './commands/clear';
-export { default as deploy } from './commands/deploy';
-export { default as docker } from './commands/docker';
-export { default as env } from './commands/env';
-export { default as _export } from './commands/export';
-export { default as extension } from './commands/extension';
-export { default as install } from './commands/install';
-export { default as kill } from './commands/kill';
-export { default as migrate } from './commands/migrate';
-export { default as _package } from './commands/package';
-export { default as plan } from './commands/plan';
-export { default as remove } from './commands/remove';
-export { default as renameCmd } from './commands/rename';
-export { default as revert } from './commands/revert';
-export { default as tag } from './commands/tag';
-export { default as verify } from './commands/verify';
-export * from './utils';
+import { commands } from './commands';
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+    const pkgPath = join(__dirname, 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    console.log(pkg.version);
+    process.exit(0);
+}
 export const options = {
     minimistOpts: {
         alias: {
@@ -32,17 +17,12 @@ export const options = {
         }
     }
 };
-if (require.main === module) {
-    if (process.argv.includes('--version') || process.argv.includes('-v')) {
-        const pkgPath = join(__dirname, 'package.json');
-        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
-        console.log(pkg.version);
-        process.exit(0);
-    }
-    const app = new CLI(commands, options);
-    app.run().then(() => {
-    }).catch(error => {
-        console.error('Unexpected error:', error);
-        process.exit(1);
-    });
-}
+const app = new CLI(commands, options);
+app.run().then(() => {
+    // all done!
+}).catch(error => {
+    // Should not reach here with the new CLI error handling pattern
+    // But keep as fallback for unexpected errors
+    console.error('Unexpected error:', error);
+    process.exit(1);
+});