@small-web/kitten-types 1.1.5 → 2.0.0

package/global.d.ts

@@ -2,1104 +2,14 @@
   Kitten Types (@small-web/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>,
-  contact?: boolean
-) => 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>
-    evergreenWebUrl: string
-    hideWelcomeMessage: boolean
-    id: {
-      ed25519: {
-        asString: string
-      }
-      ssh: {
-        asString: string
-        fingerprint: string
-      }
-    }
-    packageLockFileHashes: Record<string, string>
-    path: string
-    smallWebHostDomain: string
-    stats: {
-      hits: StatsObject
-      pages: StatsObject
-      missing: StatsObject
-      referrers: StatsObject
-      serverErrors: StatsObject
-    }
-    webhookSecret: string
-  }
-  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'
+  Generated from Kitten’s TypeScript source code
+  (see kitten/ – regenerated via `npm run sync-types` in the Kitten repository).
 
-/**
-  Global `kitten` namespace.
+  Side-effect: Brings `declare global { var kitten }` into scope.
 */
-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
-    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
-
-  /**
-    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) => 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) => 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) => { domains: string[]; port: number }
-
-    /**
-      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: RegExp
-  }
-
-  /**
-    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'
-  }
-
-  /**
-    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
-}
-
-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
-}
+import './kitten/src/types/globals.d.ts'
 
-export {}
+// Also export the global namespace shape, in case an author wants to reference it explicitly (e.g. `typeof kitten`).
+export type { kitten } from './kitten/src/types/globals.d.ts'