@alivault/pico 0.1.0

package/README.md

@@ -0,0 +1,111 @@
+# Pico
+
+Pico is a local, keyboard-friendly browser workspace for Pi coding-agent sessions.
+
+It gives you a persistent session browser, a live conversation shell, git tools, and project-aware prompt helpers in one app.
+
+![Pico workspace showing the session browser, conversation shell, composer, and git tools](./public/screenshots/pico-workspace.png)
+
+![Pico workspace showing project-aware context and coding-agent workflow](./public/screenshots/pico-workspace-alt.png)
+
+## What Pico gives you
+
+- A fast conversation shell for Pi sessions
+- Directory-organized session browsing
+- Session search, rename, delete, fork, and tree navigation
+- Streaming responses with abort, steer, and queued follow-ups
+- Prompt drafts, image attachments, slash commands, path completions, and `@file` references
+- Model and thinking-level controls
+- Optional hiding of thinking/tool output
+- Git status, changed files, commits, branches, pull, push, and commit flows
+- Desktop notifications, sound, and unread/live session indicators
+- Settings for theme, display, auth, and completion notifications
+
+## Built on Pi
+
+Pico runs Pi locally through the bundled `@mariozechner/pi-coding-agent` SDK dependency, pinned to `0.73.1` for reproducible installs. You do not need a separate global Pi install for normal use.
+
+If you intentionally want to test Pico against a different Pi SDK checkout or install, set:
+
+```bash
+PI_REMOTE_PI_SDK_DIR=/path/to/pi-coding-agent
+```
+
+To update the bundled Pi SDK dependency:
+
+```bash
+pnpm update:pi
+```
+
+## Getting started
+
+Run Pico without cloning the repo:
+
+```bash
+npx @alivault/pico
+```
+
+Or install it globally:
+
+```bash
+npm install -g @alivault/pico
+pico-app
+```
+
+Pico starts locally and opens:
+
+```text
+http://localhost:3141
+```
+
+You can choose a different port with:
+
+```bash
+pico-app --port 3000
+```
+
+## Developing from source
+
+Install dependencies:
+
+```bash
+pnpm install
+```
+
+Start Pico in development mode:
+
+```bash
+pnpm dev
+```
+
+Then open:
+
+```text
+http://localhost:3141
+```
+
+## Development commands
+
+```bash
+pnpm dev        # start the dev server
+pnpm build      # build for production
+pnpm preview    # preview the production build
+pnpm check      # format/lint/typecheck
+pnpm check:fix  # format/lint/typecheck with fixes
+```
+
+## Tech stack
+
+Pico is built with:
+
+- TanStack Start, Router, Query, Store, Hotkeys, and Pacer
+- React 19
+- TypeScript
+- Vite+ and Nitro
+- Tailwind CSS v4
+- Base UI / shadcn-style components
+- Pi SDK
+
+## License
+
+Pico is licensed under AGPL-3.0-only. See [LICENSE](./LICENSE).

package/bin/pico.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process"
+import { existsSync, readFileSync } from "node:fs"
+import process from "node:process"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)))
+const packageJsonPath = join(packageRoot, "package.json")
+const serverEntry = join(packageRoot, ".output", "server", "index.mjs")
+
+function readPackageVersion() {
+  try {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"))
+    return typeof packageJson.version === "string"
+      ? packageJson.version
+      : "0.0.0"
+  } catch {
+    return "0.0.0"
+  }
+}
+
+function printHelp() {
+  console.log(`Pico - local browser workspace for Pi coding-agent sessions
+
+Usage:
+  pico-app [options]
+
+Options:
+  --port <port>    Port to listen on (default: 3141)
+  --host <host>    Host to bind to
+  --open           Open Pico in your browser (default)
+  --no-open        Do not open a browser window
+  --version        Print the Pico version
+  --help           Show this help message
+
+Environment:
+  PICO_PORT        Port to listen on
+  PICO_HOST        Host to bind to
+  PORT             Fallback port used by the server
+  HOST             Fallback host used by the server
+`)
+}
+
+function readOptionValue(args, index, name) {
+  const value = args[index + 1]
+  if (!value || value.startsWith("-")) {
+    console.error(`Missing value for ${name}`)
+    process.exit(1)
+  }
+  return value
+}
+
+function parseArgs(args) {
+  const options = {
+    open: process.env.PICO_OPEN !== "0",
+    port: process.env.PICO_PORT || process.env.PORT || "3141",
+    host: process.env.PICO_HOST || process.env.HOST || undefined,
+  }
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+
+    if (arg === "--help") {
+      printHelp()
+      process.exit(0)
+    }
+
+    if (arg === "--version") {
+      console.log(readPackageVersion())
+      process.exit(0)
+    }
+
+    if (arg === "--open") {
+      options.open = true
+      continue
+    }
+
+    if (arg === "--no-open") {
+      options.open = false
+      continue
+    }
+
+    if (arg === "--port") {
+      options.port = readOptionValue(args, index, "--port")
+      index += 1
+      continue
+    }
+
+    if (arg.startsWith("--port=")) {
+      options.port = arg.slice("--port=".length)
+      continue
+    }
+
+    if (arg === "--host") {
+      options.host = readOptionValue(args, index, "--host")
+      index += 1
+      continue
+    }
+
+    if (arg.startsWith("--host=")) {
+      options.host = arg.slice("--host=".length)
+      continue
+    }
+
+    console.error(`Unknown option: ${arg}`)
+    console.error("Run `pico-app --help` for usage.")
+    process.exit(1)
+  }
+
+  return options
+}
+
+function browserHostFor(host) {
+  if (!host || host === "0.0.0.0" || host === "::") {
+    return "localhost"
+  }
+  return host
+}
+
+async function waitForServer(url, timeoutMs = 15_000) {
+  const startedAt = Date.now()
+
+  while (Date.now() - startedAt < timeoutMs) {
+    try {
+      const response = await fetch(url, { method: "HEAD" })
+      if (response.status < 500) return true
+    } catch {
+      // Server is not ready yet.
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 250))
+  }
+
+  return false
+}
+
+function openBrowser(url) {
+  const opener = (() => {
+    if (process.platform === "darwin") return ["open", [url]]
+    if (process.platform === "win32") return ["cmd", ["/c", "start", "", url]]
+    return ["xdg-open", [url]]
+  })()
+
+  const child = spawn(opener[0], opener[1], {
+    detached: true,
+    stdio: "ignore",
+  })
+  child.unref()
+}
+
+const options = parseArgs(process.argv.slice(2))
+
+if (!existsSync(serverEntry)) {
+  console.error("Pico server build was not found in this package.")
+  console.error("If you are developing Pico locally, run `pnpm build` first.")
+  process.exit(1)
+}
+
+const url = `http://${browserHostFor(options.host)}:${options.port}`
+
+console.log(`Starting Pico at ${url}`)
+console.log("Press Ctrl+C to stop.")
+
+const server = spawn(process.execPath, [serverEntry], {
+  stdio: "inherit",
+  env: {
+    ...process.env,
+    PORT: options.port,
+    NITRO_PORT: options.port,
+    ...(options.host
+      ? {
+          HOST: options.host,
+          NITRO_HOST: options.host,
+        }
+      : {}),
+  },
+})
+
+if (options.open) {
+  void waitForServer(url).then((isReady) => {
+    if (isReady) openBrowser(url)
+  })
+}
+
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.once(signal, () => {
+    if (!server.killed) {
+      server.kill(signal)
+      setTimeout(() => process.exit(1), 5_000).unref()
+      return
+    }
+
+    process.exit(1)
+  })
+}
+
+server.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal)
+    return
+  }
+
+  process.exit(code ?? 0)
+})

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@alivault/pico",
+  "version": "0.1.0",
+  "description": "A local, keyboard-friendly browser workspace for Pi coding-agent sessions.",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "bin": {
+    "pico-app": "bin/pico.mjs"
+  },
+  "files": [
+    ".output",
+    "bin",
+    "scripts/patch-react-jsx-dev-runtime.mjs",
+    "public/screenshots",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alivault/pico.git"
+  },
+  "homepage": "https://github.com/alivault/pico#readme",
+  "bugs": {
+    "url": "https://github.com/alivault/pico/issues"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "vp dev",
+    "build": "vp build && node ./scripts/patch-react-jsx-dev-runtime.mjs",
+    "start": "node ./bin/pico.mjs",
+    "prepack": "pnpm build",
+    "preview": "vp preview",
+    "lint": "vp lint",
+    "format": "vp fmt",
+    "check": "vp check",
+    "check:fix": "vp check --fix",
+    "update:pi": "pnpm update @mariozechner/pi-coding-agent --latest"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.4.0",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@fontsource-variable/inter": "^5.2.8",
+    "@mariozechner/pi-coding-agent": "0.73.1",
+    "@pierre/diffs": "^1.1.20",
+    "@pierre/trees": "1.0.0-beta.3",
+    "@tailwindcss/vite": "^4.2.1",
+    "@tanstack/pacer": "^0.21.0",
+    "@tanstack/react-devtools": "^0.10.0",
+    "@tanstack/react-hotkeys": "^0.10.0",
+    "@tanstack/react-query": "^5.99.0",
+    "@tanstack/react-router": "^1.167.4",
+    "@tanstack/react-router-devtools": "^1.166.9",
+    "@tanstack/react-router-ssr-query": "^1.166.9",
+    "@tanstack/react-start": "^1.166.15",
+    "@tanstack/react-store": "^0.11.0",
+    "@tanstack/router-plugin": "^1.166.13",
+    "@tanstack/store": "^0.11.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "date-fns": "^4.1.0",
+    "diff": "^9.0.0",
+    "lucide-react": "^1.8.0",
+    "next-themes": "^0.4.6",
+    "nitro": "latest",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-markdown": "^10.1.0",
+    "react-resizable-panels": "^4.10.0",
+    "remark-gfm": "^4.0.1",
+    "shadcn": "^4.3.0",
+    "sonner": "^2.0.7",
+    "sugar-high": "^1.1.0",
+    "tailwind-merge": "^3.5.0",
+    "tailwindcss": "^4.2.1",
+    "tslib": "^2.8.1",
+    "tw-animate-css": "^1.4.0",
+    "vaul": "^1.1.2",
+    "vite-tsconfig-paths": "^5.1.4",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@rolldown/plugin-babel": "^0.2.3",
+    "@tailwindcss/typography": "^0.5.19",
+    "@tanstack/devtools-vite": "^0.6.0",
+    "@types/node": "^22.19.15",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "react-scan": "^0.5.3",
+    "typescript": "^5.9.3",
+    "vite": "catalog:",
+    "vite-plus": "catalog:",
+    "web-vitals": "^5.1.0"
+  },
+  "packageManager": "pnpm@10.33.0"
+}

package/scripts/patch-react-jsx-dev-runtime.mjs

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import process from "node:process"
+
+const reactRuntimePath = join(
+  process.cwd(),
+  ".output",
+  "server",
+  "_libs",
+  "react.mjs"
+)
+
+if (!existsSync(reactRuntimePath)) {
+  console.warn(
+    "Pico postbuild: React runtime bundle not found, skipping patch."
+  )
+  process.exit(0)
+}
+
+const source = readFileSync(reactRuntimePath, "utf8")
+const oldRuntime = `var require_react_jsx_dev_runtime_production = /* @__PURE__ */ __commonJSMin(((exports) => {
+\texports.Fragment = Symbol.for("react.fragment");
+\texports.jsxDEV = void 0;
+}));`
+
+const patchedRuntime = `var require_react_jsx_dev_runtime_production = /* @__PURE__ */ __commonJSMin(((exports) => {
+\tvar REACT_ELEMENT_TYPE = Symbol.for("react.transitional.element"), REACT_FRAGMENT_TYPE = Symbol.for("react.fragment");
+\tfunction jsxProd(type, config, maybeKey) {
+\t\tvar key = null, propName, props;
+\t\tvoid 0 !== maybeKey && (key = "" + maybeKey);
+\t\tconfig == null && (config = {});
+\t\tvoid 0 !== config.key && (key = "" + config.key);
+\t\tif ("key" in config) {
+\t\t\tprops = {};
+\t\t\tfor (propName in config) "key" !== propName && (props[propName] = config[propName]);
+\t\t} else props = config;
+\t\tconfig = props.ref;
+\t\treturn {
+\t\t\t$$typeof: REACT_ELEMENT_TYPE,
+\t\t\ttype: type,
+\t\t\tkey: key,
+\t\t\tref: void 0 !== config ? config : null,
+\t\t\tprops: props
+\t\t};
+\t}
+\texports.Fragment = REACT_FRAGMENT_TYPE;
+\texports.jsxDEV = jsxProd;
+}));`
+
+if (!source.includes(oldRuntime)) {
+  console.warn(
+    "Pico postbuild: React jsxDEV runtime did not match, skipping patch."
+  )
+  process.exit(0)
+}
+
+writeFileSync(
+  reactRuntimePath,
+  source.replace(oldRuntime, () => patchedRuntime)
+)
+console.log("Pico postbuild: patched React jsxDEV runtime for SSR.")
+
+const ssrDir = join(process.cwd(), ".output", "server", "_ssr")
+let patchedVoidCalls = 0
+
+if (existsSync(ssrDir)) {
+  for (const entry of readdirSync(ssrDir)) {
+    if (!entry.endsWith(".mjs")) continue
+
+    const filePath = join(ssrDir, entry)
+    const chunk = readFileSync(filePath, "utf8")
+    if (
+      !chunk.includes("var import_jsx_dev_runtime = require_jsx_dev_runtime();")
+    ) {
+      continue
+    }
+
+    const nextChunk = chunk.replaceAll(
+      "(void 0)(",
+      "(0, import_jsx_dev_runtime.jsxDEV)("
+    )
+    if (nextChunk === chunk) continue
+
+    writeFileSync(filePath, nextChunk)
+    patchedVoidCalls += 1
+  }
+}
+
+if (patchedVoidCalls > 0) {
+  console.log(
+    `Pico postbuild: patched ${patchedVoidCalls} SSR chunk(s) with jsxDEV calls.`
+  )
+}