@meith/install 0.16.0

package/LICENSE.md

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@meith/install",
+  "version": "0.16.0",
+  "license": "LGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meith-dev/meith.git",
+    "directory": "packages/install"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.type-test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@meith/settings": "0.16.0"
+  }
+}

package/src/form.ts

@@ -0,0 +1,252 @@
+import { z } from 'zod'
+
+import {
+  defaultPort,
+  isUsableOrigin,
+  MAIL_PRESET_BY_ID,
+  type MailConfig,
+  type MailSecurity,
+  mailConfigProblems,
+  normaliseOrigin,
+} from '@meith/settings'
+
+export const MAIL_SKIP = 'skip'
+
+const mailFields = {
+  mailPreset: z.string().trim().default(MAIL_SKIP),
+  mailFrom: z.string().trim().default(''),
+  mailHost: z.string().trim().default(''),
+  mailPort: z.string().trim().default(''),
+  mailSecurity: z.preprocess(
+    (value) => (value === '' ? undefined : value),
+    z.enum(['tls', 'starttls', 'none']).optional(),
+  ),
+  mailUsername: z.string().trim().default(''),
+  mailSecret: z.string().trim().default(''),
+  mailEndpoint: z.string().trim().default(''),
+}
+
+const installInputObject = z.object({
+  boardName: z
+    .string()
+    .trim()
+    .min(1, 'install.validation.boardNameRequired')
+    .max(100, 'install.validation.nameTooLong'),
+  username: z
+    .string()
+    .trim()
+    .min(3, 'install.validation.usernameMin')
+    .max(30, 'install.validation.nameTooLong'),
+  email: z.string().trim().email('install.validation.email'),
+  boardUrl: z
+    .string()
+    .trim()
+    .min(1, 'install.validation.boardUrlRequired')
+    .refine(isUsableOrigin, 'install.validation.boardUrl')
+    .transform(normaliseOrigin),
+  password: z
+    .string()
+    .min(12, 'install.validation.passwordMin')
+    .max(200, 'install.validation.passwordTooLong'),
+  ...mailFields,
+})
+
+export const installInputSchema = installInputObject.superRefine((value, ctx) => {
+  if (value.mailPreset === MAIL_SKIP) return
+
+  const preset = MAIL_PRESET_BY_ID.get(value.mailPreset)
+  if (preset === undefined) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['mailPreset'],
+      message: 'install.validation.mailPreset',
+    })
+    return
+  }
+
+  if (value.mailFrom === '') {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['mailFrom'],
+      message: 'install.validation.mailFromRequired',
+    })
+  } else if (!z.string().email().safeParse(value.mailFrom).success) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['mailFrom'],
+      message: 'install.validation.email',
+    })
+  }
+
+  if (preset.transport === 'http') {
+    const endpoint = value.mailEndpoint === '' ? (preset.endpoint ?? '') : value.mailEndpoint
+    if (endpoint === '') {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['mailEndpoint'],
+        message: 'install.validation.mailEndpointRequired',
+      })
+    } else if (!z.string().url().safeParse(endpoint).success) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['mailEndpoint'],
+        message: 'install.validation.url',
+      })
+    }
+    if (value.mailSecret === '') {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['mailSecret'],
+        message: 'install.validation.mailSecretRequired',
+      })
+    }
+    return
+  }
+
+  if (value.mailHost === '' && (preset.host ?? '') === '') {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['mailHost'],
+      message: 'install.validation.mailHostRequired',
+    })
+  }
+
+  if (value.mailPort !== '') {
+    const port = Number(value.mailPort)
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['mailPort'],
+        message: 'install.validation.mailPort',
+      })
+    }
+  }
+
+  const username = value.mailUsername === '' ? (preset.username ?? '') : value.mailUsername
+  if (username !== '' && value.mailSecret === '') {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['mailSecret'],
+      message: 'install.validation.mailPasswordRequired',
+    })
+  }
+  if (username === '' && value.mailSecret !== '') {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['mailUsername'],
+      message: 'install.validation.mailUsernameRequired',
+    })
+  }
+})
+
+export type InstallInput = z.infer<typeof installInputSchema>
+
+export const INSTALL_FIELDS: readonly string[] = Object.keys(installInputObject.shape)
+
+export const SECRET_FIELDS: readonly string[] = ['password', 'mailSecret']
+
+export const ECHOED_FIELDS: readonly string[] = INSTALL_FIELDS.filter(
+  (name) => !SECRET_FIELDS.includes(name),
+)
+
+export interface FormLike {
+  get(name: string): unknown
+}
+
+export function installInputFromForm(form: FormLike): Record<string, string> {
+  return Object.fromEntries(
+    INSTALL_FIELDS.map((name) => {
+      const value = form.get(name)
+      return [name, typeof value === 'string' ? value : '']
+    }),
+  )
+}
+
+export interface EnvironmentAnswers {
+  readonly boardUrl: string | null
+  readonly mailIsFromEnvironment: boolean
+}
+
+export function withEnvironmentAnswers(
+  raw: Record<string, string>,
+  environment: EnvironmentAnswers,
+): Record<string, string> {
+  const answered = { ...raw }
+
+  if (environment.boardUrl !== null && environment.boardUrl !== '') {
+    answered.boardUrl = environment.boardUrl
+  }
+
+  if (environment.mailIsFromEnvironment) {
+    answered.mailPreset = MAIL_SKIP
+    for (const name of INSTALL_FIELDS) {
+      if (name.startsWith('mail') && name !== 'mailPreset') answered[name] = ''
+    }
+  }
+
+  return answered
+}
+
+export function mailConfigFromInstallInput(input: InstallInput): MailConfig {
+  if (input.mailPreset === MAIL_SKIP) return { transport: 'log' }
+
+  const preset = MAIL_PRESET_BY_ID.get(input.mailPreset)
+  if (preset === undefined) return { transport: 'log' }
+
+  if (preset.transport === 'http') {
+    return {
+      transport: 'http',
+      from: input.mailFrom,
+      endpoint: input.mailEndpoint === '' ? (preset.endpoint ?? '') : input.mailEndpoint,
+      token: input.mailSecret,
+    }
+  }
+
+  const security: MailSecurity = input.mailSecurity ?? preset.security ?? 'starttls'
+
+  return {
+    transport: 'smtp',
+    from: input.mailFrom,
+    host: input.mailHost === '' ? (preset.host ?? '') : input.mailHost,
+    port:
+      input.mailPort === ''
+        ? preset.security === security && preset.port !== undefined
+          ? preset.port
+          : defaultPort(security)
+        : Number(input.mailPort),
+    security,
+    username: input.mailUsername === '' ? (preset.username ?? '') : input.mailUsername,
+    password: input.mailSecret,
+  }
+}
+
+export function parseInstallInput(
+  raw: Record<string, unknown>,
+): { ok: true; value: InstallInput } | { ok: false; errors: Record<string, string> } {
+  const parsed = installInputSchema.safeParse(raw)
+  if (parsed.success) {
+    const problems = mailConfigProblems(mailConfigFromInstallInput(parsed.data))
+    if (problems.length > 0) {
+      return { ok: false, errors: { mailPreset: 'install.validation.mailConfiguration' } }
+    }
+    return { ok: true, value: parsed.data }
+  }
+
+  const errors: Record<string, string> = {}
+  for (const issue of parsed.error.issues) {
+    const key = String(issue.path[0] ?? 'form')
+    errors[key] ??= issue.message
+  }
+  return { ok: false, errors }
+}
+
+export function defaultForumSlug(boardName: string): string {
+  const slug = boardName
+    .toLowerCase()
+    .normalize('NFKD')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40)
+
+  return slug === '' ? 'general' : slug
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+export {
+  defaultForumSlug,
+  ECHOED_FIELDS,
+  type EnvironmentAnswers,
+  type FormLike,
+  INSTALL_FIELDS,
+  type InstallInput,
+  installInputFromForm,
+  installInputSchema,
+  MAIL_SKIP,
+  mailConfigFromInstallInput,
+  parseInstallInput,
+  SECRET_FIELDS,
+  withEnvironmentAnswers,
+} from './form'
+export {
+  fieldErrorsFromReport,
+  firstFailure,
+  freshReport,
+  INSTALL_STEPS,
+  type InstallStep,
+  installed,
+  type StepOutcome,
+  type StepStatus,
+  stepTitleKey,
+} from './plan'
+export {
+  blockers,
+  type Check,
+  canProceed,
+  type Level,
+  type MailProbe,
+  type PreflightProbe,
+  preflight,
+  warnings,
+} from './preflight'

package/src/plan.ts

@@ -0,0 +1,64 @@
+export interface InstallStep {
+  readonly id: string
+  readonly titleKey: string
+  readonly detailKey: string
+}
+
+export const INSTALL_STEPS: readonly InstallStep[] = [
+  {
+    id: 'migrate',
+    titleKey: 'install.step.migrate.title',
+    detailKey: 'install.step.migrate.detail',
+  },
+  {
+    id: 'settings',
+    titleKey: 'install.step.settings.title',
+    detailKey: 'install.step.settings.detail',
+  },
+  {
+    id: 'admin',
+    titleKey: 'install.step.admin.title',
+    detailKey: 'install.step.admin.detail',
+  },
+  {
+    id: 'forum',
+    titleKey: 'install.step.forum.title',
+    detailKey: 'install.step.forum.detail',
+  },
+  {
+    id: 'seal',
+    titleKey: 'install.step.seal.title',
+    detailKey: 'install.step.seal.detail',
+  },
+]
+
+export type StepStatus = 'pending' | 'done' | 'failed'
+
+export interface StepOutcome {
+  readonly id: string
+  readonly status: StepStatus
+  readonly error?: string
+  readonly field?: string
+}
+
+export function fieldErrorsFromReport(report: readonly StepOutcome[]): Record<string, string> {
+  const failure = firstFailure(report)
+  if (failure === null || failure.field === undefined) return {}
+  return { [failure.field]: failure.error ?? 'installAction.answerRefused' }
+}
+
+export function stepTitleKey(id: string): string {
+  return INSTALL_STEPS.find((step) => step.id === id)?.titleKey ?? id
+}
+
+export function freshReport(): readonly StepOutcome[] {
+  return INSTALL_STEPS.map((step) => ({ id: step.id, status: 'pending' as const }))
+}
+
+export function installed(report: readonly StepOutcome[]): boolean {
+  return report.length === INSTALL_STEPS.length && report.every((step) => step.status === 'done')
+}
+
+export function firstFailure(report: readonly StepOutcome[]): StepOutcome | null {
+  return report.find((step) => step.status === 'failed') ?? null
+}

package/src/preflight.ts

@@ -0,0 +1,168 @@
+import type { MailSource } from '@meith/settings'
+
+export type Level = 'blocker' | 'warning' | 'ok'
+
+export interface MailProbe {
+  readonly configured: boolean
+  readonly source: MailSource
+  readonly summary: string
+}
+
+export interface Check {
+  readonly id: string
+  readonly level: Level
+  readonly titleKey: string
+  readonly titleArgs?: Readonly<Record<string, string | number>> | undefined
+  readonly detailKey?: string | undefined
+  readonly detailArgs?: Readonly<Record<string, string | number>> | undefined
+}
+
+export interface PreflightProbe {
+  readonly dataSource: 'fixture' | 'postgres'
+  readonly databaseUrl: string | null
+  readonly hasAuthSecret: boolean
+  readonly hasTickSecret: boolean
+  readonly publicUrl: string | null
+  readonly mail: MailProbe
+  readonly canConnect: boolean | null
+  readonly pendingMigrations: number | null
+  readonly userCount: number | null
+  readonly alreadyInstalled: boolean
+}
+
+function ok(
+  id: string,
+  titleKey: string,
+  titleArgs?: Readonly<Record<string, string | number>>,
+): Check {
+  return { id, level: 'ok', titleKey, ...(titleArgs === undefined ? {} : { titleArgs }) }
+}
+
+export function preflight(probe: PreflightProbe): readonly Check[] {
+  const checks: Check[] = []
+
+  if (probe.alreadyInstalled) {
+    checks.push({
+      id: 'already-installed',
+      level: 'blocker',
+      titleKey: 'installPreflight.alreadyInstalled.title',
+      detailKey: 'installPreflight.alreadyInstalled.detail',
+    })
+  } else if (probe.userCount !== null && probe.userCount > 0) {
+    checks.push({
+      id: 'has-members',
+      level: 'blocker',
+      titleKey: 'installPreflight.hasMembers.title',
+      detailKey: 'installPreflight.hasMembers.detail',
+      detailArgs: { count: probe.userCount },
+    })
+  } else {
+    checks.push(ok('fresh', 'installPreflight.fresh.title'))
+  }
+
+  if (probe.dataSource !== 'postgres') {
+    checks.push({
+      id: 'data-source',
+      level: 'blocker',
+      titleKey: 'installPreflight.dataSource.title',
+      detailKey: 'installPreflight.dataSource.detail',
+    })
+  } else if (probe.databaseUrl === null || probe.databaseUrl === '') {
+    checks.push({
+      id: 'database-url',
+      level: 'blocker',
+      titleKey: 'installPreflight.databaseUrl.missingTitle',
+      detailKey: 'installPreflight.databaseUrl.missingDetail',
+    })
+  } else {
+    checks.push(ok('database-url', 'installPreflight.databaseUrl.setTitle'))
+  }
+
+  if (probe.canConnect === false) {
+    checks.push({
+      id: 'connect',
+      level: 'blocker',
+      titleKey: 'installPreflight.connect.refusedTitle',
+      detailKey: 'installPreflight.connect.refusedDetail',
+    })
+  } else if (probe.canConnect === true) {
+    checks.push(ok('connect', 'installPreflight.connect.acceptedTitle'))
+  }
+
+  if (probe.pendingMigrations !== null && probe.pendingMigrations > 0) {
+    checks.push({
+      id: 'migrations',
+      level: 'ok',
+      titleKey: 'installPreflight.migrations.title',
+      titleArgs: { count: probe.pendingMigrations },
+    })
+  }
+
+  if (!probe.hasAuthSecret) {
+    checks.push({
+      id: 'auth-secret',
+      level: 'blocker',
+      titleKey: 'installPreflight.authSecret.missingTitle',
+      detailKey: 'installPreflight.authSecret.missingDetail',
+    })
+  } else {
+    checks.push(ok('auth-secret', 'installPreflight.authSecret.setTitle'))
+  }
+
+  if (!probe.hasTickSecret) {
+    checks.push({
+      id: 'tick-secret',
+      level: 'warning',
+      titleKey: 'installPreflight.tickSecret.missingTitle',
+      detailKey: 'installPreflight.tickSecret.missingDetail',
+    })
+  } else {
+    checks.push(ok('tick-secret', 'installPreflight.tickSecret.setTitle'))
+  }
+
+  if (probe.publicUrl !== null && probe.publicUrl !== '') {
+    checks.push(ok('public-url', 'installPreflight.publicUrl.setTitle', { url: probe.publicUrl }))
+  } else {
+    checks.push({
+      id: 'public-url',
+      level: 'ok',
+      titleKey: 'installPreflight.publicUrl.formTitle',
+      detailKey: 'installPreflight.publicUrl.formDetail',
+    })
+  }
+
+  if (probe.mail.configured) {
+    checks.push(
+      ok('mail', 'installPreflight.mail.configuredTitle', { summary: probe.mail.summary }),
+    )
+  } else if (probe.mail.source === 'environment') {
+    checks.push({
+      id: 'mail',
+      level: 'blocker',
+      titleKey: 'installPreflight.mail.incompleteTitle',
+      detailKey: 'installPreflight.mail.incompleteDetail',
+      detailArgs: { summary: probe.mail.summary },
+    })
+  } else {
+    checks.push({
+      id: 'mail',
+      level: 'warning',
+      titleKey: 'installPreflight.mail.unconfiguredTitle',
+      detailKey: 'installPreflight.mail.unconfiguredDetail',
+    })
+  }
+
+  return checks
+}
+
+export function canProceed(checks: readonly Check[]): boolean {
+  return !checks.some((check) => check.level === 'blocker')
+}
+
+export function blockers(checks: readonly Check[]): readonly Check[] {
+  return checks.filter((check) => check.level === 'blocker')
+}
+
+export function warnings(checks: readonly Check[]): readonly Check[] {
+  return checks.filter((check) => check.level === 'warning')
+}