@openload28/create-tt 1.0.0-dev.20260828.263

package/README.md

@@ -0,0 +1,34 @@
+# @openload28/create-tt
+
+Create a ready-to-run Vite + TypeScript + tt project:
+
+```sh
+bunx @openload28/create-tt@next my-app
+```
+
+Add tt to an existing TypeScript project. The initializer detects Vite,
+Rollup, Rolldown, webpack, Rspack, esbuild, or Farm from `package.json`:
+
+```sh
+bunx @openload28/create-tt@next init
+```
+
+The initializer updates `package.json` structurally. For bundlers with a
+declarative config, it generates an `tt.*.config.mjs` wrapper instead of
+rewriting arbitrary user code. Existing scripts and config files stay intact.
+Use `--no-install` in CI or when dependencies will be installed later.
+New projects use Bun for dependency installation and scripts. Existing projects
+keep the package manager declared in `package.json` or selected by their lockfile.
+
+For packages published to a private or local npm-compatible registry, pass the
+registry through the entire bootstrap:
+
+```sh
+BUN_CONFIG_REGISTRY=http://127.0.0.1:4873 \
+  bunx @openload28/create-tt@next my-app --registry http://127.0.0.1:4873
+```
+
+The Nightly initializer installs the `next` channels of
+`@openload28/tt-lang` and `@openload28/unplugin-tt`. The current TypeScript toolchain
+prerequisite is documented in the repository
+[installation guide](https://github.com/load28/tt/blob/main/docs/getting-started.md).

package/bin/create-tt.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { run } from '../src/installer.js'
+
+run(process.argv.slice(2)).catch((error) => {
+  console.error(`@openload28/create-tt: ${error.message}`)
+  process.exitCode = 1
+})

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@openload28/create-tt",
+  "version": "1.0.0-dev.20260828.263",
+  "description": "Create a new tt project or add tt to an existing TypeScript project",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "bin": {
+    "create-tt": "bin/create-tt.js"
+  },
+  "files": [
+    "bin/create-tt.js",
+    "src/installer.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/load28/tt",
+    "directory": "packages/create-tt"
+  },
+  "keywords": [
+    "tt",
+    "typescript",
+    "scaffold",
+    "vite"
+  ]
+}

package/src/installer.js

@@ -0,0 +1,337 @@
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
+import { basename, join, relative, resolve } from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+const ownManifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'))
+const ttChannel = dependencyChannel(ownManifest.version)
+const versions = {
+  '@openload28/tt-lang': ttChannel,
+  '@openload28/unplugin-tt': ttChannel,
+  vite: '^8.0.0',
+  // ttc drives the TypeScript the project installs and looks nowhere else,
+  // so a scaffolded project has to install one — the exact version this
+  // repository tests against, which is the whole point: a user runs the
+  // compiler against the TypeScript it was verified with, and an upstream
+  // nightly cannot change their build overnight. Not `7`: declaration
+  // output (`ttc --types`, the editor's `.tt.d.ts` sidecars) needs the emit
+  // API that arrived in 7.1, and `7` resolves to the 7.0 line because
+  // ranges do not match prereleases (TASK-256). When 7.1 is released this
+  // moves to `7` everywhere at once, held by
+  // npm/scripts/typescript-version.test.mjs.
+  typescript: "7.1.0-dev.20260826.1",
+}
+
+export function dependencyChannel(packageVersion) {
+  if (/-dev\./.test(packageVersion)) return 'next'
+  if (/-rc(?:\.|$)/.test(packageVersion)) return 'rc'
+  return 'latest'
+}
+
+const bundlers = {
+  vite: {
+    packages: ['vite'],
+    configs: ['vite.config.ts', 'vite.config.js', 'vite.config.mts', 'vite.config.mjs'],
+    module: '@openload28/unplugin-tt/vite',
+    wrapper: 'tt.vite.config.mjs',
+    commands: { dev: 'vite', build: 'vite build' },
+  },
+  rollup: {
+    packages: ['rollup'],
+    configs: ['rollup.config.ts', 'rollup.config.js', 'rollup.config.mjs'],
+    module: '@openload28/unplugin-tt/rollup',
+    wrapper: 'tt.rollup.config.mjs',
+    commands: { dev: 'rollup --watch', build: 'rollup' },
+  },
+  rolldown: {
+    packages: ['rolldown'],
+    configs: ['rolldown.config.ts', 'rolldown.config.js', 'rolldown.config.mjs'],
+    module: '@openload28/unplugin-tt/rolldown',
+    wrapper: 'tt.rolldown.config.mjs',
+    commands: { dev: 'rolldown --watch', build: 'rolldown' },
+  },
+  webpack: {
+    packages: ['webpack'],
+    configs: ['webpack.config.ts', 'webpack.config.js', 'webpack.config.cjs', 'webpack.config.mjs'],
+    module: '@openload28/unplugin-tt/webpack',
+    wrapper: 'tt.webpack.config.mjs',
+    commands: { dev: 'webpack serve', build: 'webpack' },
+  },
+  rspack: {
+    packages: ['@rspack/core'],
+    configs: ['rspack.config.ts', 'rspack.config.js', 'rspack.config.mjs'],
+    module: '@openload28/unplugin-tt/rspack',
+    wrapper: 'tt.rspack.config.mjs',
+    commands: { dev: 'rspack serve', build: 'rspack build' },
+  },
+  farm: {
+    packages: ['@farmfe/core'],
+    configs: ['farm.config.ts', 'farm.config.js', 'farm.config.mjs'],
+    module: '@openload28/unplugin-tt/farm',
+    wrapper: 'tt.farm.config.mjs',
+    commands: { dev: 'farm start', build: 'farm build' },
+  },
+  esbuild: {
+    packages: ['esbuild'],
+    configs: [],
+    module: '@openload28/unplugin-tt/esbuild',
+  },
+}
+
+export async function run(argv, io = console) {
+  const options = parseArguments(argv)
+  if (options.help) {
+    io.log(help)
+    return
+  }
+  const result = options.command === 'init'
+    ? await initializeExisting(options)
+    : await createProject(options)
+
+  if (options.install) installDependencies(result.root, result.packageManager, options.registry)
+  printResult(result, io)
+}
+
+export async function createProject(options) {
+  const root = resolve(options.directory ?? 'my-tt-app')
+  if (existsSync(root) && (await readdir(root)).length > 0) {
+    throw new Error(`target directory is not empty: ${root}`)
+  }
+  await mkdir(join(root, 'src'), { recursive: true })
+  const packageManager = options.packageManager ?? 'bun'
+  const name = packageName(basename(root))
+  const manifest = {
+    name,
+    private: true,
+    version: '0.0.0',
+    type: 'module',
+    scripts: {
+      dev: 'vite',
+      build: 'ttc --check-types src && vite build',
+      check: 'ttc --check-types src',
+    },
+    devDependencies: {
+      '@openload28/tt-lang': versions['@openload28/tt-lang'],
+      '@openload28/unplugin-tt': versions['@openload28/unplugin-tt'],
+      typescript: versions.typescript,
+      vite: versions.vite,
+    },
+  }
+  await writeJson(join(root, 'package.json'), manifest)
+  await writeJson(join(root, 'tsconfig.json'), tsconfig())
+  await writeFile(join(root, 'vite.config.ts'), viteConfig)
+  await writeFile(join(root, 'index.html'), indexHtml)
+  await writeFile(join(root, 'src/main.ts'), "import './app.tt'\n")
+  await writeFile(join(root, 'src/app.tt'), starterSource)
+  await writeFile(join(root, '.gitignore'), 'node_modules/\ndist/\n.tt-types/\n')
+  if (options.registry) {
+    await writeFile(join(root, 'bunfig.toml'), `[install]\nregistry = ${JSON.stringify(options.registry)}\n`)
+  }
+  return { root, packageManager, mode: 'create', bundler: 'vite', files: ['src/main.ts', 'src/app.tt', 'vite.config.ts'] }
+}
+
+export async function initializeExisting(options) {
+  const root = resolve(options.directory ?? '.')
+  const manifestPath = join(root, 'package.json')
+  if (!existsSync(manifestPath)) throw new Error(`package.json not found in ${root}`)
+
+  const source = await readFile(manifestPath, 'utf8')
+  const manifest = JSON.parse(source)
+  const packageManager = options.packageManager ?? detectPackageManager(root, manifest)
+  const bundler = options.bundler === 'auto' ? detectBundler(manifest) : options.bundler
+  const devDependencies = manifest.devDependencies ?? {}
+  devDependencies['@openload28/tt-lang'] ??= versions['@openload28/tt-lang']
+  devDependencies.typescript ??= versions.typescript
+  manifest.devDependencies = devDependencies
+  manifest.scripts ??= {}
+  manifest.scripts['tt:check'] ??= 'ttc --check-types src'
+
+  const files = []
+  let manualModule
+  if (bundler && bundler !== 'none') {
+    devDependencies['@openload28/unplugin-tt'] ??= versions['@openload28/unplugin-tt']
+    const adapter = bundlers[bundler]
+    if (!adapter) throw new Error(`unsupported bundler: ${bundler}`)
+    const base = adapter.configs.find((file) => existsSync(join(root, file)))
+    if (bundler === 'esbuild') {
+      manualModule = adapter.module
+    } else {
+      await writeFile(join(root, adapter.wrapper), wrapperConfig(adapter.module, base))
+      files.push(adapter.wrapper)
+      manifest.scripts['tt:dev'] ??= `${adapter.commands.dev} --config ${adapter.wrapper}`
+      manifest.scripts['tt:build'] ??= `ttc --check-types src && ${adapter.commands.build} --config ${adapter.wrapper}`
+    }
+  } else {
+    manifest.scripts['tt:build'] ??= 'ttc -o .tt-build src'
+  }
+
+  await writeJson(manifestPath, manifest, indentation(source))
+  return { root, packageManager, mode: 'init', bundler: bundler ?? 'none', files, manualModule }
+}
+
+export function detectBundler(manifest) {
+  const dependencies = { ...manifest.dependencies, ...manifest.devDependencies }
+  return Object.entries(bundlers).find(([, adapter]) =>
+    adapter.packages.some((name) => name in dependencies))?.[0] ?? 'none'
+}
+
+function parseArguments(argv) {
+  const args = [...argv]
+  const options = {
+    command: args[0] === 'init' ? args.shift() : 'create',
+    install: true,
+    bundler: 'auto',
+  }
+  while (args.length) {
+    const arg = args.shift()
+    if (arg === '--help' || arg === '-h') options.help = true
+    else if (arg === '--no-install') options.install = false
+    else if (arg === '--bundler') options.bundler = requiredValue(arg, args)
+    else if (arg === '--package-manager') options.packageManager = requiredValue(arg, args)
+    else if (arg === '--registry') options.registry = registryUrl(requiredValue(arg, args))
+    else if (!arg.startsWith('-') && !options.directory) options.directory = arg
+    else throw new Error(`unknown argument: ${arg}`)
+  }
+  if (!['auto', 'none', ...Object.keys(bundlers)].includes(options.bundler)) {
+    throw new Error(`unsupported bundler: ${options.bundler}`)
+  }
+  if (options.packageManager && !['npm', 'pnpm', 'yarn', 'bun'].includes(options.packageManager)) {
+    throw new Error(`unsupported package manager: ${options.packageManager}`)
+  }
+  if (options.command === 'create' && options.packageManager && options.packageManager !== 'bun') {
+    throw new Error('new projects use Bun; --package-manager only applies to init')
+  }
+  if (options.command === 'create' && !['auto', 'vite'].includes(options.bundler)) {
+    throw new Error('new projects use Vite; --bundler only selects vite for create')
+  }
+  return options
+}
+
+function requiredValue(flag, args) {
+  const value = args.shift()
+  if (!value || value.startsWith('-')) throw new Error(`${flag} needs a value`)
+  return value
+}
+
+function detectPackageManager(root, manifest = {}) {
+  const declared = typeof manifest.packageManager === 'string'
+    ? manifest.packageManager.split('@')[0]
+    : undefined
+  if (['npm', 'pnpm', 'yarn', 'bun'].includes(declared)) return declared
+  const locks = [['pnpm-lock.yaml', 'pnpm'], ['yarn.lock', 'yarn'], ['bun.lock', 'bun'], ['bun.lockb', 'bun']]
+  return locks.find(([file]) => existsSync(join(root, file)))?.[1] ?? 'npm'
+}
+
+function installDependencies(root, packageManager, registry) {
+  const args = ['install']
+  if (registry) args.push('--registry', registry)
+  const result = spawnSync(packageManager, args, { cwd: root, stdio: 'inherit' })
+  if (result.error) throw result.error
+  if (result.status !== 0) throw new Error(`${packageManager} install exited with status ${result.status}`)
+}
+
+function registryUrl(value) {
+  let url
+  try {
+    url = new URL(value)
+  } catch {
+    throw new Error(`invalid registry URL: ${value}`)
+  }
+  if (!['http:', 'https:'].includes(url.protocol)) throw new Error('registry URL must use http or https')
+  if (url.username || url.password) throw new Error('pass registry credentials through Bun configuration or environment variables')
+  return url.href
+}
+
+function printResult(result, io) {
+  const location = relative(process.cwd(), result.root) || '.'
+  io.log(result.mode === 'create' ? `Created a tt project in ${location}.` : `Added tt to ${location}.`)
+  if (result.files.length) io.log(`Generated: ${result.files.join(', ')}`)
+  if (result.manualModule) {
+    io.log(`Add tt() from ${result.manualModule} to your esbuild plugins array.`)
+  }
+  io.log(result.mode === 'create' ? `Run: cd ${location} && ${runScript(result.packageManager, 'dev')}` : `Run: ${runScript(result.packageManager, 'tt:check')}`)
+}
+
+function runScript(packageManager, script) {
+  return packageManager === 'npm' ? `npm run ${script}` : `${packageManager} run ${script}`
+}
+
+function wrapperConfig(moduleName, base) {
+  const baseImport = base ? `import base from './${base}'\n` : 'const base = {}\n'
+  return `import tt from '${moduleName}'\n${baseImport}
+const addRl = (config = {}) => Array.isArray(config)
+  ? config.map(addRl)
+  : { ...config, plugins: [tt(), ...(config.plugins ?? [])] }
+
+export default typeof base === 'function'
+  ? async (...args) => addRl(await base(...args))
+  : Promise.resolve(base).then(addRl)
+`
+}
+
+function tsconfig() {
+  return {
+    compilerOptions: {
+      target: 'ES2022',
+      module: 'Preserve',
+      moduleResolution: 'Bundler',
+      strict: true,
+      noEmit: true,
+      skipLibCheck: true,
+    },
+    include: ['src', 'vite.config.ts'],
+  }
+}
+
+function packageName(value) {
+  const normalized = value.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '')
+  return normalized || 'my-tt-app'
+}
+
+function indentation(source) {
+  return source.match(/\n([ \t]+)\S/)?.[1] ?? '  '
+}
+
+async function writeJson(path, value, space = '  ') {
+  await writeFile(path, `${JSON.stringify(value, null, space)}\n`)
+}
+
+const viteConfig = `import { defineConfig } from 'vite'
+import tt from '@openload28/unplugin-tt/vite'
+
+export default defineConfig({
+  plugins: [tt()],
+})
+`
+
+const indexHtml = `<!doctype html>
+<html lang="en">
+  <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>tt app</title></head>
+  <body><main id="app"></main><script type="module" src="/src/main.ts"></script></body>
+</html>
+`
+
+const starterSource = `variant Greeting {
+  Hello(name: string),
+  Welcome,
+}
+
+const greeting = Greeting.Hello('tt')
+document.querySelector<HTMLDivElement>('#app')!.textContent = match (greeting) {
+  Hello(name) => \`Hello, \${name}!\`,
+  Welcome => 'Welcome!',
+}
+`
+
+const help = `Create a new tt project or add tt to an existing TypeScript project.
+
+Usage:
+  bunx @openload28/create-tt@next [directory] [--no-install]
+  bunx @openload28/create-tt@next init [directory] [--bundler vite]
+
+Options:
+  --bundler <auto|none|vite|rollup|rolldown|webpack|rspack|esbuild|farm>
+  --package-manager <npm|pnpm|yarn|bun>
+  --registry <url>     install from an npm-compatible private/local registry
+  --no-install
+  -h, --help`