@luckystack/docs-ui 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to `@luckystack/docs-ui` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+### Added
+
+- Initial public release as part of the LuckyStack package split.

package/CLAUDE.md

@@ -0,0 +1,55 @@
+# @luckystack/docs-ui
+
+> AI summary + function INDEX. For deep specs see `docs/` next to this file.
+
+## What this package does
+
+Dev-only API docs browser for LuckyStack. Mounts a single page (default `/_docs`) that fetches the framework's generated `apiDocs.generated.json` and renders every API endpoint grouped by page, with HTTP method, auth, rate limit, input shape, and output shape. Sync events appear alongside APIs when the type-map emitter has produced metadata for them. Ships a `customRoutes` handler — composable with `createLuckyStackServer`'s `customRoutes` option without taking ownership of the request pipeline.
+
+## When to USE this package
+
+- Local development: developer wants a Swagger-style overview of every route in the project without leaving the browser.
+- Internal developer-portal: opt-in production rendering via `enabledInProd: true` for an authenticated team-only deploy.
+- Custom branded API docs: replace the default template via the `template: DocsTemplateBuilder` option to render in a sidebar/tabs/marketing layout while reusing the JSON endpoint.
+- Inline request runner: enable `enableTryItOut` so each endpoint gets a textarea + Send button that posts against the live server using the browser session cookie.
+
+## When to NOT suggest this (yet)
+
+- Public production surface where API discoverability is sensitive — keep the default `enabledInProd: false` and don't mount in prod.
+- Replacement for `apiDocs.generated.json` itself — this package only reads/renders that file; regenerate via `@luckystack/devkit`'s type-map emitter (`npm run generateArtifacts`).
+- A non-HTTP transport — the handler is bound to `IncomingMessage` / `ServerResponse`; do not wire it directly into Socket.io handlers.
+- React-tree integration — the docs UI is a single self-contained HTML document with no React/Tailwind dependency on the client; do not import `renderDocsHtml` into the app bundle.
+
+## Function Index
+
+| Function / Export | 1-regel | Deep doc |
+|---|---|---|
+| `mountDocsUi(options?)` | Returns a `DocsRouteHandler` for `customRoutes`; serves HTML + JSON | → docs/mounting.md |
+| `renderDocsHtml(jsonPath, pageTitle, options?)` | Builds the self-contained docs HTML document | → docs/html-generation.md |
+| Type: `DocsRouteHandler` | `(req, res) => Promise<boolean>`; returns `true` when route handled | → docs/mounting.md |
+| Type: `DocsTemplateBuilder` | Custom HTML builder hook: `({ jsonPath, pageTitle, branding }) => string` | → docs/html-generation.md |
+| Type: `MountDocsUiOptions` | All mount inputs (routePath, enabledInProd, branding, template, enableTryItOut, ...) | → docs/mounting.md |
+| Type: `DocsBranding` | `{ logoUrl?, brandColor?, fontFamily? }` applied by default template | → docs/theming.md |
+| Type: `RenderDocsHtmlOptions` | `{ branding?, enableTryItOut? }` passed to `renderDocsHtml` | → docs/html-generation.md |
+| Extension field: `meta.stream` | Per-endpoint stream shape rendered in expanded detail panel | → docs/extension-fields.md |
+| Extension field: `meta.owner` | Owner string rendered in expanded detail panel | → docs/extension-fields.md |
+| Extension field: `meta.tags` | Tag badges rendered in expanded detail panel | → docs/extension-fields.md |
+| Extension field: `meta.deprecated` | Deprecation note (red) rendered in expanded detail panel | → docs/extension-fields.md |
+
+## Config keys (env vars + registerProjectConfig slots)
+
+- `NODE_ENV` (env) — when `'production'`, the route returns `404` unless `enabledInProd: true` is set.
+- `ProjectConfig.paths.generatedApiDocs` (config, resolved via `getGeneratedApiDocsPath()` from `@luckystack/core`) — default JSON file path; override per-mount via `options.apiDocsPath`.
+- No package-private env vars. All behavior is controlled via `MountDocsUiOptions`.
+
+## Peer dependencies
+
+- **Required**: `@luckystack/core` (provides `getGeneratedApiDocsPath` + `tryCatch`).
+- **Required (runtime composition)**: `@luckystack/server` — the handler is intended to be passed to `createLuckyStackServer({ customRoutes })` / `bootstrapLuckyStack({ customRoutes })`. The package itself does not import `@luckystack/server`; the dependency is on the consumer side.
+- **Required (data source)**: `@luckystack/devkit` (build-time) — emits `apiDocs.generated.json`. Without it the JSON endpoint returns a 404 with a hint to run `npm run generateArtifacts`.
+
+## Related
+
+- Architecture deep-dives: `/docs/ARCHITECTURE_API.md` (lifecycle of documented endpoints), `/docs/ARCHITECTURE_PACKAGING.md` (how the JSON artifact is produced).
+- README (consumer quickstart): `./README.md`.
+- Source: `./src/index.ts` (mount + route handling), `./src/docsHtml.ts` (embedded HTML renderer).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mathijs van Melick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @luckystack/docs-ui
+
+Dev-only API docs UI for [LuckyStack](https://github.com/ItsLucky23/LuckyStack-v2).
+
+Mounts a single page at `/_docs` that fetches the framework's generated
+`apiDocs.generated.json` and renders every API endpoint grouped by page,
+with HTTP method, auth requirements, rate limit, input shape, and output
+shape.
+
+## Install
+
+```bash
+npm install @luckystack/docs-ui
+```
+
+Peer deps (already installed if you have any other LuckyStack package):
+
+- `@luckystack/core`
+- `@luckystack/server` (the docs UI is mounted via `createLuckyStackServer`'s `customRoutes` option)
+
+## Quickstart
+
+```ts
+// luckystack/docs-ui/index.ts (overlay file — auto-imported by bootstrapLuckyStack)
+import { mountDocsUi } from '@luckystack/docs-ui';
+
+export const docsUiHandler = mountDocsUi({
+  // Title shown in the header + browser tab. Defaults to 'LuckyStack — API docs'.
+  // Pass your project name explicitly — there's no implicit lookup from
+  // ProjectConfig because consumer config shapes vary too widely to introspect.
+  pageTitle: 'My App — API docs',
+});
+```
+
+```ts
+// server/server.ts
+import { docsUiHandler } from '../luckystack/docs-ui';
+import { bootstrapLuckyStack } from '@luckystack/server';
+import { serveFile, serveFavicon } from './prod/serveFile';
+
+await (await bootstrapLuckyStack({
+  serveFile,
+  serveFavicon,
+  customRoutes: docsUiHandler,
+})).listen();
+```
+
+Open `http://localhost/_docs` and you'll see every API in your project,
+grouped by page, with one-click expand for each endpoint's input/output.
+
+## Production
+
+By default the route returns 404 in production (`NODE_ENV === 'production'`).
+Pass `{ enabledInProd: true }` to render it anyway — useful for an internal
+developer-portal deployment, but **never** safe on a public surface unless
+your APIs are intentionally documented to the world.
+
+## Options
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `routePath` | `/_docs` | Path the page is served from. The JSON is at `${routePath}/api.json`. |
+| `pageTitle` | `LuckyStack — API docs` | Shown in the header + browser tab. Pass your project name explicitly — there is no implicit lookup from `ProjectConfig`. |
+| `enabledInProd` | `false` | Set to `true` to render the docs in production. |
+| `apiDocsPath` | `getGeneratedApiDocsPath()` | Override the JSON file path. Default reads from `ProjectConfig.paths.generatedApiDocs`. |
+
+## How it works
+
+The docs page is a single embedded HTML file (no build step, no React, no
+external dependencies). It fetches `${routePath}/api.json` at runtime,
+which is served from the project's `apiDocs.generated.json` — generated by
+`@luckystack/devkit`'s type-map emitter on every dev-server reload and on
+every `npm run generateArtifacts`.
+
+The handler is a `customRoutes` predicate: it returns `true` when it
+matches the configured paths, `false` otherwise — so it composes cleanly
+with any other custom HTTP handler.
+
+## Related architecture docs
+
+- [`docs/ARCHITECTURE_API.md`](../../docs/ARCHITECTURE_API.md) — the lifecycle these endpoints document.
+- [`docs/ARCHITECTURE_PACKAGING.md`](../../docs/ARCHITECTURE_PACKAGING.md) — how `apiDocs.generated.json` is produced.
+
+## License
+
+MIT — see the [repository LICENSE](https://github.com/ItsLucky23/LuckyStack-v2/blob/master/LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+interface DocsBranding {
+    /** Logo URL shown in the header. PNG / SVG / data: URLs all accepted. */
+    logoUrl?: string;
+    /** CSS color for the header / accent (`#hex` or `rgb()` literal). */
+    brandColor?: string;
+    /** Web-safe font family for the page. */
+    fontFamily?: string;
+}
+/**
+ * Custom HTML builder. Receives the JSON-endpoint path the page should
+ * fetch from + page title + branding; returns the full HTML document
+ * (`<!doctype html>` + everything). Use to swap layout entirely (sidebar
+ * vs tabs, dark/light theme, embedded auth-token field).
+ */
+type DocsTemplateBuilder = (input: {
+    jsonPath: string;
+    pageTitle: string;
+    branding: DocsBranding;
+}) => string;
+interface MountDocsUiOptions {
+    /** Path the docs UI is served from. Default: `/_docs`. */
+    routePath?: string;
+    /**
+     * Page title shown in the header + browser tab. Defaults to
+     * "LuckyStack — API docs". Pass an explicit string to brand for a consumer.
+     */
+    pageTitle?: string;
+    /**
+     * Allow rendering the docs UI in production. Default: false. Useful only
+     * when the docs are intentionally public (developer-portal, internal-only
+     * deployment, etc.). When false, the route returns 404 in production.
+     */
+    enabledInProd?: boolean;
+    /**
+     * Override the path to `apiDocs.generated.json`. Defaults to whatever
+     * `getGeneratedApiDocsPath()` resolves to via ProjectConfig.paths.
+     */
+    apiDocsPath?: string;
+    /**
+     * Optional branding inputs (logo, brand color, font). Applied by the
+     * default template. Custom templates may ignore these.
+     */
+    branding?: DocsBranding;
+    /**
+     * Custom HTML template builder. When provided, the default `renderDocsHtml`
+     * is bypassed entirely. Use for radically different layouts (sidebar,
+     * tabs, dark mode, marketing-page-style). Receives a tested JSON path +
+     * title + branding so your template doesn't need to know about
+     * `getGeneratedApiDocsPath`.
+     */
+    template?: DocsTemplateBuilder;
+    /**
+     * Enable the inline "try-it-out" runner. When true, the default template
+     * renders a request-input box + send button per endpoint that calls
+     * `apiRequest` against the live server. Off by default because the
+     * runner needs a logged-in session.
+     */
+    enableTryItOut?: boolean;
+}
+type DocsRouteHandler = (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+/**
+ * Returns a route handler compatible with `createLuckyStackServer`'s
+ * `customRoutes` option. The handler returns `true` (response sent) when
+ * the URL matches the configured docs route, `false` otherwise.
+ */
+declare const mountDocsUi: (options?: MountDocsUiOptions) => DocsRouteHandler;
+
+export { type DocsBranding, type DocsRouteHandler, type DocsTemplateBuilder, type MountDocsUiOptions, mountDocsUi };