@nuxtagentic/kit 0.0.0-stage → 0.1.1

package/LICENSE.md

@@ -0,0 +1,9 @@
+Proprietary software. All rights reserved.
+
+Use of Nuxt Agentic packages and starter materials is governed by the applicable
+commercial agreement supplied with a purchase. This repository does not grant
+an open-source license or permission to redistribute the packages as a competing
+template or module library.
+
+Third-party dependencies retain their respective licenses. This notice does not
+replace or modify those licenses.

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# Module registration
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@nuxtagentic/kit` is the build-time helper shared by the local Nuxt modules.
+It exports `registerWorkspaceModule` and `getWorkspaceModules`; it is not itself a
+Nuxt module to add to the host's `modules` array.
+
+`externalizeSsrDependencies(names, nuxt)` lets Nitro bundle shared server
+libraries once when both SSR and server routes import the same dependency. It resolves from the importing module,
+including unhoisted pnpm dependencies. Browser builds and development retain
+their existing bundling behavior.
+
+A module passes its ID, runtime directory, optional catalog entry, feature, metadata, and
+server contribution paths to `registerWorkspaceModule`. Kit registers its
+composable and server directories and creates four generated manifests:
+
+| Alias                 | Contains                                                       |
+| --------------------- | -------------------------------------------------------------- |
+| `#workspace/modules`  | Installable catalog entries, defaults, and dependencies        |
+| `#workspace/features` | UI and workspace contributions tagged with their owning module |
+| `#workspace/client`   | Browser-safe model, tool, and integration metadata             |
+| `#workspace/server`   | Server resource factories and integration hooks                |
+
+Use `catalog` for business features that users can install. It provides a label,
+description, icon, icon classes, optional opening URL, dependencies, and an optional
+`defaultInstalled` flag. Shared services and core features omit the catalog entry
+and remain active. A package can
+own multiple contributions.
+Client and server manifests expose `getWorkspaceMetadata(installedIds)` to select
+active contributions. The no-argument metadata exports contain all available entries.
+
+Each consuming module still owns its page, layout, component, configuration, and
+worker registration in `module.ts`. Registration is scoped to the Nuxt instance
+and rejects duplicate IDs.
+
+Registration opts the package's TypeScript sources into both Vite and Nitro
+transpilation. Nitro normally excludes `node_modules`; Kit narrows that default
+to allow `@nuxtagentic` sources while preserving other exclusion rules. Registered
+package roots are bundled into the server output, including Cloudflare Workers.
+
+Kit does not mutate `cloud.config.ts` or run migrations. The host statically
+composes schema exports so CloudConfig's CLI can read them outside Nuxt.
+Feature packages declare schema exports in their `cloudconfig.models` metadata.
+See [the package map and setup guide](../README.md).
+
+The portable fixture installs one module at a time without the host app:
+
+```sh
+NUXT_TEST_MODULE=agents pnpm exec nuxt typecheck packages/kit/tests/fixture
+```
+
+Replace `agents` with another module name. `pnpm test:modules` checks import
+boundaries, dependency cycles, exported sources, and fixture isolation.

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@nuxtagentic/kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "type": "module",
+  "files": [
+    "registration.ts",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "exports": {
+    ".": "./registration.ts",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@nuxt/kit": "4.6.1",
+    "@nuxt/schema": "4.6.1"
+  },
+  "peerDependencies": {
+    "nuxt": "^4.6.1"
+  },
+  "devDependencies": {
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "description": "Nuxt module registration and runtime discovery for Nuxt Agentic.",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": "^22.22.3 || ^24.15.0 || >=26.0.0"
+  }
 }

package/registration.ts

@@ -0,0 +1,207 @@
+import { addImportsDir, addServerScanDir, addTemplate, useNuxt } from '@nuxt/kit'
+import { existsSync } from 'node:fs'
+import { dirname } from 'node:path'
+import type { Nuxt } from '@nuxt/schema'
+
+const ssrDependenciesKey = Symbol.for('nuxt-agentic.ssrDependencies')
+
+/** Let Nitro bundle shared server dependencies once, instead of rebundling Vite's copies. */
+export function externalizeSsrDependencies(dependencies: readonly string[], nuxt = useNuxt()) {
+  if (nuxt.options.dev) {
+    return
+  }
+  const app = nuxt as Nuxt & { [ssrDependenciesKey]?: Set<string> }
+  if (app[ssrDependenciesKey]) {
+    for (const dependency of dependencies) {
+      app[ssrDependenciesKey].add(dependency)
+    }
+    return
+  }
+  const packages = new Set(dependencies)
+  app[ssrDependenciesKey] = packages
+  nuxt.hook('vite:extendConfig', (config, { isServer }) => {
+    if (!isServer) {
+      return
+    }
+    const viteConfig = config as { plugins?: NonNullable<typeof config.plugins> }
+    viteConfig.plugins ??= []
+    viteConfig.plugins.unshift({
+      name: 'nuxt-agentic:ssr-dependencies',
+      enforce: 'pre',
+      async resolveId(source, importer) {
+        if (!packages.has(source)) {
+          return null
+        }
+        // Resolve from the importing module so pnpm's unhoisted dependencies work.
+        const resolved = await this.resolve(source, importer, { skipSelf: true })
+        if (!resolved) {
+          throw new Error(`Cannot resolve SSR dependency ${source}`)
+        }
+        return { ...resolved, external: true }
+      },
+    })
+  })
+}
+
+export interface FeatureRegistration {
+  id: string
+  runtime: string
+  feature?: { from: string; name: string }
+  metadata?: string
+  server?: string
+  catalog?: Omit<WorkspaceModuleDefinition, 'id'>
+}
+
+export interface WorkspaceModuleDefinition {
+  id: string
+  label: string
+  description: string
+  icon: string
+  iconClass: string
+  to?: string
+  dependencies?: string[]
+  defaultInstalled?: boolean
+}
+
+// Nuxt can load this helper in separate module contexts; keep registration on its instance.
+const registryKey = Symbol.for('nuxt-agentic.modules')
+type RegisteredNuxt = Nuxt & { [registryKey]?: FeatureRegistration[] }
+
+export function getWorkspaceModules(nuxt = useNuxt()) {
+  return (nuxt as RegisteredNuxt)[registryKey] ?? []
+}
+
+/** Include registered package UI in Tailwind's scan, including packages in node_modules. */
+export function registerWorkspaceStyles(stylesheet: string, nuxt = useNuxt()) {
+  const sources = addTemplate({
+    filename: 'workspace/styles.css',
+    getContents: () =>
+      [
+        `@import ${JSON.stringify(stylesheet)};`,
+        ...getWorkspaceModules(nuxt).map(
+          ({ runtime }) => `@source ${JSON.stringify(dirname(runtime))};`,
+        ),
+      ].join('\n'),
+    write: true,
+  })
+  nuxt.options.css.push(sources.dst)
+}
+
+export function registerWorkspaceModule(entry: FeatureRegistration, nuxt = useNuxt()) {
+  const app = nuxt as RegisteredNuxt
+  let entries = app[registryKey]
+  if (!entries) {
+    entries = []
+    app[registryKey] = entries
+    const modules = entries
+    nuxt.hook('nitro:config', (config) => {
+      // Published packages ship TypeScript; Nitro otherwise skips everything in node_modules.
+      config.esbuild ??= {}
+      config.esbuild.options ??= {}
+      // Nuxt merges exclusion arrays, so adding an exception leaves its broad default active.
+      const exclusions = config.esbuild.options.exclude ?? [/node_modules/]
+      config.esbuild.options.exclude = (Array.isArray(exclusions) ? exclusions : [exclusions]).map(
+        (pattern) =>
+          pattern instanceof RegExp && pattern.source === 'node_modules'
+            ? /[/\\]node_modules[/\\](?!(?:.*[/\\])?@nuxtagentic[/\\])/
+            : pattern,
+      )
+    })
+    nuxt.hook('modules:done', () => {
+      if (modules.some((entry) => entry.id === 'workspace')) {
+        registerManifest(nuxt, '#workspace/features', 'features', () => featureManifest(modules))
+        registerManifest(nuxt, '#workspace/modules', 'modules', () =>
+          [
+            "import type { WorkspaceModuleDefinition } from '@nuxtagentic/kit'",
+            `export const MODULE_CATALOG: readonly WorkspaceModuleDefinition[] = ${JSON.stringify(
+              modules.flatMap((entry) =>
+                entry.catalog ? [{ id: entry.id, ...entry.catalog }] : [],
+              ),
+            )}`,
+          ].join('\n'),
+        )
+      }
+      if (modules.some((entry) => entry.id === 'prompt')) {
+        registerManifest(nuxt, '#workspace/client', 'client', () =>
+          metadataManifest(modules, false),
+        )
+        registerManifest(nuxt, '#workspace/server', 'server', () => metadataManifest(modules, true))
+      }
+    })
+  }
+  if (entries.some((module) => module.id === entry.id)) {
+    throw new Error(`Workspace module "${entry.id}" was registered twice.`)
+  }
+  entries.push(entry)
+  // Nuxt excludes node_modules from auto-import injection unless the runtime is opted in.
+  const runtimePath = entry.runtime.replaceAll('\\', '/').replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  nuxt.options.imports.transform ??= {}
+  nuxt.options.imports.transform.include ??= []
+  nuxt.options.imports.transform.include.push(new RegExp(`^${runtimePath}/`))
+  nuxt.options.build.transpile.push(entry.runtime)
+  if (existsSync(`${entry.runtime}/composables`)) {
+    addImportsDir(`${entry.runtime}/composables`)
+  }
+  if (existsSync(`${entry.runtime}/server`)) {
+    addServerScanDir(`${entry.runtime}/server`)
+  }
+}
+
+function registerManifest(nuxt: Nuxt, alias: string, name: string, getContents: () => string) {
+  const template = addTemplate({ filename: `workspace/${name}.ts`, getContents, write: true })
+  nuxt.options.alias[alias] = template.dst
+  nuxt.hook('nitro:config', (config) => {
+    config.alias ??= {}
+    config.alias[alias] = template.dst
+  })
+}
+
+function featureManifest(entries: FeatureRegistration[]) {
+  const features = entries.flatMap((entry) =>
+    entry.feature ? [{ ...entry.feature, id: entry.id }] : [],
+  )
+  return [
+    "import type { WorkspaceContribution, WorkspaceFeature } from '@nuxtagentic/workspace/runtime/types'",
+    ...features.map(
+      (feature, index) =>
+        `import { ${feature.name} as feature${index} } from ${JSON.stringify(feature.from.replace(/\.ts$/, ''))}`,
+    ),
+    `export const WORKSPACE_CONTRIBUTIONS: readonly WorkspaceContribution[] = [${features.map((feature, index) => `[feature${index}].flat().map(entry => ({ ...entry, moduleId: ${JSON.stringify(feature.id)} }))`).join(', ')}].flat()`,
+    'export const WORKSPACE_FEATURES = WORKSPACE_CONTRIBUTIONS.filter((entry): entry is WorkspaceFeature => "component" in entry && !!entry.component)',
+    'export type WorkspaceFeatureId = string',
+  ].join('\n')
+}
+
+function metadataManifest(entries: FeatureRegistration[], server: boolean) {
+  const sources = entries.flatMap((entry) => {
+    const path = server ? (entry.server ?? entry.metadata) : entry.metadata
+    return path ? [{ path, id: entry.id, optional: !!entry.catalog }] : []
+  })
+  const type = server ? 'ServerContribution' : 'WorkspaceMetadata'
+  return [
+    `import type { ${type} } from '@nuxtagentic/prompt/server-contributions'`,
+    ...sources.map(
+      (source, index) =>
+        `import entry${index} from ${JSON.stringify(source.path.replace(/\.ts$/, ''))}`,
+    ),
+    `const contributions: (${type} & { moduleId: string; optional: boolean })[] = [${sources.map((source, index) => `({ ...entry${index}, moduleId: ${JSON.stringify(source.id)}, optional: ${source.optional} })`).join(', ')}]`,
+    'export function getWorkspaceMetadata(installed?: readonly string[]) {',
+    '  const entries = contributions.filter(entry => !entry.optional || !installed || installed.includes(entry.moduleId))',
+    '  return {',
+    '    MODEL_VIEWS: entries.flatMap(entry => entry.views ?? []),',
+    `    AGENT_TOOLS: Object.assign({}, ...entries.map(entry => entry.tools ?? {})) as NonNullable<${type}['tools']>,`,
+    `    AGENT_RESOURCE_ALIASES: Object.assign({}, ...entries.map(entry => entry.resourceAliases ?? {})) as NonNullable<${type}['resourceAliases']>,`,
+    `    GOOGLE_SERVICES: Object.assign({}, ...entries.map(entry => entry.googleServices ?? {})) as NonNullable<${type}['googleServices']>,`,
+    '    AGENT_EXCLUDED_MODELS: entries.flatMap(entry => entry.excludedModels ?? []),',
+    ...(server
+      ? [
+          '    resourceFactories: entries.flatMap(entry => entry.resourceFactories ?? []),',
+          '    googleDisconnectHooks: entries.flatMap(entry => entry.googleDisconnectHooks ?? []),',
+          '    googleAvailabilityHooks: entries.flatMap(entry => entry.googleAvailabilityHooks ?? []),',
+        ]
+      : []),
+    '  }',
+    '}',
+    `export const { MODEL_VIEWS, AGENT_TOOLS, AGENT_RESOURCE_ALIASES, GOOGLE_SERVICES, AGENT_EXCLUDED_MODELS${server ? ', resourceFactories, googleDisconnectHooks, googleAvailabilityHooks' : ''} } = getWorkspaceMetadata()`,
+  ].join('\n')
+}