@owdproject/cli 0.0.3 → 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025  Open Web Desktop Team ~ github.com/owdproject
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,33 +1,67 @@
-# Open Web Desktop CLI
+<p align="center">
+  <img width="160" height="160" src="https://avatars.githubusercontent.com/u/65117737?s=160&v=4" />
+</p>
+<h1 align="center">CLI</h1>
+<h3 align="center">
+  Control Panel and Command Line Interface for Open Web Desktop.
+</h3>
 
-This command-line interface (CLI) provides a set of tools to easily manage your project.
+<br />
+
+## Overview
+
+This package provides the official `desktop` (and legacy `owd`) CLI tool for Open Web Desktop. It features a rich Terminal User Interface (TUI) Control Panel to manage your running local OWD dev server, install/remove apps, modules, and themes, configure workspace settings, and scaffold new OWD components.
 
 ## Installation
 
-To install the CLI globally, run:
+```bash
+pnpm add -g @owdproject/cli
+```
+*Note: You can also install it as a devDependency in your OWD workspace project and run it via `pnpm desktop`.*
 
-`npm install -g @owdproject/cli`
+## Features
+
+- **Control Panel (TUI)**: An interactive terminal interface for managing OWD projects.
+- **Scaffolding**: Instantly initialize new workspaces or scaffold new apps and themes.
+- **Package Management**: Install and validate OWD modules from npm, local directories, or custom Git repositories.
+- **Graceful Fallback**: The interactive Control Panel compiles a fast Go-based TUI locally, falling back seamlessly to a JavaScript runner if Go is not available.
 
 ## Usage
 
-Once installed, you can use the CLI commands by typing `npx @owdproject/cli` followed by a command.
+Once installed, run the `desktop` command to open the control panel:
 
-### Available Commands
+```bash
+desktop
+```
 
-- `npx @owdproject/cli create`: Create a new Open Web Desktop project from a template.
-- `npx @owdproject/cli start`: Start the project in development mode (runs Nuxt.js).
-- `npx @owdproject/cli generate`: Generate the project for static deployment.
+### CLI Reference
 
-For more information on each command, use:
+#### Dev Server
+Start the development server for the monorepo or automatically detect a module's playground:
+```bash
+desktop dev [--playground]
+```
 
-`npx @owdproject/cli <command> --help`
+#### Add Packages
+Install apps, modules, or themes from npm, local directories, or custom repositories:
+```bash
+desktop add app-todo --npm
+desktop add theme-nova --dev
+desktop add module-fs --from <github-user>
+```
 
-## Features
+#### Scaffold a Project
+Initialize a fresh OWD workspace:
+```bash
+desktop init [project-name]
+```
 
-- Easy setup for new Open Web Desktop projects.
-- Allows you to start development mode quickly with `npx @owdproject/cli start`.
-- Generates files for static deployment with `npx @owdproject/cli generate`.
+#### Validation
+Check Nuxt module configuration and playground directory structures:
+```bash
+desktop validate
+```
 
 ## License
 
-This project is released under the [MIT License](LICENSE).
+This package is released under the [MIT License](LICENSE).

package/bin/bridge.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+import { writeFileSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  findWorkspaceRoot,
+  loadSettings,
+  desktopPaths,
+  saveSettings
+} from './lib/workspace.js'
+import {
+  readDesktopConfig,
+  writeDesktopConfig,
+  readDesktopDependencies,
+  writeDesktopDependencies
+} from './lib/config.js'
+import { loadCatalog, mergeInstalled } from './lib/catalog.js'
+import { resolveDevTarget } from './lib/playgroundContext.js'
+import {
+  resolveDesktopConfigPath,
+  desktopConfigWritePath
+} from './lib/desktopConfig.js'
+
+function getWorkspaceContext() {
+  const workspaceRoot = findWorkspaceRoot()
+  if (!workspaceRoot) {
+    throw new Error('Not inside an OWD workspace')
+  }
+
+  const devTarget = resolveDevTarget(process.cwd(), workspaceRoot)
+  let paths
+  
+  if (devTarget && devTarget.mode === 'playground') {
+    const playgroundDir = devTarget.playgroundDir
+    const resolved = resolveDesktopConfigPath(playgroundDir)
+    const configWrite = desktopConfigWritePath(playgroundDir)
+    paths = {
+      desktop: playgroundDir,
+      config: resolved?.path ?? configWrite,
+      configWrite,
+      configLegacy: resolved?.legacy ?? false,
+      packageJson: join(playgroundDir, 'package.json'),
+      isPlayground: true,
+      packageName: devTarget.packageName,
+      packageDir: devTarget.packageDir,
+      metaDir: join(playgroundDir, '.desktop'),
+    }
+  } else {
+    paths = {
+      ...desktopPaths(workspaceRoot),
+      isPlayground: false,
+      metaDir: join(workspaceRoot, '.desktop'),
+    }
+  }
+
+  const settings = loadSettings(workspaceRoot, paths.metaDir)
+  
+  let config = { theme: null, apps: [], modules: [] }
+  try {
+    config = readDesktopConfig(paths.config, workspaceRoot)
+  } catch (err) {
+    console.error('Config load error:', err)
+  }
+  const deps = readDesktopDependencies(paths.packageJson)
+  return { workspaceRoot, settings, paths, config, deps }
+}
+
+async function main() {
+  const args = process.argv.slice(2)
+  const cmd = args[0]
+
+  try {
+    if (cmd === '--read') {
+      const ctx = getWorkspaceContext()
+      console.log(JSON.stringify({
+        workspaceRoot: ctx.workspaceRoot,
+        settings: ctx.settings,
+        config: ctx.config,
+        deps: ctx.deps,
+        paths: ctx.paths,
+      }, null, 2))
+    } else if (cmd === '--catalog') {
+      const ctx = getWorkspaceContext()
+      const force = args.includes('--force')
+      const catalog = await loadCatalog(ctx.workspaceRoot, ctx.settings, { force })
+      catalog.entries = mergeInstalled(catalog.entries, ctx.config, ctx.deps, ctx.workspaceRoot)
+      console.log(JSON.stringify(catalog, null, 2))
+    } else if (cmd === '--write') {
+      const ctx = getWorkspaceContext()
+      
+      // Read JSON payload from stdin
+      let input = ''
+      for await (const chunk of process.stdin) {
+        input += chunk
+      }
+      
+      const payload = JSON.parse(input)
+      // payload = { config: { theme, apps, modules }, depsToAdd: { name: version }, depsToRemove: [name], settings?: { ... } }
+      
+      if (payload.config) {
+        writeDesktopConfig(ctx.paths.config, ctx.workspaceRoot, payload.config)
+      }
+      
+      if (payload.depsToAdd || payload.depsToRemove) {
+        writeDesktopDependencies(
+          ctx.paths.packageJson,
+          payload.depsToAdd || {},
+          payload.depsToRemove || []
+        )
+      }
+
+      if (payload.settings) {
+        saveSettings(ctx.workspaceRoot, payload.settings, ctx.paths.metaDir)
+      }
+      
+      console.log(JSON.stringify({ success: true }))
+    } else {
+      console.error('Usage: node bridge.js [--read|--catalog [--force]|--write]')
+      process.exit(1)
+    }
+  } catch (err) {
+    console.error(JSON.stringify({ error: err.message }))
+    process.exit(1)
+  }
+}
+
+main()

package/bin/cli.js

@@ -0,0 +1,433 @@
+import { spawn, execSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { runDevForeground } from './lib/status.js'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import getopts from 'getopts'
+import {
+  resolveSource,
+  printPlan,
+  printNextSteps,
+  runWorkspaceInstall,
+  runNpmInstall,
+} from './lib/install.js'
+import { findWorkspaceRoot, inferKind } from './lib/workspace.js'
+import { resolveDevTarget } from './lib/playgroundContext.js'
+import { scaffoldProject } from './lib/scaffold.js'
+
+const SCOPE = '@owdproject/'
+
+/** @type {Record<string, { configKey: string, workspaceDir: string, nx: string, label: string }>} */
+const KINDS = {
+  app: {
+    label: 'app',
+    configKey: 'apps',
+    workspaceDir: 'apps',
+    nx: 'desktop:install-app',
+  },
+  module: {
+    label: 'module',
+    configKey: 'modules',
+    workspaceDir: 'packages',
+    nx: 'desktop:install-module',
+  },
+  theme: {
+    label: 'theme',
+    configKey: 'theme',
+    workspaceDir: 'themes',
+    nx: 'desktop:install-theme',
+  },
+}
+
+const LEGACY_COMMANDS = {
+  'install-app': 'app',
+  'install-module': 'module',
+  'install-theme': 'theme',
+}
+
+/** @type {string} */
+let commandName = 'desktop'
+
+function buildHelp(name) {
+  return `
+${name} — add apps, modules, and themes to your Open Web Desktop
+
+USAGE
+  ${name}                 Open the control panel (interactive TUI)
+  ${name} dev [--playground]  Start dev server (auto-detects module playground)
+
+CONTROL PANEL (TUI)
+  m                       Open command menu (all actions)
+  s                       Start the Nuxt dev server
+  x                       Stop the Nuxt dev server
+  R                       Reboot the Nuxt dev server (stop + start)
+  w                       Save catalog/theme changes to desktop.config.ts
+  1 / 2 / 3               Apps / Modules / Themes catalog tabs
+  o / O                   Cycle sort (o) or open sort picker (O)
+  i                       Open in-app docs (when module-docs is installed)
+  g                       Settings (GitHub user, SSH, trusted orgs)
+  r                       Refresh package list from GitHub (detects new modules)
+  b                       Run pnpm run generate
+  q / Esc                 Quit
+  ${name} init [dir]      Create a new OWD project (then opens the control panel)
+  ${name} add <package> [options]
+  ${name} add <kind> <name> [options]
+  ${name} validate [path...]  Check Nuxt module + playground layout
+  ${name} template [--dry-run] [--check]  Regenerate client/template/ (maintainers)
+
+TEMPLATE (monorepo maintainers)
+  ${name} template              Write template/ from blueprint + desktop/ + latest npm versions
+  ${name} template --dry-run    Show planned @owdproject/* and starter versions
+  ${name} template --check      Fail if committed template/ differs (CI)
+
+VALIDATE
+  ${name} validate            Validate cwd package, or all apps/themes/modules at repo root
+  ${name} validate .          Validate explicit package directory
+  ${name} validate apps       Validate every @owdproject/* module under apps/
+  --json                      Machine-readable output
+  --strict                    Treat warnings as failures
+  --smoke                     Run dev:prepare + nuxt build playground (slow, CI)
+
+INSTALL SOURCES (control panel or CLI)
+  npm                   registry (default for desktop add)
+  --dev                 clone github.com/owdproject/<package>
+  --from <user>         clone from GitHub user or full git URL (SSH supported)
+
+EXAMPLES
+  pnpm ${name}            # control panel
+  pnpm ${name} dev        # monorepo desktop (from repo root)
+  cd apps/app-about && pnpm ${name} dev   # app-about playground
+  pnpm ${name} dev --playground           # force playground when cwd is in a module
+  ${name} init my-desktop # scaffold + pnpm install + control panel
+  ${name} add app-todo --npm
+  ${name} add app-todo --dev
+  ${name} add module-persistence --from dxlliv
+
+KINDS (optional — inferred from the package name)
+  app       app-*     → apps/
+  module    module-*  → packages/  (kit-* and *-template are not listed in the control panel)
+  theme     theme-*   → themes/
+
+OPTIONS
+  --playground      Start the module playground dev server (when cwd is inside an @owdproject/* package with playground/)
+  --from <source>   Git source (user, user/repo, or URL)
+  --branch <name>   Git branch to clone
+  --npm             Install from npm (default when --from is omitted)
+  --dev, --workspace  Clone from github.com/owdproject/<package>
+  --protocol https|ssh  With --from <user>, use HTTPS (default) or SSH clone URL
+  --dry-run         Print the plan without changing anything
+  -h, --help        Show this help
+
+--from <source>
+  (omit)          npm registry (default)
+  npm             npm registry
+  owdproject      Clone official repo (monorepo only)
+  <github-user>   Clone github.com/<user>/<package> (your fork)
+  <user>/<repo>   Explicit GitHub repo
+  <git-url>       Full clone URL
+
+LEGACY (still supported)
+  ${name} install-app @owdproject/app-todo
+  → prefer: ${name} add app-todo
+`
+}
+
+async function openControlPanel(name) {
+  const cliDir = join(fileURLToPath(import.meta.url), '..')
+  const goDir = join(cliDir, '../go')
+  const binaryPath = join(goDir, 'desktop-go')
+
+  // Compile the Go Control Panel if binary doesn't exist
+  if (!existsSync(binaryPath)) {
+    console.log('Go Control Panel binary not found. Compiling...')
+    try {
+      execSync('go build -o desktop-go .', { cwd: goDir, stdio: 'inherit' })
+      console.log('Go Control Panel compiled successfully!')
+    } catch (err) {
+      console.warn('Failed to compile Go Control Panel, falling back to legacy CP:', err.message)
+      const { runCp } = await import('./cp.js')
+      await runCp(name)
+      return
+    }
+  }
+
+  // Execute Go TUI
+  const child = spawn(binaryPath, [], { stdio: 'inherit' })
+  child.on('exit', (code) => {
+    process.exit(code ?? 0)
+  })
+}
+
+function fail(message, hint) {
+  console.error(`\n✗ ${message}`)
+  if (hint) console.error(`  ${hint}`)
+  console.error(`\nRun \`${commandName} --help\` for usage.\n`)
+  process.exit(1)
+}
+
+function warn(message) {
+  console.warn(`\n⚠ ${message}\n`)
+}
+
+/**
+ * @param {string} input
+ * @param {string | undefined} explicitKind
+ */
+function normalizePackage(input, explicitKind) {
+  let raw = input.trim()
+  if (raw.startsWith(SCOPE)) raw = raw.slice(SCOPE.length)
+
+  if (!raw) {
+    fail('Package name is required.', `Example: ${commandName} add app-todo`)
+  }
+
+  const kind = explicitKind ?? inferKind(raw)
+
+  if (explicitKind) {
+    const prefixes = {
+      app: 'app-',
+      theme: 'theme-',
+      module: ['module-', 'kit-'],
+    }
+    const expected = prefixes[explicitKind]
+    const list = Array.isArray(expected) ? expected : [expected]
+    if (!list.some((p) => raw.startsWith(p))) {
+      raw = `${list[0]}${raw}`
+    }
+  }
+
+  return { pkgName: `${SCOPE}${raw}`, shortName: raw, kind }
+}
+
+function mapLegacyFlags(parsed) {
+  const { dev, workspace, fork, repo, branch, from, npm } = parsed
+  let mappedFrom = from
+  let mappedNpm = npm
+  const forceDev = dev || workspace
+
+  if (fork || repo) {
+    warn('`--fork` and `--repo` are deprecated — use `--from` instead.')
+    mappedFrom = repo || fork
+  }
+  if (forceDev && !mappedFrom && !mappedNpm) {
+    mappedFrom = 'owdproject'
+  }
+  if (mappedNpm) mappedFrom = 'npm'
+
+  return { from: mappedFrom, branch, npm: mappedNpm, dev: forceDev }
+}
+
+function parseAddArgs(positionals) {
+  const kindNames = Object.keys(KINDS)
+  if (positionals.length === 0) {
+    fail('Missing package name.', `Example: ${commandName} add app-todo`)
+  }
+
+  if (kindNames.includes(positionals[0])) {
+    const kind = positionals[0]
+    const name = positionals[1]
+    if (!name) {
+      fail(`Missing name for kind "${kind}".`, `Example: ${commandName} add ${kind} todo`)
+    }
+    return normalizePackage(name, kind)
+  }
+
+  return normalizePackage(positionals[0])
+}
+
+function parseLegacyInstall(cmd, positionals) {
+  const kind = LEGACY_COMMANDS[cmd]
+  const raw = positionals[0]
+  if (!raw) {
+    fail('Missing package name.', `Example: ${commandName} ${cmd} ${SCOPE}app-todo`)
+  }
+  warn(`\`${cmd}\` is deprecated — use \`${commandName} add …\` instead.`)
+  return normalizePackage(raw, kind)
+}
+
+/**
+ * @param {string} name CLI binary name (`desktop` or deprecated `owd`)
+ * @param {string[]} argv Arguments (without node and script path)
+ * @param {{ deprecated?: boolean }} [options]
+ */
+export async function runCli(name, argv, options = {}) {
+  commandName = name
+
+  if (options.deprecated) {
+    warn('The `owd` command is deprecated. Use `desktop` instead.')
+  }
+
+  const parsed = getopts(argv, {
+    alias: { h: 'help', b: 'branch' },
+    boolean: ['help', 'npm', 'dry-run', 'dev', 'workspace', 'playground', 'json', 'strict', 'smoke', 'check'],
+    string: ['from', 'branch', 'fork', 'repo', 'protocol'],
+  })
+
+  const { _, help, npm: npmFlag } = parsed
+  const dryRun = parsed['dry-run'] === true
+  const { from, branch, npm: npmFromLegacy, dev: devFlag } = mapLegacyFlags(parsed)
+  const protocol = parsed.protocol === 'ssh' ? 'ssh' : 'https'
+  const useNpm = npmFlag || npmFromLegacy || (!from && !devFlag)
+
+  if (help || _[0] === 'help') {
+    console.log(buildHelp(name))
+    process.exit(0)
+  }
+
+  const cmd = _[0]
+
+  if (cmd === 'init') {
+    const projectDir = (_[1] || 'owd-client').trim()
+    const cwd = process.cwd()
+
+    if (findWorkspaceRoot(cwd)) {
+      fail(
+        'Already inside an OWD workspace.',
+        `Use \`${name}\` to manage this project, or run init from a parent directory.`,
+      )
+    }
+
+    try {
+      await scaffoldProject({ dir: projectDir, cwd, commandName: name })
+    } catch (error) {
+      fail(error.message ?? String(error))
+    }
+    return
+  }
+
+  const workspaceRoot = findWorkspaceRoot()
+
+  if (cmd === 'dev') {
+    if (!workspaceRoot) {
+      fail(
+        'Not inside an OWD workspace.',
+        'Run from the client repo, or try: desktop · desktop add <package>',
+      )
+    }
+    const forcePlayground = parsed.playground === true
+    const devTarget = resolveDevTarget(process.cwd(), workspaceRoot, { forcePlayground })
+    if (forcePlayground && !devTarget) {
+      fail(
+        'No @owdproject module with playground/desktop.config.ts found from this directory.',
+        'Run from an app/theme/module package (e.g. apps/app-about), or omit --playground for the monorepo desktop.',
+      )
+    }
+    runDevForeground(devTarget)
+    return
+  }
+
+  if (cmd === 'validate') {
+    const { runValidateCli, formatValidationReport } = await import('./lib/validateModule.js')
+    const strict = parsed.strict === true
+    const json = parsed.json === true
+    const smoke = parsed.smoke === true
+    const paths = _.slice(1).map(String)
+    const { exitCode, results } = runValidateCli(paths, {
+      workspaceRoot,
+      json,
+      strict,
+      smoke,
+    })
+    for (const result of results) {
+      console.log(formatValidationReport(result, { json }))
+      if (!json) console.log('')
+    }
+    process.exit(exitCode)
+  }
+
+  if (cmd === 'template') {
+    if (!workspaceRoot) {
+      fail(
+        'Not inside an OWD workspace.',
+        `Run from the client monorepo root to regenerate template/.`,
+      )
+    }
+    const { runGenerateTemplateCli } = await import('./lib/generateTemplate.js')
+    await runGenerateTemplateCli({
+      workspaceRoot,
+      dryRun: parsed['dry-run'] === true,
+      check: parsed.check === true,
+    })
+    return
+  }
+
+  if (!cmd) {
+    if (!workspaceRoot) {
+      fail(
+        'Not inside an OWD workspace.',
+        'Run from the client repo, or try: desktop · desktop add <package>',
+      )
+    }
+    await openControlPanel(name)
+    return
+  }
+
+  if (cmd === 'ui') {
+    fail('The `ui` subcommand was removed.', `Use \`${name}\` to open the control panel.`)
+  }
+
+  if (!workspaceRoot) {
+    fail(
+      'Not inside an OWD workspace.',
+      'Run from the client repo (needs pnpm-workspace.yaml + nx.json), or use a generated project with the same layout.',
+    )
+  }
+
+  let pkgInfo
+
+  if (cmd === 'add') {
+    pkgInfo = parseAddArgs(_.slice(1))
+  } else if (LEGACY_COMMANDS[cmd]) {
+    pkgInfo = parseLegacyInstall(cmd, _.slice(1))
+  } else {
+    fail(`Unknown command: ${cmd}`, `Use \`${name}\`, \`${name} dev\`, or \`${name} add <package>\`.`)
+  }
+
+  const { pkgName, shortName, kind } = pkgInfo
+  const inMonorepo = Boolean(workspaceRoot)
+  let resolvedFrom = useNpm ? 'npm' : from
+  if (
+    !useNpm &&
+    resolvedFrom &&
+    resolvedFrom !== 'npm' &&
+    resolvedFrom !== 'owdproject' &&
+    resolvedFrom !== 'official' &&
+    protocol === 'ssh' &&
+    !/[@/]/.test(resolvedFrom)
+  ) {
+    resolvedFrom = `git@github.com:${resolvedFrom}/${shortName}.git`
+  }
+  const source = resolveSource(resolvedFrom, shortName, inMonorepo, {
+    npm: useNpm,
+    dev: devFlag,
+  })
+
+  if (source.mode === 'npm') {
+    if (dryRun) {
+      printPlan({
+        pkgName,
+        kind,
+        targetDir: '(npm → node_modules)',
+        source,
+        branch: null,
+        dryRun: true,
+      })
+      process.exit(0)
+    }
+    runNpmInstall(kind, pkgName, workspaceRoot)
+  } else {
+    try {
+      await runWorkspaceInstall({
+        pkgName,
+        shortName,
+        kind,
+        workspaceRoot,
+        source,
+        branch,
+        dryRun,
+      })
+    } catch (error) {
+      fail(error.message ?? String(error))
+    }
+  }
+}