create-cordisx-plugin 0.1.0-beta.0 → 0.1.0-beta.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-cordisx-plugin",
-  "version": "0.1.0-beta.0",
-  "description": "Create a minimal CordisX plugin project",
+  "version": "0.1.0-beta.3",
+  "description": "Create standalone, workspace, or embedded CordisX plugin projects",
   "type": "module",
   "files": [
     "dist",
@@ -15,10 +15,11 @@
     "create-cordisx-plugin": "dist/cli.js"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "check": "npm run typecheck",
+    "build": "tsc -p tsconfig.json && node scripts/normalize-bin-mode.mjs",
+    "check": "npm run typecheck && npm run build && npm test",
     "check:package": "node scripts/check-package-contents.mjs",
     "prepack": "npm run build",
+    "test": "node --test test/*.node-test.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "engines": {
@@ -42,11 +43,13 @@
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "beta",
     "provenance": true
   },
   "devDependencies": {
     "@types/node": "^22.18.1",
     "typescript": "^5.9.2"
+  },
+  "dependencies": {
+    "yaml": "2.8.1"
   }
 }

package/template/README.md

@@ -1,21 +1,48 @@
 # {{packageName}}
 
-A minimal trusted-local CordisX plugin. Its manifest is exported from
-`src/{{pluginId}}.ts`, which is also the runtime entry used by CordisX.
+A minimal trusted-local CordisX React plugin. Its manifest is exported from
+`src/{{pluginId}}.tsx`, which is also CordisX's local-development entry.
+The page component lives in `src/overview-page.tsx` as a named component-only
+module so local development can preserve its state with React Fast Refresh.
 
 ```bash
-npm install
-npm run check
-npm run dev:dry-run
-npm run dev
+{{packageManager}} install
+{{packageManager}} run check
+{{packageManager}} run dev:dry-run
+{{packageManager}} run dev
 ```
 
-`npm run dev:dry-run` bundles the plugin without launching Codex Desktop.
-`npm run dev` launches the separate CordisX development host.
+`{{packageManager}} run dev:dry-run` validates the plugin module graph without
+launching Codex Desktop. `{{packageManager}} run dev` launches the separate
+CordisX development host. Component-only modules use React Fast Refresh;
+manifest, entry, and `apply()` changes replace the plugin generation.
 
-The template intentionally requests no platform capabilities. It contributes
-structured data to a host-owned toolbar surface and does not depend on a
-marketplace, signing, a permission sandbox, or hot module replacement.
+`{{packageManager}} run build` creates a production Vite ESM graph in `dist/runtime/`.
+Its stable `module.js` entry may load content-addressed JavaScript chunks, CSS,
+and static assets only when an `import()` reaches them. The generated formal
+`artifact.json` records that graph for packaging; declarations are kept outside
+the closed graph in `dist/types/`, and `package.json#files` includes the complete
+`dist/` tree. Production generations remain immutable package
+artifacts and do not use the development HMR connection.
+
+The generated config calls the public `cordisx/vite`
+`cordisXPluginViteConfig()` helper. That shared author/Host pipeline owns the
+output rules, virtualizes only the closed Host singleton imports, and emits the
+formal `dist/runtime/artifact.json`. A portable CordisX package manifest points its
+browser entry at the adjacent prebuilt `dist/runtime/module.js`; the Host validates and
+retains the complete indexed graph.
+
+The template intentionally requests no platform capabilities. It contributes a
+structured toolbar route and a React page body. Import React from
+`cordisx/react` and components from `cordisx/ui`; do not install `react`,
+`react-dom`, React type packages, or a component library. CordisX supplies one
+Host React singleton and rejects a plugin artifact that bundles another copy.
+
+The route and page use closed route-v2/page-v3 documents with separate retained
+localized `title` and `description` messages. Path, outlet, page id, route id,
+params, and chrome remain untranslated. CordisX owns the route, page header,
+theme, error boundary, and React root cleanup; the plugin owns only the page
+body component. Plugins remain trusted local code, not sandboxed code.
 
 This generated project is Marked Template Material under the
 [CordisX Independent Plugin Exception](https://github.com/cordisx/cordisx/blob/main/CORDISX-INDEPENDENT-PLUGIN-EXCEPTION.md).
@@ -24,3 +51,25 @@ CordisX plugin interfaces, it may be commercial and use a license you choose.
 Replace `UNLICENSED` in `package.json` with that license before distribution.
 The Exception does not cover copying or modifying CordisX host/runtime/CLI code
 or using private interfaces.
+
+Plugin-owned styles use `import './details.css'` in the owning component (or
+lazy page module). Keep `src/vite-env.d.ts`: Vite types distinguish side-effect
+CSS, CSS Module class maps, and explicit `?inline` text. Ordinary CSS imports
+do not return strings. Component unmount is not CSS-module disposal; verify
+plugin replacement separately from CSS HMR. See the maintained
+[CSS guidance](https://github.com/cordisx/cordisx/blob/main/skills/cordisx-plugin-development/references/css-and-lifecycle.md)
+for lifecycle boundaries and installed-Host CSS Modules limitations.
+
+For operation feedback, use `ctx.notifications.show()` and declare
+`notifications` in plugin injection. Host supplies plugin identity, cards and
+user suppression rules. Do not create a Toast provider, manually positioned
+alert or page-wide operation error; keep field validation and durable business
+state next to the relevant control. See the
+[notification guide](https://github.com/cordisx/cordisx/blob/efbff656d84b482d51598bc5ba303d24134e0c62/.agents/docs/notifications.md).
+Verify SDK/Host availability first: an older version without this service is a
+capability gap, not a reason to build a private DOM fallback.
+
+For modals, use Host `Dialog`/`DialogProvider` from `cordisx/ui` or `ctx.dialogs`.
+Keep full JSX in the body and use structured header/footer actions. The Host
+owns the rightmost close button, focus, theme and lifecycle. See the
+[dialog guide](https://github.com/cordisx/cordisx/blob/main/.agents/docs/dialogs.md).

package/template/README.zh-Hans.md

@@ -0,0 +1,39 @@
+# {{packageName}}
+
+一个最小的 CordisX 本地可信插件。插件清单由
+`src/{{pluginId}}.tsx` 导出；该文件同时也是 CordisX 本地开发使用的入口。
+
+```bash
+{{packageManager}} install
+{{packageManager}} run check
+{{packageManager}} run dev:dry-run
+{{packageManager}} run dev
+```
+
+`{{packageManager}} run dev:dry-run` 会在不启动 Codex Desktop 的情况下打包插件；
+`{{packageManager}} run dev` 会启动独立的 CordisX 开发宿主。
+
+`{{packageManager}} run build` 会在 `dist/runtime/` 中生成生产用 Vite ESM graph。固定入口
+`module.js` 可以在 `import()` 实际触发后再加载带内容摘要的 JavaScript chunk、
+CSS 和静态资源；正式的 `artifact.json` 会记录完整产物图，类型声明则隔离在
+`dist/types/`，
+`package.json#files` 会将整个 `dist/` 纳入打包。生产 generation 仍是不可变包
+产物，不使用开发 HMR 连接。
+
+生成的配置会调用公开的 `cordisx/vite` `cordisXPluginViteConfig()` helper。
+这个作者侧与 Host 共用的流水线负责产物规则，只虚拟化封闭的 Host 单例导入，并
+生成正式的 `dist/runtime/artifact.json`。可移植 CordisX package manifest 应把浏览器入口
+指向相邻的预构建 `dist/runtime/module.js`；Host 会验证并保留该完整索引 graph。
+
+这个生成项目属于 [CordisX 独立插件例外](https://github.com/cordisx/cordisx/blob/main/CORDISX-INDEPENDENT-PLUGIN-EXCEPTION.md)
+定义的“已标记模板材料”。只要它保持为独立插件，并且只使用有文档、带版本的
+CordisX 公共插件接口，就可以用于商业用途并采用你选择的许可证。发布前请将
+`package.json` 中的 `UNLICENSED` 替换为所选许可证。该例外不包括复制或修改
+CordisX Host、Runtime、CLI 代码，也不包括使用私有接口。
+
+插件自有样式在所属组件或 lazy 页面模块中使用 `import './details.css'`。
+保留 `src/vite-env.d.ts`：Vite 类型区分普通 CSS 副作用导入、CSS Modules
+类名映射和显式 `?inline` 文本，普通 CSS 不返回字符串。组件卸载不等于
+CSS 模块回收；CSS HMR 与插件替换需要分别验证。具体生命周期和已安装
+Host 的 CSS Modules 限制见
+[CSS 指导](https://github.com/cordisx/cordisx/blob/main/skills/cordisx-plugin-development/references/css-and-lifecycle.md)。

package/template/package.json

@@ -5,20 +5,33 @@
   "license": "UNLICENSED",
   "description": "A CordisX plugin",
   "type": "module",
-  "main": "./dist/{{pluginId}}.js",
-  "types": "./dist/{{pluginId}}.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "README.zh-Hans.md"
+  ],
+  "main": "./dist/runtime/module.js",
+  "types": "./dist/types/{{pluginId}}.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/{{pluginId}}.d.ts",
+      "import": "./dist/runtime/module.js",
+      "default": "./dist/runtime/module.js"
+    }
+  },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "check": "npm run typecheck && npm run build && npm test",
-    "dev": "cordisx dev ./src/{{pluginId}}.ts",
-    "dev:dry-run": "cordisx dev ./src/{{pluginId}}.ts --dry-run",
+    "build": "vite build && tsc -p tsconfig.json --emitDeclarationOnly",
+    "check": "tsc -p tsconfig.json --noEmit && vite build && tsc -p tsconfig.json --emitDeclarationOnly && node --test test/manifest.mjs",
+    "dev": "cordisx dev ./src/{{pluginId}}.tsx",
+    "dev:dry-run": "cordisx dev ./src/{{pluginId}}.tsx --dry-run",
     "test": "node --test test/manifest.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.1",
     "cordisx": "{{cordisxVersion}}",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "vite": "8.2.2"
   },
   "engines": {
     "node": ">=22.19"

package/template/src/overview-page.tsx

@@ -0,0 +1,30 @@
+import { useState } from 'cordisx/react'
+import { Button, Card, Heading, Stack, Text } from 'cordisx/ui'
+import type { CordisXReactPageProps } from 'cordisx/contracts'
+
+export type Messages = {
+  'command.open': undefined
+  'page.title': undefined
+  'page.description': undefined
+  'route.title': undefined
+  'route.description': undefined
+  'counter.label': { count: number }
+}
+
+/** A named component-only module forms a stable React Fast Refresh boundary. */
+export function OverviewPage({ t }: CordisXReactPageProps<Messages>) {
+  const [count, setCount] = useState(0)
+  return (
+    <Stack gap="large">
+      <Heading>{t('page.title')}</Heading>
+      <Card>
+        <Stack gap="medium" align="flex-start">
+          <Text tone="muted">{t('page.description')}</Text>
+          <Button variant="primary" onClick={() => setCount(value => value + 1)}>
+            {t('counter.label', { count })}
+          </Button>
+        </Stack>
+      </Card>
+    </Stack>
+  )
+}

package/template/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/template/src/{{packageName}}.tsx

@@ -0,0 +1,96 @@
+import type { Context } from '@deepseek-ai/cordis'
+import { defineReactPage, lazy, Suspense } from 'cordisx/react'
+import {
+  CORDISX_PAGE_SCHEMA_V3,
+  CORDISX_PLUGIN_MANIFEST_SCHEMA_V1,
+  CORDISX_ROUTE_SCHEMA_V2,
+  type CordisXPluginManifestV1,
+  type CordisXReactPageProps,
+} from 'cordisx/contracts'
+import type { Messages } from './overview-page.js'
+
+export const manifest = {
+  $schema: CORDISX_PLUGIN_MANIFEST_SCHEMA_V1,
+  schemaVersion: 1,
+  id: '{{pluginId}}',
+  name: '{{packageName}}',
+  capabilities: [],
+} as const satisfies CordisXPluginManifestV1
+
+export const inject = ['i18n', 'pages', 'routes', 'slots']
+
+const page = {
+  $schema: CORDISX_PAGE_SCHEMA_V3,
+  schemaVersion: 3,
+  id: 'overview',
+  title: { key: 'page.title', fallback: '{{packageName}}' },
+  description: { key: 'page.description', fallback: 'A React page rendered by the shared CordisX Host runtime.' },
+  icon: 'host:info',
+} as const
+
+const route = {
+  $schema: CORDISX_ROUTE_SCHEMA_V2,
+  schemaVersion: 2,
+  id: 'overview',
+  path: '/app/{{pluginId}}',
+  outlet: 'app',
+  page: 'overview',
+  title: { key: 'route.title', fallback: '{{packageName}}' },
+  description: { key: 'route.description', fallback: 'Open the plugin React example.' },
+} as const
+
+const OverviewPage = lazy(async () => {
+  const module = await import('./overview-page.js')
+  return { default: module.OverviewPage }
+})
+
+function OverviewPageBoundary(props: CordisXReactPageProps<Messages>) {
+  return (
+    <Suspense fallback={null}>
+      <OverviewPage {...props} />
+    </Suspense>
+  )
+}
+
+const mountOverview = defineReactPage<Messages>(OverviewPageBoundary)
+
+export function apply(ctx: Context): void {
+  ctx.i18n.define<Messages>({
+    namespace: '{{pluginId}}',
+    locale: 'en',
+    default: true,
+    messages: {
+      'command.open': 'Open {{packageName}}',
+      'page.title': '{{packageName}}',
+      'page.description': 'This page uses the React singleton and components provided by CordisX.',
+      'route.title': '{{packageName}}',
+      'route.description': 'Open the plugin React example.',
+      'counter.label': 'Clicked {count, number} times',
+    },
+  })
+  ctx.i18n.define<Messages>({
+    namespace: '{{pluginId}}',
+    locale: 'zh-CN',
+    messages: {
+      'command.open': '打开 {{packageName}}',
+      'page.title': '{{packageName}}',
+      'page.description': '此页面复用 CordisX 提供的 React 单例与组件。',
+      'route.title': '{{packageName}}',
+      'route.description': '打开插件的 React 示例。',
+      'counter.label': '已点击 {count, number} 次',
+    },
+  })
+  ctx.pages.register<Messages>(page, mountOverview)
+  ctx.routes.register(route)
+  ctx.slots.register({
+    name: 'workspace.toolbar.items',
+    id: 'open',
+    order: 10,
+  }, {
+    anchor: 'workspace.primary',
+    placement: 'after',
+    label: { key: 'command.open', fallback: 'Open {{packageName}}' },
+    icon: 'host:open',
+    route: { id: 'overview' },
+  })
+}

package/template/test/manifest.mjs

@@ -1,11 +1,27 @@
 import assert from 'node:assert/strict'
 import test from 'node:test'
-import { apply, inject, manifest } from '../dist/{{pluginId}}.js'
+
+const component = () => null
+const noop = () => undefined
+const React = new Proxy({ Fragment: Symbol('Fragment'), Suspense: component, lazy: () => component }, {
+  get(target, property) {
+    return Reflect.get(target, property) ?? noop
+  },
+})
+globalThis.__cordisxSharedReactRuntime = {
+  React,
+  defineReactPage: page => page,
+  jsxRuntime: { Fragment: React.Fragment, jsx: component, jsxs: component },
+  jsxDevRuntime: { Fragment: React.Fragment, jsxDEV: component },
+  ui: new Proxy({}, { get: () => component }),
+}
+
+const { apply, inject, manifest } = await import('../dist/runtime/module.js')
 
 test('exports a minimal CordisX plugin module', () => {
   assert.equal(manifest.schemaVersion, 1)
   assert.equal(manifest.id, '{{pluginId}}')
   assert.deepEqual(manifest.capabilities, [])
-  assert.deepEqual(inject, ['i18n', 'commands', 'slots'])
+  assert.deepEqual(inject, ['i18n', 'pages', 'routes', 'slots'])
   assert.equal(typeof apply, 'function')
 })

package/template/tsconfig.json

@@ -3,14 +3,16 @@
     "target": "ES2022",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
+    "jsx": "react-jsx",
+    "jsxImportSource": "cordisx/react",
     "lib": ["ES2023", "DOM"],
     "rootDir": "src",
-    "outDir": "dist",
+    "outDir": "dist/types",
     "strict": true,
     "declaration": true,
     "forceConsistentCasingInFileNames": true,
     "skipLibCheck": true
   },
-  "include": ["src/**/*.ts"],
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
   "exclude": ["dist", "node_modules"]
 }

package/template/vite.config.ts

@@ -0,0 +1,13 @@
+import { fileURLToPath } from 'node:url'
+import { cordisXPluginViteConfig } from 'cordisx/vite'
+
+const projectRoot = fileURLToPath(new URL('.', import.meta.url))
+
+const config: ReturnType<typeof cordisXPluginViteConfig> = cordisXPluginViteConfig({
+  root: projectRoot,
+  entry: fileURLToPath(new URL('./{{sourceEntry}}', import.meta.url)),
+  outDir: fileURLToPath(new URL('./{{outDir}}', import.meta.url)),
+  entryFileName: 'module.js',
+})
+
+export default config

package/template/src/{{packageName}}.ts

@@ -1,48 +0,0 @@
-import type { Context } from '@deepseek-ai/cordis'
-import {
-  CORDISX_PLUGIN_MANIFEST_SCHEMA_V1,
-  type CordisXPluginManifestV1,
-} from 'cordisx/contracts'
-import type {} from 'cordisx/contracts'
-
-export const manifest = {
-  $schema: CORDISX_PLUGIN_MANIFEST_SCHEMA_V1,
-  schemaVersion: 1,
-  id: '{{pluginId}}',
-  name: '{{packageName}}',
-  capabilities: [],
-} as const satisfies CordisXPluginManifestV1
-
-export const inject = ['i18n', 'commands', 'slots']
-
-export function apply(ctx: Context): void {
-  ctx.i18n.define({
-    namespace: '{{pluginId}}',
-    locale: 'en',
-    default: true,
-    messages: { 'command.hello': 'Say hello from {{packageName}}' },
-  })
-  ctx.commands.register({
-    id: 'hello',
-    title: {
-      namespace: '{{pluginId}}',
-      key: 'command.hello',
-      fallback: 'Say hello from {{packageName}}',
-    },
-  }, () => console.info('[{{pluginId}}] hello'))
-  ctx.slots.register({
-    name: 'workspace.toolbar.items',
-    id: 'hello',
-    order: 10,
-  }, {
-    anchor: 'workspace.primary',
-    placement: 'after',
-    label: {
-      namespace: '{{pluginId}}',
-      key: 'command.hello',
-      fallback: 'Say hello from {{packageName}}',
-    },
-    icon: 'host:open',
-    command: { id: 'hello' },
-  })
-}