@maildock/mailctl 0.1.0-rc.2

package/dist/index.js

@@ -0,0 +1,1452 @@
+// src/commands/install.ts
+import { Command, Flags } from "@oclif/core";
+import fs2 from "node:fs/promises";
+import path3 from "node:path";
+import { parse as parseYaml } from "yaml";
+
+// ../../packages/core/src/primitives.ts
+import { z } from "zod";
+var LABEL = /^(?!-)[a-z0-9-]{1,63}(?<!-)$/;
+function normalizeDomain(input) {
+  return input.trim().toLowerCase().replace(/\.$/, "");
+}
+var DomainName = z.string().overwrite(normalizeDomain).refine(
+  (v) => v.length <= 253 && v.split(".").length >= 2 && v.split(".").every((l) => LABEL.test(l)),
+  "must be a fully-qualified domain name"
+);
+var Hostname = DomainName;
+var LocalPart = z.string().trim().toLowerCase().refine(
+  (v) => /^[a-z0-9](?:[a-z0-9._+-]{0,62}[a-z0-9])?$/.test(v) && !v.includes(".."),
+  "invalid local part"
+);
+var EmailAddress = z.string().trim().toLowerCase().refine((v) => {
+  const at = v.lastIndexOf("@");
+  if (at <= 0) return false;
+  return LocalPart.safeParse(v.slice(0, at)).success && DomainName.safeParse(v.slice(at + 1)).success;
+}, "invalid email address");
+var Uuid = z.uuid();
+var Password = z.string().min(10, "at least 10 characters").max(256);
+var QuotaBytes = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+var PageQuery = z.object({
+  limit: z.coerce.number().int().min(1).max(500).default(100),
+  offset: z.coerce.number().int().min(0).default(0)
+});
+var ApiError = z.object({
+  statusCode: z.number(),
+  error: z.string(),
+  message: z.string(),
+  code: z.string().optional()
+});
+
+// ../../packages/core/src/entities.ts
+import { z as z2 } from "zod";
+var timestamps = { createdAt: z2.iso.datetime(), updatedAt: z2.iso.datetime() };
+var Domain = z2.object({
+  id: Uuid,
+  name: DomainName,
+  active: z2.boolean(),
+  defaultQuotaBytes: QuotaBytes,
+  ...timestamps
+});
+var DomainCreate = z2.object({ name: DomainName, defaultQuotaBytes: QuotaBytes.default(0) });
+var DomainUpdate = z2.object({
+  active: z2.boolean().optional(),
+  defaultQuotaBytes: QuotaBytes.optional()
+});
+var Mailbox = z2.object({
+  id: Uuid,
+  domainId: Uuid,
+  localPart: LocalPart,
+  address: EmailAddress,
+  displayName: z2.string().nullable(),
+  quotaBytes: QuotaBytes,
+  active: z2.boolean(),
+  suspended: z2.boolean(),
+  ...timestamps
+});
+var MailboxUsage = z2.object({
+  mailboxId: Uuid,
+  address: EmailAddress,
+  quotaBytes: QuotaBytes,
+  usedBytes: z2.number().int().nonnegative(),
+  messages: z2.number().int().nonnegative(),
+  /** 0–100+ (may exceed 100 when the quota was lowered); null when the quota is unlimited. */
+  percent: z2.number().nullable(),
+  updatedAt: z2.iso.datetime().nullable()
+});
+var MailboxCreate = z2.object({
+  localPart: LocalPart,
+  password: Password,
+  displayName: z2.string().max(200).optional(),
+  /** Omit to inherit the domain default. */
+  quotaBytes: QuotaBytes.optional()
+});
+var MailboxUpdate = z2.object({
+  displayName: z2.string().max(200).nullable().optional(),
+  quotaBytes: QuotaBytes.optional(),
+  suspended: z2.boolean().optional(),
+  active: z2.boolean().optional()
+});
+var MailboxPasswordReset = z2.object({ password: Password });
+var Alias = z2.object({
+  id: Uuid,
+  domainId: Uuid,
+  address: EmailAddress,
+  destinations: z2.array(EmailAddress).min(1),
+  active: z2.boolean(),
+  ...timestamps
+});
+var AliasCreate = z2.object({
+  localPart: LocalPart,
+  destinations: z2.array(EmailAddress).min(1).max(50)
+});
+var AliasUpdate = z2.object({
+  destinations: z2.array(EmailAddress).min(1).max(50).optional(),
+  active: z2.boolean().optional()
+});
+var Forwarder = z2.object({
+  id: Uuid,
+  mailboxId: Uuid,
+  destination: EmailAddress,
+  keepCopy: z2.boolean(),
+  active: z2.boolean(),
+  ...timestamps
+});
+var ForwarderCreate = z2.object({ destination: EmailAddress, keepCopy: z2.boolean().default(true) });
+var ForwarderUpdate = z2.object({ keepCopy: z2.boolean().optional(), active: z2.boolean().optional() });
+var Catchall = z2.object({
+  id: Uuid,
+  domainId: Uuid,
+  destination: EmailAddress,
+  active: z2.boolean(),
+  ...timestamps
+});
+var CatchallSet = z2.object({ destination: EmailAddress, active: z2.boolean().default(true) });
+var AuditEntry = z2.object({
+  id: z2.number().int(),
+  actorUserId: Uuid.nullable(),
+  actor: z2.string().nullable(),
+  action: z2.string(),
+  entity: z2.string(),
+  entityId: z2.string().nullable(),
+  before: z2.unknown().nullable(),
+  after: z2.unknown().nullable(),
+  ip: z2.string().nullable(),
+  at: z2.iso.datetime()
+});
+
+// ../../packages/core/src/auth.ts
+import { z as z3 } from "zod";
+var UserRole = z3.enum(["owner", "admin", "domain_admin", "mailbox_user"]);
+var User = z3.object({
+  id: Uuid,
+  email: EmailAddress,
+  role: UserRole,
+  totpEnabled: z3.boolean(),
+  active: z3.boolean(),
+  createdAt: z3.iso.datetime()
+});
+var LoginRequest = z3.object({
+  email: EmailAddress,
+  password: z3.string().min(1),
+  /** Required once the user has enabled TOTP. */
+  totp: z3.string().regex(/^\d{6}$/).optional()
+});
+var LoginResponse = z3.object({
+  accessToken: z3.string(),
+  expiresIn: z3.number().int(),
+  user: User
+});
+var TotpSetupResponse = z3.object({ secret: z3.string(), otpauthUrl: z3.string() });
+var TotpEnableRequest = z3.object({ code: z3.string().regex(/^\d{6}$/) });
+var ApiToken = z3.object({
+  id: Uuid,
+  name: z3.string(),
+  role: UserRole,
+  lastUsedAt: z3.iso.datetime().nullable(),
+  expiresAt: z3.iso.datetime().nullable(),
+  createdAt: z3.iso.datetime()
+});
+var ApiTokenCreate = z3.object({
+  name: z3.string().min(1).max(100),
+  role: UserRole.default("admin"),
+  expiresAt: z3.iso.datetime().optional()
+});
+var ApiTokenCreated = ApiToken.extend({ token: z3.string() });
+var UserCreate = z3.object({ email: EmailAddress, password: Password, role: UserRole });
+var Principal = z3.object({
+  /** `mailbox` = a mailbox owner signed in to webmail (role `mailbox_user`); `id` is then the mailbox id. */
+  kind: z3.enum(["user", "token", "mailbox"]),
+  id: Uuid,
+  tenantId: Uuid,
+  role: UserRole,
+  label: z3.string()
+});
+
+// ../../packages/core/src/server-config.ts
+import { z as z4 } from "zod";
+var TlsMode = z4.enum(["acme", "byo", "none"]);
+var ServerConfig = z4.object({
+  hostname: Hostname,
+  tls: z4.object({
+    mode: TlsMode,
+    /** ACME contact / expiry notices. Required for `acme`. */
+    acmeEmail: EmailAddress.optional()
+  }),
+  limits: z4.object({
+    messageSizeBytes: z4.number().int().min(1048576).max(1073741824).default(52428800),
+    /** Outbound messages per hour per authenticated sender (Rspamd ratelimit, soft-reject above); 0 = unlimited. */
+    perUserMessagesPerHour: z4.number().int().min(0).default(500),
+    /** Outbound messages per hour per sender domain; 0 = unlimited. */
+    perDomainMessagesPerHour: z4.number().int().min(0).default(2e3),
+    smtpdClientConnectionRateLimit: z4.number().int().min(0).default(60)
+  }),
+  relay: z4.object({
+    host: Hostname,
+    port: z4.number().int().min(1).max(65535).default(587),
+    username: z4.string().min(1),
+    password: z4.string().min(1)
+  }).nullable().default(null),
+  spam: z4.object({
+    rejectScore: z4.number().default(15),
+    addHeaderScore: z4.number().default(6),
+    greylistScore: z4.number().default(4)
+  }),
+  /**
+   * MTA-STS policy served at https://mta-sts.<domain>/.well-known/mta-sts.txt for every domain (needs
+   * `tls.mode = acme`: Caddy issues the mta-sts.<domain> certificates on demand). `none` publishes no policy.
+   */
+  mtaSts: z4.object({
+    mode: z4.enum(["none", "testing", "enforce"]).default("testing"),
+    maxAgeSeconds: z4.number().int().min(86400).max(31557600).default(604800)
+  }).default({ mode: "testing", maxAgeSeconds: 604800 }),
+  /**
+   * IP warm-up: a server-wide outbound cap that grows from 50/h on day 1 by 25 %/day until it reaches
+   * `targetPerHour` (≈ 3 weeks for 2000/h). Rendered as an rspamd ratelimit bucket and re-applied hourly
+   * by the API while the cap is still below the target.
+   */
+  warmup: z4.object({
+    enabled: z4.boolean().default(false),
+    /** Day 1 of the schedule (ISO date); set when enabling. */
+    startedAt: z4.iso.datetime().optional(),
+    targetPerHour: z4.number().int().min(10).default(2e3)
+  }).default({ enabled: false, targetPerHour: 2e3 }),
+  /** Trusted networks that may relay without auth (docker network is always included by the adapter). */
+  trustedNetworks: z4.array(z4.string().regex(/^[0-9a-f.:]+\/\d{1,3}$/i)).default([])
+});
+var ServerConfigInput = ServerConfig.partial({
+  limits: true,
+  spam: true,
+  relay: true,
+  trustedNetworks: true,
+  mtaSts: true,
+  warmup: true
+});
+var ServerConfigVersion = z4.object({
+  version: z4.number().int(),
+  config: ServerConfig,
+  status: z4.enum(["pending", "applied", "failed", "rolled_back"]),
+  message: z4.string().nullable(),
+  createdBy: z4.string().nullable(),
+  createdAt: z4.iso.datetime()
+});
+
+// ../../packages/core/src/setup.ts
+import { z as z5 } from "zod";
+var SetupState = z5.enum(["pending", "complete"]);
+var SetupStatus = z5.object({
+  state: SetupState,
+  version: z5.string(),
+  steps: z5.object({
+    hostname: z5.boolean(),
+    tls: z5.boolean(),
+    domain: z5.boolean(),
+    owner: z5.boolean()
+  }),
+  hostname: Hostname.nullable(),
+  tlsMode: TlsMode.nullable(),
+  domain: DomainName.nullable(),
+  ownerEmail: EmailAddress.nullable()
+});
+var SetupHostname = z5.object({ hostname: Hostname });
+var SetupTls = z5.discriminatedUnion("mode", [
+  z5.object({ mode: z5.literal("acme"), acmeEmail: EmailAddress }),
+  z5.object({ mode: z5.literal("byo"), certificatePem: z5.string().min(1), privateKeyPem: z5.string().min(1) }),
+  z5.object({ mode: z5.literal("none") })
+]);
+var SetupDomain = z5.object({ name: DomainName, defaultQuotaBytes: QuotaBytes.default(0) });
+var SetupOwner = z5.object({
+  email: EmailAddress,
+  password: Password,
+  /** Also create a mailbox for the owner address when it belongs to the first domain. */
+  createMailbox: z5.boolean().default(true)
+});
+var SetupAnswers = z5.object({
+  version: z5.literal(1),
+  hostname: Hostname,
+  tls: SetupTls,
+  domain: SetupDomain,
+  owner: SetupOwner
+});
+
+// ../../packages/core/src/dns.ts
+import { z as z6 } from "zod";
+var DnsRecord = z6.object({
+  type: z6.enum(["A", "AAAA", "MX", "TXT", "CNAME", "SRV", "PTR"]),
+  name: z6.string(),
+  value: z6.string(),
+  priority: z6.number().int().optional(),
+  ttl: z6.number().int().default(3600),
+  purpose: z6.string(),
+  /** Stable key for matching records across list / verification results. */
+  key: z6.string(),
+  /** Records the domain needs before it is considered ready to send and receive (MX, SPF, DKIM). */
+  required: z6.boolean().default(true)
+});
+var DkimKey = z6.object({
+  id: z6.string(),
+  domainId: z6.string(),
+  selector: z6.string(),
+  algorithm: z6.literal("rsa"),
+  bits: z6.number().int(),
+  status: z6.enum(["active", "retired"]),
+  /** Base64 SPKI public key (the `p=` value). */
+  publicKey: z6.string(),
+  dnsName: z6.string(),
+  dnsValue: z6.string(),
+  createdAt: z6.string(),
+  retiredAt: z6.string().nullable()
+});
+var DnsRecordStatus = z6.enum(["ok", "propagating", "mismatch", "missing", "error"]);
+var DnsResolverResult = z6.object({
+  resolver: z6.string(),
+  status: DnsRecordStatus,
+  observed: z6.array(z6.string())
+});
+var DnsRecordCheck = z6.object({
+  record: DnsRecord,
+  /** `ok` when every resolver agrees, `propagating` when at least one does. */
+  status: DnsRecordStatus,
+  /** Union of what the resolvers returned for this name/type (for showing the admin what is actually published). */
+  observed: z6.array(z6.string()),
+  resolvers: z6.array(DnsResolverResult)
+});
+var DnsVerification = z6.object({
+  domainId: z6.string(),
+  checkedAt: z6.string(),
+  /** Every `required` record is `ok` or `propagating`. */
+  ready: z6.boolean(),
+  records: z6.array(DnsRecordCheck)
+});
+
+// ../../packages/core/src/sieve.ts
+import { z as z7 } from "zod";
+var HeaderName = z7.string().trim().regex(/^[!-9;-~]{1,64}$/, "invalid header name");
+var FolderName = z7.string().trim().min(1).max(255);
+var FilterCondition = z7.discriminatedUnion("type", [
+  z7.object({
+    type: z7.literal("header"),
+    /** e.g. Subject, From, To, X-Spam-Flag. */
+    header: HeaderName,
+    operator: z7.enum([
+      "contains",
+      "not_contains",
+      "is",
+      "not_is",
+      "matches",
+      "not_matches",
+      "exists",
+      "not_exists"
+    ]),
+    value: z7.string().max(998).default("")
+  }),
+  z7.object({
+    type: z7.literal("address"),
+    header: z7.enum(["From", "To", "Cc", "Sender", "Reply-To"]),
+    part: z7.enum(["all", "localpart", "domain"]).default("all"),
+    operator: z7.enum(["contains", "not_contains", "is", "not_is", "matches", "not_matches"]),
+    value: z7.string().max(998)
+  }),
+  z7.object({
+    type: z7.literal("body"),
+    operator: z7.enum(["contains", "not_contains"]),
+    value: z7.string().min(1).max(998)
+  }),
+  z7.object({
+    type: z7.literal("size"),
+    operator: z7.enum(["over", "under"]),
+    /** Bytes. */
+    value: z7.number().int().positive().max(Number.MAX_SAFE_INTEGER)
+  })
+]);
+var FilterAction = z7.discriminatedUnion("type", [
+  z7.object({ type: z7.literal("fileinto"), folder: FolderName }),
+  z7.object({ type: z7.literal("copy"), folder: FolderName }),
+  z7.object({ type: z7.literal("redirect"), address: EmailAddress }),
+  z7.object({ type: z7.literal("redirect_copy"), address: EmailAddress }),
+  z7.object({ type: z7.literal("flag"), flag: z7.enum(["\\Seen", "\\Flagged", "\\Answered", "\\Deleted"]) }),
+  z7.object({ type: z7.literal("discard") }),
+  z7.object({ type: z7.literal("keep") })
+]);
+var FilterRule = z7.object({
+  name: z7.string().trim().min(1).max(100),
+  enabled: z7.boolean().default(true),
+  /** `all` = every condition must hold (allof); `any` = at least one (anyof). */
+  match: z7.enum(["all", "any"]).default("all"),
+  conditions: z7.array(FilterCondition).min(1).max(20),
+  actions: z7.array(FilterAction).min(1).max(10),
+  /** Stop processing later rules when this one matched. */
+  stop: z7.boolean().default(true)
+});
+var Autoresponder = z7.object({
+  enabled: z7.boolean().default(false),
+  subject: z7.string().trim().max(200).default(""),
+  body: z7.string().max(1e4).default(""),
+  /** Days before the same sender gets another reply (Sieve `:days`, 1–30). */
+  intervalDays: z7.number().int().min(1).max(30).default(1),
+  /** ISO dates; outside the window the responder is silent. Null = open-ended. */
+  startsAt: z7.iso.datetime().nullable().default(null),
+  endsAt: z7.iso.datetime().nullable().default(null)
+});
+var MailboxFiltersSet = z7.object({
+  mode: z7.enum(["rules", "raw"]).default("rules"),
+  rules: z7.array(FilterRule).max(100).default([]),
+  raw: z7.string().max(64e3).default("")
+});
+var MailboxFilters = z7.object({
+  mailboxId: z7.uuid(),
+  mode: z7.enum(["rules", "raw"]),
+  rules: z7.array(FilterRule),
+  raw: z7.string(),
+  autoresponder: Autoresponder,
+  /** The Sieve script currently active in Dovecot (compiled from rules, or `raw`). */
+  script: z7.string(),
+  /** When the script was last accepted by Dovecot; null if never pushed. */
+  pushedAt: z7.iso.datetime().nullable(),
+  updatedAt: z7.iso.datetime().nullable()
+});
+var SieveCheck = z7.object({ script: z7.string().max(64e3) });
+var SieveCheckResult = z7.object({ ok: z7.boolean(), message: z7.string() });
+
+// ../../packages/core/src/deliverability.ts
+import { z as z8 } from "zod";
+var AlertSeverity = z8.enum(["warning", "critical"]);
+var Alert = z8.object({
+  id: z8.string(),
+  /** Stable identity of the condition (`dns:<domainId>:<recordKey>`, `dnsbl:<zone>`, `rdns`, `tls_expiry`). */
+  key: z8.string(),
+  kind: z8.enum(["dns_drift", "dnsbl", "rdns", "tls_expiry"]),
+  severity: AlertSeverity,
+  title: z8.string(),
+  detail: z8.record(z8.string(), z8.unknown()),
+  firstSeen: z8.string(),
+  lastSeen: z8.string(),
+  resolvedAt: z8.string().nullable()
+});
+var DnsblResult = z8.object({
+  zone: z8.string(),
+  status: z8.enum(["clean", "listed", "error"]),
+  detail: z8.string().nullable(),
+  delistUrl: z8.string()
+});
+var RdnsResult = z8.object({
+  ip: z8.string(),
+  hostname: z8.string(),
+  ptr: z8.array(z8.string()),
+  ptrMatches: z8.boolean(),
+  forwardConfirmed: z8.boolean(),
+  heloResolves: z8.boolean(),
+  ok: z8.boolean(),
+  error: z8.string().nullable()
+});
+var TlsExpiryResult = z8.object({
+  subject: z8.string(),
+  issuer: z8.string(),
+  notAfter: z8.string(),
+  daysLeft: z8.number().int()
+});
+var ReputationReport = z8.object({
+  checkedAt: z8.string(),
+  ip: z8.string().nullable(),
+  dnsbl: z8.array(DnsblResult),
+  rdns: RdnsResult.nullable(),
+  tls: TlsExpiryResult.nullable()
+});
+
+// ../../packages/core/src/dmarc.ts
+import { z as z9 } from "zod";
+var DmarcRecord = z9.object({
+  sourceIp: z9.string(),
+  count: z9.number().int(),
+  disposition: z9.enum(["none", "quarantine", "reject"]),
+  dkim: z9.enum(["pass", "fail"]),
+  spf: z9.enum(["pass", "fail"]),
+  headerFrom: z9.string(),
+  /** Per-mechanism auth results: `dkim:selector:result`, `spf:domain:result`. */
+  authResults: z9.array(z9.string())
+});
+var DmarcReport = z9.object({
+  id: z9.string(),
+  domainId: z9.string(),
+  reportId: z9.string(),
+  orgName: z9.string(),
+  orgEmail: z9.string().nullable(),
+  /** Reporting window (ISO). */
+  begin: z9.string(),
+  end: z9.string(),
+  policy: z9.object({
+    domain: z9.string(),
+    p: z9.string().nullable(),
+    sp: z9.string().nullable(),
+    adkim: z9.string().nullable(),
+    aspf: z9.string().nullable(),
+    pct: z9.number().int().nullable()
+  }),
+  records: z9.array(DmarcRecord),
+  receivedAt: z9.string()
+});
+var DmarcSummary = z9.object({
+  domainId: z9.string(),
+  days: z9.number().int(),
+  reports: z9.number().int(),
+  messages: z9.number().int(),
+  /** Messages where DKIM or SPF passed with alignment (DMARC pass). */
+  aligned: z9.number().int(),
+  dkimPass: z9.number().int(),
+  spfPass: z9.number().int(),
+  byDisposition: z9.object({ none: z9.number().int(), quarantine: z9.number().int(), reject: z9.number().int() }),
+  sources: z9.array(
+    z9.object({
+      sourceIp: z9.string(),
+      messages: z9.number().int(),
+      aligned: z9.number().int(),
+      dkimPass: z9.number().int(),
+      spfPass: z9.number().int(),
+      reporters: z9.array(z9.string())
+    })
+  ),
+  latest: z9.array(DmarcReport)
+});
+
+// ../../packages/core/src/delivery-log.ts
+import { z as z10 } from "zod";
+var DeliveryStatus = z10.enum(["sent", "bounced", "deferred", "expired"]);
+var DeliveryClass = z10.enum(["delivered", "hard", "soft", "policy", "reputation"]);
+var DeliveryDirection = z10.enum(["inbound", "outbound", "internal"]);
+var DeliveryEvent = z10.object({
+  id: z10.string(),
+  queueId: z10.string(),
+  at: z10.string(),
+  /** Envelope sender as logged by qmgr (SRS-rewritten for forwards); null until the from= line was seen. */
+  sender: z10.string().nullable(),
+  messageId: z10.string().nullable(),
+  recipient: z10.string(),
+  origTo: z10.string().nullable(),
+  relay: z10.string(),
+  status: DeliveryStatus,
+  class: DeliveryClass,
+  dsn: z10.string().nullable(),
+  /** The remote server's reply or Postfix's reason, verbatim. */
+  detail: z10.string(),
+  direction: DeliveryDirection
+});
+var DeliveryLogQuery = z10.object({
+  /** Matches sender, recipient, original recipient, message-id or queue id (substring, case-insensitive). */
+  q: z10.string().trim().max(200).optional(),
+  status: DeliveryStatus.optional(),
+  class: DeliveryClass.optional(),
+  direction: DeliveryDirection.optional(),
+  /** Restrict to a domain (sender or recipient side). */
+  domain: z10.string().trim().toLowerCase().max(253).optional(),
+  days: z10.coerce.number().int().min(1).max(90).default(7),
+  limit: z10.coerce.number().int().min(1).max(500).default(100),
+  offset: z10.coerce.number().int().min(0).default(0)
+});
+var DeliveryLogPage = z10.object({
+  items: z10.array(DeliveryEvent),
+  total: z10.number().int(),
+  /** Counts by class over the same filter (for the stat tiles). */
+  byClass: z10.object({
+    delivered: z10.number().int(),
+    hard: z10.number().int(),
+    soft: z10.number().int(),
+    policy: z10.number().int(),
+    reputation: z10.number().int()
+  })
+});
+
+// ../../packages/core/src/webmail.ts
+import { z as z11 } from "zod";
+var FolderRole = z11.enum(["inbox", "sent", "drafts", "trash", "junk", "archive", "other"]);
+var Folder = z11.object({
+  /** IMAP path (also the id used in every other endpoint), e.g. `INBOX`, `Sent`, `Projects/2026`. */
+  path: z11.string(),
+  name: z11.string(),
+  role: FolderRole,
+  delimiter: z11.string().nullable(),
+  subscribed: z11.boolean(),
+  messages: z11.number().int(),
+  unseen: z11.number().int()
+});
+var Address = z11.object({ name: z11.string().nullable(), address: z11.string() });
+var MessageSummary = z11.object({
+  uid: z11.number().int(),
+  folder: z11.string(),
+  messageId: z11.string().nullable(),
+  /** `References`/`In-Reply-To` heads used for conversation grouping on the client. */
+  inReplyTo: z11.string().nullable(),
+  subject: z11.string(),
+  from: z11.array(Address),
+  to: z11.array(Address),
+  date: z11.string().nullable(),
+  size: z11.number().int(),
+  flags: z11.array(z11.string()),
+  seen: z11.boolean(),
+  flagged: z11.boolean(),
+  answered: z11.boolean(),
+  hasAttachments: z11.boolean()
+});
+var MessageListQuery = z11.object({
+  folder: z11.string().default("INBOX"),
+  /** Newest first; `before` = uid to continue from (exclusive) for infinite scroll. */
+  before: z11.coerce.number().int().positive().optional(),
+  limit: z11.coerce.number().int().min(1).max(200).default(50),
+  /** Free-text search (from/to/subject/body via IMAP SEARCH, Dovecot FTS when enabled). */
+  q: z11.string().trim().max(200).optional(),
+  unseen: z11.enum(["true", "false"]).optional().transform((v) => v === "true"),
+  flagged: z11.enum(["true", "false"]).optional().transform((v) => v === "true"),
+  attachments: z11.enum(["true", "false"]).optional().transform((v) => v === "true"),
+  since: z11.iso.date().optional(),
+  until: z11.iso.date().optional()
+});
+var MessageList = z11.object({
+  folder: z11.string(),
+  items: z11.array(MessageSummary),
+  /** Total messages matching (folder size when unfiltered). */
+  total: z11.number().int(),
+  /** Pass as `before` to fetch the next (older) page; null when exhausted. */
+  next: z11.number().int().nullable()
+});
+var Attachment = z11.object({
+  /** IMAP body part id (`2`, `1.2`) — download via `/mail/messages/{uid}/parts/{part}`. */
+  part: z11.string(),
+  filename: z11.string(),
+  contentType: z11.string(),
+  size: z11.number().int(),
+  /** `cid:` reference for inline images, without the angle brackets. */
+  contentId: z11.string().nullable(),
+  inline: z11.boolean()
+});
+var Message = MessageSummary.extend({
+  cc: z11.array(Address),
+  bcc: z11.array(Address),
+  replyTo: z11.array(Address),
+  references: z11.array(z11.string()),
+  /** Plain-text body (derived from HTML when the message has none). */
+  text: z11.string(),
+  /** Raw HTML body; the client sanitises before rendering (DOMPurify + sandboxed iframe). */
+  html: z11.string().nullable(),
+  attachments: z11.array(Attachment),
+  headers: z11.record(z11.string(), z11.string())
+});
+var FlagsUpdate = z11.object({
+  folder: z11.string(),
+  uids: z11.array(z11.number().int().positive()).min(1).max(1e3),
+  add: z11.array(z11.string()).default([]),
+  remove: z11.array(z11.string()).default([])
+});
+var MoveRequest = z11.object({
+  folder: z11.string(),
+  uids: z11.array(z11.number().int().positive()).min(1).max(1e3),
+  to: z11.string()
+});
+var DeleteRequest = z11.object({
+  folder: z11.string(),
+  uids: z11.array(z11.number().int().positive()).min(1).max(1e3),
+  /** Skip the Trash and expunge immediately (what "delete" does inside Trash/Junk). */
+  permanent: z11.boolean().default(false)
+});
+var FolderCreate = z11.object({ path: z11.string().min(1).max(255) });
+var FolderRename = z11.object({ path: z11.string().min(1), to: z11.string().min(1).max(255) });
+var SendRequest = z11.object({
+  to: z11.array(z11.string().min(3)).min(1),
+  cc: z11.array(z11.string()).default([]),
+  bcc: z11.array(z11.string()).default([]),
+  subject: z11.string().max(998).default(""),
+  text: z11.string().default(""),
+  html: z11.string().optional(),
+  /** Message-ID being replied to / forwarded (sets In-Reply-To/References and the \Answered flag). */
+  inReplyTo: z11.string().optional(),
+  replyFolder: z11.string().optional(),
+  replyUid: z11.number().int().positive().optional(),
+  /** Draft to delete after a successful send. */
+  draftUid: z11.number().int().positive().optional(),
+  /** Attachments already uploaded with POST /mail/uploads (ids), plus optional forwarded parts. */
+  uploads: z11.array(z11.string()).default([]),
+  forwardParts: z11.array(z11.object({ folder: z11.string(), uid: z11.number().int().positive(), part: z11.string() })).default([])
+});
+var DraftSave = SendRequest.omit({ draftUid: true, replyFolder: true, replyUid: true }).extend({
+  /** Existing draft uid to replace. */
+  uid: z11.number().int().positive().optional()
+});
+var DraftSaved = z11.object({ uid: z11.number().int(), folder: z11.string() });
+var Upload = z11.object({
+  id: z11.string(),
+  filename: z11.string(),
+  size: z11.number().int(),
+  contentType: z11.string()
+});
+var MailEvent = z11.object({
+  type: z11.enum(["exists", "expunge", "flags", "connected", "error"]),
+  folder: z11.string().nullable(),
+  uid: z11.number().int().nullable(),
+  count: z11.number().int().nullable()
+});
+var MailboxSettings = z11.object({
+  signature: z11.string().max(4e3).default(""),
+  signatureHtml: z11.boolean().default(false),
+  /** Reply-quoting and display preferences. */
+  replyQuote: z11.boolean().default(true),
+  messagesPerPage: z11.number().int().min(10).max(200).default(50),
+  theme: z11.enum(["system", "light", "dark"]).default("system"),
+  /** Delay before a queued send actually goes out (undo window), seconds. */
+  undoSendSeconds: z11.number().int().min(0).max(30).default(5)
+});
+var MailboxSettingsUpdate = MailboxSettings.partial();
+var MailAccount = z11.object({
+  mailboxId: z11.string(),
+  address: z11.string(),
+  displayName: z11.string().nullable(),
+  quotaBytes: z11.number().int(),
+  usedBytes: z11.number().int(),
+  settings: MailboxSettings
+});
+var PasswordChange = z11.object({ current: z11.string().min(1), password: z11.string().min(10).max(200) });
+
+// src/lib/api.ts
+var ApiClient = class {
+  constructor(baseUrl) {
+    this.baseUrl = baseUrl;
+  }
+  async health() {
+    try {
+      const res = await fetch(`${this.baseUrl}/api/v1/health`, { signal: AbortSignal.timeout(3e3) });
+      return res.ok ? await res.json() : null;
+    } catch {
+      return null;
+    }
+  }
+  async waitHealthy(timeoutMs, onTick) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      const h = await this.health();
+      if (h?.ok) return h;
+      onTick?.(Date.now() - start);
+      await new Promise((r) => setTimeout(r, 2e3));
+    }
+    throw new Error(`API at ${this.baseUrl} did not become healthy within ${timeoutMs / 1e3}s`);
+  }
+  async applyAnswers(answers) {
+    const res = await fetch(`${this.baseUrl}/api/v1/setup/answers`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(answers),
+      signal: AbortSignal.timeout(12e4)
+    });
+    const body = await res.json();
+    if (!res.ok) throw new Error(`setup failed (${res.status}): ${body.message ?? JSON.stringify(body)}`);
+    return body;
+  }
+};
+function formatDns(records) {
+  const rows = records.map((r) => [
+    r.type,
+    r.name,
+    r.priority !== void 0 ? `${r.priority} ${r.value}` : r.value,
+    r.purpose
+  ]);
+  const w = [0, 1, 2].map((i) => Math.max(...rows.map((r) => r[i].length)));
+  return rows.map((r) => `${r[0].padEnd(w[0])}  ${r[1].padEnd(w[1])}  ${r[2].padEnd(w[2])}  # ${r[3]}`).join("\n");
+}
+
+// src/lib/compose.ts
+import path2 from "node:path";
+
+// src/lib/host.ts
+import { execFile } from "node:child_process";
+import dns from "node:dns/promises";
+import net from "node:net";
+import os from "node:os";
+import { promisify } from "node:util";
+var execFileP = promisify(execFile);
+async function run(cmd, args, opts = {}) {
+  if (opts.stdio === "inherit") {
+    const { spawn } = await import("node:child_process");
+    return new Promise((resolve, reject) => {
+      const child = spawn(cmd, args, {
+        cwd: opts.cwd,
+        env: { ...process.env, ...opts.env },
+        stdio: "inherit"
+      });
+      child.on(
+        "exit",
+        (code) => code === 0 ? resolve({ stdout: "", stderr: "" }) : reject(new Error(`${cmd} ${args.join(" ")} exited with ${code}`))
+      );
+      child.on("error", reject);
+    });
+  }
+  return execFileP(cmd, args, {
+    cwd: opts.cwd,
+    env: { ...process.env, ...opts.env },
+    maxBuffer: 64 * 1024 * 1024
+  });
+}
+async function commandExists(cmd) {
+  try {
+    await execFileP(process.platform === "win32" ? "where" : "which", [cmd]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function dockerVersion() {
+  const out = { docker: null, compose: null };
+  try {
+    out.docker = (await execFileP("docker", ["version", "--format", "{{.Server.Version}}"])).stdout.trim();
+  } catch {
+  }
+  try {
+    out.compose = (await execFileP("docker", ["compose", "version", "--short"])).stdout.trim();
+  } catch {
+  }
+  return out;
+}
+function portFree(port, host = "0.0.0.0") {
+  return new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.once("error", () => resolve(false));
+    srv.listen({ port, host, exclusive: true }, () => srv.close(() => resolve(true)));
+  });
+}
+function memoryGiB() {
+  return os.totalmem() / 1024 ** 3;
+}
+async function diskFreeGiB(path7) {
+  try {
+    const { stdout } = await execFileP("df", ["-Pk", path7]);
+    const line = stdout.trim().split("\n").at(-1) ?? "";
+    const avail = Number(line.split(/\s+/)[3]);
+    return Number.isFinite(avail) ? avail / 1024 ** 2 : null;
+  } catch {
+    return null;
+  }
+}
+async function publicIp() {
+  for (const url of ["https://api.ipify.org", "https://ifconfig.me/ip"]) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(4e3) });
+      const ip = (await res.text()).trim();
+      if (net.isIP(ip)) return ip;
+    } catch {
+    }
+  }
+  return null;
+}
+async function resolveA(hostname) {
+  try {
+    return await dns.resolve4(hostname);
+  } catch {
+    return [];
+  }
+}
+async function reverseDns(ip) {
+  try {
+    return await dns.reverse(ip);
+  } catch {
+    return [];
+  }
+}
+function randomSecret(bytes = 32) {
+  return Buffer.from(Array.from({ length: bytes }, () => Math.floor(Math.random() * 256))).toString(
+    "base64url"
+  );
+}
+
+// src/lib/install-dir.ts
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+var DEFAULT_DIR = process.env["MAILSERVER_DIR"] ?? "/opt/mailserver";
+function bundledComposeFile() {
+  return path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "assets", "compose.yaml");
+}
+function bundledCaddyfile() {
+  return path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "assets", "Caddyfile");
+}
+async function readEnv(dir) {
+  const text = await fs.readFile(path.join(dir, ".env"), "utf8").catch(() => "");
+  const env = {};
+  for (const line of text.split("\n")) {
+    const m = /^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/.exec(line);
+    if (m) env[m[1]] = m[2];
+  }
+  return env;
+}
+async function writeEnv(dir, env) {
+  const body = [
+    "# Written by mailctl. Secrets, ports, paths and image tags only (ADR 0005). Configuration lives in the database.",
+    ...Object.entries(env).map(([k, v]) => `${k}=${v}`),
+    ""
+  ].join("\n");
+  await fs.writeFile(path.join(dir, ".env"), body, { mode: 384 });
+}
+function defaultEnv(opts) {
+  return {
+    IMAGE_REGISTRY: opts.registry,
+    IMAGE_TAG: opts.tag,
+    MAIL_HOSTNAME: opts.hostname,
+    DB_ADMIN_USER: "mail",
+    DB_ADMIN_PASSWORD: randomSecret(24),
+    DB_NAME: "mail",
+    DB_DAEMON_USER: "mail_daemon",
+    DB_DAEMON_PASSWORD: randomSecret(24),
+    JWT_SECRET: randomSecret(48),
+    DOVECOT_MASTER_PASSWORD: randomSecret(32),
+    SRS_SECRET: randomSecret(32),
+    PUBLIC_IP: opts.publicIp ?? "",
+    COOKIE_SECURE: "true",
+    SMTP_PORT: "25",
+    SMTPS_PORT: "465",
+    SUBMISSION_PORT: "587",
+    IMAP_PORT: "143",
+    IMAPS_PORT: "993",
+    POP3_PORT: "110",
+    POP3S_PORT: "995",
+    SIEVE_PORT: "4190",
+    HTTP_PORT: "80",
+    HTTPS_PORT: "443",
+    API_PORT: "3000",
+    DB_PORT: "5432"
+  };
+}
+async function materialise(dir) {
+  await fs.mkdir(path.join(dir, "docker", "caddy"), { recursive: true });
+  await fs.mkdir(path.join(dir, "compose"), { recursive: true });
+  await fs.copyFile(bundledComposeFile(), path.join(dir, "compose", "compose.yaml"));
+  await fs.copyFile(bundledCaddyfile(), path.join(dir, "docker", "caddy", "Caddyfile"));
+}
+var composeFile = (dir) => path.join(dir, "compose", "compose.yaml");
+
+// src/lib/compose.ts
+function compose(dir) {
+  const base = [
+    "compose",
+    "--project-name",
+    "mailserver",
+    "--env-file",
+    path2.join(dir, ".env"),
+    "-f",
+    composeFile(dir)
+  ];
+  return {
+    exec: (args, stdio = "inherit") => run("docker", [...base, ...args], { cwd: dir, stdio }),
+    pull: () => run("docker", [...base, "pull", "--quiet"], { cwd: dir, stdio: "inherit" }),
+    up: () => run("docker", [...base, "up", "-d", "--remove-orphans", "--wait"], { cwd: dir, stdio: "inherit" }),
+    down: () => run("docker", [...base, "down"], { cwd: dir, stdio: "inherit" }),
+    ps: async () => (await run("docker", [...base, "ps", "--format", "json"], { cwd: dir, stdio: "pipe" })).stdout,
+    /** Run a one-off command inside a service container, capturing stdout. */
+    execIn: (service, cmd, input) => execInService(base, dir, service, cmd, input)
+  };
+}
+async function execInService(base, dir, service, cmd, input) {
+  const { spawn } = await import("node:child_process");
+  return new Promise((resolve, reject) => {
+    const child = spawn("docker", [...base, "exec", "-T", service, ...cmd], {
+      cwd: dir,
+      stdio: ["pipe", "pipe", "inherit"]
+    });
+    const chunks = [];
+    child.stdout.on("data", (c) => chunks.push(c));
+    child.on("error", reject);
+    child.on(
+      "exit",
+      (code) => code === 0 ? resolve(Buffer.concat(chunks)) : reject(new Error(`docker compose exec ${service} ${cmd[0]} exited with ${code}`))
+    );
+    if (input !== void 0) child.stdin.end(input);
+    else child.stdin.end();
+  });
+}
+
+// src/lib/preflight.ts
+var DEFAULT_PORTS = [25, 80, 443, 465, 587, 993, 995];
+async function preflight(o) {
+  const checks = [];
+  const dv = await dockerVersion();
+  checks.push({
+    name: "docker",
+    ok: !!dv.docker,
+    level: "error",
+    detail: dv.docker ? `engine ${dv.docker}` : "docker engine not reachable (install Docker or run as a user in the docker group)"
+  });
+  checks.push({
+    name: "docker compose",
+    ok: !!dv.compose,
+    level: "error",
+    detail: dv.compose ? `v${dv.compose}` : "compose plugin missing"
+  });
+  checks.push({
+    name: "curl/tar",
+    ok: await commandExists("tar") && await commandExists("curl"),
+    level: "warn",
+    detail: "needed for backup/restore"
+  });
+  const mem = memoryGiB();
+  const minMem = o.minMemoryGiB ?? 2;
+  checks.push({
+    name: "memory",
+    ok: mem >= minMem,
+    level: "error",
+    detail: `${mem.toFixed(1)} GiB (min ${minMem})`
+  });
+  const disk = await diskFreeGiB(o.dataDir);
+  const minDisk = o.minDiskGiB ?? 10;
+  checks.push({
+    name: "disk",
+    ok: disk === null || disk >= minDisk,
+    level: "warn",
+    detail: disk === null ? `cannot stat ${o.dataDir}` : `${disk.toFixed(1)} GiB free at ${o.dataDir} (min ${minDisk})`
+  });
+  if (!o.skipPorts) {
+    for (const p of o.ports) {
+      const free = await portFree(p);
+      checks.push({
+        name: `port ${p}`,
+        ok: free,
+        level: "error",
+        detail: free ? "free" : "in use \u2014 stop the service using it (e.g. an existing MTA, nginx, apache)"
+      });
+    }
+  }
+  const ip = await publicIp();
+  checks.push({
+    name: "public ip",
+    ok: !!ip,
+    level: "warn",
+    detail: ip ?? "could not determine (no outbound HTTPS?)"
+  });
+  if (o.hostname) {
+    const a = await resolveA(o.hostname);
+    const matches = !!ip && a.includes(ip);
+    checks.push({
+      name: "hostname A record",
+      ok: a.length > 0,
+      level: "warn",
+      detail: a.length ? `${o.hostname} \u2192 ${a.join(", ")}${matches ? "" : " (does not match this host's public IP)"}` : `${o.hostname} does not resolve \u2014 ACME will fail until it does`
+    });
+    if (ip) {
+      const ptr = await reverseDns(ip);
+      checks.push({
+        name: "reverse DNS (PTR)",
+        ok: ptr.includes(o.hostname),
+        level: "warn",
+        detail: ptr.length ? `${ip} \u2192 ${ptr.join(", ")}${ptr.includes(o.hostname) ? "" : ` (expected ${o.hostname}; set at your VPS provider)`}` : `no PTR for ${ip} \u2014 many receivers will reject or spam-folder your mail`
+      });
+    }
+  }
+  return checks;
+}
+var blocking = (checks) => checks.filter((c) => !c.ok && c.level === "error");
+function formatChecks(checks) {
+  return checks.map((c) => `${c.ok ? "\u2714" : c.level === "error" ? "\u2716" : "\u26A0"} ${c.name.padEnd(20)} ${c.detail}`).join("\n");
+}
+
+// src/commands/install.ts
+var Install = class _Install extends Command {
+  static description = "Install the mail server on this host: preflight, secrets, compose up, then hand off to setup (wizard URL or --answers).";
+  static examples = [
+    "<%= config.bin %> install --hostname mail.example.com",
+    "<%= config.bin %> install --answers setup.yaml"
+  ];
+  static flags = {
+    dir: Flags.string({ description: "install directory", default: DEFAULT_DIR }),
+    hostname: Flags.string({ description: "mail hostname (FQDN); read from --answers when given" }),
+    answers: Flags.string({
+      description: "answers file (YAML/JSON) for a headless install \u2014 completes setup without the wizard"
+    }),
+    tag: Flags.string({
+      description: "image tag to install",
+      default: process.env["MAILSERVER_VERSION"] ?? "latest"
+    }),
+    registry: Flags.string({
+      description: "image registry/namespace",
+      default: process.env["MAILSERVER_REGISTRY"] ?? "ghcr.io/mail-dock/mailserver"
+    }),
+    "skip-preflight": Flags.boolean({
+      description: "continue despite failed preflight checks",
+      default: false
+    }),
+    "no-pull": Flags.boolean({ description: "do not pull images (use local builds)", default: false })
+  };
+  async run() {
+    const { flags } = await this.parse(_Install);
+    let answers;
+    if (flags.answers) {
+      const raw = await fs2.readFile(flags.answers, "utf8");
+      const parsed = SetupAnswers.safeParse(parseYaml(raw));
+      if (!parsed.success)
+        this.error(
+          `invalid answers file:
+${parsed.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n")}`
+        );
+      answers = parsed.data;
+    }
+    const hostname = answers?.hostname ?? flags.hostname;
+    if (!hostname) this.error("--hostname is required (or provide --answers)");
+    const dir = flags.dir;
+    await fs2.mkdir(dir, { recursive: true });
+    const existing = await readEnv(dir);
+    if (existing["JWT_SECRET"]) this.log(`Existing install found in ${dir}; keeping its secrets.`);
+    this.log("Preflight\u2026");
+    const checks = await preflight({
+      hostname,
+      dataDir: dir,
+      ports: DEFAULT_PORTS,
+      skipPorts: !!existing["JWT_SECRET"]
+    });
+    this.log(formatChecks(checks));
+    const blockers = blocking(checks);
+    if (blockers.length && !flags["skip-preflight"])
+      this.error(`${blockers.length} blocking check(s) failed. Fix them or re-run with --skip-preflight.`);
+    const ip = await publicIp();
+    const env = {
+      ...defaultEnv({ hostname, tag: flags.tag, registry: flags.registry, publicIp: ip }),
+      ...existing,
+      MAIL_HOSTNAME: hostname,
+      IMAGE_TAG: flags.tag,
+      IMAGE_REGISTRY: flags.registry
+    };
+    await writeEnv(dir, env);
+    await materialise(dir);
+    this.log(`Wrote ${path3.join(dir, ".env")} and compose bundle.`);
+    const c = compose(dir);
+    if (!flags["no-pull"]) {
+      this.log("Pulling images\u2026");
+      await c.pull();
+    }
+    this.log("Starting services\u2026");
+    await c.up();
+    const api = new ApiClient(`http://127.0.0.1:${env["API_PORT"] ?? "3000"}`);
+    const health = await api.waitHealthy(
+      18e4,
+      (t) => t % 1e4 < 2e3 && this.log(`  waiting for API (${Math.round(t / 1e3)}s)\u2026`)
+    );
+    this.log(`API ${health.version} healthy; setup ${health.setup}.`);
+    if (answers) {
+      if (health.setup === "complete")
+        this.error(
+          "setup is already complete on this server; --answers ignored. Use the admin UI to change settings."
+        );
+      this.log("Applying answers file\u2026");
+      const result = await api.applyAnswers(answers);
+      this.log("\nSetup complete. Publish these DNS records:\n");
+      this.log(formatDns(result.dns));
+      this.log(`
+Admin: https://${hostname}/  \xB7  API docs: https://${hostname}/api/v1/docs`);
+    } else if (health.setup === "pending") {
+      this.log(
+        `
+Open the Setup Wizard to finish: https://${hostname}/  (or http://${ip ?? "<server-ip>"}/ until DNS resolves)`
+      );
+    } else {
+      this.log(`
+Installed. Admin: https://${hostname}/`);
+    }
+  }
+};
+
+// src/commands/doctor.ts
+import { Command as Command2, Flags as Flags2 } from "@oclif/core";
+var Doctor = class _Doctor extends Command2 {
+  static description = "Re-run host preflight, check every service and the API, and verify DNS for the mail hostname.";
+  static flags = { dir: Flags2.string({ description: "install directory", default: DEFAULT_DIR }) };
+  async run() {
+    const { flags } = await this.parse(_Doctor);
+    const env = await readEnv(flags.dir);
+    if (!env["MAIL_HOSTNAME"]) this.error(`no install found in ${flags.dir} (missing .env)`);
+    const checks = await preflight({
+      hostname: env["MAIL_HOSTNAME"],
+      dataDir: flags.dir,
+      ports: [],
+      skipPorts: true
+    });
+    let services = [];
+    try {
+      services = (await compose(flags.dir).ps()).split("\n").filter(Boolean).map((l) => JSON.parse(l));
+    } catch (e) {
+      checks.push({ name: "compose", ok: false, level: "error", detail: String(e) });
+    }
+    for (const s of services) {
+      const ok = s.State === "running" && (!s.Health || s.Health === "healthy");
+      checks.push({
+        name: `service ${s.Service}`,
+        ok,
+        level: "error",
+        detail: `${s.State}${s.Health ? ` (${s.Health})` : ""}`
+      });
+    }
+    const expected = [
+      "postgres",
+      "redis",
+      "rspamd",
+      "dovecot",
+      "postfix",
+      "api",
+      "worker",
+      "web",
+      "caddy",
+      "cert-sync"
+    ];
+    for (const name of expected.filter((n) => !services.some((s) => s.Service === n))) {
+      checks.push({ name: `service ${name}`, ok: false, level: "error", detail: "not running" });
+    }
+    const api = new ApiClient(`http://127.0.0.1:${env["API_PORT"] ?? "3000"}`);
+    const h = await api.health();
+    checks.push({
+      name: "api",
+      ok: !!h?.ok,
+      level: "error",
+      detail: h ? `version ${h.version}, setup ${h.setup}` : "unreachable"
+    });
+    this.log(formatChecks(checks));
+    const bad = checks.filter((c) => !c.ok && c.level === "error");
+    if (bad.length) this.error(`${bad.length} problem(s) found`, { exit: 1 });
+    this.log("\nAll checks passed.");
+  }
+};
+
+// src/commands/backup.ts
+import { Command as Command3, Flags as Flags3 } from "@oclif/core";
+import { createHash } from "node:crypto";
+import fs3 from "node:fs/promises";
+import path4 from "node:path";
+var Backup = class _Backup extends Command3 {
+  static description = "Back up the database (pg_dump), all mail (maildir tar) and .env to a timestamped directory with checksums.";
+  static flags = {
+    dir: Flags3.string({ description: "install directory", default: DEFAULT_DIR }),
+    out: Flags3.string({ description: "backup root directory", default: path4.join(DEFAULT_DIR, "backups") })
+  };
+  async run() {
+    const { flags } = await this.parse(_Backup);
+    const target = await backup(flags.dir, flags.out, (m) => this.log(m));
+    this.log(`Backup written to ${target}`);
+  }
+};
+var sha256 = async (file) => createHash("sha256").update(await fs3.readFile(file)).digest("hex");
+async function backup(dir, outRoot, log) {
+  const env = await readEnv(dir);
+  if (!env["DB_NAME"]) throw new Error(`no install found in ${dir}`);
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const out = path4.join(outRoot, stamp);
+  await fs3.mkdir(out, { recursive: true });
+  const c = compose(dir);
+  log("Dumping database\u2026");
+  const dump = await c.execIn("postgres", [
+    "pg_dump",
+    "-U",
+    env["DB_ADMIN_USER"] ?? "mail",
+    "-Fc",
+    env["DB_NAME"]
+  ]);
+  await fs3.writeFile(path4.join(out, "database.dump"), dump);
+  log("Archiving mail\u2026");
+  await run(
+    "docker",
+    [
+      "run",
+      "--rm",
+      "-v",
+      "mailserver_vmail:/var/vmail:ro",
+      "-v",
+      `${out}:/backup`,
+      "alpine:3.20",
+      "tar",
+      "czf",
+      "/backup/vmail.tar.gz",
+      "-C",
+      "/var",
+      "vmail"
+    ],
+    { stdio: "inherit" }
+  );
+  await fs3.copyFile(path4.join(dir, ".env"), path4.join(out, "env"));
+  await fs3.chmod(path4.join(out, "env"), 384);
+  const files = ["database.dump", "vmail.tar.gz", "env"];
+  const manifest = {
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    version: env["IMAGE_TAG"] ?? "unknown",
+    hostname: env["MAIL_HOSTNAME"],
+    files: Object.fromEntries(
+      await Promise.all(
+        files.map(async (f) => [
+          f,
+          { sha256: await sha256(path4.join(out, f)), bytes: (await fs3.stat(path4.join(out, f))).size }
+        ])
+      )
+    )
+  };
+  await fs3.writeFile(path4.join(out, "manifest.json"), JSON.stringify(manifest, null, 2));
+  return out;
+}
+async function verifyBackup(backupDir) {
+  const manifest = JSON.parse(await fs3.readFile(path4.join(backupDir, "manifest.json"), "utf8"));
+  for (const [f, meta] of Object.entries(manifest.files)) {
+    const actual = await sha256(path4.join(backupDir, f));
+    if (actual !== meta.sha256)
+      throw new Error(`integrity check failed for ${f} (expected ${meta.sha256}, got ${actual})`);
+  }
+  return manifest;
+}
+
+// src/commands/restore.ts
+import { Command as Command4, Flags as Flags4 } from "@oclif/core";
+import fs4 from "node:fs/promises";
+import path5 from "node:path";
+var Restore = class _Restore extends Command4 {
+  static description = "Restore a backup made by `mailctl backup` (verifies checksums, restores .env, database and mail, restarts the stack).";
+  static args = {};
+  static flags = {
+    dir: Flags4.string({ description: "install directory", default: DEFAULT_DIR }),
+    from: Flags4.string({ description: "backup directory (contains manifest.json)", required: true }),
+    yes: Flags4.boolean({ description: "do not ask for confirmation", default: false })
+  };
+  async run() {
+    const { flags } = await this.parse(_Restore);
+    const manifest = await verifyBackup(flags.from);
+    this.log(`Backup verified: ${manifest.hostname} @ ${manifest.version}`);
+    if (!flags.yes) {
+      const { confirm } = await import("@inquirer/prompts").catch(() => ({ confirm: null }));
+      if (confirm && !await confirm({
+        message: `This REPLACES the database and all mail in ${flags.dir}. Continue?`,
+        default: false
+      }))
+        this.exit(1);
+    }
+    await fs4.mkdir(flags.dir, { recursive: true });
+    await fs4.copyFile(path5.join(flags.from, "env"), path5.join(flags.dir, ".env"));
+    await fs4.chmod(path5.join(flags.dir, ".env"), 384);
+    await materialise(flags.dir);
+    const env = await readEnv(flags.dir);
+    const c = compose(flags.dir);
+    this.log("Stopping mail services\u2026");
+    await c.exec(["stop", "postfix", "dovecot", "api", "cert-sync"]);
+    await c.exec(["up", "-d", "--wait", "postgres"]);
+    this.log("Restoring database\u2026");
+    const user = env["DB_ADMIN_USER"] ?? "mail";
+    const db = env["DB_NAME"] ?? "mail";
+    await c.execIn("postgres", [
+      "psql",
+      "-U",
+      user,
+      "-d",
+      "postgres",
+      "-c",
+      `DROP DATABASE IF EXISTS ${db} WITH (FORCE)`
+    ]);
+    await c.execIn("postgres", ["psql", "-U", user, "-d", "postgres", "-c", `CREATE DATABASE ${db}`]);
+    await c.execIn(
+      "postgres",
+      ["pg_restore", "-U", user, "-d", db, "--no-owner"],
+      await fs4.readFile(path5.join(flags.from, "database.dump"))
+    );
+    this.log("Restoring mail\u2026");
+    await run(
+      "docker",
+      [
+        "run",
+        "--rm",
+        "-v",
+        "mailserver_vmail:/var/vmail",
+        "-v",
+        `${path5.resolve(flags.from)}:/backup:ro`,
+        "alpine:3.20",
+        "sh",
+        "-c",
+        "rm -rf /var/vmail/* && tar xzf /backup/vmail.tar.gz -C /var && chown -R 5000:5000 /var/vmail"
+      ],
+      { stdio: "inherit" }
+    );
+    this.log("Starting services\u2026");
+    await c.up();
+    await new ApiClient(`http://127.0.0.1:${env["API_PORT"] ?? "3000"}`).waitHealthy(12e4);
+    this.log("Restore complete.");
+  }
+};
+
+// src/commands/upgrade.ts
+import { Command as Command5, Flags as Flags5 } from "@oclif/core";
+import path6 from "node:path";
+var Upgrade = class _Upgrade extends Command5 {
+  static description = "Upgrade to a new version: pre-upgrade backup, pull images, restart, run migrations, verify health.";
+  static flags = {
+    dir: Flags5.string({ description: "install directory", default: DEFAULT_DIR }),
+    tag: Flags5.string({ description: "target image tag (default: latest)", default: "latest" }),
+    "skip-backup": Flags5.boolean({
+      default: false,
+      description: "skip the pre-upgrade backup (not recommended)"
+    })
+  };
+  async run() {
+    const { flags } = await this.parse(_Upgrade);
+    const env = await readEnv(flags.dir);
+    if (!env["IMAGE_TAG"]) this.error(`no install found in ${flags.dir}`);
+    this.log(`Upgrading ${env["MAIL_HOSTNAME"]} from ${env["IMAGE_TAG"]} to ${flags.tag}`);
+    if (!flags["skip-backup"]) {
+      const out = await backup(flags.dir, path6.join(flags.dir, "backups"), (m) => this.log(m));
+      this.log(`Pre-upgrade backup: ${out}`);
+    }
+    const defaults = defaultEnv({
+      hostname: env["MAIL_HOSTNAME"] ?? "",
+      tag: flags.tag,
+      registry: env["IMAGE_REGISTRY"] ?? "",
+      publicIp: env["PUBLIC_IP"]
+    });
+    const added = Object.keys(defaults).filter((k) => !(k in env));
+    if (added.length) this.log(`Adding new .env keys: ${added.join(", ")}`);
+    await writeEnv(flags.dir, { ...defaults, ...env, IMAGE_TAG: flags.tag });
+    await materialise(flags.dir);
+    const c = compose(flags.dir);
+    this.log("Pulling images\u2026");
+    await c.pull();
+    this.log("Restarting services (migrations run on API start)\u2026");
+    await c.up();
+    const h = await new ApiClient(`http://127.0.0.1:${env["API_PORT"] ?? "3000"}`).waitHealthy(18e4);
+    this.log(`Upgrade complete: API reports version ${h.version}.`);
+    this.log(`If something is wrong: mailctl restore --from <backup dir> restores the pre-upgrade state.`);
+  }
+};
+
+// src/index.ts
+var PACKAGE_NAME = "@maildock/mailctl";
+var COMMANDS = {
+  install: Install,
+  doctor: Doctor,
+  backup: Backup,
+  restore: Restore,
+  upgrade: Upgrade
+};
+export {
+  Backup,
+  COMMANDS,
+  Doctor,
+  Install,
+  PACKAGE_NAME,
+  Restore,
+  Upgrade,
+  blocking,
+  defaultEnv,
+  formatChecks,
+  preflight,
+  readEnv,
+  writeEnv
+};
+//# sourceMappingURL=index.js.map