@factorim/monotui 0.1.0

package/src/utils/navigation/grid-navigation.ts

@@ -0,0 +1,60 @@
+import type { WorkspacesNavigationGrid } from "../../types/workspace-grid"
+
+export function findNextPosition(
+  grid: WorkspacesNavigationGrid,
+  position: { row: number; col: number },
+  direction: "up" | "down" | "left" | "right",
+): { row: number; col: number } {
+  const numRows = grid.length
+  const numCols = grid[0]?.cells.length || 0
+  const { row, col } = position
+
+  function isValid(r: number, c: number) {
+    const navRow = grid[r]
+    return (
+      r >= 0 &&
+      r < numRows &&
+      c >= 0 &&
+      c < (navRow?.cells.length || 0) &&
+      navRow?.cells[c] !== null &&
+      navRow?.cells[c] !== undefined
+    )
+  }
+
+  let nextRow = row
+  let nextCol = col
+  let found = false
+  let attempts = 0
+  const maxAttempts = numRows * numCols
+
+  while (!found && attempts < maxAttempts) {
+    switch (direction) {
+      case "up":
+        nextRow = (nextRow - 1 + numRows) % numRows
+        break
+      case "down":
+        nextRow = (nextRow + 1) % numRows
+        break
+      case "left":
+        nextCol = (nextCol - 1 + numCols) % numCols
+        break
+      case "right":
+        nextCol = (nextCol + 1) % numCols
+        break
+    }
+    if (isValid(nextRow, nextCol)) {
+      found = true
+    } else {
+      // If moving left/right, stay in the same row; if up/down, stay in the same col
+      if (direction === "left" || direction === "right") {
+        // wrap around row if needed
+        if (nextCol === col) break
+      } else {
+        if (nextRow === row) break
+      }
+    }
+    attempts++
+  }
+
+  return { row: nextRow, col: nextCol }
+}

package/src/utils/navigation/navigation-helper.ts

@@ -0,0 +1,84 @@
+import type { WorkspacesNavigationGrid } from "../../types/workspace-grid.js"
+
+interface QuickActionLikeCell {
+  action: {
+    name: string
+  }
+}
+
+export function findNextPosition(
+  grid: WorkspacesNavigationGrid,
+  position: { row: number; col: number },
+  direction: "up" | "down" | "left" | "right",
+): { row: number; col: number } {
+  const numRows = grid.length
+  const numCols = grid[0]?.cells.length || 0
+  const { row, col } = position
+
+  function isValid(r: number, c: number) {
+    const navRow = grid[r]
+    return (
+      r >= 0 &&
+      r < numRows &&
+      c >= 0 &&
+      c < (navRow?.cells.length || 0) &&
+      navRow?.cells[c] !== null &&
+      navRow?.cells[c] !== undefined
+    )
+  }
+
+  let nextRow = row
+  let nextCol = col
+  let found = false
+  let attempts = 0
+  const maxAttempts = numRows * numCols
+
+  while (!found && attempts < maxAttempts) {
+    switch (direction) {
+      case "up":
+        nextRow = (nextRow - 1 + numRows) % numRows
+        break
+      case "down":
+        nextRow = (nextRow + 1) % numRows
+        break
+      case "left":
+        nextCol = (nextCol - 1 + numCols) % numCols
+        break
+      case "right":
+        nextCol = (nextCol + 1) % numCols
+        break
+    }
+    if (isValid(nextRow, nextCol)) {
+      found = true
+    } else {
+      // If moving left/right, stay in the same row; if up/down, stay in the same col
+      if (direction === "left" || direction === "right") {
+        // wrap around row if needed
+        if (nextCol === col) break
+      } else {
+        if (nextRow === row) break
+      }
+    }
+    attempts++
+  }
+
+  return { row: nextRow, col: nextCol }
+}
+
+/**
+ * Returns max text width for each quick-action column index across all rows.
+ */
+export function getQuickActionColumnMaxSizes(
+  quickActionRows: QuickActionLikeCell[][],
+): number[] {
+  const maxSizes: number[] = []
+
+  for (const row of quickActionRows) {
+    row.forEach((cell, index) => {
+      const width = cell.action.name.length
+      maxSizes[index] = Math.max(maxSizes[index] ?? 0, width)
+    })
+  }
+
+  return maxSizes
+}

package/src/utils/project/project-grid.ts

@@ -0,0 +1,165 @@
+import path from "node:path"
+
+import type { Project } from "../../types/project.js"
+import {
+  COMPOSE_COMMANDS,
+  type ComposeCommandCell,
+  type ComposeServiceCell,
+  type MakefileCell,
+  type PackageJsonCell,
+  type ProjectGridCell,
+  type ProjectGridGrid,
+} from "../../types/project-grid.js"
+
+export function buildProjectGrid(workspace: Project): ProjectGridGrid {
+  const makefileCells: MakefileCell[] = []
+  const packageJsonCells: PackageJsonCell[] = []
+  const composeCommandCells: ComposeCommandCell[] = []
+  const composeServiceCells: ComposeServiceCell[] = []
+
+  const makefileCommands = workspace.facets.makefile?.commands ?? []
+  const scripts = workspace.facets.packageJson?.scripts ?? []
+  const services = workspace.facets.compose?.services ?? []
+  const hasCompose = services.length > 0
+
+  // Assign column indices dynamically, skipping empty facets
+  let nextCol = 0
+  const makefileCol = makefileCommands.length > 0 ? nextCol++ : -1
+  const packageJsonCol = scripts.length > 0 ? nextCol++ : -1
+  const composeCol = hasCompose ? nextCol++ : -1
+
+  // Always show compose commands if column exists (even without services)
+  // but only create the column if there are services
+  const maxCol = Math.max(nextCol - 1, 0)
+
+  // Column: Makefile commands
+  if (makefileCol >= 0) {
+    for (let i = 0; i < makefileCommands.length; i++) {
+      makefileCells.push({
+        type: "makefile",
+        filepath: path.join(
+          workspace.path,
+          workspace.facets.makefile?.filename ?? "",
+        ),
+        row: i,
+        col: makefileCol,
+        command: makefileCommands[i],
+      })
+    }
+  }
+
+  // Column: Package.json scripts
+  if (packageJsonCol >= 0) {
+    for (let i = 0; i < scripts.length; i++) {
+      packageJsonCells.push({
+        type: "packageJson",
+        filepath: path.join(
+          workspace.path,
+          workspace.facets.packageJson?.filename ?? "",
+        ),
+        row: i,
+        col: packageJsonCol,
+        script: scripts[i],
+      })
+    }
+  }
+
+  // Column: Compose commands + services
+  if (composeCol >= 0) {
+    let composeRow = 0
+    for (const command of COMPOSE_COMMANDS) {
+      composeCommandCells.push({
+        type: "composeCommand",
+        filepath: path.join(
+          workspace.path,
+          workspace.facets.compose?.filename ?? "",
+        ),
+        row: composeRow,
+        col: composeCol,
+        action: {
+          name: command,
+          command: `docker compose ${command}`,
+        },
+      })
+      composeRow++
+    }
+
+    for (const service of services) {
+      composeServiceCells.push({
+        type: "composeService",
+        filepath: path.join(
+          workspace.path,
+          workspace.facets.compose?.filename ?? "",
+        ),
+        row: composeRow,
+        col: composeCol,
+        service,
+      })
+      composeRow++
+    }
+  }
+
+  return {
+    makefileCells,
+    packageJsonCells,
+    composeCommandCells,
+    composeServiceCells,
+    maxCol,
+  }
+}
+
+/**
+ * Returns the cell at the given position from the grid.
+ */
+export function getProjectCellByPosition(
+  grid: ProjectGridGrid,
+  row: number,
+  col: number,
+): ProjectGridCell | null {
+  const allCells: ProjectGridCell[] = [
+    ...grid.makefileCells,
+    ...grid.packageJsonCells,
+    ...grid.composeCommandCells,
+    ...grid.composeServiceCells,
+  ]
+
+  return allCells.find((cell) => cell.row === row && cell.col === col) ?? null
+}
+
+/**
+ * Returns the maximum row count across all columns.
+ */
+export function getMaxRows(grid: ProjectGridGrid): number {
+  const col0Max = grid.makefileCells.length
+  const col1Max = grid.packageJsonCells.length
+  const col2Max =
+    grid.composeCommandCells.length + grid.composeServiceCells.length
+  return Math.max(col0Max, col1Max, col2Max)
+}
+
+/**
+ * Returns all cells for a given column.
+ */
+export function getCellsByColumn(
+  grid: ProjectGridGrid,
+  col: number,
+): ProjectGridCell[] {
+  const allCells: ProjectGridCell[] = [
+    ...grid.makefileCells,
+    ...grid.packageJsonCells,
+    ...grid.composeCommandCells,
+    ...grid.composeServiceCells,
+  ]
+  return allCells.filter((cell) => cell.col === col)
+}
+
+const CELL_TYPE_LABELS: Record<ProjectGridCell["type"], string> = {
+  makefile: "Makefile",
+  packageJson: "Package.json",
+  composeCommand: "Docker Compose",
+  composeService: "Docker Service",
+}
+
+export function getCellLabel(cell: ProjectGridCell): string {
+  return `${CELL_TYPE_LABELS[cell.type]} - ${cell.filepath}`
+}

package/src/utils/runtime/port.test.ts

@@ -0,0 +1,34 @@
+import { createServer } from "node:net"
+import { afterEach, describe, expect, it } from "@jest/globals"
+
+import { isPortInUse } from "./port"
+
+describe("isPortInUse", () => {
+  let server: ReturnType<typeof createServer> | null = null
+  const testPort = 45678
+
+  afterEach((done) => {
+    if (server) {
+      server.close(() => {
+        server = null
+        done()
+      })
+    } else {
+      done()
+    }
+  })
+
+  it("returns false for a free port", async () => {
+    const inUse = await isPortInUse(testPort)
+    expect(inUse).toBe(false)
+  })
+
+  it("returns true for a taken port", async () => {
+    server = createServer()
+    await new Promise((resolve) =>
+      server?.listen(testPort, () => resolve(undefined)),
+    )
+    const inUse = await isPortInUse(testPort)
+    expect(inUse).toBe(true)
+  })
+})

package/src/utils/runtime/port.ts

@@ -0,0 +1,26 @@
+import { createServer } from "node:net"
+
+/**
+ * Check whether a TCP port is already in use on localhost.
+ * Returns `true` if the port is taken, `false` if it is free.
+ */
+export function isPortInUse(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const server = createServer()
+
+    server.once("error", (err: NodeJS.ErrnoException) => {
+      if (err.code === "EADDRINUSE") {
+        resolve(true)
+      } else {
+        // Unexpected error — treat as in use to be safe
+        resolve(true)
+      }
+    })
+
+    server.once("listening", () => {
+      server.close(() => resolve(false))
+    })
+
+    server.listen(port, "127.0.0.1")
+  })
+}

package/src/utils/workspace/framework-detector.ts

@@ -0,0 +1,77 @@
+import type { PackageJson } from "type-fest"
+
+/**
+ * Detect framework based on package.json dependencies
+ * Priority order matters - checks more specific frameworks first
+ */
+export function detectFramework(pkg: PackageJson): string | undefined {
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+  const depKeys = Object.keys(deps)
+
+  // Meta-frameworks (check first - most specific)
+  if (depKeys.includes("next")) return "Next.js"
+  if (depKeys.includes("@remix-run/react")) return "Remix"
+  if (depKeys.includes("@sveltejs/kit")) return "SvelteKit"
+  if (depKeys.includes("nuxt")) return "Nuxt"
+  if (depKeys.includes("astro")) return "Astro"
+  if (depKeys.includes("gatsby")) return "Gatsby"
+  if (depKeys.includes("@redwoodjs/core")) return "RedwoodJS"
+  if (depKeys.includes("blitz")) return "Blitz"
+  if (depKeys.includes("@solidjs/start")) return "SolidStart"
+  if (depKeys.includes("@analogjs/platform")) return "Analog"
+  if (depKeys.includes("hardhat")) return "Hardhat"
+
+  // Backend frameworks
+  if (depKeys.includes("@nestjs/core")) return "NestJS"
+  if (depKeys.includes("h3")) return "H3"
+  if (depKeys.includes("express")) return "Express"
+  if (depKeys.includes("fastify")) return "Fastify"
+  if (depKeys.includes("koa")) return "Koa"
+  if (depKeys.includes("@hapi/hapi")) return "Hapi"
+  if (depKeys.includes("nitro")) return "Nitro"
+  if (depKeys.includes("@trpc/server")) return "tRPC"
+  if (depKeys.includes("elysia")) return "Elysia"
+  if (depKeys.includes("hono")) return "Hono"
+
+  // Frontend frameworks
+  if (depKeys.includes("@docusaurus/core")) return "Docusaurus"
+  if (depKeys.includes("react")) return "React"
+  if (depKeys.includes("vue")) return "Vue"
+  if (depKeys.includes("svelte")) return "Svelte"
+  if (depKeys.includes("@angular/core")) return "Angular"
+  if (depKeys.includes("solid-js")) return "Solid"
+  if (depKeys.includes("preact")) return "Preact"
+  if (depKeys.includes("@builder.io/qwik")) return "Qwik"
+  if (depKeys.includes("lit")) return "Lit"
+  if (depKeys.includes("alpine")) return "Alpine.js"
+  if (depKeys.includes("htmx.org")) return "HTMX"
+
+  // Build tools (fallback)
+  if (depKeys.includes("vite")) return "Vite"
+  if (depKeys.includes("webpack")) return "Webpack"
+  if (depKeys.includes("parcel")) return "Parcel"
+  if (depKeys.includes("rollup")) return "Rollup"
+  if (depKeys.includes("turbo")) return "Turborepo"
+  if (depKeys.includes("esbuild")) return "esbuild"
+
+  // Mobile frameworks
+  if (depKeys.includes("react-native")) return "React Native"
+  if (
+    depKeys.includes("@ionic/react") ||
+    depKeys.includes("@ionic/angular") ||
+    depKeys.includes("@ionic/vue")
+  )
+    return "Ionic"
+  if (depKeys.includes("@nativescript/core")) return "NativeScript"
+  if (depKeys.includes("@tauri-apps/api")) return "Tauri"
+  if (depKeys.includes("electron")) return "Electron"
+
+  // Desktop frameworks
+  if (depKeys.includes("@neutralinojs/lib")) return "Neutralino"
+  if (depKeys.includes("nw")) return "NW.js"
+
+  // Testing frameworks (only if no other framework detected)
+  if (depKeys.includes("vitest")) return "Vitest"
+
+  return undefined
+}

package/src/utils/workspace/workspace-grid.ts

@@ -0,0 +1,161 @@
+import type { Project } from "../../types/project.js"
+import type {
+  WorkspaceCell,
+  WorkspaceQuickActionCell,
+  WorkspaceRuntimeCell,
+  WorkspacesNavigationCell,
+  WorkspacesNavigationGrid,
+  WorkspacesNavigationRow,
+} from "../../types/workspace-grid"
+import type { WorkspaceQuickAction } from "../../types/workspace-quick-actions.js"
+import type { WorkspaceRuntimeState } from "../../types/workspace-runtime.js"
+import { logger } from "../../utils/logging/logger.js"
+import { getQuickActionByPath, getRuntimeByPath } from "./workspace-helper.js"
+
+export function buildWorkspacesGrid(
+  workspaces: Project[],
+  quickActions: WorkspaceQuickAction[],
+  runtimes: WorkspaceRuntimeState[],
+): WorkspacesNavigationGrid {
+  const maxQuickActionFacets = getMaxQuickActionRowItems(quickActions)
+  const maxRuntimeFacets = getMaxRuntimeRowItems(runtimes)
+
+  const grid: WorkspacesNavigationGrid = []
+  for (let rowIndex = 0; rowIndex < workspaces.length; rowIndex++) {
+    const ws = workspaces[rowIndex]
+    const cells: (WorkspacesNavigationCell | null)[] = []
+
+    // Workspace cell (col 0)
+    cells.push({ type: "workspace", workspace: ws, row: rowIndex, col: 0 })
+
+    // Quick actions
+    const quickAction = getQuickActionByPath(quickActions, ws.path)
+    const qaFacets = quickAction?.facets ?? []
+    for (let i = 0; i < maxQuickActionFacets; i++) {
+      if (qaFacets[i]) {
+        cells.push({
+          type: "quickAction",
+          action: qaFacets[i],
+          row: rowIndex,
+          col: i + 1,
+        })
+      } else {
+        cells.push(null)
+      }
+    }
+
+    // Runtimes
+    const runtime = getRuntimeByPath(runtimes, ws.path)
+    const rtFacets =
+      runtime?.runStates?.filter((rs) => rs.status !== "stopped") ?? []
+    for (let i = 0; i < maxRuntimeFacets; i++) {
+      if (rtFacets[i]) {
+        cells.push({
+          type: "runtime",
+          runState: rtFacets[i],
+          row: rowIndex,
+          col: i + maxQuickActionFacets + 1,
+        })
+      } else {
+        cells.push(null)
+      }
+    }
+
+    const navRow: WorkspacesNavigationRow = {
+      id: ws.path,
+      cells,
+    }
+    grid.push(navRow)
+  }
+
+  logger.debug("Workspaces Navigation Grid")
+  logger.debug(JSON.stringify(grid, null, 2))
+  return grid
+}
+
+/**
+ * Returns the highest number of items found in the array.
+ */
+function getMaxQuickActionRowItems(arr: { facets?: unknown[] }[]): number {
+  return arr.reduce((max, item) => {
+    const count = Array.isArray(item.facets) ? item.facets.length : 0
+    return count > max ? count : max
+  }, 0)
+}
+
+/**
+ * Returns the highest number of items found in the array.
+ */
+function getMaxRuntimeRowItems(arr: { runStates?: unknown[] }[]): number {
+  return arr.reduce((max, item) => {
+    const count = Array.isArray(item.runStates) ? item.runStates.length : 0
+    return count > max ? count : max
+  }, 0)
+}
+
+/**
+ * Returns the first WorkspaceCell found in a row
+ */
+export function getWorkspaceCell(
+  cells: (WorkspacesNavigationCell | null)[],
+): WorkspaceCell {
+  return cells.find(
+    (cell) => cell && cell.type === "workspace",
+  ) as WorkspaceCell
+}
+
+/**
+ * Returns all WorkspaceQuickActionCell in a row
+ */
+export function getWorkspaceQuickActionCells(
+  cells: (WorkspacesNavigationCell | null)[],
+): WorkspaceQuickActionCell[] {
+  const result: WorkspaceQuickActionCell[] = []
+  for (const cell of cells) {
+    if (cell && cell.type === "quickAction")
+      result.push(cell as WorkspaceQuickActionCell)
+  }
+  return result
+}
+
+/**
+ * Returns all WorkspaceRuntimeCell in a row
+ */
+export function getWorkspaceRuntimeCells(
+  cells: (WorkspacesNavigationCell | null)[],
+): WorkspaceRuntimeCell[] {
+  const result: WorkspaceRuntimeCell[] = []
+  for (const cell of cells) {
+    if (cell && cell.type === "runtime")
+      result.push(cell as WorkspaceRuntimeCell)
+  }
+  return result
+}
+
+// /**
+//  * Returns the WorkspaceCell at the given cursor position (row, col) from the grid.
+//  */
+// export function getWorkspaceCellByPosition(
+//   grid: WorkspacesNavigationGrid,
+//   row: number,
+//   col: number,
+// ): WorkspaceCell | null {
+//   const navRow = grid[row]
+//   if (!navRow || !navRow.cells[col]) return null
+//   const cell = navRow.cells[col]
+//   return cell && cell.type === "workspace" ? (cell as WorkspaceCell) : null
+// }
+
+/**
+ * Returns the WorkspacesNavigationCell (any type) at the given row and col from the grid.
+ */
+export function getWorkspaceCellByPosition(
+  grid: WorkspacesNavigationGrid,
+  row: number,
+  col: number,
+): WorkspacesNavigationCell | null {
+  const navRow = grid[row]
+  if (!navRow || !navRow.cells[col]) return null
+  const cell = navRow.cells[col]
+  return cell ? cell : null
+}

package/src/utils/workspace/workspace-helper.ts

@@ -0,0 +1,21 @@
+import type { Project } from "../../types/project.js"
+import type { WorkspaceQuickAction } from "../../types/workspace-quick-actions.js"
+import type { WorkspaceRuntimeState } from "../../types/workspace-runtime.js"
+
+export function getQuickActionByPath(
+  quickActions: WorkspaceQuickAction[],
+  path: string,
+): WorkspaceQuickAction | undefined {
+  return quickActions.find((action) => action.workspacePath === path)
+}
+
+export function getRuntimeByPath(
+  runtimes: WorkspaceRuntimeState[],
+  path: string,
+): WorkspaceRuntimeState | undefined {
+  return runtimes.find((runtime) => runtime.workspacePath === path)
+}
+
+export function getRootWorkspace(workspaces: Project[]): Project | undefined {
+  return workspaces.find((ws) => ws.type === "workspace")
+}

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "react"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/workspace-cli.mjs

@@ -0,0 +1,18 @@
+export default {
+  discovery: {
+    enabled: true,
+    maxDepth: 4,
+    ignore: ["node_modules", ".git", "dist", "build"],
+    scripts: {
+      exclude: [],
+    },
+    env: {
+      files: [".env.local", ".env.development", ".env", ".env.example"],
+      portKeys: ["PORT", "APP_PORT", "VITE_PORT", "NEXT_PUBLIC_PORT"],
+    },
+    order: ["workspace", "app", "contract", "infra", "package"],
+  },
+  execution: {
+    useTmux: true,
+  },
+}