@aopslabs/aops 0.2.0

package/dist/commands/target.js

@@ -0,0 +1,309 @@
+import { Command } from 'commander';
+import { getActiveApiTarget, getApiTarget, listApiTargets, isRemoteSessionAuthProvider, normalizeApiTargetAuthProvider, normalizeApiTargetName, removeApiTarget, setApiTarget, useApiTarget, validateApiTarget, } from '../utils/config.js';
+import { createCliApiClientFromOptions, fetchCliPublicJson } from '../utils/api.js';
+import { evaluateCommunityCompatibility, resolveCommunityCliIdentity, } from '../lib/community-client-contract.js';
+function output(value, json = false) {
+    if (json)
+        console.log(JSON.stringify(value, null, 2));
+    else if (typeof value === 'string')
+        console.log(value);
+    else
+        console.log(JSON.stringify(value, null, 2));
+}
+export async function runTargetAdd(options) {
+    const name = normalizeApiTargetName(options.name);
+    const target = validateApiTarget(options);
+    if (!options.apply) {
+        const result = {
+            status: 'preview',
+            mutationFree: true,
+            action: 'target-add',
+            target: { name, ...target, active: options.use === true },
+            next: 'Re-run with --apply to persist this target.',
+        };
+        options.resultSink?.(result);
+        if (!options.quiet)
+            output(result, options.json);
+        return;
+    }
+    const result = setApiTarget({ ...options, name, activate: options.use });
+    const payload = { status: 'target-saved', target: result };
+    options.resultSink?.(payload);
+    if (!options.quiet)
+        output(payload, options.json);
+}
+export async function runTargetUse(name, options) {
+    const normalized = normalizeApiTargetName(name);
+    const target = getApiTarget(normalized);
+    if (!target)
+        throw new Error(`aops_target_not_found:${normalized}`);
+    if (!options.apply) {
+        output({
+            status: 'preview',
+            mutationFree: true,
+            action: 'target-use',
+            target: { ...target, active: true },
+            next: 'Re-run with --apply to select this target.',
+        }, options.json);
+        return;
+    }
+    output({ status: 'target-selected', target: useApiTarget(normalized) }, options.json);
+}
+export async function runTargetList(options) {
+    const targets = listApiTargets();
+    if (options.json)
+        output({ status: 'ok', targets }, true);
+    else if (targets.length === 0)
+        output('No targets configured.');
+    else
+        for (const target of targets) {
+            output(`${target.active ? '*' : ' '} ${target.name} ${target.apiBaseUrl} ${target.authProvider} credentials=${target.hasCredentials ? 'stored' : 'none'}`);
+        }
+}
+export async function runTargetShow(name, options) {
+    const target = name ? getApiTarget(name) : getActiveApiTarget();
+    if (!target)
+        throw new Error(name ? `aops_target_not_found:${name}` : 'aops_target_active_missing');
+    output({ status: 'ok', target }, options.json);
+}
+export async function runTargetRemove(name, options) {
+    const normalized = normalizeApiTargetName(name);
+    const target = getApiTarget(normalized);
+    if (!target)
+        throw new Error(`aops_target_not_found:${normalized}`);
+    if (!options.apply) {
+        output({
+            status: 'preview',
+            mutationFree: true,
+            action: 'target-remove',
+            target,
+            credentialsWillBeRemoved: target.hasCredentials,
+            next: 'Re-run with --apply --confirm to remove the target and its stored credentials.',
+        }, options.json);
+        return;
+    }
+    if (!options.confirm)
+        throw new Error('aops_target_remove_confirmation_required:use_--confirm');
+    removeApiTarget(normalized);
+    output({ status: 'target-removed', name: normalized }, options.json);
+}
+export async function inspectTargetDoctor(name, options = {}) {
+    const target = name ? getApiTarget(name) : getActiveApiTarget();
+    if (!target)
+        throw new Error(name ? `aops_target_not_found:${name}` : 'aops_target_active_missing');
+    const cli = resolveCommunityCliIdentity();
+    const api = await createCliApiClientFromOptions({ targetName: target.name, timeoutMs: options.timeoutMs });
+    let discovery;
+    try {
+        discovery = await fetchCliPublicJson(api, '/api-info.json', {
+            timeoutMs: options.timeoutMs,
+        });
+    }
+    catch (error) {
+        return {
+            status: 'unavailable',
+            mutationFree: false,
+            networkMutationFree: true,
+            localConfigMigrationPossible: true,
+            target,
+            endpointSource: api.endpointSource,
+            serverIdentity: null,
+            bootstrap: null,
+            session: {
+                state: 'unavailable',
+                authenticated: null,
+                credentialsStored: target.hasCredentials,
+                principal: null,
+                httpStatus: null,
+            },
+            compatibility: {
+                status: 'incompatible',
+                compatible: false,
+                reason: error instanceof Error ? error.message : String(error),
+                cli,
+            },
+        };
+    }
+    const compatibility = evaluateCommunityCompatibility(discovery?.clientCompatibility, cli);
+    let healthResponse;
+    try {
+        healthResponse = await api.client.requestXfJson('/api/health', { method: 'GET' }, { auth: false, retry401: false, timeoutMs: options.timeoutMs });
+    }
+    catch (error) {
+        return {
+            status: 'unavailable',
+            mutationFree: false,
+            networkMutationFree: true,
+            localConfigMigrationPossible: true,
+            target,
+            endpointSource: api.endpointSource,
+            serverIdentity: compatibility.server ?? null,
+            bootstrap: null,
+            session: {
+                state: 'unavailable',
+                authenticated: null,
+                credentialsStored: target.hasCredentials,
+                principal: null,
+                httpStatus: null,
+            },
+            compatibility,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const healthData = healthResponse.result?.data;
+    const bootstrap = healthData?.bootstrap;
+    const rawObservedProvider = bootstrap?.authProvider ?? bootstrap?.auth?.provider;
+    const observedProvider = normalizeApiTargetAuthProvider(rawObservedProvider) ?? null;
+    const observedAuthRequired = typeof bootstrap?.authRequired === 'boolean' ? bootstrap.authRequired : null;
+    const expectedAuthRequired = isRemoteSessionAuthProvider(target.authProvider);
+    const healthContractKnown = observedProvider !== null && observedAuthRequired !== null;
+    const providerMatches = observedProvider === target.authProvider;
+    const authRequiredMatches = observedAuthRequired === expectedAuthRequired;
+    const healthContractMatches = healthContractKnown && providerMatches && authRequiredMatches;
+    let session;
+    try {
+        const response = await api.client.requestXfJson('/api/auth/me', { method: 'GET' }, {
+            retry401: false,
+            timeoutMs: options.timeoutMs,
+        });
+        const responseData = response.result?.data;
+        const principal = responseData?.principal;
+        const principalUserId = typeof principal?.userId === 'string' ? principal.userId.trim() : '';
+        const principalResponseOk = response.status === 200 && response.result?.ok === true && Boolean(principalUserId);
+        const sessionProvider = normalizeApiTargetAuthProvider(responseData?.authProvider) ?? null;
+        const sessionAuthRequired = typeof responseData?.authRequired === 'boolean' ? responseData.authRequired : null;
+        const sessionContractKnown = !principalResponseOk || (sessionProvider !== null && sessionAuthRequired !== null);
+        const sessionProviderMatches = !principalResponseOk || sessionProvider === target.authProvider;
+        const sessionAuthRequiredMatches = !principalResponseOk || sessionAuthRequired === expectedAuthRequired;
+        const sessionContractMatches = sessionContractKnown && sessionProviderMatches && sessionAuthRequiredMatches;
+        const authenticated = principalResponseOk && sessionContractMatches;
+        const directError = response.result?.error;
+        const reason = typeof directError === 'string'
+            ? directError
+            : response.result?.messages?.map((message) => message.messageText).filter(Boolean).join('; ') || null;
+        session = {
+            state: principalResponseOk && !sessionContractKnown
+                ? 'auth-contract-unknown'
+                : principalResponseOk && !sessionContractMatches
+                    ? 'auth-provider-mismatch'
+                    : authenticated
+                        ? expectedAuthRequired ? 'authenticated' : 'trusted-local'
+                        : 'authentication-required',
+            authenticated,
+            credentialsStored: target.hasCredentials,
+            authProvider: sessionProvider,
+            authRequired: sessionAuthRequired,
+            contractKnown: sessionContractKnown,
+            providerMatches: sessionProviderMatches,
+            authRequiredMatches: sessionAuthRequiredMatches,
+            principal: authenticated
+                ? {
+                    userId: principalUserId,
+                    ...(typeof principal?.email === 'string' ? { email: principal.email } : {}),
+                    ...(typeof principal?.fullName === 'string' ? { fullName: principal.fullName } : {}),
+                    ...(Array.isArray(principal?.roles) ? { roles: principal.roles } : {}),
+                    ...(Array.isArray(principal?.capabilities) ? { capabilities: principal.capabilities } : {}),
+                }
+                : null,
+            httpStatus: response.status,
+            reason,
+        };
+    }
+    catch (error) {
+        session = {
+            state: 'unavailable',
+            authenticated: null,
+            credentialsStored: target.hasCredentials,
+            principal: null,
+            httpStatus: null,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const authenticated = session.authenticated === true;
+    const status = !compatibility.compatible
+        ? 'incompatible'
+        : healthResponse.status < 200 || healthResponse.status >= 300
+            ? 'bootstrap-action-required'
+            : !healthContractKnown || session.state === 'auth-contract-unknown'
+                ? 'auth-contract-unknown'
+                : !healthContractMatches || session.state === 'auth-provider-mismatch'
+                    ? 'auth-provider-mismatch'
+                    : expectedAuthRequired && !authenticated
+                        ? 'authentication-required'
+                        : compatibility.status;
+    return {
+        status,
+        mutationFree: false,
+        networkMutationFree: true,
+        localConfigMigrationPossible: true,
+        target,
+        endpointSource: api.endpointSource,
+        serverIdentity: compatibility.server ?? null,
+        health: {
+            httpStatus: healthResponse.status,
+            status: healthData?.status ?? null,
+            service: healthData?.service ?? null,
+        },
+        bootstrap: {
+            authProvider: observedProvider,
+            authRequired: observedAuthRequired,
+            configOk: bootstrap?.configOk ?? null,
+            loginSupported: bootstrap?.auth?.loginSupported ?? null,
+            storagePolicyOk: bootstrap?.auth?.storagePolicyOk ?? null,
+            firstAdminState: bootstrap?.auth?.firstAdminState ?? null,
+            userCount: bootstrap?.auth?.userCount ?? null,
+            adminUserCount: bootstrap?.auth?.adminUserCount ?? null,
+            expectedAuthProvider: target.authProvider,
+            expectedAuthRequired,
+            contractKnown: healthContractKnown,
+            providerMatches,
+            authRequiredMatches,
+        },
+        session,
+        compatibility,
+    };
+}
+export async function runTargetDoctor(name, options) {
+    const result = await inspectTargetDoctor(name, options);
+    output(result, options.json);
+    if (result.status === 'incompatible' ||
+        result.status === 'unavailable' ||
+        result.status === 'auth-contract-unknown' ||
+        result.status === 'auth-provider-mismatch' ||
+        result.status === 'bootstrap-action-required' ||
+        result.status === 'authentication-required')
+        process.exitCode = 1;
+}
+export function makeTargetCommand() {
+    const command = new Command('target').description('Manage named local or remote AOPS server targets');
+    command.command('add')
+        .requiredOption('--name <name>', 'Stable local target name')
+        .requiredOption('--api-base-url <url>', 'Server base URL without credentials or a path')
+        .option('--auth-provider <trusted-local|remote-session>', 'Authentication policy; authv2-jwt-session remains a one-release alias')
+        .option('--tls-policy <loopback-http|system-ca>', 'Transport trust policy')
+        .option('--use', 'Select this target after it is saved')
+        .option('--apply', 'Persist the target; default is a mutation-free preview')
+        .option('--json', 'Output JSON')
+        .action(runTargetAdd);
+    command.command('use <name>')
+        .option('--apply', 'Persist the active target; default is a mutation-free preview')
+        .option('--json', 'Output JSON')
+        .action(runTargetUse);
+    command.command('list').option('--json', 'Output JSON').action(runTargetList);
+    command.command('show [name]').option('--json', 'Output JSON').action(runTargetShow);
+    command.command('remove <name>')
+        .option('--apply', 'Remove the target; default is a mutation-free preview')
+        .option('--confirm', 'Confirm removal of the target and its credentials')
+        .option('--json', 'Output JSON')
+        .action(runTargetRemove);
+    command.command('doctor [name]')
+        .option('--timeout-ms <ms>', 'Request timeout', (value) => Number.parseInt(value, 10))
+        .option('--json', 'Output JSON')
+        .action(runTargetDoctor)
+        .addHelpText('after', `
+Plain HTTP is accepted only for loopback trusted-local targets. Every
+remote-session target, including Tailscale addresses, must use HTTPS with the
+system CA policy.
+`);
+    return command;
+}

package/dist/commands/version.js

@@ -0,0 +1,42 @@
+import { Command } from 'commander';
+import { getActiveApiTarget } from '../utils/config.js';
+import { inspectCommunityInstall } from '../lib/community-lifecycle.js';
+import { resolveCommunityCliIdentity } from '../lib/community-client-contract.js';
+export async function runVersion(options = {}) {
+    const identity = resolveCommunityCliIdentity();
+    if (!options.verbose) {
+        if (options.json)
+            console.log(JSON.stringify(identity, null, 2));
+        else
+            console.log(identity.version);
+        return;
+    }
+    const target = getActiveApiTarget();
+    const install = inspectCommunityInstall({ instanceName: options.instance, dataRoot: options.dataRoot });
+    const result = {
+        cli: identity,
+        selectedTarget: target ?? null,
+        localInstance: install.status === 'installed'
+            ? {
+                status: install.status,
+                instance: install.state.instanceName,
+                runtime: 'oci',
+                releaseVersion: install.state.activeRelease.releaseVersion,
+            }
+            : { status: install.status, instanceRoot: install.paths.instanceRoot },
+        compatibility: target?.compatibility ?? null,
+    };
+    if (options.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(JSON.stringify(result, null, 2));
+}
+export function makeVersionCommand() {
+    return new Command('version')
+        .description('Show immutable CLI identity and optional target/runtime context')
+        .option('--verbose', 'Include selected target, local instance, and last observed compatibility')
+        .option('--instance <name>', 'Local instance name used by --verbose', 'default')
+        .option('--data-root <path>', 'Local instance data-root override')
+        .option('--json', 'Output JSON')
+        .action(runVersion);
+}