@promptbook/cli 0.112.0-96 → 0.112.0-98

package/apps/agents-server/src/utils/standaloneVpsDnsDiagnostics.ts

@@ -0,0 +1,258 @@
+import { lookup } from 'dns/promises';
+import type {
+    ManagedServerDnsDiagnostic,
+    ManagedServerDnsExpectedRecord,
+    ManagedServerDnsProviderGuide,
+    ManagedServerDnsStatus,
+} from '../app/admin/servers/ServersRegistryDnsTypes';
+
+/**
+ * Resolver signature used for DNS lookups.
+ */
+type ResolveDnsAddresses = (domain: string) => Promise<ReadonlyArray<string>>;
+
+/**
+ * Input used to create one standalone VPS DNS diagnostic.
+ */
+type CreateStandaloneVpsDomainDnsDiagnosticOptions = {
+    /**
+     * Domain currently configured in the standalone VPS server registry.
+     */
+    readonly domain: string;
+
+    /**
+     * Public IP address detected/stored for the VPS runtime.
+     */
+    readonly publicIpAddress: string | null | undefined;
+
+    /**
+     * Optional already-working hostname that subdomains may target via CNAME.
+     */
+    readonly fallbackCnameTargetDomain?: string | null | undefined;
+
+    /**
+     * Optional resolver override used by unit tests.
+     */
+    readonly resolveDnsAddresses?: ResolveDnsAddresses;
+};
+
+/**
+ * Provider guides shown together with DNS record instructions.
+ */
+const DNS_PROVIDER_GUIDES: ReadonlyArray<ManagedServerDnsProviderGuide> = [
+    {
+        label: 'Cloudflare DNS records',
+        href: 'https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/',
+    },
+    {
+        label: 'GoDaddy DNS records',
+        href: 'https://www.godaddy.com/help/manage-dns-records-680',
+    },
+    {
+        label: 'Namecheap DNS records',
+        href: 'https://www.namecheap.com/support/knowledgebase/article.aspx/319/2237/how-can-i-set-up-an-a-address-record-for-my-domain/',
+    },
+    {
+        label: 'Squarespace DNS records',
+        href: 'https://support.squarespace.com/hc/en-us/articles/360002101888-Adding-custom-DNS-records-to-your-Squarespace-managed-domain',
+    },
+];
+
+/**
+ * DNS error codes treated as "not resolving yet" during propagation.
+ */
+const DNS_PENDING_ERROR_CODES = new Set(['ENOTFOUND', 'ENODATA', 'EAI_AGAIN', 'ESERVFAIL']);
+
+/**
+ * Creates the browser-safe DNS status for one standalone VPS domain.
+ *
+ * @param options - Domain, VPS IP, and optional resolver override.
+ * @returns DNS diagnostic rendered on `/admin/servers`.
+ */
+export async function createStandaloneVpsDomainDnsDiagnostic(
+    options: CreateStandaloneVpsDomainDnsDiagnosticOptions,
+): Promise<ManagedServerDnsDiagnostic> {
+    const publicIpAddress = normalizePublicIpAddress(options.publicIpAddress);
+    const expectedRecords = createExpectedDnsRecords({
+        domain: options.domain,
+        publicIpAddress,
+        fallbackCnameTargetDomain: options.fallbackCnameTargetDomain,
+    });
+
+    if (!publicIpAddress) {
+        return createDnsDiagnostic({
+            expectedRecords,
+            publicIpAddress: null,
+            resolvedAddresses: [],
+            status: 'unavailable',
+            summary: 'The VPS public IP address is not available yet, so DNS cannot be verified automatically.',
+        });
+    }
+
+    try {
+        const resolvedAddresses = uniqueStrings(
+            await (options.resolveDnsAddresses || resolveDnsAddresses)(options.domain),
+        );
+
+        if (resolvedAddresses.includes(publicIpAddress)) {
+            return createDnsDiagnostic({
+                expectedRecords,
+                publicIpAddress,
+                resolvedAddresses,
+                status: 'verified',
+                summary: `DNS is ready. \`${options.domain}\` resolves to this VPS.`,
+            });
+        }
+
+        if (resolvedAddresses.length === 0) {
+            return createDnsDiagnostic({
+                expectedRecords,
+                publicIpAddress,
+                resolvedAddresses,
+                status: 'pending',
+                summary: `\`${options.domain}\` does not resolve yet. Add the record below and wait for DNS propagation.`,
+            });
+        }
+
+        return createDnsDiagnostic({
+            expectedRecords,
+            publicIpAddress,
+            resolvedAddresses,
+            status: 'misconfigured',
+            summary: `\`${options.domain}\` currently resolves to ${resolvedAddresses.join(', ')}, not to this VPS IP \`${publicIpAddress}\`.`,
+        });
+    } catch (error) {
+        return createDnsDiagnostic({
+            expectedRecords,
+            publicIpAddress,
+            resolvedAddresses: [],
+            status: 'unavailable',
+            summary: `DNS verification failed: ${error instanceof Error ? error.message : 'Unknown DNS lookup error.'}`,
+        });
+    }
+}
+
+/**
+ * Resolves one hostname to all currently known IP addresses.
+ *
+ * @param domain - Domain to resolve.
+ * @returns Unique list of resolved IP addresses.
+ */
+async function resolveDnsAddresses(domain: string): Promise<ReadonlyArray<string>> {
+    try {
+        return (await lookup(domain, { all: true, verbatim: true })).map((record) => record.address);
+    } catch (error) {
+        const code = typeof error === 'object' && error !== null && 'code' in error ? String(error.code) : null;
+
+        if (code && DNS_PENDING_ERROR_CODES.has(code)) {
+            return [];
+        }
+
+        throw error;
+    }
+}
+
+/**
+ * Creates the expected DNS records shown in the admin UI.
+ *
+ * @param options - Record inputs.
+ * @returns DNS records the admin can copy into their provider.
+ */
+function createExpectedDnsRecords(options: {
+    readonly domain: string;
+    readonly publicIpAddress: string | null;
+    readonly fallbackCnameTargetDomain?: string | null | undefined;
+}): ReadonlyArray<ManagedServerDnsExpectedRecord> {
+    const expectedRecords: Array<ManagedServerDnsExpectedRecord> = [];
+
+    if (options.publicIpAddress) {
+        expectedRecords.push({
+            type: isIpv6Address(options.publicIpAddress) ? 'AAAA' : 'A',
+            name: options.domain,
+            value: options.publicIpAddress,
+            note: 'Recommended. Point this hostname directly to the VPS public IP address.',
+        });
+    }
+
+    if (options.fallbackCnameTargetDomain && options.fallbackCnameTargetDomain !== options.domain) {
+        expectedRecords.push({
+            type: 'CNAME',
+            name: options.domain,
+            value: options.fallbackCnameTargetDomain,
+            note: `Optional alternative for subdomains only. Use this only when \`${options.fallbackCnameTargetDomain}\` already works on this VPS.`,
+        });
+    }
+
+    return expectedRecords;
+}
+
+/**
+ * Normalizes the stored VPS public IP address.
+ *
+ * @param value - Raw environment/config value.
+ * @returns Normalized IP address or `null` when unavailable.
+ */
+function normalizePublicIpAddress(value: string | null | undefined): string | null {
+    const normalizedValue = (value || '').trim();
+
+    if (!normalizedValue || normalizedValue === 'localhost') {
+        return null;
+    }
+
+    return normalizedValue;
+}
+
+/**
+ * Creates one consistent browser payload for the DNS diagnostic.
+ *
+ * @param options - Normalized DNS state.
+ * @returns Browser-safe DNS payload.
+ */
+function createDnsDiagnostic(options: {
+    readonly expectedRecords: ReadonlyArray<ManagedServerDnsExpectedRecord>;
+    readonly publicIpAddress: string | null;
+    readonly resolvedAddresses: ReadonlyArray<string>;
+    readonly status: ManagedServerDnsStatus;
+    readonly summary: string;
+}): ManagedServerDnsDiagnostic {
+    return {
+        status: options.status,
+        summary: options.summary,
+        publicIpAddress: options.publicIpAddress,
+        resolvedAddresses: options.resolvedAddresses,
+        expectedRecords: options.expectedRecords,
+        providerGuides: DNS_PROVIDER_GUIDES,
+    };
+}
+
+/**
+ * Detects whether one resolved address is IPv6.
+ *
+ * @param value - Candidate IP address.
+ * @returns `true` when the address looks like IPv6.
+ */
+function isIpv6Address(value: string): boolean {
+    return value.includes(':');
+}
+
+/**
+ * Removes empty values and duplicates while preserving order.
+ *
+ * @param values - Candidate values.
+ * @returns Stable unique list.
+ */
+function uniqueStrings(values: ReadonlyArray<string>): Array<string> {
+    const uniqueValues: Array<string> = [];
+
+    for (const value of values) {
+        const normalizedValue = value.trim();
+
+        if (!normalizedValue || uniqueValues.includes(normalizedValue)) {
+            continue;
+        }
+
+        uniqueValues.push(normalizedValue);
+    }
+
+    return uniqueValues;
+}

package/apps/agents-server/src/utils/standaloneVpsRawIpBootstrap.ts

@@ -0,0 +1,87 @@
+/**
+ * Request-independent context used to decide whether standalone VPS setup should
+ * continue allowing raw-IP bootstrap access.
+ */
+export type StandaloneVpsRawIpBootstrapContext = {
+    /**
+     * Current canonical public site URL stored in the environment.
+     */
+    readonly nextPublicSiteUrl: string | null | undefined;
+
+    /**
+     * Known public IPv4/IPv6 address of the standalone VPS.
+     */
+    readonly publicIpAddress: string | null | undefined;
+};
+
+/**
+ * Returns whether the standalone VPS should keep allowing raw-IP bootstrap access.
+ *
+ * This stays enabled while the canonical public site URL still points to the VPS
+ * raw IP over plain HTTP, which means domain activation has not completed yet.
+ */
+export function isStandaloneVpsRawIpBootstrapActive(context: StandaloneVpsRawIpBootstrapContext): boolean {
+    const parsedPublicSiteUrl = parseAbsoluteHttpUrl(context.nextPublicSiteUrl);
+    if (!parsedPublicSiteUrl || parsedPublicSiteUrl.protocol !== 'http:') {
+        return false;
+    }
+
+    const normalizedSiteHost = normalizeHost(parsedPublicSiteUrl.host);
+    if (!normalizedSiteHost || !isIpAddressHost(normalizedSiteHost)) {
+        return false;
+    }
+
+    const normalizedConfiguredPublicIpAddress = normalizeHost(context.publicIpAddress || '');
+    if (normalizedConfiguredPublicIpAddress && normalizedSiteHost !== normalizedConfiguredPublicIpAddress) {
+        return false;
+    }
+
+    return true;
+}
+
+/**
+ * Parses one absolute HTTP(S) URL from environment configuration.
+ *
+ * @param value - Raw environment value.
+ * @returns Parsed URL or `null` when missing/invalid.
+ */
+function parseAbsoluteHttpUrl(value: string | null | undefined): URL | null {
+    if (!value) {
+        return null;
+    }
+
+    try {
+        const parsedUrl = new URL(value);
+
+        if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+            return null;
+        }
+
+        return parsedUrl;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Removes ports and IPv6 brackets from host-like strings.
+ *
+ * @param host - Raw host header value.
+ * @returns Normalized bare hostname or IP address.
+ */
+function normalizeHost(host: string | null | undefined): string {
+    return (host || '')
+        .trim()
+        .replace(/^\[(.+)\](?::\d+)?$/u, '$1')
+        .replace(/:\d+$/u, '');
+}
+
+/**
+ * Checks whether a host string points to a raw IPv4 or IPv6 address.
+ *
+ * @param host - Host header or hostname.
+ * @returns `true` when the host is a raw IP address.
+ */
+function isIpAddressHost(host: string): boolean {
+    return /^\d{1,3}(?:\.\d{1,3}){3}$/u.test(host) || host.includes(':');
+}

package/apps/agents-server/src/utils/vpsConfiguration.ts

@@ -6,6 +6,7 @@ import { promisify } from 'util';
 import { spaceTrim } from 'spacetrim';
 import { NotAllowed } from '../../../../src/errors/NotAllowed';
 import { normalizeServerDomain } from './serverRegistry';
+import { isStandaloneVpsRawIpBootstrapActive } from './standaloneVpsRawIpBootstrap';
 
 const execFileAsync = promisify(execFile);
 
@@ -87,6 +88,21 @@ export type VpsCommandResult = {
     readonly output: string;
 };
 
+/**
+ * Runtime-installer execution options used by VPS admin actions.
+ */
+type RunVpsInstallerCommandOptions = {
+    /**
+     * Whether the installer should disable interactive prompts.
+     */
+    readonly isNonInteractiveModeEnabled?: boolean;
+
+    /**
+     * Whether the installer may restart the running Agents Server process.
+     */
+    readonly isProcessRestartEnabled?: boolean;
+};
+
 /**
  * Parsed `.env` line representation used to preserve comments and ordering.
  */
@@ -191,30 +207,51 @@ export async function listConfiguredVpsDomains(): Promise<Array<string>> {
     return parseDomainsCsv(rawServers);
 }
 
+/**
+ * Options used when updating the standalone VPS domain list.
+ */
+type UpdateConfiguredVpsDomainsOptions = {
+    /**
+     * Optional server-level table prefix to persist together with the domain list.
+     */
+    readonly tablePrefix?: string | null;
+};
+
 /**
  * Replaces the standalone VPS domain list in `.env`.
  *
  * @param domains - Domains to store in `SERVERS`.
+ * @param options - Optional server-level settings to persist.
  * @returns Safe environment snapshot after writing.
  */
 export async function updateConfiguredVpsDomains(
     domains: ReadonlyArray<string>,
+    options?: UpdateConfiguredVpsDomainsOptions,
 ): Promise<Awaited<ReturnType<typeof listVpsEnvironmentVariables>>> {
     const normalizedDomains = normalizeDomains(domains);
     const primaryDomain = normalizedDomains[0] ?? '';
+    const envValues = await readVpsEnvironmentMap(resolveVpsEnvironmentFilePath());
+    const currentPublicSiteUrl = envValues.get('NEXT_PUBLIC_SITE_URL') ?? process.env.NEXT_PUBLIC_SITE_URL ?? '';
+    const publicIpAddress = envValues.get('PTBK_PUBLIC_IP_ADDRESS') ?? process.env.PTBK_PUBLIC_IP_ADDRESS ?? '';
     const updates: Record<string, string> = {
         SERVERS: normalizedDomains.join(','),
     };
 
     if (primaryDomain) {
-        updates.NEXT_PUBLIC_SITE_URL = `https://${primaryDomain}`;
-        updates.SUPABASE_TABLE_PREFIX = buildDomainTablePrefix(primaryDomain);
+        updates.NEXT_PUBLIC_SITE_URL = isStandaloneVpsRawIpBootstrapActive({
+            nextPublicSiteUrl: currentPublicSiteUrl,
+            publicIpAddress,
+        })
+            ? currentPublicSiteUrl
+            : `https://${primaryDomain}`;
     } else {
-        const publicIpAddress = process.env.PTBK_PUBLIC_IP_ADDRESS?.trim();
         updates.NEXT_PUBLIC_SITE_URL = publicIpAddress
             ? `http://${publicIpAddress}`
             : '';
-        updates.SUPABASE_TABLE_PREFIX = '';
+    }
+
+    if (options && Object.prototype.hasOwnProperty.call(options, 'tablePrefix')) {
+        updates.SUPABASE_TABLE_PREFIX = options.tablePrefix?.trim() || '';
     }
 
     return updateVpsEnvironmentVariables(updates);
@@ -225,8 +262,14 @@ export async function updateConfiguredVpsDomains(
  *
  * @returns Command output or a skipped reason when not running on a Linux VPS.
  */
-export async function applyVpsRuntimeConfiguration(): Promise<VpsCommandResult> {
-    return runVpsInstallerCommand('apply-domains', 'VPS runtime configuration can only be applied on Linux.');
+export async function applyVpsRuntimeConfiguration(
+    options?: RunVpsInstallerCommandOptions,
+): Promise<VpsCommandResult> {
+    return runVpsInstallerCommand(
+        'apply-domains',
+        'VPS runtime configuration can only be applied on Linux.',
+        options,
+    );
 }
 
 /**
@@ -270,7 +313,11 @@ export async function readVpsPm2Logs(lineCount = 200): Promise<VpsCommandResult>
  * @param unavailableOutput - Message returned on non-Linux platforms.
  * @returns Command output or unavailable reason.
  */
-async function runVpsInstallerCommand(command: string, unavailableOutput: string): Promise<VpsCommandResult> {
+async function runVpsInstallerCommand(
+    command: string,
+    unavailableOutput: string,
+    options?: RunVpsInstallerCommandOptions,
+): Promise<VpsCommandResult> {
     if (process.platform !== 'linux') {
         return {
             isAvailable: false,
@@ -288,10 +335,7 @@ async function runVpsInstallerCommand(command: string, unavailableOutput: string
 
     try {
         const { stdout, stderr } = await execFileAsync('bash', [scriptPath, command], {
-            env: {
-                ...process.env,
-                PTBK_NON_INTERACTIVE: '1',
-            },
+            env: createVpsInstallerCommandEnvironment(options),
             maxBuffer: 1024 * 1024,
         });
 
@@ -316,6 +360,31 @@ async function runVpsInstallerCommand(command: string, unavailableOutput: string
     }
 }
 
+/**
+ * Creates the environment passed to the shared VPS installer script.
+ *
+ * @param options - Installer execution options.
+ * @returns Child-process environment.
+ *
+ * @private internal helper of `vpsConfiguration`
+ */
+export function createVpsInstallerCommandEnvironment(
+    options?: RunVpsInstallerCommandOptions,
+): NodeJS.ProcessEnv {
+    const environment: NodeJS.ProcessEnv = {
+        ...process.env,
+        ...(options?.isProcessRestartEnabled === false ? { PTBK_SKIP_PM2_RESTART: '1' } : {}),
+    };
+
+    if (options?.isNonInteractiveModeEnabled === false) {
+        delete environment.PTBK_NON_INTERACTIVE;
+    } else {
+        environment.PTBK_NON_INTERACTIVE = '1';
+    }
+
+    return environment;
+}
+
 /**
  * Returns whether an environment variable must be masked in the UI.
  *
@@ -477,7 +546,12 @@ function parseEnvLines(content: string): Array<ParsedEnvLine> {
             return { type: 'raw', raw };
         }
 
-        const [, key, rawValue = ''] = match;
+        const key = match[1];
+        const rawValue = match[2] ?? '';
+        if (!key) {
+            return { type: 'raw', raw };
+        }
+
         return {
             type: 'entry',
             raw,
@@ -528,7 +602,7 @@ async function readOptionalTextFile(filePath: string): Promise<string> {
  *
  * @returns Script path or `null` when unavailable.
  */
-async function resolveVpsInstallerScriptPath(): Promise<string | null> {
+export async function resolveVpsInstallerScriptPath(): Promise<string | null> {
     const candidates = [
         process.env.PTBK_VPS_INSTALL_SCRIPT?.trim(),
         process.env.PTBK_REPOSITORY_DIR ? join(process.env.PTBK_REPOSITORY_DIR, 'other/vps/install.sh') : '',