@vitaliysimkin/create-t-platform-app 0.0.0-stage → 1.0.0-next.0

package/index.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// `npm create @vitaliysimkin/t-platform-app [dir]`: copies template/ (FE app + BE glue). Node >= 22.
+import { spawnSync } from 'node:child_process'
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join, relative, resolve } from 'node:path'
+import { createInterface } from 'node:readline/promises'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const TEMPLATE = join(here, 'template')
+const DEFAULT_SERVER_CORE = '../../t-platform/backend/src/TPlatform.Server/TPlatform.Server.csproj'
+const fail = (msg) => {
+  console.error(`error: ${msg}`)
+  process.exit(1)
+}
+
+const { values: o, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    name: { type: 'string' },
+    title: { type: 'string' },
+    'core-source': { type: 'string' },
+    'server-core': { type: 'string' },
+    'no-install': { type: 'boolean', default: false },
+  },
+})
+
+let dir = positionals[0]
+let { name, title } = o
+if (process.stdin.isTTY && (!dir || !name || !title)) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  const ask = async (q, def) => (await rl.question(`${q} (${def}): `)).trim() || def
+  dir ??= await ask('Folder', 't-platform-app')
+  name ??= await ask('Name', basename(resolve(dir)))
+  title ??= await ask('Title', name)
+  rl.close()
+}
+dir ??= 't-platform-app'
+name ??= basename(resolve(dir))
+title ??= name
+
+if (!/^[a-z][a-z0-9-]*$/.test(name))
+  fail(`invalid name "${name}": use lowercase letters, digits and "-" (^[a-z][a-z0-9-]*$).`)
+const target = resolve(dir)
+if (existsSync(target) && readdirSync(target).length) fail(`${target}: folder is not empty.`)
+
+const own = JSON.parse(readFileSync(join(here, 'package.json'), 'utf8')).version
+const vars = {
+  __NAME__: name,
+  __TITLE__: title,
+  // exact pin: the core released with this scaffolder, or a local tarball/folder (tests)
+  __CORE__: o['core-source'] ? `file:${resolve(o['core-source'])}` : own,
+  __SERVER_CORE__: o['server-core'] ? resolve(o['server-core']) : DEFAULT_SERVER_CORE,
+}
+const fill = (s) =>
+  s.replace(/__(NAME|TITLE|CORE|SERVER_CORE)__/g, (k) =>
+    k === '__TITLE__' ? vars[k].replace(/['"<>&\\]/g, '') : vars[k],
+  )
+
+for (const f of walk(TEMPLATE)) {
+  // npm pack drops `.gitignore`, so the template keeps it as `gitignore`
+  const out = join(target, relative(TEMPLATE, f).replace(/(^|[\\/])gitignore$/, '$1.gitignore'))
+  mkdirSync(dirname(out), { recursive: true })
+  writeFileSync(out, fill(readFileSync(f, 'utf8')))
+}
+console.log(`created: ${target}`)
+
+if (!o['no-install']) {
+  const r = spawnSync('npm', ['install'], {
+    cwd: target,
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  })
+  if (r.status !== 0) fail('npm install failed.')
+  // agent material ships with the core: AGENTS.md and `.claude/skills/t-platform-*`
+  const agents = join(target, 'node_modules/@vitaliysimkin/t-platform-ui/agents')
+  if (!existsSync(agents)) fail(`${agents}: not found.`)
+  cpSync(join(agents, 'AGENTS.section.md'), join(target, 'AGENTS.md'))
+  for (const s of readdirSync(join(agents, 'skills')))
+    cpSync(join(agents, 'skills', s), join(target, '.claude/skills', `t-platform-${s}`), {
+      recursive: true,
+    })
+}
+console.log(`Next:\n  cd ${relative(process.cwd(), target) || '.'}\n  npm run dev:mock`)
+
+function walk(d) {
+  return readdirSync(d, { withFileTypes: true }).flatMap((e) =>
+    e.isDirectory() ? walk(join(d, e.name)) : [join(d, e.name)],
+  )
+}

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@vitaliysimkin/create-t-platform-app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-next.0",
+  "description": "Create a t-platform service: FE app + small BE glue (`npm create @vitaliysimkin/t-platform-app`).",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vitaliysimkin/t-platform.git",
+    "directory": "ui/packages/create-app"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "create-t-platform-app": "index.js"
+  },
+  "files": [
+    "index.js",
+    "template"
+  ],
+  "engines": {
+    "node": ">=22"
+  }
+}

package/template/README.md

@@ -0,0 +1,13 @@
+# `__NAME__`
+
+Frontend (`src/`, Vue + `@vitaliysimkin/t-platform-ui`) and backend glue (`server/`, .NET 10 + `TPlatform.Server`).
+
+| Command                                                           | What                                              |
+| ----------------------------------------------------------------- | ------------------------------------------------- |
+| `npm run dev:mock`                                                | Frontend with the mock backend                    |
+| `npm run server` + `npm run dev`                                  | Real backend on :5168 + frontend (proxies `/api`) |
+| `npm test`, `npm run typecheck`, `npm run check`, `npm run build` | Checks and build                                  |
+| `npx t-platform new extension <id>`                               | New extension (FE + BE part)                      |
+
+`server/App.Server.csproj` references `TPlatform.Server` by path until it ships on NuGet: `TPlatformServerPath`, by default a `t-platform` clone next to this folder.
+Override it with `dotnet build server -p:TPlatformServerPath=/path/to/TPlatform.Server.csproj`.

package/template/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+*.tsbuildinfo
+server/bin/
+server/obj/
+server/data/

package/template/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>__TITLE__</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/template/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "__NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "dev:mock": "vite --mode mock",
+    "server": "dotnet run --project server",
+    "build": "vite build",
+    "typecheck": "vue-tsc --noEmit",
+    "test": "vitest run",
+    "check": "t-platform check"
+  },
+  "dependencies": {
+    "@iconify/vue": "^5.0.5",
+    "@vitaliysimkin/t-components": "^1.5.1",
+    "@vitaliysimkin/t-platform-ui": "__CORE__",
+    "@vueuse/core": "^14.4.0",
+    "vue": "^3.5.44",
+    "vue-i18n": "^11.4.18",
+    "vue-router": "^4.6.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vue/test-utils": "^2.5.1",
+    "happy-dom": "^21.0.4",
+    "typescript": "~6.0.3",
+    "vite": "^8.3.5",
+    "vitest": "^5.1.0",
+    "vue-tsc": "^3.3.14"
+  }
+}

package/template/server/App.Server.csproj

@@ -0,0 +1,11 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <TPlatformServerPath Condition="'$(TPlatformServerPath)' == ''">__SERVER_CORE__</TPlatformServerPath>
+  </PropertyGroup>
+  <ItemGroup>
+    <ProjectReference Include="$(TPlatformServerPath)" />
+  </ItemGroup>
+</Project>

package/template/server/Program.cs

@@ -0,0 +1,8 @@
+using TPlatform.Server;
+
+var builder = WebApplication.CreateBuilder(args);
+builder.AddTPlatform();
+// t-platform:extensions
+var app = builder.Build();
+app.MapTPlatform();
+app.Run();

package/template/server/Properties/launchSettings.json

@@ -0,0 +1,11 @@
+{
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "applicationUrl": "http://localhost:5168",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

package/template/server/appsettings.json

@@ -0,0 +1,5 @@
+{
+  "TPlatform": {
+    "DataRoot": "./data"
+  }
+}

package/template/src/extensions/dashboard/DashboardPage.test.ts

@@ -0,0 +1,11 @@
+import { mountExtension } from '@vitaliysimkin/t-platform-ui/testing'
+import { expect, it } from 'vitest'
+import dashboard from './index'
+
+it('dashboard page shows the server health from the mock', async () => {
+  const t = await mountExtension(dashboard)
+  expect(t.router.currentRoute.value.path).toBe('/dashboard')
+  expect(t.wrapper.find('h1').text()).toBe('Dashboard')
+  expect(t.wrapper.find('.dashboard-status').text()).toBe('Server is up.')
+  expect(t.http.last('GET', '/api/health')).toBeDefined()
+})

package/template/src/extensions/dashboard/contract.test.ts

@@ -0,0 +1,5 @@
+import { expectValidExtension } from '@vitaliysimkin/t-platform-ui/testing'
+import { it } from 'vitest'
+import ext from './index'
+
+it('dashboard: valid extension', () => expectValidExtension(ext))

package/template/src/extensions/dashboard/index.ts

@@ -0,0 +1,18 @@
+import { defineExtension, defineExtensionStore } from '@vitaliysimkin/t-platform-ui'
+import en from './messages/en'
+
+export const useDashboard = defineExtensionStore('dashboard', (ctx) => ctx)
+
+/** Frontend-only home page; it reads the core `GET /api/health`. */
+export default defineExtension({
+  id: 'dashboard',
+  title: 'Dashboard',
+  icon: 'platform:grid',
+  home: { route: '/dashboard' },
+  messages: { en },
+  routes: [
+    { path: '/dashboard', name: 'dashboard', component: () => import('./pages/DashboardPage') },
+  ],
+  menu: [{ title: 'Dashboard', icon: 'platform:grid', route: '/dashboard', order: 0 }],
+  mock: () => import('./mock'),
+})

package/template/src/extensions/dashboard/messages/en.ts

@@ -0,0 +1,5 @@
+export default {
+  title: 'Dashboard',
+  ok: 'Server is up.',
+  down: 'Server is down.',
+}

package/template/src/extensions/dashboard/mock.ts

@@ -0,0 +1,6 @@
+import { defineMock } from '@vitaliysimkin/t-platform-ui/mock'
+
+// Frontend-only extension: mock paths are absolute (the core `GET /api/health`).
+export default defineMock((m) => {
+  m.get('/api/health', () => ({ status: 'ok' }), { public: true })
+})

package/template/src/extensions/dashboard/pages/DashboardPage.ts

@@ -0,0 +1,17 @@
+import { defineComponent, h } from 'vue'
+import { useDashboard } from '../index'
+
+export default defineComponent({
+  name: 'DashboardPage',
+  setup() {
+    const ctx = useDashboard()
+    const health = ctx.resource(() => ctx.http.get<{ status: string }>('/api/health'), {
+      initial: { status: '' },
+    })
+    const status = () =>
+      health.error.value ??
+      (health.loaded.value ? ctx.t(health.data.value.status === 'ok' ? 'ok' : 'down') : '…')
+    return () =>
+      h('section', [h('h1', ctx.t('title')), h('p', { class: 'dashboard-status' }, status())])
+  },
+})

package/template/src/extensions/index.ts

@@ -0,0 +1,5 @@
+// <t-platform:extensions>
+import dashboard from './dashboard'
+
+export const extensions = [dashboard]
+// </t-platform:extensions>

package/template/src/main.ts

@@ -0,0 +1,18 @@
+import '@vitaliysimkin/t-platform-ui/styles.css'
+import { createPlatformApp, sessionCookieAuth } from '@vitaliysimkin/t-platform-ui'
+import { extensions } from './extensions'
+
+createPlatformApp({
+  name: '__NAME__',
+  title: '__TITLE__',
+  extensions,
+  auth: {
+    provider: sessionCookieAuth({
+      meUrl: '/api/me',
+      loginUrl: '/api/auth/login',
+      logoutUrl: '/api/auth/logout',
+      setupUrl: '/api/auth/setup',
+    }),
+  },
+  backendExtensions: {},
+}).mount('#app')

package/template/tests/smoke.test.ts

@@ -0,0 +1,13 @@
+import { mountExtension } from '@vitaliysimkin/t-platform-ui/testing'
+import { describe, expect, it } from 'vitest'
+import dashboard from '../src/extensions/dashboard'
+import { extensions } from '../src/extensions'
+
+describe.each(['desktop', 'mobile'] as const)('smoke (%s)', (viewport) => {
+  it('boots all extensions and opens the home page', async () => {
+    const others = extensions.filter((e) => e !== dashboard)
+    const t = await mountExtension(dashboard, { extensions: others, viewport, route: '/' })
+    // the home page (dashboard) is rendered at `/`
+    expect(t.wrapper.find('.dashboard-status').exists()).toBe(true)
+  })
+})

package/template/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "types": ["node", "vite/client"]
+  },
+  "include": ["src", "tests", "vite.config.ts", "vitest.config.ts"]
+}

package/template/vite.config.ts

@@ -0,0 +1,6 @@
+import { platform } from '@vitaliysimkin/t-platform-ui/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [platform({ name: '__NAME__', apiProxy: 'http://localhost:5168' })],
+})

package/template/vitest.config.ts

@@ -0,0 +1,5 @@
+import { platformVitest } from '@vitaliysimkin/t-platform-ui/testing/vitest'
+import { mergeConfig } from 'vitest/config'
+import viteConfig from './vite.config.ts'
+
+export default mergeConfig(viteConfig, platformVitest())

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.