Devframe Definition

import { defineDevframe, defineRpcFunction } from 'devframe'
import * as v from 'valibot' // npm i valibot

export default defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  version: '1.0.0',
  packageName: 'my-tool',
  importMetaUrl: import.meta.url,
  homepage: 'https://github.com/me/my-tool',
  description: 'A one-line summary of what the tool does.',
  icon: 'ph:gauge-duotone',
  setup(ctx) {
    // A scoped context auto-namespaces ids with your devframe `id`.
    const my = ctx.scope('my-tool')

    // Register your RPC functions, shared state, etc. here.
    my.rpc.register(defineRpcFunction({
      name: 'hello', // stored as `my-tool:hello`
      type: 'static',
      jsonSerializable: true,
      handler: () => ({ message: 'hello' }),
    }))
  },
})

import pkg from '../package.json' with { type: 'json' }

export default defineDevframe({
  id: 'my-tool',
  name: 'My Tool', // display label
  version: pkg.version,
  packageName: pkg.name,
  importMetaUrl: import.meta.url,
  homepage: pkg.homepage,
  description: pkg.description,
  setup(ctx) { /* … */ },
})

export default defineDevframe({
  /** …metadata as above */
  importMetaUrl: import.meta.url,
  /**
   * Served from the locally installed `my-tool--assets`, resolved via
   * `importMetaUrl`; it works under pnpm's strict layout with zero network.
   */
  clientAssets: { package: `${pkg.name}--assets`, version: pkg.version },
  /** Imported from `my-tool`'s own dependency graph. */
  services: [{ package: '@scope/my-service', version: pkg.version }],
  setup(ctx) { /* … */ },
})

import { fileURLToPath } from 'node:url'

export default defineDevframe({
  /** …metadata as above */
  importMetaUrl: import.meta.url,
  /**
   * A local build resolved from the module; it works from source and the
   * published package.
   */
  clientAssets: fileURLToPath(new URL('../dist/spa', import.meta.url)),
  setup(ctx) { /* … */ },
})

defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  setup(ctx) {
    if (ctx.mode === 'build') {
      // Static-only work, baked into the RPC dump.
      ctx.rpc.addFunctions(staticFunctions)
    }
    else {
      // Dev-mode wiring, file watchers, etc.
      watchProject(ctx)
    }
  },
})

interface DevframeNodeContext {
  readonly cwd: string
  readonly workspaceRoot: string
  readonly mode: 'dev' | 'build'

  host: DevframeHost // runtime abstraction (mountStatic / resolveOrigin / getStorageDir)
  rpc: RpcFunctionsHost // register + broadcast + sharedState
  views: DevframeViewHost // static file hosting (`hostStatic`)
  diagnostics: DevframeDiagnosticsHost
  agent: DevframeAgentHost // expose tools + resources to coding agents
  services: DevframeServicesHost // typed cross-devframe service registry
  staticConfig: Partial<DevframeConnectionConfigsRegistry> // this context's own ConnectionMeta.configs

  scope: (id) => DevframeScopedNodeContext // namespaced view (preferred)
}

ctx.services.provide('my-plugin:sources', sources)

ctx.services.whenAvailable('my-plugin:sources', (sources) => {
  sources.register(/* ... */)
})

declare module 'devframe/types' {
  interface DevframeConnectionConfigsRegistry {
    'my-plugin': { featureFlag: boolean }
  }
}

ctx.staticConfig['my-plugin'] = { featureFlag: true }

defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  clientAssets: './client/dist', // built SPA served as the UI
  cli: {
    command: 'my-tool', // binary name; default: the `id`
    port: 9876, // preferred port; default: 9999
    portRange: [9876, 10000], // forwarded to get-port-please
    random: false, // forwarded to get-port-please
    host: 'localhost', // default host; --host overrides
    open: true, // auto-open the browser on dev start; embeds the current OTP so the tab lands authenticated
    configure(cli) { // contribute capability flags/commands
      cli
        .option('--my-flag <value>', 'Tool-specific flag')
    },
  },
  setup(ctx, { flags }) {
    // `flags` carries the parsed cac bag: the built-in flags
    // (`--port`, `--host`, `--open`, `--no-open`) and anything you added
    // in `configure`.
  },
})

import { createPluginFromDevframe } from '@vitejs/devtools-kit/node'
import { createBuild } from 'devframe/adapters/build'
import { createCac } from 'devframe/adapters/cac'

const myDevframe = defineDevframe({ id: 'my-tool', name: 'My Tool', setup() {} })

// 1. Standalone CLI:
await createCac(myDevframe).parse()

// 2. Offline snapshot:
await createBuild(myDevframe, { outDir: 'dist-static' })

/** 3. Mount into a host framework (Vite DevTools shown; others can implement equivalents): */
export const myPlugin = () => createPluginFromDevframe(myDevframe)