@antigenic-oss/paint 0.2.3 → 0.2.5

package/README.md

@@ -48,6 +48,27 @@ bun add -g @antigenic-oss/paint
 
 Requires Node.js `>=20.9.0`.
 
+If `paint` is not found after install, add your global bin directory to `PATH`
+once:
+
+```bash
+# Bun
+echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
+
+# npm (uses npm global prefix)
+echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
+
+# pnpm
+pnpm setup
+```
+
+After install, run:
+
+```bash
+paint help
+paint start
+```
+
 Then use:
 
 ```bash

package/bin/paint.js

@@ -10,6 +10,21 @@ const { spawn, spawnSync } = require('node:child_process')
 const ENTRY_REAL_PATH = fs.realpathSync(__filename)
 const APP_ROOT = path.resolve(path.dirname(ENTRY_REAL_PATH), '..')
 const STATE_DIR = path.join(os.homedir(), '.paint')
+const APP_PACKAGE_JSON = path.join(APP_ROOT, 'package.json')
+const APP_VERSION = (() => {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(APP_PACKAGE_JSON, 'utf8'))
+    return typeof pkg.version === 'string' ? pkg.version : 'dev'
+  } catch {
+    return 'dev'
+  }
+})()
+const RUNNING_FROM_NODE_MODULES = APP_ROOT.includes(
+  `${path.sep}node_modules${path.sep}`,
+)
+const RUNTIME_ROOT = RUNNING_FROM_NODE_MODULES
+  ? path.join(STATE_DIR, 'runtime', APP_VERSION)
+  : APP_ROOT
 
 const APP_STATE_FILE = path.join(STATE_DIR, 'server.json')
 const TERMINAL_STATE_FILE = path.join(STATE_DIR, 'terminal.json')
@@ -52,6 +67,62 @@ function ensureStateDir() {
   fs.mkdirSync(STATE_DIR, { recursive: true })
 }
 
+function ensureRuntimeRoot() {
+  if (!RUNNING_FROM_NODE_MODULES) return APP_ROOT
+
+  const stampFile = path.join(RUNTIME_ROOT, '.paint-runtime-stamp.json')
+  if (fs.existsSync(stampFile)) {
+    return RUNTIME_ROOT
+  }
+
+  ensureStateDir()
+  fs.mkdirSync(path.dirname(RUNTIME_ROOT), { recursive: true })
+
+  // Build outside node_modules so Next.js webpack always transpiles TS sources.
+  fs.rmSync(RUNTIME_ROOT, { recursive: true, force: true })
+  fs.mkdirSync(RUNTIME_ROOT, { recursive: true })
+
+  const runtimeEntries = [
+    'bin',
+    'public',
+    'src',
+    'next-env.d.ts',
+    'next.config.ts',
+    'postcss.config.mjs',
+    'tsconfig.json',
+    'package.json',
+    'README.md',
+    'LICENSE',
+    'NOTICE',
+  ]
+
+  for (const entry of runtimeEntries) {
+    const src = path.join(APP_ROOT, entry)
+    const dst = path.join(RUNTIME_ROOT, entry)
+    if (!fs.existsSync(src)) continue
+
+    fs.cpSync(src, dst, { recursive: true, force: true })
+  }
+
+  const runtimeNodeModules = path.join(RUNTIME_ROOT, 'node_modules')
+  fs.symlinkSync(path.join(APP_ROOT, 'node_modules'), runtimeNodeModules, 'dir')
+
+  fs.writeFileSync(
+    stampFile,
+    JSON.stringify(
+      {
+        version: APP_VERSION,
+        sourceRoot: APP_ROOT,
+        preparedAt: now(),
+      },
+      null,
+      2,
+    ),
+  )
+
+  return RUNTIME_ROOT
+}
+
 function now() {
   return new Date().toISOString()
 }
@@ -181,12 +252,12 @@ function validatePort(port, flagName) {
 }
 
 function spawnDetached(command, args, opts) {
-  const { env, logFile } = opts
+  const { env, logFile, cwd = APP_ROOT } = opts
   const fd = fs.openSync(logFile, 'a')
   fs.writeSync(fd, `\n[${now()}] spawn: ${command} ${args.join(' ')}\n`)
 
   const child = spawn(command, args, {
-    cwd: APP_ROOT,
+    cwd,
     env,
     detached: true,
     stdio: ['ignore', fd, fd],
@@ -262,8 +333,9 @@ function ensureNextInstalled() {
 function ensureBuilt(forceRebuild) {
   ensureStateDir()
   ensureNextInstalled()
+  const runtimeRoot = ensureRuntimeRoot()
 
-  const buildIdPath = path.join(APP_ROOT, '.next', 'BUILD_ID')
+  const buildIdPath = path.join(runtimeRoot, '.next', 'BUILD_ID')
   if (!forceRebuild && fs.existsSync(buildIdPath)) {
     return
   }
@@ -274,7 +346,7 @@ function ensureBuilt(forceRebuild) {
   // Use webpack for packaged/global runtime builds.
   // Turbopack can fail when the app lives under node_modules.
   const result = spawnSync(process.execPath, [NEXT_BIN, 'build', '--webpack'], {
-    cwd: APP_ROOT,
+    cwd: runtimeRoot,
     env: process.env,
     stdio: 'inherit',
   })
@@ -302,6 +374,7 @@ async function startApp(options) {
 
   ensureBuilt(options.rebuild)
   ensureStateDir()
+  const runtimeRoot = ensureRuntimeRoot()
 
   const webChild = spawnDetached(
     process.execPath,
@@ -314,6 +387,7 @@ async function startApp(options) {
       options.host,
     ],
     {
+      cwd: runtimeRoot,
       env: process.env,
       logFile: WEB_LOG_FILE,
     },

package/bin/postinstall.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+const path = require('node:path')
+const fs = require('node:fs')
+const { spawnSync } = require('node:child_process')
+
+function detectRcFile() {
+  const shell = process.env.SHELL || ''
+  const home = process.env.HOME || '~'
+  const base = path.basename(shell)
+
+  if (base === 'zsh') return `${home}/.zshrc`
+  if (base === 'bash') return `${home}/.bashrc`
+  if (base === 'fish') return `${home}/.config/fish/config.fish`
+  return `${home}/.profile`
+}
+
+function shouldPrintHint() {
+  const isGlobal = process.env.npm_config_global === 'true'
+  const ua = process.env.npm_config_user_agent || ''
+  const isBun = ua.includes('bun/')
+  return isGlobal || isBun
+}
+
+function resolveNextBin(appRoot) {
+  const directPath = path.join(
+    appRoot,
+    'node_modules',
+    'next',
+    'dist',
+    'bin',
+    'next',
+  )
+  if (fs.existsSync(directPath)) {
+    return directPath
+  }
+
+  try {
+    return require.resolve('next/dist/bin/next', { paths: [appRoot] })
+  } catch {
+    return null
+  }
+}
+
+function tryWarmBuild() {
+  if (process.env.PAINT_SKIP_POSTINSTALL_BUILD === '1') {
+    return
+  }
+
+  const appRoot = path.resolve(__dirname, '..')
+  const buildIdPath = path.join(appRoot, '.next', 'BUILD_ID')
+  if (fs.existsSync(buildIdPath)) {
+    return
+  }
+
+  const nextBin = resolveNextBin(appRoot)
+  if (!nextBin) {
+    return
+  }
+
+  console.log('@antigenic-oss/paint: prebuilding runtime (webpack)...')
+  const result = spawnSync(
+    process.execPath,
+    [nextBin, 'build', '--webpack'],
+    {
+      cwd: appRoot,
+      env: process.env,
+      stdio: 'inherit',
+    },
+  )
+
+  // Keep install resilient across package managers/environments where
+  // install-time build is unsupported; first-run build remains as fallback.
+  if (result.status !== 0) {
+    console.warn(
+      '@antigenic-oss/paint: postinstall prebuild failed, will build on first `paint start`.',
+    )
+  }
+}
+
+tryWarmBuild()
+
+if (shouldPrintHint()) {
+  const rcFile = detectRcFile()
+  const exportLine = 'export PATH="$HOME/.bun/bin:$PATH"'
+  console.log('\n@antigenic-oss/paint: if `paint` is not found, run:')
+  console.log(`echo '${exportLine}' >> ${rcFile} && source ${rcFile}`)
+  console.log('Then run: paint help\n')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antigenic-oss/paint",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Visual editor for localhost web projects with a global paint CLI",
   "license": "Apache-2.0",
   "homepage": "https://github.com/Antigenic-OSS/pAInt",
@@ -46,6 +46,7 @@
     "dev:terminal": "node ./bin/terminal-server.js",
     "dev:all": "node ./bin/terminal-server.js & node ./bin/bridge-server.js & next dev --port 4000 --turbopack",
     "bridge": "node ./bin/bridge-server.js",
+    "postinstall": "node ./bin/postinstall.js",
     "build": "next build",
     "start": "next start --port 4000",
     "lint": "biome lint .",

package/tsconfig.json

@@ -17,6 +17,7 @@
     "isolatedModules": true,
     "jsx": "react-jsx",
     "incremental": true,
+    "baseUrl": ".",
     "plugins": [
       {
         "name": "next"