@jotsu/devtools

Floating developer tools for generated Jotsu applications. The package owns the Workbench launcher, Tell Jotsu review UI, Context explorer, Database and Designs screens, AI Artifacts browsing, the Markdown document reader, and workflow activity, history, and manual-run controls. Tool links navigate to app-owned routes. Portable MCP inspection and database query parameter helpers live in this package. Templates and shared capability overlays retain routes, authentication, data access, and workflow execution adapters.

Install

npm install @jotsu/devtools react react-dom

The package is ESM and requires React 19.1.1 or later within React 19. It ships compiled JavaScript, TypeScript declarations, and CSS; consumers do not need to compile Tailwind or scan package source. The host supplies shadcn-style raw HSL color variables (--background, --foreground, --card, --border, --input, --muted, --muted-foreground, --primary, --primary-foreground, --popover, --popover-foreground, --accent, --accent-foreground, --destructive, --ring) and a CSS length for --radius.

import { JotsuDevtools } from '@jotsu/devtools';
import '@jotsu/devtools/styles.css';

export function DeveloperTools({ enabled, pathname, navigate }: {
    enabled: boolean;
    pathname: string;
    navigate: (href: string) => void;
}) {
    // The host sets enabled only after checking development mode and authentication.
    return enabled ? <JotsuDevtools pathname={pathname} onNavigate={navigate}
        links={[{ href: '/context', label: 'Context' }]} /> : null;
}

The package renders tools; it does not create routes or authorize their endpoints.

Integration

The host mounts JotsuDevtools once at the application root after checking runtime ENVIRONMENT === 'development' and authentication. The shared template adapter loads it lazily, imports @jotsu/devtools/styles.css, and supplies:

• links: app-owned { label, href, children? } navigation entries.
• pathname: current location, used for active links and review context.
• onNavigate: optional client-side navigation callback; links also have native hrefs.
• review: validated { appId, jotsuOrigin } configuration or null.

@jotsu/devtools/review exports the existing review-session utilities and JotsuReviewSessionBridge. The bridge captures incoming review context before sign-in; it renders no UI. Tell Jotsu appears in Workbench only for an active review session. Feedback uses the trusted destination fragment and preserves the current route and optional semantic element.

The launcher uses the host's semantic CSS variables and theme radius. Its compiled Tailwind styles use jdt- selectors, with no global reset. Internal controls follow the shared shadcn treatments; Radix provides popover focus and dismissal behavior. React and React DOM are peer dependencies. Forms use React Hook Form and Zod; icons use Phosphor. TypeScript, PostCSS, and Tailwind compile the distributable.

Context explorer

@jotsu/devtools/context exports ContextExplorer, its source/client types, and createContextClient. The host supplies source metadata and a client; the HTTP adapter accepts explicit same-origin source and toolDetail endpoint URLs. The component loads sources independently, cancels abandoned requests, supports retries, and displays tools, resources, prompts, Markdown help, and copyable schemas. Load @jotsu/devtools/styles.css alongside the screen, including when the launcher is disabled. Markdown uses the approved react-markdown and remark-gfm packages.

@jotsu/devtools/server exports the MCP inspection helpers, including loadMcpCapabilitiesWithFetch and loadMcpToolDetailWithFetch. Callers provide authenticated fetch adapters and tokens. These helpers are not imported by the browser entry points. Templates retain the route loaders, account discovery, authentication, authorization, and Cloudflare bindings.

Database screens

@jotsu/devtools/database exports DatabaseCatalog and DatabaseTable. The host supplies loader data, route paths, navigation callbacks, and pending navigation state. Both screens use the package stylesheet. They have no router or D1 dependency.

Catalog filtering updates the host URL. The table screen preserves URL sorting, pagination, the legacy rows:<table> parameter, and per-table row-count preferences. Explicit URL row counts take precedence over browser storage. Storage failures do not prevent navigation. The host supplies base paths without query strings and the table screen receives the current search string separately.

Database data types and query parameter helpers are also exported from @jotsu/devtools/server for use by loaders without importing browser components. shared/database retains SQL, metadata discovery, table visibility rules, and D1 bindings. Route loaders retain authentication and HTTP error responses.

Designs screen

@jotsu/devtools/designs exports DesignPresets and its catalog item/props types. The host supplies catalog data, loading/errors, selected and pending preset names, and select/reset/retry callbacks. The package owns search, preview cards, image fallbacks, and status UI; it does not fetch registry assets or change global theme variables. Load the package stylesheet with the screen.

The shared app route owns authenticated registry actions and temporary theme application. Previews last for the document's lifetime, survive client navigation, and disappear on reload. Reset removes the temporary style and ignores any pending preview response. Presets are not saved as application configuration.

AI Artifacts

@jotsu/devtools/artifacts exports ArtifactLibrary, ArtifactReader, and their metadata/props types. The library receives discovered document metadata and an onNavigate callback. It owns search, pinned context, category grouping, and Overview-first sorting. Links retain native new-tab behavior.

ArtifactReader supplies the back link around host-rendered content. The templates compose it with the packaged Markdown reader also used by Docs. Hosts supply libraryHref, navigation, and children; both screens use the package stylesheet. File discovery, authorization, route loaders, and missing-document responses remain app-owned.

Document reader

@jotsu/devtools/documents exports MarkdownDocumentView and its props type. The host supplies Markdown content and optional showTitle (defaults to true). The reader owns GFM tables/task lists, heading anchors, the table of contents, and lazy Mermaid rendering. It uses native fragment links and has no router dependency. Load the package stylesheet on each reader route, even with the launcher disabled.

Mermaid uses strict security mode and host theme colors, updates on light/dark changes, and shows source text with an error when rendering fails. Document loading, authorization, page layouts, metadata, and 404 responses remain app-owned.

Mermaid’s published declarations reference type-fest without installing it; the package keeps it as a development dependency for strict TypeScript checks. It is not part of the public reader API.

Workflow activity

@jotsu/devtools/workflow exports WorkflowActivityPanel and its event/props types. The host supplies its event stream and selected instanceId (or null). The panel filters to that run, groups step updates, and displays lifecycle events, elapsed time, failures, and expandable input/output. It owns the running-step clock and stops it when no steps are running or the panel unmounts. Load the package stylesheet.

WorkflowLatestRun displays the host-selected instance, status, errors, and output. WorkflowHistory receives instances, clearing, clearError, and onClear. It owns the history table and accessible clear confirmation; the host performs the action, reports failures, and supplies refreshed instances after success.

WorkflowManualRun receives controlled JSON text, onChange, starting, error, and an async onRun callback. It owns the CodeMirror editor, JSON-object validation, and submission/error states. Blank input becomes {}; valid input is parsed before calling the host. The app retains per-app input persistence.

The application retains execution, authenticated WebSocket/SSE connections, loader data, and the authenticated history-clear action. The package panel makes no requests and does not import runtime or worker types.

Development and packaging

From the repository root:

npm ci --prefix packages/devtools
npm run typecheck --prefix packages/devtools
npm run test:devtools
make pack-devtools
make materialize-internal-app WORK_ROOT=build/devtools-validation
make zip-internal-app WORK_ROOT=build/devtools-validation

Use a separate WORK_ROOT while an app is running. Materialization and ZIP creation recreate the selected workspace.

Both base templates pin the published npm dependency and its lockfile; product overlays inherit it. Generated apps install @jotsu/devtools from npm with npm ci. Composition does not build local package source or include a vendor tarball.

To test unpublished package changes in an isolated materialized app, run make pack-devtools, then install the resulting tarball explicitly:

npm install --prefix build/devtools-validation/internal-app ./build/packages/jotsu-devtools-0.1.0.tgz

This override is for the disposable validation workspace. After publishing a new version, update both base templates' dependency pins and lockfiles and validate all seven composed templates before shipping their archives.

Public exports are @jotsu/devtools, @jotsu/devtools/review, @jotsu/devtools/context, @jotsu/devtools/database, @jotsu/devtools/designs, @jotsu/devtools/artifacts, @jotsu/devtools/documents, @jotsu/devtools/server, @jotsu/devtools/workflow, and @jotsu/devtools/styles.css. The package has no application aliases, generated route types, or global Env dependencies. Templates retain authentication, authorization, runtime bindings, and route declarations.

Preparing an npm release

Use Node.js 24 and npm 11 for repository development and release checks. Update the package version and lockfile for each release, then commit the release inputs. From the repository root, run:

npm ci --prefix packages/devtools
npm run release:devtools:prepare

The command requires committed package/release inputs, runs typecheck, package behavior tests, and a relocated consumer installation/TypeScript smoke test. It packs a fresh isolated build, checks the archive contents, and runs npm publish --dry-run. It does not upload the package or change registry state.

Outputs live under build/releases/devtools/<version>/: the .tgz, a .sha256 checksum, and release.json containing the source commit, archive hash, dry-run result, and npm authentication status. Authentication failure does not invalidate the local artifact, but prevents actual publication.

Publishing to npm

Run these commands from the repository root. The examples use 0.1.0; replace that version in paths and commands for later releases.

1. Sign in with an npm account authorized to publish packages under @jotsu:

npm login --registry https://registry.npmjs.org
npm whoami --registry https://registry.npmjs.org

If whoami returns 401, resolve the npm login before publishing. A successful login identifies the account but does not verify its @jotsu publish permissions.

2. Commit the release inputs and run the preparation steps above. Review build/releases/devtools/0.1.0/release.json, including its source commit, version, and dry-run result. Verify the tarball checksum:

(cd build/releases/devtools/0.1.0 && shasum -a 256 -c jotsu-devtools-0.1.0.tgz.sha256)

3. Publish the exact validated tarball publicly:

npm publish ./build/releases/devtools/0.1.0/jotsu-devtools-0.1.0.tgz --access public --registry https://registry.npmjs.org --ignore-scripts

This command uploads the package. Complete any npm authentication or second-factor prompt. --ignore-scripts preserves the already-built artifact; preparation has already run the validation checks.

4. Verify the published version and integrity:

npm view @jotsu/[email protected] version dist.integrity --registry https://registry.npmjs.org

Compare dist.integrity with dryRun.integrity in the release report. The report records preparation only; its published: false value does not change after this manual upload.

Published name/version pairs cannot be reused; increment the package version and lockfile, commit, and prepare a new artifact before another release. See the npm publish documentation. Template composition uses the published version pinned in both base templates. Publishing alone does not update those pins or already-generated applications.

License

MIT. See LICENSE.