@small-web/kitten-types 1.1.3 → 2.0.0

package/kitten/src/types/globals.d.ts

@@ -0,0 +1,1239 @@
+/**
+  Kitten types.
+
+  Type declarations for global `kitten` namespace.
+*/
+
+import type { EventEmitter } from 'node:events'
+import type { Server } from 'node:https'
+import type { AutoEncryptedServer } from '@small-tech/auto-encrypt'
+import type { AutoEncryptedLocalhostServer } from '@small-tech/auto-encrypt-localhost'
+
+import type {
+  Session,
+  Upload,
+  KittenComponent,
+  KittenPage,
+  MarkdownIt,
+  Polka,
+  WebSocket as KittenWebSocket,
+  slugify as Slugify,
+  yaml as Yaml,
+  Point,
+  Signature
+} from './types.d.ts'
+
+import type { KittenIcons } from 'kitten-icons/types.d.ts'
+
+/**
+  Tagged template function (e.g. `kitten.html`, `kitten.css`).
+*/
+export type TaggedTemplate = (
+  strings: TemplateStringsArray,
+  ...properties: any[]
+) => string | Array<string> | Promise<string | Array<string>>
+
+/**
+  Sanitisation helper (e.g. `kitten.safelyAddHtml`, `kitten.sanitise`).
+*/
+export type SanitisationFunction = (
+  untrustedContent: string,
+  allowedTags?: Array<string>,
+  concat?: boolean
+) => string | Array<string> | Promise<string | Array<string>>
+
+/**
+  Record that maps URL fragments to hit counts.
+*/
+type StatsObject = Record<string, number>
+
+/**
+  Internal Kitten database (`kitten._db`).
+*/
+export interface KittenInternalDatabase {
+  sessions: Record<string, Session>
+  settings: {
+    autoUpdate: {
+      interval: number
+    }
+    domainToken: string
+    domainRedirects: Record<string, string>
+    localRedirects: Record<string, string>
+    evergreenWebUrl: string
+    hideWelcomeMessage: boolean
+    id: {
+      ed25519: {
+        asString: string
+      }
+      ssh: {
+        asString: string
+        fingerprint: string
+      }
+      pgp?: {
+        asString: string
+      }
+    }
+    path: string
+    smallWebHostDomain: string
+    webhookSecret: string
+  }
+  packageLockFileHashes: Record<string, string>
+  stats: {
+    hits: StatsObject
+    pages: StatsObject
+    missing: StatsObject
+    referrers: StatsObject
+    serverErrors: StatsObject
+  }
+  uploads: UploadStore,
+  scheduledRestart: {
+    lastRestartDate: number
+    restartHour: number
+  }
+}
+
+/**
+  The `kitten.uploads` store.
+*/
+export type UploadStore = {
+  get(id: string): Upload
+  length(): number
+  all(): Upload[]
+  allIds(): string[]
+  delete(id: string): Promise<void>
+} & Record<string, Upload>
+
+/**
+  Configuration options for the Kitten server.
+*/
+interface ServerOptions {
+  domain?: string
+  port?: number
+  aliases?: string
+  open?: boolean
+  'working-directory'?: string
+  'domain-token'?: string
+  'small-web-host-domain'?: string
+}
+
+type UpdateType = 'upgrade' | 'downgrade' | 'updating' | 'restarting'
+
+/**
+  Conditionally-active logger.
+
+  Logs a message when enabled (via the `LOG` environment variable, the runtime control methods, or while the Kitten REPL is active for REPL loggers).
+*/
+export type Logger = ((...args: unknown[]) => void) & { enabled: boolean }
+
+/**
+  Names of log sections used by Kitten.
+*/
+export type LogSection =
+  | 'lifecycle' | 'event' | 'streamingHtml' | 'repl' | 'debug'
+  | 'router' | 'html' | 'watcher' | 'pageSocketRoute'
+  | 'webSocketRoute' | 'verbose'
+
+/**
+  Kitten’s logging namespace, exposed at `kitten.log`.
+
+  Exposes one {@link Logger} per {@link LogSection} plus runtime controls to enable/disable loggers and display logging information.
+*/
+export interface Log extends Record<LogSection, Logger> {
+  /** Whether any logger is currently enabled. */
+  isActive: boolean
+  /** Prints the key of symbols used in log prefixes. */
+  showKey: () => void
+  /** Lists the currently enabled loggers. */
+  listEnabled: () => void
+  /** Enables all loggers. */
+  all: () => void
+  /** Alias for {@link all}. */
+  on: () => void
+  /** Enables only the specified loggers, disabling the rest. */
+  only: (...loggers: LogSection[]) => void
+  /** Disables all loggers. */
+  none: () => void
+  /** Alias for {@link none}. */
+  off: () => void
+  /** Whether the log key has already been shown. */
+  keyAlreadyShown: boolean
+}
+
+/**
+  Global `kitten` namespace.
+*/
+export interface kitten {
+  /**
+    Kitten’s version number and releated utilities.
+  */
+  version: {
+    date: Date
+    versionStamp: number
+    gitHash: string
+    apiVersion: number
+    nodeVersion: string
+    exactVersion: string
+    birthday: string
+    starSign: string
+    Component: () => Function
+    html: () => string
+    printToConsole: () => void
+  }
+
+  /**
+    The Kitten app.
+
+    Includes references to the Kitten router (Polka) and server as well as the Kitten package (in deployed servers).
+  */
+  app: {
+    /** The parsed package.json file for the current Kitten app (if any). */
+    package?: any
+    // Note: Type 'Polka' *is* generic. If you’re seeing an error to the contrary, the type checker is picking up more recent type information for Polka from its @types package from a global typescript install.
+    // `router` and `server` are wired up incrementally after the `app` object is first created (as `{}`) in `globals.ts`, hence optional.
+    router?: Polka<any>
+    server?: Server | AutoEncryptedServer | AutoEncryptedLocalhostServer
+  }
+
+  /**
+    This is your custom JSDB database.
+
+    If you want type safety for it, create a database app module in your project and declare the types there.
+
+    @see https://codeberg.org/kitten/app#database-app-module
+  */
+  db: any
+
+  /**
+    Kitten’s internal database.
+
+    You should not need to access this directly.
+  */
+  _db: KittenInternalDatabase
+
+  /**
+    Kitten’s global internal database.
+
+    Unlike Kitten’s internal and app databases, this database is scoped to the Kitten instance, *not* to the app that Kitten is serving.
+
+    You should not need to access this directly. (That’s two underscores to – uhum – underscore the fact. 👻)
+  */
+  __db: import('../GlobalInternalDatabase.ts').GlobalInternalDatabaseType
+
+  /**
+    Represents an uploaded file.
+
+    @see https://kitten.small-web.org/tutorials/multipart-forms-and-file-uploads/
+  */
+  Upload: typeof Upload
+
+  /**
+    Uploads sent to `POST` routes via `<input type='file'>` in your pages are automatically saved in your project’s uploads folder. Kitten also automatically assigns them unique IDs, maps to IDs to their locations on disk in its internal database (`kitten._db.uploads`), and serves them from the `/uploads/<unique-id>` route.
+
+    You can access uploads by ID from this global reference (which, itself, is simply a reference to `kitten._db.uploads`).
+
+    The Upload objects are also available to your `POST` routes in the `request.uploads` array.
+
+    @see https://kitten.small-web.org/tutorials/multipart-forms-and-file-uploads/
+  */
+  uploads: UploadStore
+
+  /**
+    Kitten’s built-in icon set.
+
+    A subset of the Phosphor icon set by Helena Zhang and Tobias Fried as Kitten components.
+
+    @example
+    export default () => kitten.html`
+      <h1>I’m a cat! <${kitten.icons.Cat} /></h1>
+    `
+
+    @see
+    https://kitten.small-web.org/reference/#icons
+  */
+  icons: KittenIcons
+
+  /**
+    The domain or Web Number (IP Address) Kitten is running at.
+  */
+  domain: string
+
+  /**
+    The port number Kitten is running at.
+  */
+  port: number
+
+  /**
+    The unique identifier for this Kitten site/app, calculated using the base path of the source code as well as the domain and port the server is running on.
+  */
+  projectIdentifier: string
+
+  /**
+    Represents the git repository of the app that Kitten is currently serving.
+
+    Available in production mode only (when Kitten is run with PRODUCTION=true).
+
+    @remarks For internal use only.
+  */
+  appRepository?: {
+    latestCompatibleVersion?: string,
+    latestVersion?: string,
+    latestApiVersion?: number,
+    manualUpdateAvailable?: boolean,
+    originRemoteUrl?: string,
+    currentVersion?: string,
+    latestAvailableCommit?: string,
+    upgradeAppToLatestCompatibleVersion(): Promise<void>
+    upgradeAppToLatestAvailableCommit(): Promise<void>
+    updateAppToVersion(versionTag: string): Promise<void>
+    update(): Promise<void>
+    hasCompatibleAppVersion: boolean
+    canBeUpgraded: boolean
+    hasNewerApiVersion: boolean
+    upgradeOrDowngrade(versionTag: string, lowercase: boolean): 'upgrade' | 'Upgrade' | 'downgrade' | 'Downgrade' | false
+    isEqualToVersion(versionTag: string): boolean
+
+    /** Returns a configured update button component. */
+    UpdateButtonComponent(): ({type, version, small}: { type?: UpdateType, version?: string, small?: boolean }) => ReturnType<TaggedTemplate>
+
+    VersionComponent ({version, compatible, brief}: { version: string, compatible: boolean, brief: boolean}): ReturnType<TaggedTemplate>
+
+    /** Returns a configured Current app version component. */
+    CurrentAppVersionComponent(): () => ReturnType<TaggedTemplate>
+
+    /** Returns a configured All available versions component or kitten.html (it probably shouoldn’t be doing that). */
+    AllAvailableVersionsComponent(): (() => ReturnType<TaggedTemplate>) | ReturnType<TaggedTemplate>
+    displayAppVersion(): void
+  }
+
+  /**
+    Schedules and runs automatic updates of both Kitten itself and the app that Kitten is running.
+
+    Available in production mode only (when Kitten is run with PRODUCTION=true).
+
+    @remarks For internal use only.
+  */
+  automaticUpdates?: {
+    interval: number
+    intervalInHours: number
+    timeToNextCheck(): number
+    timeToNextCheckPretty(): string | number
+    start(): void
+    checkForUpdates(): Promise<void>
+    stop(): void
+  }
+
+  /**
+    Represents the currently-installed Kitten package.
+
+    Provides information about and manages updates of the package by communicating with Kitten’s deployment site (https://kittens.small-web.org).
+
+    _Note that this class does NOT manage automatic updates. For that, please see the {@link AutomaticUpdates} class._
+
+    @remarks For internal use only.
+  */
+  package: {
+    hasCompatibleVersion: boolean
+    isLatestReleaseVersion: boolean
+    isMoreRecentThanReleaseVersion: boolean
+    canBeUpgraded: boolean
+    upgrade(apiVersion?: number): void
+    update(): Promise<void>,
+    latestRecommendedVersion?: {
+      versionStamp: number,
+      gitHash: string,
+      apiVersion: number,
+      nodeVersion: string,
+      exactVersion: string,
+      buildDate: Date,
+      releaseDate: Date,
+      upload: Upload,
+      _buildDate:string,
+      _releaseDate:string
+    }
+  }
+
+  /**
+    A truncated log of the last 25 request URLs for debugging purposes.
+  */
+  requests: Array<string>
+
+  /**
+    Record of all active KittenPage instances, keyed by page ID (UUID).
+  */
+  pages: Record<string, KittenPage>
+
+  /**
+    Global Kitten event emitter.
+  */
+  events: EventEmitter
+
+  /**
+    KittenComponent class.
+
+    Extend this class to create your own stateful Kitten components.
+
+    @example
+    export default class MyComponent extends kitten.Component {
+      override html () {
+        return kitten.html`
+          What a lovely component I am! :)
+        `
+      }
+    }
+  */
+  Component: typeof KittenComponent
+
+  /**
+    KittenPage class.
+
+    Extend this class to create your custom stateful Kitten pages.
+
+    @example
+    export default class MyPage extends kitten.Page {
+      override html () {
+        return kitten.html`
+          I am a KittenPage, short and sweet!
+        `
+      }
+    }
+  */
+  Page: typeof KittenPage
+
+  /**
+    Kitten HTML tagged template string with support for Kitten components and JavaScript string interpolation.
+
+    This is the primary means of authoring HTML in Kitten.
+
+    @example
+    // A simple Kitten page (e.g., index.page.js) that says “Happy <month name>!” and uses the built-in kitten.icons.Smiley Kitten component to display a smiley.
+    export default function () {
+      const currentMonth = new Intl.DateTimeFormat('en-IE', { month: 'long' }).format(new Date())
+      return kitten.html`
+        <h1>Happy ${currentMonth}! <${kitten.icons.Smiley} /></h1>
+      `
+    }
+
+    @see https://kitten.small-web.org/reference/#html
+  */
+  html: TaggedTemplate
+
+  /**
+    CSS tagged template.
+
+    Wraps passed string in `<style>…</style>` tags.
+
+    Useful if you want to use JavaScript variables in your CSS.
+
+    @example
+    const randomColour = ['red', 'green', 'blue'][Math.floor(Math.random()*3)]
+    const css = kitten.css`body { background-color: ${randomColour} }`
+
+    @see To include external static CSS, use CSS fragments (_.fragment.css_ files) instead. https://kitten.small-web.org/tutorials/components-and-fragments/#html-css-and-markdown-fragments
+  */
+  css: TaggedTemplate
+
+  /**
+    JS tagged template. This is a basic function that simply attaches its input to the page
+    without any escaping. It can be used to get language intelligence/syntax highlighting
+    for Alpine.js snippets in your editor (if your editor and/or language server understands
+    to display kitten.js`` tagged templates as JavaScript).
+
+    Be careful if using this as you will have to escape backticks in your code and it
+    can make your code harder to read and understand for other people.
+
+    Use for simple things only.
+
+    @param {string[]} strings - Static strings.
+    @param {[]} interpolations - Interpolated values.
+  */
+  js: TaggedTemplate
+
+  /**
+    Markdown wrapper.
+
+    Results in exactly the same thing as `` kitten.html`<markdown>…</markdown>` `` but without
+    requiring you to add the markdown tags. In a lot of ways more limited than just
+    using ``` kitten.html`` ``` with markdown tags inside it but might be nicer semantically in
+    certain cases.
+
+    @see https://kitten.small-web.org/reference/#markdown-support
+  */
+  markdown: TaggedTemplate
+
+  /**
+    Reference to the MarkdownIt instance used internally by Kitten.
+
+    Use `kitten.md.render()` and `kitten.md.renderInline()` if you need more flexibility than what the other Markdown features in Kitten allow.
+
+    @example
+    <!-- Safely display comments on a blog that contain Markdown syntax. -->
+    <ul>
+      ${kitten.db.comments.map(comment => kitten.html`
+        <li>
+          <p>${kitten.safelyAddHtml(kitten.md.render(comment.message))}</p>
+          <p class='nameAndDate'>${comment.name} (${new Date(comment.date).toLocaleString()})</p>
+        </li>
+      `)}
+    </ul>
+  */
+  md: MarkdownIt
+
+  /**
+    Slugify a string.
+
+    @example
+    kitten.slugify('I ♥ Dogs') // i-love-dogs
+
+    @see https://github.com/sindresorhus/slugify
+  */
+  slugify: typeof Slugify
+
+  /**
+    YAML parser and serialiser.
+
+    Used internally by the Markdown loader for parsing YAML frontmatter but also exposed here for you to use in your own apps.
+
+    @example
+    kitten.yaml.parse(`
+      YAML:
+        - A human-readable data serialization language
+        - https://en.wikipedia.org/wiki/YAML
+    `)
+
+    @see https://github.com/eemeli/yaml
+  */
+  yaml: typeof Yaml
+
+  /**
+    Kitten Crypto API
+
+    Crypographic functions used by Kitten and available for you to use in your own apps.
+
+    Remember that secrets that belong to people should only be handled on the client. The exact same API is available to use in the browser.
+
+    @example
+    // Client side use
+    <script type='module' async>
+      import { createKeys } from '/🐱/library/crypto-1.js'
+
+      async function generateSecret(event, secretView, copySecretButtonPlaceholder) {
+        const keys = await createKeys('${domain}')
+        const secret = keys.private.ed25519.asString
+      }
+    </script>
+  */
+  crypto: {
+    /**
+      Converts Uint8Array to hex string.
+
+      From @noble/hashes.
+
+      @see https://github.com/paulmillr/noble-hashes#utils
+    */
+    bytesToHex: (uint8a: Uint8Array) => string
+
+    /**
+      Decrypts passed encoded ciphertext using shared key.
+
+      From micro-aes-gcm.
+
+      @see https://www.npmjs.com/package/micro-aes-gcm
+    */
+    decrypt: (sharedKey: Uint8Array, encoded: string | Uint8Array) => Promise<Uint8Array>
+
+    /**
+      Convert emoji string to secret bytes.
+
+      @see https://kitten.small-web.org/reference/#cryptographic-properties
+    */
+    emojiStringToSecret: (emojiString: string) => Uint8Array
+
+    /**
+      Encrypts passed plain text using the shared key.
+
+      From micro-aes-gcm.
+
+      @see https://www.npmjs.com/package/micro-aes-gcm
+    */
+    encrypt: (sharedKey: Uint8Array, plaintext: string | Uint8Array) => Promise<Uint8Array>
+
+    /**
+      Encrypts a message for a domain.
+
+      @param message Message to encrypt
+      @param ourPrivateKey Our emoji-encoded private key
+      @param domain The domain to encrypt the message for
+      @returns Hex-encoded encrypted message.
+
+      @remarks While this function can be used on the server, all encryption should be carried out on the client as the server should never have person’s secrets.
+    */
+    encryptMessageForDomain: (message: string, ourPrivateKey: string, domain: string) => Promise<string>
+
+    /**
+      Converts ed25519 private / public keys to Curve25519 and calculates Elliptic Curve Diffie Hellman (ECDH) with X25519. Conforms to RFC7748.
+
+      From `@noble/ed25519` (v1).
+
+      @see https://github.com/paulmillr/noble-ed25519/tree/v1#getsharedsecretprivatekey-publickey
+    */
+    getSharedSecret: (
+      privateKey: Uint8Array | string | bigint | number,
+      publicKey: Uint8Array | string
+    ) => Promise<Uint8Array>
+
+    /**
+      Converts hex string to Uint8Array .
+
+      From `@noble/hashes`.
+
+      @see https://github.com/paulmillr/noble-hashes#usage
+    */
+    hexToBytes: (hex: string) => Uint8Array
+
+    /**
+      Produces cryptographically secure random Uint8Array of length bytes.
+
+      From `@noble/hashes`.
+
+      @see https://github.com/paulmillr/noble-hashes#utils
+    */
+    randomBytes: (bytesLength?: number) => Uint8Array
+
+    /**
+      Generates cryptographically random 32-byte token and coverts it to hexadecimal representation.
+
+      Use anywhere you need a secret token (domain token, webhook secret, etc.)
+    */
+    random32ByteTokenInHex: () => string
+
+    /**
+      Convert secret bytes to emoji string.
+
+      @see https://kitten.small-web.org/reference/#cryptographic-properties
+    */
+    secretToEmojiString: (secret: Uint8Array) => string
+
+    /**
+      Calculates the shared secret for a domain using the domain’s public key and our private key.
+
+      Part of the Meow Protocol.
+    */
+    sharedSecretForDomain: (domain: string, ourPrivateKey: string) => Promise<Uint8Array>
+
+    /**
+      Signs message with privatek key and returns EdDSA signature.
+
+      From `@noble/ed25519` (v1).
+
+      @param message Message (not message hash) which would be signed
+      @param privateKey Private key which will sign the hash
+      @returns EdDSA signature. You can consume it with the `Signature.fromHex()` method: `Signature.fromHex(ed25519.sign(hash, privateKey))`
+
+      @see https://github.com/paulmillr/noble-ed25519/tree/v1#signmessage-privatekey
+    */
+    sign: (message: Uint8Array | string, privateKey: Uint8Array | string) => Promise<Uint8Array>
+
+    /**
+      Verifies signature.
+
+      From `@noble/ed25519` (v1).
+
+      Compatible with [ZIP215](https://zips.z.cash/zip-0215), accepts:
+
+      ```
+      0 <= sig.R/publicKey < 2**256 (can be >= curve.P aka non-canonical encoding)
+      0 <= sig.s < l
+      ```
+
+      @param sig Signature returned by {@link sign} function
+      @param message Message to be verified
+      @param publicKey Public key (e.g., as generated from privateKey using it’s getPublicKey method)
+
+      @see https://github.com/paulmillr/noble-ed25519/tree/v1#verifysignature-message-publickey
+
+      @remarks Not compatible with RFC8032 because rfc encorces canonical encoding of R/publicKey. There is no security risk in ZIP behavior, and there is no effect on honestly generated signatures. For additional info about verification strictness, check out It’s [255:19AM](https://hdevalence.ca/blog/2020-10-04-its-25519am/).
+    */
+    verify: (
+      sig: Uint8Array | string | Signature,
+      message: Uint8Array | string,
+      publicKey: Uint8Array | string | Point
+    ) => Promise<boolean>
+  }
+
+  /**
+    Kitten utility functions and properties.
+  */
+  utils: {
+    /**
+      Currently contains the same extensions as in {@link DYNAMIC_ROUTE_EXTENSIONS}.
+    */
+    ALL_ROUTE_EXTENSIONS: Array<string>
+
+    /**
+      Extensions that Kitten treats as backend routes.
+
+      Currently: `socket.js` and `socket.ts`.
+
+      @see https://kitten.small-web.org/tutorials/htmx-the-htmx-web-socket-extension-and-socket-routes/
+    */
+    BACKEND_EXTENSIONS: Array<string>
+
+    /**
+      Extensions that don’t map to routes but are elements that can be imported and used in routes.
+
+      @example
+      `component.js`, `component.ts`, `fragment.html`, `fragment.css`, `layout.js`, `layout.ts`
+
+      @see https://kitten.small-web.org/tutorials/components-and-fragments/
+    */
+    DEPENDENCY_EXTENSIONS: Array<string>
+
+    /**
+      File extensions Kitten considers to be dynamic (not static) routes.
+
+      Currently, this includes all extensions in {@link BACKEND_EXTENSIONS} and {@link FRONTEND_EXTENSIONS}.
+    */
+    DYNAMIC_ROUTE_EXTENSIONS: Array<string>
+
+    /**
+      Extensions for files that hold front-end functionality.
+
+      Currently: `page.js`, `page.ts`, and `page.md`.
+
+      @remarks For internal use only.
+    */
+    FRONTEND_EXTENSIONS: Array<string>
+
+    /**
+      Extensions Kitten maps to standard HTTP routes.
+
+      @example
+      `get.js`, `post.js`, `put.js`, `head.js`, etc.
+
+      @see https://kitten.small-web.org/reference/#http-routes
+
+      @remarks For internal use only.
+    */
+    HTTP_METHODS: Array<string>
+
+    /**
+      File extensions that that Kitten treats as static files.
+
+      Currently: `html` and `htm`.
+
+      @see https://kitten.small-web.org/tutorials/static-html/
+
+      @remarks For internal use only.
+    */
+    STATIC_ROUTE_EXTENSIONS: Array<string>
+
+    /**
+      Given a file path, derives the unique class name for its route.
+
+      @remarks For internal use only.
+    */
+    classNameFromFilePath: (filePath: string, basePath: string) => string
+
+    /**
+      Converts a route in the form of, e.g., `'/some_thing/with/underscores-and-hyphens'` to `'SomeThingWithUnderscoresAndHyphensPage'`.
+
+      @remarks For internal use only.
+    */
+    classNameFromRoutePattern: (pattern: string) => string
+
+    /**
+      db namespace for JSDB database-related utility functions.
+    */
+    db: {
+      /**
+        Given a JSDB change string, returns the dot-separated keypath of the changed property.
+      */
+      keypathForChange(change: string): string
+    }
+
+    /**
+      Inverse of encodeFilePath. Used when we want to avoid double escaping of file paths.
+    */
+    decodeFilePath: (filePath: string) => string
+
+    /**
+      Since Polka does not handle unicode in paths correctly (see https://github.com/lukeed/polka/issues/187), we have to split the file path and URI encode each component ourselves.
+    */
+    encodeFilePath: (filePath: string) => string
+
+    /**
+      Display error in console and exit process.
+
+      @remarks For internal use only.
+    */
+    exitWithError: (message: string) => void
+
+    /**
+      Routes sorted by category based on their extensions (e.g., .page.js, post.js, etc.)
+
+      Routes in the different categories are served differently by Kitten.
+
+      @see https://kitten.small-web.org/reference/#valid-file-types
+
+      @remarks For internal use only.
+    */
+    extensionCategories: {
+      backendRoutes: Array<string>
+      frontendRoutes: Array<string>
+      dependencies: Array<string>
+      dynamicRoutes: Array<string>
+      staticRoutes: Array<string>
+      allRoutes: Array<string>
+    }
+
+    /**
+      Returns the complete extension (e.g., page.js not just .js) of the passed file path. Works with any number of extensions, returning the last two without a dot at the start.
+    */
+    extensionOfFilePath: (filePath: string) => string
+
+    /**
+      Determines which places the server should listen at.
+    */
+    getDomainsAndPort: (options: ServerOptions) => Promise<{ domains: string[]; port: number | boolean }>
+
+    /**
+      Returns unique project identifier based on the path of the project. This can be used as the name of a directory that is certain to be unique for this project.
+    */
+    getProjectIdentifierForDomain: (domain: string, port: number) => string
+
+    /**
+      Kitten app path, formatted in a way that works regardless of whether Kitten was invoked using the `kitten` command from the bundled distribution or via _bin/kitten_ from source.
+    */
+    kittenAppPath: string
+
+    /**
+      Run passed command (either `'ci'` or `'install'`) on the given module path.
+    */
+    npm: (command: 'ci' | 'install', modulePath: string) => boolean
+
+    /**
+      Derives the route pattern for the passed file path based on the base path.
+    */
+    routePatternFromFilePath: (filePath: string, basePath: string) => string
+
+    /**
+      Runs npm ci on the passed module path.
+    */
+    runNpmCiOnModulePath: (modulePath: string) => void
+
+    /**
+      Calculates the base path used by the Kitten server to find files in the served app.
+    */
+    setBasePath: (workingDirectory: string, pathToServe: string) => string
+
+    /**
+      A regular expression that matches all extensions supported by Kitten.
+
+      Currently, this includes all extensions in {@link DYNAMIC_ROUTE_EXTENSIONS} and {@link STATIC_ROUTE_EXTENSIONS}.
+
+      @remarks For internal use only.
+    */
+    supportedExtensionsRegExp: string
+  }
+
+  /**
+    Constants for well-known/supported client-side libraries meant to be referenced in page routes.
+
+    Usually the file names held by these properties will refer to the minified version when `process.env.PRODUCTION` is `true` and non-minified versions otherwise (in development mode, so we can get more meaningful stack traces).
+
+    @see https://kitten.small-web.org/reference/#kitten-client-side-libraries
+  */
+  libraries: {
+    htmx: string
+    htmxIdiomorph: string
+    htmxWebSocket: string
+    alpineJs: string
+    water: string
+  }
+
+  /**
+    Special page slot names (constants) that can be used as targets of `<content for='…'>` tags.
+
+    @example
+    export default () => kitten.html`
+      <markdown>
+        # Special page slots
+
+        This is just regular page content.
+      </markdown>
+      <!-- Whereas this will be added to the <head>…</head> -->
+      <content for='${kitten.page.head}'>
+        <title>Special page slots</title>
+        <link rel='icon' href='/favicon.ico'>
+      </content>
+    `
+    
+    @see https://kitten.small-web.org/tutorials/special-page-slots/
+  */
+  page: {
+    html: 'HTML'
+    head: 'HEAD'
+    startOfBody: 'START_OF_BODY'
+    beforeLibraries: 'BEFORE_LIBRARIES'
+    afterLibraries: 'AFTER_LIBRARIES'
+    endOfBody: 'END_OF_BODY'
+
+    // Common aliases/miscapitalisations added at runtime to be more forgiving
+    // during authoring. Optional because they are set after the base object
+    // literal is first assigned in `globals.ts`.
+    HTML?: 'HTML'
+    Html?: 'HTML'
+    HEAD?: 'HEAD'
+    Head?: 'HEAD'
+    START_OF_BODY?: 'START_OF_BODY'
+    StartOfBody?: 'START_OF_BODY'
+    startofbody?: 'START_OF_BODY'
+    AFTER_LIBRARIES?: 'AFTER_LIBRARIES'
+    AfterLibraries?: 'AFTER_LIBRARIES'
+    afterlibraries?: 'AFTER_LIBRARIES'
+    END_OF_BODY?: 'END_OF_BODY'
+    EndOfBody?: 'END_OF_BODY'
+    endofbody?: 'END_OF_BODY'
+  }
+
+  /**
+    Use this method to add untrusted markup to your page safely.
+
+    You can customise the list of allowed tags by providing a list of ones to add to them (e.g., `['img']`) or by replacing it altogether with your own list by passing `false` as the last argument.
+
+    @example
+    <!-- Safely display comments on a blog that contain Markdown syntax. -->
+    <ul>
+      ${kitten.db.comments.map(comment => kitten.html`
+        <li>
+          <p>${kitten.safelyAddHtml(kitten.md.render(comment.message))}</p>
+          <p class='nameAndDate'>${comment.name} (${new Date(comment.date).toLocaleString()})</p>
+        </li>
+      `)}
+    </ul>
+
+    @remarks
+    Kitten escapes interpolated content by default so you’re safe from injection attacks by default. It also does not give you direct access to a `dangerouslySetInnerHTML()` style method on purpose. If you _really, really_ want to dangerously add HTML, you can do so by returning an array from your interpolation. e.g., `` `kitten.html`${[ thisContentWontBeSanitised ]}` ``. Needless to say, only ever do this with trusted content and then only if you absolutely must.
+  */
+  safelyAddHtml: SanitisationFunction
+
+  /**
+    This is a wrapper around sanitize-html that you can use to only allow whitelisted HTML in strings.
+
+    @example
+    // Kitten’s `kitten.safelyAddHtml()` function uses `sanitise()`.
+    kitten.safelyAddHtml = (untrustedContent, allowedTags = [], concat = true) => kitten.html`${[ sanitise(untrustedContent, allowedTags, concat) ]}`
+
+    @see https://github.com/apostrophecms/apostrophe/tree/main/packages/sanitize-html
+  */
+  sanitise: SanitisationFunction
+
+  /**
+    Reference to `WebSocket` class from ws.
+
+    Use it to create your own server-to-server WebSocket connections.
+
+    @see https://github.com/websockets/ws
+
+    @example
+    // Detail of _updates.socket.js_ route in Kitten’s Streamiverse example.
+    stream = new kitten.WebSocket('wss://streamiverse.small-web.org/stream.socket')
+
+    stream.addEventListener('message', event => {
+      const message = JSON.parse(event.data)
+      if (message.event === 'update') {
+        const post = JSON.parse(message.payload)
+
+        console.info(`  🐘 Got an update from ${post.account.username}!`)
+      }
+    })
+  */
+  WebSocket: typeof KittenWebSocket
+
+  /**
+    Kitten is run by default to silence Node’s deprecation warnings (you can turn them on by running `kitten` with `SHOW_DEPRECATION_WARNINGS=true`) as we use experimental features and we don’t what the console output to be noisy.
+
+    Any deprecation warnings that are encountered are kept here even if they’re not shown in the console.
+
+    @see https://codeberg.org/kitten/app/src/branch/main/suppress-experimental.cjs
+  */
+  deprecationWarnings: Array<string>
+
+  /**
+    File system paths of important Kitten resources.
+  */
+  paths: {
+    /**
+      Absolute local system path for binaries (~/.local/bin)
+    */
+    BINARY_HOME: string,
+
+    /**
+      Path to Kitten’s own “binary” (shell script that starts the Node runtime and loads the loader and main process bundles).
+    */
+    KITTEN_BINARY_PATH: string,
+
+    /**
+      The path where a person’s data files should be stored according to the XDG Base Directory Specification (if the `XDG_DATA_HOME` environment variable is set, otherwise, falls back to _~/.local/share_).
+
+      @see https://specifications.freedesktop.org/basedir/latest/
+    */
+    DATA_HOME: string,
+
+    /**
+      The small-tech.org namespace within the person’s data home folder.
+
+      All Small Technology Foundation tools, including Kitten, live under this namespace.
+    */
+    SMALL_TECH_DATA_HOME: string,
+
+    /**
+      The home directory of Kitten’s own data.
+
+      Set to {@link SMALL_TECH_DATA_HOME}/kitten
+    */
+    KITTEN_DATA_HOME: string,
+
+    /**
+      The directory that hosts the Kitten app itself.
+
+      Set to {@link KITTEN_DATA_HOME}/app
+    */
+    KITTEN_APP_DIRECTORY_PATH: string,
+
+    /**
+      The directory containing Kitten’s own web app (settings, initial secret creation, etc.)
+
+      Set to {@link KITTEN_APP_DIRECTORY_PATH}/web
+    */
+    KITTEN_WEB_APP_DIRECTORY_PATH: string,
+
+    /**
+      The directory that houses all the TLS certificate information for Kitten servers (both local and globally-accessible ones).
+
+      Stores certificate data managed by \@small-tech/auto-encrypt (Let’s Encrypt) and \@small-tech/auto-encrypt-localhost, as abstracted by \@small-tech/https.
+
+      @see https://codeberg.org/small-tech/https
+    */
+    KITTEN_TLS_DIRECTORY: string,
+
+    /**
+      Contains certificate data for localhost domains.
+
+      As managed by Auto Encrypt Localhost (\@small-tech/auto-encrypt-localhost).
+
+      @see https://codeberg.org/small-tech/auto-encrypt-localhost
+    */
+    KITTEN_TLS_LOCAL_CERTIFICATE_DIRECTORY: string,
+
+    /**
+      Contains certificate data for production domains (and Web Numbers/IP Addresses).
+
+      As managed by Auto Encrypt (\@small-tech/auto-encrypt).
+
+      @see https://codeberg.org/small-tech/auto-encrypt
+    */
+    KITTEN_TLS_GLOBAL_CERTIFICATE_DIRECTORY: string,
+
+    /**
+      Location under /tmp that Kitten stores its temporary files.
+
+      Currently /tmp/small-tech.org/kitten
+    */
+    KITTEN_TEMP_DIRECTORY: string,
+
+    /**
+      Location of runtime.tar.xz, the archived version of Kitten’s runtime.
+
+      (Currently, Node.js).
+    */
+    KITTEN_TEMP_RUNTIME_ARCHIVE_PATH: string,
+
+    /**
+      The same-device temp directory is guaranteed to be on the same device as the rest of Kitten’s data so you can use, for example, `fs.rename` on it while you may not be able to do so with `KITTEN_TEMP_DIRECTORY`, which might be on a different partition.
+    */
+    KITTEN_SAME_DEVICE_TEMP_DIRECTORY: string,
+
+    /**
+      This directory holds Kitten’s runtime (currently, Node.js)
+    */
+    KITTEN_RUNTIME_DIRECTORY: string,
+
+    /**
+      The directory that holds the binary of Kitten’s runtime (currently, Node.js)
+    */
+    KITTEN_RUNTIME_BIN_DIRECTORY: string,
+
+    /**
+      The directory that holds the data for all projects (sites/apps) that have been served on this device.
+
+      Subfolders within this directory are named based on {@link utils.getProjectIdentifierForDomain}.
+    */
+    KITTEN_DATA_DIRECTORY: string,
+
+    /**
+      Kitten has two different types of internal databases: a global one for Kitten itself and separate internal databases for every project.
+
+      This is path for the global one.
+
+      @remarks For internal use only.
+    */
+    KITTEN_GLOBAL_INTERNAL_DATABASE_DIRECTORY: string,
+
+    /**
+      The directory that kitten projects are deployed to when you use the `kitten deploy` command.
+    */
+    KITTEN_DEPLOYMENTS_DIRECTORY: string,
+
+    /**
+      The directory that the repositories are cloned to when you use the `kitten run` command to clone and run a Kitten project based on the HTTPS git URL of the project’s repository.
+    */
+    KITTEN_CLONES_DIRECTORY: string,
+
+    /**
+      The path where a person’s configuration files should be stored according to the XDG Base Directory Specification (if the `XDG_CONFIG_HOME` environment variable is set, otherwise, falls back to _~/.config_).
+
+      @see https://specifications.freedesktop.org/basedir/latest/
+    */
+    CONFIG_HOME: string,
+
+    /**
+      Path of the systemd “user” (we don’t use that term in Small Tech as it’s an othering) directory.
+
+      Defaults to _~/.config/systemd/user_.
+    */
+    SYSTEMD_USER_DIRECTORY: string,
+
+    /**
+      Path to Kitten’s systemd unit.
+
+      Set to {@link SYSTEMD_USER_DIRECTORY}/kitten.service
+    */
+    KITTEN_SYSTEMD_UNIT_PATH: string
+
+    // From Kitten’s src/lib/globals.ts
+
+    /**
+      The app data directory for the current app (site/project).
+
+      Use when opening your database in a Database App Module to get the path to it.
+
+      @example
+      JSDB.open(
+        path.join(kitten.paths.APP_DATA_DIRECTORY, 'db'),
+        {
+          compactOnLoad, 
+          classes: [
+            Database,
+            Kitten
+          ]
+        }
+      )
+
+      @see https://kitten.small-web.org/tutorials/database-app-modules/
+      @see https://codeberg.org/kitten/app/src/branch/main/examples/database-app-module/app_modules/database/database.js#L46
+    */
+    APP_DATA_DIRECTORY: string
+
+    /**
+      The location of file uploads for the current app.
+
+      Set to {@link APP_DATA_DIRECTORY}/uploads
+    */
+    APP_UPLOADS_DIRECTORY: string
+
+    /**
+      The location of REPL data (REPL history) for the current app.
+
+      Set to {@link APP_DATA_DIRECTORY}/repl
+    */
+    APP_REPL_DIRECTORY: string
+  }
+
+  /**
+    For internal use by Kitten’s web app.
+  */
+  deploy: Function
+
+  /**
+    Kitten’s built-in components.
+
+    Contains both the stateless (function) and stateful (class) variants of each built-in component.
+  */
+  components: {
+    /**
+      Stateless copy-to-clipboard button component.
+    */
+    copyButton: typeof import('../lib/components/stateless/copyButton.component.ts')['default']
+
+    /**
+      Stateful copy-to-clipboard button component.
+    */
+    CopyButton: typeof KittenComponent
+  }
+
+  /**
+    Helper method: Returns value by applying keypath to passed object.
+
+    @remarks For internal (debug/REPL) use only.
+  */
+  ___valueAtKeypath: (object: any, keypath: string) => any
+
+  /**
+    Easily listen for events on JSDB tables from the Kitten Interactive Shell (REPL).
+
+    @remarks For debug-time use only. It does not remove listeners so should not be used in authored code.
+  */
+  $showEventsOnTable: (tableName: string, showPersistedChange?: boolean) => void
+
+  /**
+    The names of the tables in your custom JSDB database (`kitten.db`).
+
+    @remarks For debug-time use only (e.g., from the Kitten Interactive Shell/REPL).
+  */
+  readonly $tables: Array<string>
+
+  /**
+    Kitten’s logger.
+
+    Separates logs out by sections that can be enabled using the `LOG` environment variable (e.g. `LOG=event,lifecycle kitten` or `LOG='*' kitten`)  or toggled at runtime via `kitten.log.all()`, `kitten.log.none()`, and `kitten.log.only(…)`.
+  */
+  log: Log
+
+  /**
+    Tracks whether the Kitten REPL (interactive shell) is active.
+
+    Used by loggers to emit additional information while the REPL is active.
+
+    @remarks For internal use only.
+  */
+  __replIsActive: boolean
+}
+
+declare global {
+  /**
+    Kitten’s global `kitten` object.
+
+    The most common properties you’ll be using in daily authoring include:
+
+      - {@link html}          - Write HTML with component and string interpolation support.
+      - {@link db}            - Reference your site/apps custom JSDB database.
+      - {@link Page}          - Extend this class to create your own Kitten pages.
+      - {@link Component}     - Extend this class to create your own stateful Kitten components.
+      - {@link safelyAddHtml} - Use when adding untrusted content to your pages.
+      - {@link crypto}         - Kitten’s cryptographic library.
+      - {@link icons}         - Kitten’s built-in icon library.
+
+    @see https://kitten.small-web.org/tutorials/
+  */
+  var kitten: kitten
+
+  /**
+    Deprecation warnings encountered by Kitten (silenced by default).
+
+    @see https://codeberg.org/kitten/app/src/branch/main/suppress-experimental.cjs
+  */
+  var deprecationWarnings: Array<string>
+}
+
+export {}