@promptbook/cli 0.114.0-2 → 0.114.0-21

package/apps/agents-server/src/utils/cronExpression/resolveNextCronRun.ts

@@ -0,0 +1,100 @@
+import { spaceTrim } from 'spacetrim';
+import { ParseError } from '../../../../../src/errors/ParseError';
+import type { ParsedCronExpression } from './CronExpression';
+import { parseCronExpression } from './parseCronExpression';
+
+/**
+ * Maximum number of minutes scanned while finding the next cron run.
+ *
+ * Five years keeps leap-day schedules valid while still rejecting impossible expressions.
+ *
+ * @private constant of `cronExpression`
+ */
+const CRON_EXPRESSION_LOOKAHEAD_MINUTES = 366 * 24 * 60 * 5;
+
+/**
+ * Finds the next local server time matching one cron expression.
+ *
+ * @param cronExpression - Cron expression, validated on the fly.
+ * @param afterDate - Date after which the next run must happen.
+ * @returns Next matching local server time.
+ *
+ * @private function of `cronExpression`
+ */
+export function resolveNextCronRun(cronExpression: string, afterDate = new Date()): Date {
+    return resolveNextCronRunFromParsedExpression(parseCronExpression(cronExpression), afterDate);
+}
+
+/**
+ * Finds the next local server time matching one already parsed cron expression.
+ *
+ * @param parsedCronExpression - Parsed cron expression.
+ * @param afterDate - Date after which the next run must happen.
+ * @returns Next matching local server time.
+ *
+ * @private function of `cronExpression`
+ */
+export function resolveNextCronRunFromParsedExpression(
+    parsedCronExpression: ParsedCronExpression,
+    afterDate: Date,
+): Date {
+    const cursor = new Date(afterDate.getTime());
+    cursor.setSeconds(0, 0);
+    cursor.setMinutes(cursor.getMinutes() + 1);
+
+    for (let index = 0; index < CRON_EXPRESSION_LOOKAHEAD_MINUTES; index++) {
+        if (isCronExpressionDateMatched(parsedCronExpression, cursor)) {
+            return new Date(cursor.getTime());
+        }
+
+        cursor.setMinutes(cursor.getMinutes() + 1);
+    }
+
+    throw new ParseError(
+        spaceTrim(`
+            Cron expression cannot be scheduled.
+
+            **Use a cron expression that matches at least one valid date.**
+        `),
+    );
+}
+
+/**
+ * Tests whether one date matches a parsed cron expression.
+ *
+ * @param parsedCronExpression - Parsed cron expression.
+ * @param date - Candidate local server date.
+ * @returns `true` when the date matches.
+ *
+ * @private function of `resolveNextCronRun`
+ */
+function isCronExpressionDateMatched(parsedCronExpression: ParsedCronExpression, date: Date): boolean {
+    if (!parsedCronExpression.minute.values.has(date.getMinutes())) {
+        return false;
+    }
+
+    if (!parsedCronExpression.hour.values.has(date.getHours())) {
+        return false;
+    }
+
+    if (!parsedCronExpression.month.values.has(date.getMonth() + 1)) {
+        return false;
+    }
+
+    const isDayOfMonthMatched = parsedCronExpression.dayOfMonth.values.has(date.getDate());
+    const isDayOfWeekMatched = parsedCronExpression.dayOfWeek.values.has(date.getDay());
+
+    if (parsedCronExpression.dayOfMonth.isWildcard && parsedCronExpression.dayOfWeek.isWildcard) {
+        return true;
+    }
+
+    if (parsedCronExpression.dayOfMonth.isWildcard) {
+        return isDayOfWeekMatched;
+    }
+
+    if (parsedCronExpression.dayOfWeek.isWildcard) {
+        return isDayOfMonthMatched;
+    }
+
+    return isDayOfMonthMatched || isDayOfWeekMatched;
+}

package/apps/agents-server/src/utils/cronExpression/throwInvalidCronExpressionField.ts

@@ -0,0 +1,20 @@
+import { spaceTrim } from 'spacetrim';
+import { ParseError } from '../../../../../src/errors/ParseError';
+
+/**
+ * Throws a branded validation error for one invalid cron field value.
+ *
+ * @param value - Invalid field value.
+ * @param fieldName - Field name shown in the error message.
+ *
+ * @private function of `cronExpression`
+ */
+export function throwInvalidCronExpressionField(value: string, fieldName: string): never {
+    throw new ParseError(
+        spaceTrim(`
+            Cron field \`${fieldName}\` contains invalid value \`${value}\`.
+
+            **Use numbers, \`*\`, comma lists, ranges, and step values only.**
+        `),
+    );
+}

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

@@ -0,0 +1,10 @@
+export { CRON_EXPRESSION_FIELD_COUNT } from './cronExpression/CronExpression';
+export { normalizeCronExpression } from './cronExpression/normalizeCronExpression';
+export { normalizeCronExpressionWhitespace } from './cronExpression/normalizeCronExpressionWhitespace';
+export { parseCronExpression } from './cronExpression/parseCronExpression';
+export { resolveNextCronRun, resolveNextCronRunFromParsedExpression } from './cronExpression/resolveNextCronRun';
+export type {
+    CronExpressionField,
+    CronExpressionFieldOptions,
+    ParsedCronExpression,
+} from './cronExpression/CronExpression';

package/apps/agents-server/src/utils/dnsRecords/DnsRecordInstruction.ts

@@ -31,3 +31,23 @@ export type DnsRecordInstruction = {
      */
     readonly note: string | null;
 };
+
+/**
+ * DNS records which belong together and share one all-or-one configuration rule.
+ *
+ * One DNS manual can show more groups at once, for example the server domain records, the generated project domain
+ * records, and the email records of one Agents Server.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export type DnsRecordGroup = {
+    /**
+     * Whether every record of the group or just one of its alternatives must be configured.
+     */
+    readonly recordSelection: DnsRecordSelection;
+
+    /**
+     * DNS records of the group.
+     */
+    readonly records: ReadonlyArray<DnsRecordInstruction>;
+};

package/apps/agents-server/src/utils/dnsRecords/DnsRecordsSection.ts

@@ -0,0 +1,77 @@
+import type { ReactNode } from 'react';
+import type { DnsRecordGroup } from './DnsRecordInstruction';
+
+/**
+ * One alternative setup of a DNS record section.
+ *
+ * A section with a single variant has nothing to choose from, a section with more variants lets the administrator
+ * pick exactly one of them, for example the wildcard or the single-project setup of generated project domains.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export type DnsRecordsSectionVariant = DnsRecordGroup & {
+    /**
+     * Stable identifier of the variant, unique within its section.
+     */
+    readonly id: string;
+
+    /**
+     * Label of the variant button.
+     */
+    readonly label: string;
+
+    /**
+     * Explanation of what the selected variant covers.
+     */
+    readonly description?: ReactNode;
+};
+
+/**
+ * One part of the DNS setup of an Agents Server, for example its domain, its projects, or its email.
+ *
+ * Every page shows the same sections in the same shared component, just filtered down to the sections which are
+ * relevant for that page.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export type DnsRecordsSection = {
+    /**
+     * Stable identifier of the section, unique within one DNS manual.
+     */
+    readonly id: string;
+
+    /**
+     * Human-readable name of the configured part, for example `Email`.
+     */
+    readonly title: string;
+
+    /**
+     * Explanation of what the section configures.
+     */
+    readonly description?: ReactNode;
+
+    /**
+     * Label shown above the variant buttons.
+     */
+    readonly variantsLabel?: string;
+
+    /**
+     * Alternative setups of the section, at least one of them.
+     */
+    readonly variants: ReadonlyArray<DnsRecordsSectionVariant>;
+
+    /**
+     * Current DNS verification state of the section, when it is known.
+     */
+    readonly statusSummary?: string | null;
+
+    /**
+     * Addresses currently returned by public DNS, when verification is available.
+     */
+    readonly resolvedAddresses?: ReadonlyArray<string>;
+
+    /**
+     * Whether the section currently needs attention.
+     */
+    readonly isDnsIssue?: boolean;
+};

package/apps/agents-server/src/utils/dnsRecords/createServerDnsRecordsSections.ts

@@ -0,0 +1,58 @@
+import type { ManagedServerDnsDiagnostic } from '../../app/superadmin/servers/ServersRegistryDnsTypes';
+import { createAgentProjectsDnsRecordsSection } from '../agentProjects/createAgentProjectsDnsRecordsSection';
+import { createEmailDnsRecordsSection } from '../stalwart/createEmailDnsRecordsSection';
+import type { DnsRecordsSection } from './DnsRecordsSection';
+import { createServerDomainDnsRecordsSection } from './createServerDomainDnsRecordsSection';
+
+/**
+ * Creates every DNS section which one Agents Server needs to be fully configured.
+ *
+ * This is the single source of truth of the complete DNS setup of one server, so that `/superadmin/servers` can show
+ * the server domain, the generated project domains, and the email records in one manual and one Cloudflare wizard.
+ *
+ * @param options - Server domain, its DNS diagnostic, and the generated project domain state.
+ * @returns All DNS sections of one server.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export function createServerDnsRecordsSections(options: {
+    /**
+     * Public domain of the Agents Server.
+     */
+    readonly serverDomain: string;
+
+    /**
+     * DNS verification details of the server domain, when the deployment provides them.
+     */
+    readonly dnsDiagnostic: ManagedServerDnsDiagnostic | null | undefined;
+
+    /**
+     * Whether at least one generated project domain currently fails DNS verification.
+     */
+    readonly isProjectDnsIssue?: boolean;
+
+    /**
+     * Example generated project domain, when one is already assigned.
+     */
+    readonly projectDomain?: string | null;
+}): ReadonlyArray<DnsRecordsSection> {
+    const publicIpAddress = options.dnsDiagnostic?.publicIpAddress ?? null;
+    const serverDomainSection = createServerDomainDnsRecordsSection({
+        serverDomain: options.serverDomain,
+        dnsDiagnostic: options.dnsDiagnostic,
+    });
+
+    return [
+        ...(serverDomainSection ? [serverDomainSection] : []),
+        createAgentProjectsDnsRecordsSection({
+            isDnsIssue: options.isProjectDnsIssue,
+            projectDomain: options.projectDomain,
+            publicIpAddress,
+            serverDomain: options.serverDomain,
+        }),
+        createEmailDnsRecordsSection({
+            domain: options.serverDomain,
+            publicIpAddress,
+        }),
+    ];
+}

package/apps/agents-server/src/utils/dnsRecords/createServerDomainDnsRecordsSection.ts

@@ -0,0 +1,48 @@
+import {
+    isManagedServerDnsDiagnosticIssue,
+    type ManagedServerDnsDiagnostic,
+} from '../../app/superadmin/servers/ServersRegistryDnsTypes';
+import type { DnsRecordsSection } from './DnsRecordsSection';
+
+/**
+ * Creates the DNS section which makes the Agents Server itself reachable on its own domain.
+ *
+ * @param options - Server domain and its DNS diagnostic.
+ * @returns Server domain section, or `null` when the deployment does not verify server domains.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export function createServerDomainDnsRecordsSection(options: {
+    /**
+     * Public domain of the Agents Server.
+     */
+    readonly serverDomain: string;
+
+    /**
+     * DNS verification details of the server domain, when the deployment provides them.
+     */
+    readonly dnsDiagnostic: ManagedServerDnsDiagnostic | null | undefined;
+}): DnsRecordsSection | null {
+    const { dnsDiagnostic, serverDomain } = options;
+
+    if (!dnsDiagnostic || dnsDiagnostic.expectedRecords.length === 0) {
+        return null;
+    }
+
+    return {
+        id: 'server-domain',
+        title: `Server domain ${serverDomain}`,
+        description: `Makes the Agents Server reachable on ${serverDomain} and lets it issue its HTTPS certificate.`,
+        variants: [
+            {
+                id: 'server-domain',
+                label: 'Server domain',
+                recordSelection: 'one',
+                records: dnsDiagnostic.expectedRecords,
+            },
+        ],
+        statusSummary: dnsDiagnostic.summary,
+        resolvedAddresses: dnsDiagnostic.resolvedAddresses,
+        isDnsIssue: isManagedServerDnsDiagnosticIssue(dnsDiagnostic),
+    };
+}

package/apps/agents-server/src/utils/dnsRecords/dnsRecordGroups.ts

@@ -0,0 +1,52 @@
+import type { DnsRecordGroup } from './DnsRecordInstruction';
+
+/**
+ * Determines whether every record of every shown group has to be configured.
+ *
+ * @param recordGroups - Groups shown in one DNS manual.
+ * @returns `true` when no group offers alternatives.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export function isEveryDnsRecordGroupRequired(recordGroups: ReadonlyArray<DnsRecordGroup>): boolean {
+    return recordGroups.every((recordGroup) => recordGroup.recordSelection === 'all');
+}
+
+/**
+ * Determines whether every shown group offers alternatives out of which only one may be configured.
+ *
+ * @param recordGroups - Groups shown in one DNS manual.
+ * @returns `true` when no group requires all of its records.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export function isEveryDnsRecordGroupAlternative(recordGroups: ReadonlyArray<DnsRecordGroup>): boolean {
+    return recordGroups.every((recordGroup) => recordGroup.recordSelection === 'one');
+}
+
+/**
+ * Determines whether at least one shown group offers alternatives.
+ *
+ * Such a group can conflict with already configured records on the same hostname, so the manual has to mention
+ * removing them.
+ *
+ * @param recordGroups - Groups shown in one DNS manual.
+ * @returns `true` when at least one group offers alternatives.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export function hasAlternativeDnsRecordGroup(recordGroups: ReadonlyArray<DnsRecordGroup>): boolean {
+    return recordGroups.some((recordGroup) => recordGroup.recordSelection === 'one');
+}
+
+/**
+ * Counts all records shown in the given groups.
+ *
+ * @param recordGroups - Groups shown in one DNS manual.
+ * @returns Number of shown records.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export function countDnsRecordGroupRecords(recordGroups: ReadonlyArray<DnsRecordGroup>): number {
+    return recordGroups.reduce((recordCount, recordGroup) => recordCount + recordGroup.records.length, 0);
+}

package/apps/agents-server/src/utils/dnsRecords/resolveDnsRecordBatchPlan.ts

@@ -1,4 +1,4 @@
-import type { DnsRecordInstruction, DnsRecordSelection } from './DnsRecordInstruction';
+import type { DnsRecordGroup, DnsRecordInstruction, DnsRecordSelection } from './DnsRecordInstruction';
 
 /**
  * Placeholder values like `<VPS_PUBLIC_IP>` have to be filled in by a human before the record can be created.
@@ -79,3 +79,49 @@ export function resolveDnsRecordBatchPlan(options: {
 
     return { applicableRecords, excludedRecords };
 }
+
+/**
+ * Resolves one batch plan for all groups shown in one DNS manual.
+ *
+ * Every group keeps its own all-or-one rule, so a manual which shows the server domain, the generated project
+ * domains, and the email records at once still writes exactly the records which each of these parts needs.
+ *
+ * @param recordGroups - Groups shown in one DNS manual.
+ * @returns One batch plan covering all groups without duplicated records.
+ */
+export function resolveDnsRecordBatchPlanForGroups(recordGroups: ReadonlyArray<DnsRecordGroup>): DnsRecordBatchPlan {
+    const applicableRecords: Array<DnsRecordInstruction> = [];
+    const excludedRecords: Array<ExcludedDnsRecordInstruction> = [];
+    const alreadyPlannedRecordKeys = new Set<string>();
+
+    for (const recordGroup of recordGroups) {
+        const groupBatchPlan = resolveDnsRecordBatchPlan(recordGroup);
+
+        for (const record of groupBatchPlan.applicableRecords) {
+            const recordKey = createDnsRecordKey(record);
+
+            if (alreadyPlannedRecordKeys.has(recordKey)) {
+                continue;
+            }
+
+            alreadyPlannedRecordKeys.add(recordKey);
+            applicableRecords.push(record);
+        }
+
+        excludedRecords.push(...groupBatchPlan.excludedRecords);
+    }
+
+    return { applicableRecords, excludedRecords };
+}
+
+/**
+ * Creates the identity of one DNS record used to keep the batch free of duplicates.
+ *
+ * @param record - DNS record shown in the DNS manual.
+ * @returns Case-insensitive record key.
+ *
+ * @private function of `resolveDnsRecordBatchPlanForGroups`
+ */
+function createDnsRecordKey(record: DnsRecordInstruction): string {
+    return [record.type.toUpperCase(), record.name.toLowerCase(), record.value].join('\t');
+}

package/apps/agents-server/src/utils/email/agentEmailAddress.ts

@@ -82,6 +82,20 @@ export function extractEmailAddress(value: string): string {
     return value.match(/<\s*([^>]+?)\s*>/)?.[1]?.trim() || value.trim();
 }
 
+/**
+ * Extracts and normalizes the domain of an email address.
+ */
+export function getEmailAddressDomain(value: string): string {
+    const emailAddress = extractEmailAddress(value);
+    const separatorIndex = emailAddress.lastIndexOf('@');
+
+    if (separatorIndex === -1) {
+        return '';
+    }
+
+    return normalizeEmailDomain(emailAddress.slice(separatorIndex + 1));
+}
+
 /**
  * Normalizes a mail domain for comparisons and generated addresses.
  */

package/apps/agents-server/src/utils/email/sendEmailThroughStalwart.ts

@@ -4,6 +4,7 @@ import { parseEmailAddress } from '../../message-providers/email/_common/utils/p
 import { createStalwartMessageProviderFromEnvironment } from '../../message-providers/email/stalwart/StalwartMessageProvider';
 import { sendMessage } from '../messages/sendMessage';
 import { synchronizeStalwartEmailDomain } from '../stalwart/synchronizeStalwartEmailDomain';
+import { getEmailAddressDomain } from './agentEmailAddress';
 
 /**
  * Stable provider name stored with outbound Stalwart delivery attempts.
@@ -20,7 +21,7 @@ export async function sendEmailThroughStalwart(message: OutboundEmail): Promise<
     }
 
     const senderAddress = parseEmailAddress(message.sender).fullEmail;
-    const senderDomain = senderAddress.slice(senderAddress.lastIndexOf('@') + 1).toLowerCase();
+    const senderDomain = getEmailAddressDomain(senderAddress);
     await synchronizeStalwartEmailDomain(senderDomain).catch((error) => {
         console.error('[stalwart-email]', 'pre_delivery_domain_synchronization_failed', {
             senderDomain,

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

@@ -0,0 +1,130 @@
+import type { string_book } from '../../../../src/_packages/types.index'; // <- [🚾]
+
+/**
+ * Commitment keyword that declares the parent agent of one book.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+const FROM_COMMITMENT_TYPE = 'FROM';
+
+/**
+ * Matches one standalone `FROM` commitment line and captures its inline content.
+ *
+ * The Book parser accepts horizontal whitespace between a commitment keyword and its value, so inheritance resolution
+ * must do the same. Keeping this pattern here makes every server-side consumer agree on which `FROM` lines are real.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+const FROM_COMMITMENT_LINE_PATTERN = new RegExp(`^${FROM_COMMITMENT_TYPE}(?:\\s+(.*))?$`);
+
+/**
+ * One explicit `FROM` commitment written in a book.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export type ExplicitFromCommitment = {
+    /**
+     * Zero-based index of the line the commitment was found on, within the scanned lines.
+     */
+    readonly lineIndex: number;
+
+    /**
+     * Trimmed commitment content, empty string for a blank `FROM`.
+     */
+    readonly content: string;
+};
+
+/**
+ * Collects every explicit single-line `FROM` commitment of one book.
+ *
+ * This lightweight parser is intentionally limited to the subset needed by inheritance
+ * resolution so it stays safe to bundle into the Next.js proxy path.
+ *
+ * @param sourceLines - Book source already split into lines.
+ * @returns Found `FROM` commitments in source order, empty when the book declares no parent.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export function collectExplicitFromCommitments(
+    sourceLines: ReadonlyArray<string>,
+): ReadonlyArray<ExplicitFromCommitment> {
+    const explicitFromCommitments: Array<ExplicitFromCommitment> = [];
+    let hasSeenTitle = false;
+    let isInsideCodeBlock = false;
+
+    for (let lineIndex = 0; lineIndex < sourceLines.length; lineIndex++) {
+        const trimmedLine = (sourceLines[lineIndex] || '').trim();
+
+        if (!hasSeenTitle) {
+            if (!trimmedLine) {
+                continue;
+            }
+
+            hasSeenTitle = true;
+            continue;
+        }
+
+        if (trimmedLine.startsWith('```')) {
+            isInsideCodeBlock = !isInsideCodeBlock;
+            continue;
+        }
+
+        if (isInsideCodeBlock) {
+            continue;
+        }
+
+        const fromCommitmentMatch = FROM_COMMITMENT_LINE_PATTERN.exec(trimmedLine);
+        if (fromCommitmentMatch) {
+            explicitFromCommitments.push({
+                lineIndex,
+                content: (fromCommitmentMatch[1] || '').trim(),
+            });
+        }
+    }
+
+    return explicitFromCommitments;
+}
+
+/**
+ * Returns the effective explicit `FROM` commitment of one book.
+ *
+ * A book may repeat `FROM`, in which case the last one wins and overrides every earlier one.
+ *
+ * @param agentSource - Raw book source.
+ * @returns The last explicit `FROM` commitment, or `undefined` when the book declares no parent.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export function getEffectiveExplicitFromCommitment(agentSource: string_book): ExplicitFromCommitment | undefined {
+    const explicitFromCommitments = collectExplicitFromCommitments(agentSource.split(/\r?\n/));
+    return explicitFromCommitments[explicitFromCommitments.length - 1];
+}
+
+/**
+ * Returns the effective explicit `FROM` commitment content of one book.
+ *
+ * A book may repeat `FROM`, in which case the last one wins and overrides every earlier one.
+ *
+ * @param agentSource - Raw book source.
+ * @returns Trimmed commitment content, empty string for a blank explicit `FROM`, or `undefined` when `FROM` is absent.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export function getExplicitFromCommitmentContent(agentSource: string_book): string | undefined {
+    return getEffectiveExplicitFromCommitment(agentSource)?.content;
+}
+
+/**
+ * Returns true when one book declares no parent at all and therefore implicitly inherits from `@Adam`.
+ *
+ * Writing no `FROM` commitment is equivalent to writing `FROM @Adam`, so only an explicit
+ * `FROM @Null` / `FROM {Void}` turns the inheritance off.
+ *
+ * @param agentSource - Raw book source.
+ * @returns True when the implicit `@Adam` ancestor applies to this book.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export function isImplicitAdamInheritance(agentSource: string_book): boolean {
+    return getExplicitFromCommitmentContent(agentSource) === undefined;
+}