@briancray/belte 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@briancray/belte",
-    "version": "0.2.0",
+    "version": "0.2.2",
     "type": "module",
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
     "license": "MIT",

package/src/belteResolverPlugin.ts

@@ -2,6 +2,7 @@
 import { existsSync, statSync } from 'node:fs'
 import type { BunPlugin } from 'bun'
 import { Glob } from 'bun'
+import { belteImportName } from './lib/shared/belteImportName.ts'
 import { fileStem } from './lib/shared/fileStem.ts'
 import { jsonSchemaForPromptArguments } from './lib/shared/jsonSchemaForPromptArguments.ts'
 import { log } from './lib/shared/log.ts'
@@ -111,6 +112,13 @@ export function belteResolverPlugin({
     const promptsDir = `${mcpDir}/prompts`
     const resourcesDir = `${mcpDir}/resources`
 
+    /*
+    The bare specifier the project imports belte under (canonical
+    `@briancray/belte` or a package alias). Resolved once from the project's
+    package.json and threaded into every generated module so the codegen's
+    imports resolve regardless of which install style the project uses.
+    */
+    const belteImportNameOnce = once(() => belteImportName(cwd))
     /*
     The whole-tree validation + per-leaf classification only needs to run
     once per build. Memoise the promise so the virtual manifests
@@ -120,7 +128,11 @@ export function belteResolverPlugin({
     */
     const scanPagesOnce = once(() =>
         scanPages(pagesDir).then(async (scan) => {
-            await writeRoutesDts({ cwd, pageFiles: scan.pageFiles })
+            await writeRoutesDts({
+                cwd,
+                pageFiles: scan.pageFiles,
+                importName: await belteImportNameOnce(),
+            })
             return scan
         }),
     )
@@ -176,7 +188,8 @@ export function belteResolverPlugin({
                 const relativePath = args.path.slice(rpcDir.length + 1)
                 const source = await Bun.file(args.path).text()
                 const url = rpcUrlForFile(relativePath)
-                const prepared = prepareRpcModule(source)
+                const importName = await belteImportNameOnce()
+                const prepared = prepareRpcModule(source, importName)
                 if (!prepared) {
                     throw new Error(
                         `[belte] src/server/rpc/${relativePath} has no \`export const <name> = <VERB>(...)\` — every $rpc module must declare exactly one remote function`,
@@ -196,7 +209,7 @@ export function belteResolverPlugin({
                 so page imports resolve identically on both sides.
                 */
                 if (target === 'client') {
-                    const contents = `import { remoteProxy as __belteRemoteProxy__ } from 'belte/browser/remoteProxy';
+                    const contents = `import { remoteProxy as __belteRemoteProxy__ } from '${importName}/browser/remoteProxy';
 export const ${prepared.exportName} = __belteRemoteProxy__(${JSON.stringify(prepared.verb)}, ${JSON.stringify(url)});
 `
                     return { contents, loader: 'ts' }
@@ -211,7 +224,7 @@ export const ${prepared.exportName} = __belteRemoteProxy__(${JSON.stringify(prep
                 tokenizer-driven so `GET` mentions inside strings and
                 comments are left alone.
                 */
-                const banner = `import { defineVerb as __belteDefineVerb__ } from 'belte/server/rpc/defineVerb';
+                const banner = `import { defineVerb as __belteDefineVerb__ } from '${importName}/server/rpc/defineVerb';
 `
                 return { contents: `${banner}${prepared.rewriteForServer(url)}`, loader: 'ts' }
             })
@@ -223,7 +236,8 @@ export const ${prepared.exportName} = __belteRemoteProxy__(${JSON.stringify(prep
                 const relativePath = args.path.slice(socketsDir.length + 1)
                 const source = await Bun.file(args.path).text()
                 const name = socketNameForFile(relativePath)
-                const prepared = prepareSocketModule(source)
+                const importName = await belteImportNameOnce()
+                const prepared = prepareSocketModule(source, importName)
                 if (!prepared) {
                     throw new Error(
                         `[belte] src/server/sockets/${relativePath} has no \`export const <name> = socket(...)\` — every $sockets module must declare exactly one socket`,
@@ -241,12 +255,12 @@ export const ${prepared.exportName} = __belteRemoteProxy__(${JSON.stringify(prep
                     clientPublish) are server-side state and don't
                     affect the client's wire behaviour.
                     */
-                    const contents = `import { socketProxy as __belteSocketProxy__ } from 'belte/browser/socketProxy';
+                    const contents = `import { socketProxy as __belteSocketProxy__ } from '${importName}/browser/socketProxy';
 export const ${prepared.exportName} = __belteSocketProxy__(${JSON.stringify(name)});
 `
                     return { contents, loader: 'ts' }
                 }
-                const banner = `import { defineSocket as __belteDefineSocket__ } from 'belte/server/sockets/defineSocket';
+                const banner = `import { defineSocket as __belteDefineSocket__ } from '${importName}/server/sockets/defineSocket';
 `
                 return {
                     contents: `${banner}${prepared.rewriteForServer(name)}`,
@@ -277,6 +291,7 @@ export const ${prepared.exportName} = __belteSocketProxy__(${JSON.stringify(name
                 const relativePath = args.path.slice(promptsDir.length + 1)
                 const source = await Bun.file(args.path).text()
                 const name = promptNameForFile(relativePath)
+                const importName = await belteImportNameOnce()
                 const parsed = parsePromptMarkdown(source)
                 const jsonSchema = jsonSchemaForPromptArguments(parsed.arguments)
                 const optionLines = [
@@ -288,8 +303,8 @@ export const ${prepared.exportName} = __belteSocketProxy__(${JSON.stringify(name
                 ]
                     .filter((line) => line !== undefined)
                     .join('\n')
-                const contents = `import { definePrompt as __belteDefinePrompt__ } from 'belte/server/prompts/definePrompt'
-import { renderPromptTemplate as __belteRenderPromptTemplate__ } from 'belte/server/prompts/renderPromptTemplate'
+                const contents = `import { definePrompt as __belteDefinePrompt__ } from '${importName}/server/prompts/definePrompt'
+import { renderPromptTemplate as __belteRenderPromptTemplate__ } from '${importName}/server/prompts/renderPromptTemplate'
 const __template__ = ${JSON.stringify(parsed.body)}
 export const prompt = __belteDefinePrompt__(${JSON.stringify(name)}, {
 ${optionLines}
@@ -574,9 +589,9 @@ export const footer = ${JSON.stringify(footer)}
                     from src/mcp/resources. createMcpServer is internal; there
                     is no user-authored server module.
                     */
+                    const importName = await belteImportNameOnce()
                     return {
-                        contents:
-                            "import { createMcpServer } from 'belte/mcp/createMcpServer'\nexport default createMcpServer()\n",
+                        contents: `import { createMcpServer } from '${importName}/mcp/createMcpServer'\nexport default createMcpServer()\n`,
                         loader: 'js',
                     }
                 }

package/src/lib/shared/belteImportName.test.ts

@@ -0,0 +1,58 @@
+import { afterAll, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { belteImportName } from './belteImportName.ts'
+
+const roots: string[] = []
+afterAll(() => roots.forEach((root) => rmSync(root, { recursive: true, force: true })))
+
+// Writes a package.json into a fresh temp dir and returns the dir.
+async function projectWith(packageJson: unknown): Promise<string> {
+    const root = mkdtempSync(`${tmpdir()}/belte-import-name-`)
+    roots.push(root)
+    await Bun.write(`${root}/package.json`, JSON.stringify(packageJson))
+    return root
+}
+
+test('uses the canonical name for a direct dependency', async () => {
+    const cwd = await projectWith({ dependencies: { '@briancray/belte': '^0.2.0' } })
+    expect(await belteImportName(cwd)).toBe('@briancray/belte')
+})
+
+test('uses the `belte` alias key for an npm alias', async () => {
+    const cwd = await projectWith({ dependencies: { belte: 'npm:@briancray/belte@^0.2.0' } })
+    expect(await belteImportName(cwd)).toBe('belte')
+})
+
+test('uses the `belte` alias key for a workspace alias', async () => {
+    const cwd = await projectWith({ dependencies: { belte: 'workspace:@briancray/belte@*' } })
+    expect(await belteImportName(cwd)).toBe('belte')
+})
+
+test('uses a non-`belte` alias key when that is how belte is declared', async () => {
+    const cwd = await projectWith({ dependencies: { framework: 'npm:@briancray/belte' } })
+    expect(await belteImportName(cwd)).toBe('framework')
+})
+
+test('prefers the `belte` alias over a direct canonical dependency', async () => {
+    const cwd = await projectWith({
+        dependencies: { '@briancray/belte': '^0.2.0', belte: 'npm:@briancray/belte@^0.2.0' },
+    })
+    expect(await belteImportName(cwd)).toBe('belte')
+})
+
+test('finds the alias in devDependencies', async () => {
+    const cwd = await projectWith({ devDependencies: { belte: 'npm:@briancray/belte@^0.2.0' } })
+    expect(await belteImportName(cwd)).toBe('belte')
+})
+
+test('falls back to the canonical name when belte is absent', async () => {
+    const cwd = await projectWith({ dependencies: { svelte: '^5.0.0' } })
+    expect(await belteImportName(cwd)).toBe('@briancray/belte')
+})
+
+test('falls back to the canonical name when package.json is missing', async () => {
+    const root = mkdtempSync(`${tmpdir()}/belte-import-name-`)
+    roots.push(root)
+    expect(await belteImportName(root)).toBe('@briancray/belte')
+})

package/src/lib/shared/belteImportName.ts

@@ -0,0 +1,45 @@
+import { beltePackageName } from './beltePackageName.ts'
+
+/*
+Resolves the bare specifier prefix a consuming project imports belte under —
+the name belte is installed as in its package.json. A project may depend on
+belte directly (`@briancray/belte`) or behind a package alias
+(`"belte": "npm:@briancray/belte@..."`, or `workspace:@briancray/belte@*`
+inside this repo). An alias-only install resolves only under the alias key and
+a direct install only under the canonical name, so the generated rpc / socket
+/ prompt modules must import under whichever name the project actually
+declared.
+
+Prefers a `belte` alias (the ergonomic surface the docs use) when present, then
+a direct canonical dependency, then any other alias targeting belte. Falls back
+to the canonical name when belte isn't found in package.json — the build can't
+resolve belte at all in that case, and the canonical name yields the clearest
+resolution error.
+*/
+export async function belteImportName(cwd: string): Promise<string> {
+    const packageJsonPath = `${cwd}/package.json`
+    if (!(await Bun.file(packageJsonPath).exists())) {
+        return beltePackageName
+    }
+    const packageJson = (await Bun.file(packageJsonPath).json()) as {
+        dependencies?: Record<string, string>
+        devDependencies?: Record<string, string>
+    }
+    const dependencies = { ...packageJson.devDependencies, ...packageJson.dependencies }
+    /*
+    Alias entries whose target is belte — `npm:` for a published install,
+    `workspace:` for the in-repo examples. The key is the name the project
+    imports under; the version suffix (`@^0.2.0`, `@*`) is optional.
+    */
+    const aliasPattern = new RegExp(`^(npm|workspace):${beltePackageName}(@.*)?$`)
+    const aliasNames = Object.entries(dependencies)
+        .filter(([, specifier]) => aliasPattern.test(specifier))
+        .map(([name]) => name)
+    if (aliasNames.includes('belte')) {
+        return 'belte'
+    }
+    if (beltePackageName in dependencies) {
+        return beltePackageName
+    }
+    return aliasNames[0] ?? beltePackageName
+}

package/src/lib/shared/beltePackageName.ts

@@ -0,0 +1,7 @@
+/*
+The package's published npm name. The codegen and the import-name resolver
+match a consuming project's dependency (direct or aliased) against this to
+decide which specifier to emit, so keeping it in one place means a future
+rename touches a single constant.
+*/
+export const beltePackageName = '@briancray/belte'

package/src/lib/shared/prepareRpcModule.ts

@@ -1,10 +1,10 @@
 import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
+import { beltePackageName } from './beltePackageName.ts'
 import { findExportCallSite } from './findExportCallSite.ts'
 import { stripImport } from './stripImport.ts'
 
 const VERB_NAMES = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'] as const
 const VERB_SET = new Set<string>(VERB_NAMES)
-const VERB_IMPORT_PATHS = VERB_NAMES.map((verb) => `belte/server/${verb}`)
 
 const SINGLE_EXPORT_ERROR =
     '[belte] $rpc module contains more than one `<VERB>(...)` export — each file must declare exactly one remote function'
@@ -27,14 +27,24 @@ A regex pass would be tidier but it can't tell a `GET` mention inside a
 docstring or template literal from the real call, and it can't follow
 nested generics like `GET<Map<K, V>>(`.
 */
-export function prepareRpcModule(source: string): PreparedRpcModule | undefined {
+export function prepareRpcModule(
+    source: string,
+    importName: string,
+): PreparedRpcModule | undefined {
     /*
     The "no barrels" surface places each verb at its own path
     (`belte/server/GET`, `belte/server/POST`, …) — strip every one so
     the user's verb import doesn't linger and side-effect-load the
-    stub module into the server bundle.
+    stub module into the server bundle. The user may import under the
+    project's chosen name or the canonical package name, so strip both.
     */
-    const stripped = VERB_IMPORT_PATHS.reduce((current, path) => stripImport(current, path), source)
+    const importNames =
+        importName === beltePackageName ? [beltePackageName] : [importName, beltePackageName]
+    const stripped = importNames.reduce(
+        (current, name) =>
+            VERB_NAMES.reduce((acc, verb) => stripImport(acc, `${name}/server/${verb}`), current),
+        source,
+    )
     const site = findExportCallSite(stripped, (ident) => VERB_SET.has(ident), SINGLE_EXPORT_ERROR)
     if (!site) {
         return undefined

package/src/lib/shared/prepareSocketModule.ts

@@ -1,3 +1,4 @@
+import { beltePackageName } from './beltePackageName.ts'
 import { findExportCallSite } from './findExportCallSite.ts'
 import { stripImport } from './stripImport.ts'
 
@@ -17,8 +18,21 @@ original source). The single scan replaces the prior separate
 extract + rewrite passes, so the resolver plugin only walks each source
 character-by-character once.
 */
-export function prepareSocketModule(source: string): PreparedSocketModule | undefined {
-    const stripped = stripImport(source, 'belte/server/socket')
+export function prepareSocketModule(
+    source: string,
+    importName: string,
+): PreparedSocketModule | undefined {
+    /*
+    Strip the user's `socket` import under the project's chosen name and the
+    canonical package name so the dead import can't side-effect-load the
+    socket helper into the server bundle.
+    */
+    const importNames =
+        importName === beltePackageName ? [beltePackageName] : [importName, beltePackageName]
+    const stripped = importNames.reduce(
+        (current, name) => stripImport(current, `${name}/server/socket`),
+        source,
+    )
     const site = findExportCallSite(stripped, (ident) => ident === 'socket', SINGLE_EXPORT_ERROR)
     if (!site) {
         return undefined

package/src/lib/shared/writeRoutesDts.ts

@@ -30,14 +30,19 @@ page file in the project. Page picks this up as a discriminated union keyed
 on `route`, so `if (page.route === '/media/[id]') page.params.id` is typed
 automatically without consumers writing route types by hand.
 The file is written to `src/.belte/routes.d.ts` so the consumer's existing
-src tsconfig include picks it up with no extra configuration.
+src tsconfig include picks it up with no extra configuration. The augmented
+module is keyed on the name the project imports belte under (`importName`),
+so the augmentation matches the consumer's `page` import whether belte is
+installed directly (`@briancray/belte`) or behind an alias.
 */
 export async function writeRoutesDts({
     cwd,
     pageFiles,
+    importName,
 }: {
     cwd: string
     pageFiles: string[]
+    importName: string
 }): Promise<void> {
     const entries = pageFiles
         .map((file) => ({
@@ -50,7 +55,7 @@ export async function writeRoutesDts({
         )
         .join('\n')
     const contents = `// Generated by belte. Do not edit by hand.
-declare module 'belte/browser/page' {
+declare module '${importName}/browser/page' {
     interface Routes {
 ${entries}
     }

package/template/package.json

@@ -11,7 +11,7 @@
         "bundle": "belte bundle"
     },
     "dependencies": {
-        "@briancray/belte": "^0.1.0",
+        "@briancray/belte": "^0.2.0",
         "svelte": "^5.0.0"
     }
 }

package/template/src/app.ts

@@ -7,7 +7,7 @@ module — no import is needed from your own code.
   handle      middleware wrapping the default request pipeline
   handleError custom 500 fallback
 */
-import type { AppModule } from 'belte/server/AppModule'
+import type { AppModule } from '@briancray/belte/server/AppModule'
 
 export const init: AppModule['init'] = ({ server }) => {
     console.log(`server listening on http://localhost:${server.port}`)

package/template/src/browser/pages/page.svelte

@@ -3,7 +3,7 @@ Root page — served at GET /. Every folder under src/browser/pages/ that
 contains a page.svelte mounts at that folder's URL.
 -->
 <script lang="ts">
-import { cache } from 'belte/browser/cache'
+import { cache } from '@briancray/belte/browser/cache'
 import { getHello } from '$server/rpc/getHello.ts'
 
 /*

package/template/src/server/rpc/getHello.ts

@@ -27,7 +27,7 @@ Every rpc value also exposes `.raw(args?)` (returns the underlying
 for callers that need headers/status or want to iterate SSE/JSONL frames.
 */
 
-import { GET } from 'belte/server/GET'
-import { json } from 'belte/server/json'
+import { GET } from '@briancray/belte/server/GET'
+import { json } from '@briancray/belte/server/json'
 
 export const getHello = GET(() => json({ message: 'Hello from belte' }))

package/template/svelte.config.js

@@ -3,7 +3,7 @@ Optional Svelte compiler configuration. Same shape as upstream Svelte.
 Delete this file to use defaults.
 */
 
-/** @type {import('belte').SvelteConfig} */
+/** @type {import('@briancray/belte').SvelteConfig} */
 export default {
     compilerOptions: {
         // Opt in to top-level await inside Svelte components.

package/template/tsconfig.json

@@ -1,5 +1,5 @@
 {
-    "extends": "belte/tsconfig",
+    "extends": "@briancray/belte/tsconfig",
     "include": ["src/**/*.ts", "src/**/*.svelte"],
     "compilerOptions": {
         "paths": {