neondeck 1.0.0-beta.4

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## Unreleased
+
+## 1.0.0-beta.4 - 2026-07-12
+
+- fix(runtime): make concurrent runtime-home initialization atomic
+- fix(flue): expose command, watch, scheduler, GitHub, and doctor operations through Flue actions/workflows
+- feat(release): add release watch command and default-branch check polling
+- feat(dev): add local dev doctor command and diagnostics action
+- feat(dashboard): add runtime overview panel for home, repos, jobs, and skills
+- feat(watches): add automatic PR watch polling and an active watches panel
+- feat(commands): add Neon slash command workflows and dashboard buttons
+- feat(setup): add explicit runtime home setup command
+- feat(skills): add runtime skill discovery, loading, and reload actions
+- feat(scheduler): add durable scheduled jobs, notifications, and blueprint automations
+- feat(watches): add persistent PR watch actions with quiet refresh semantics
+- feat(repos): add repo registry API and registry-aware GitHub PR queries
+- fix(config): reject empty self-configuration action inputs
+- fix(config): audit self-configuration mutations and require confirmation for destructive actions
+- feat(config): add Valibot-backed Neondeck self-configuration actions for repos and schedules
+- feat(runtime): add validated Neondeck runtime home bootstrap with seeded config, runtime skill, and separate app/Flue SQLite state

package/DEVELOPMENT.md

@@ -0,0 +1,310 @@
+# Development
+
+This file is for people working inside this repository. The root
+[`README.md`](./README.md) is the high-level landing page; the public docs site
+under `docs/` carries the detailed user-facing guides.
+
+## Requirements
+
+- Node 26.4.0 or newer
+- A KiloCode, OpenAI, or Anthropic API key for the configured Flue model
+  provider
+- A GitHub token for GitHub-backed panels and workflows
+
+Use any Node installer or version manager. With `fnm`, that looks like:
+
+```sh
+fnm install 26.4.0
+fnm use 26.4.0
+```
+
+Then install dependencies:
+
+```sh
+npm install
+```
+
+## First Run
+
+Run the guided setup wizard:
+
+```sh
+npm run init
+```
+
+The wizard prepares the runtime home, writes local secrets to
+`$NEONDECK_HOME/.env`, tunes `SOUL.md`, configures the selected model provider,
+optionally sets a low-cost utility model, adds local git checkouts, applies a
+dashboard preset, and can create command preapprovals.
+
+The CLI is also the base for direct command-and-control surfaces:
+
+```sh
+npm run cli -- status
+npm run cli -- doctor
+npm run cli -- db status
+npm run cli -- repo add ~/dev/neondeck
+npm run cli -- watch-pr pandemicsyn/neondeck#123
+npm run cli -- tui
+```
+
+## Runtime Home And Secrets
+
+Packaged/local app secrets live in the runtime home:
+
+```text
+$NEONDECK_HOME/.env
+```
+
+For checkout-based development, repo-root `.env` is also supported as a
+dev-only fallback when the runtime-home file does not define a value.
+
+```sh
+KILOCODE_API_KEY=...
+KILOCODE_ORGANIZATION_ID=...
+OPENAI_API_KEY=...
+ANTHROPIC_API_KEY=...
+GITHUB_TOKEN=...
+GITHUB_LOGIN=...
+```
+
+Neondeck resolves runtime home in this order:
+
+```text
+NEONDECK_HOME
+XDG_CONFIG_HOME/neondeck
+~/.config/neondeck
+```
+
+The runtime home contains `.env`, `config.json`, `mcp.json`, `repos.json`,
+`dashboard.json`, `SOUL.md`, `skills/`, and separate
+`data/neondeck.db` and `data/flue.db` databases. Neondeck app database
+migrations are shipped with the package and auto-apply before app code touches
+`data/neondeck.db`; pre-migration backups are kept under `data/backups/`.
+
+Initialize or validate the runtime home explicitly without starting the server:
+
+```sh
+npm run setup
+npm run setup -- --home ./data/dev-home
+```
+
+For new installs, prefer `npm run init`; `npm run setup` is the lower-level
+non-interactive initializer.
+
+## Local Development
+
+```sh
+npm run dev
+```
+
+Open `http://127.0.0.1:5173/`.
+
+The dev command runs the Flue/Hono backend and Vite dashboard together. Runtime
+home, repository, MCP server/approval, scheduler, and skill state are visible in
+the Runtime Overview panel.
+
+Neon command workflows can be run from dashboard controls, typed into chat, or
+invoked through Flue:
+
+```sh
+curl -X POST 'http://127.0.0.1:5173/api/flue/workflows/command-run?wait=result' \
+  -H 'Content-Type: application/json' \
+  -d '{"input":{"command":"/briefing"}}'
+```
+
+Common commands include `/repo-status`, `/review-queue`, `/review-pr <ref>`,
+`/fix-ci [ref]`, `/explain-ci [--report] [ref]`, `/summarize-pr [ref]`,
+`/draft-pr-description [repo]`, `/prepare-pr [repo]`, `/review-local [repo]`,
+`/briefing`, `/reasoning [level]`, `/memory ...`, `/dev-doctor`,
+`/watch-pr <ref>`.
+
+## CLI Surface
+
+From a source checkout, use `npm run cli -- <command>`. After package install,
+use `neondeck <command>`.
+
+Available top-level commands:
+
+```sh
+npm run cli -- init
+npm run cli -- dev
+npm run cli -- serve
+npm run cli -- open [profile]
+npm run cli -- service status
+npm run cli -- status
+npm run cli -- repo list
+npm run cli -- mcp list
+npm run cli -- db status
+npm run cli -- learning status
+npm run cli -- watch-pr <repo#number>
+npm run cli -- note "message"
+npm run cli -- register-pr <repo#number>
+npm run cli -- doctor
+npm run cli -- tui
+```
+
+The `tui` command exists as the future OpenTUI entrypoint.
+
+## Checks
+
+Fast loop:
+
+```sh
+npm run check
+```
+
+Individual checks:
+
+```sh
+npm run lint
+npm run typecheck
+npm run test
+npm run test:integration
+npm run test:all
+npm run format:check
+npm run db:check
+```
+
+Full verification:
+
+```sh
+npm run verify
+```
+
+`npm run check` is the fast local loop: lint, import-layer check, database
+migration check, typecheck, and the unit Vitest suite. The slower
+git/worktree/Kilo/autopilot workflow coverage lives under
+`npm run test:integration`, while `npm run test:all` runs every Vitest suite.
+`npm run verify` keeps the full pre-release path: lint, import-layer check,
+database migration check, typecheck, all tests, production builds, npm package
+smoke checks, and format check.
+
+## Database Migrations
+
+Use Drizzle migrations for Neondeck app state:
+
+```sh
+npm run db:generate -- --name <migration_name>
+npm run db:check
+```
+
+Keep Neondeck app state separate from Flue runtime state unless the roadmap says
+otherwise.
+
+## Build And Package
+
+```sh
+npm run typecheck
+npm run build
+npm start
+```
+
+Production app release helpers:
+
+```sh
+npm run release:app
+npm run release:npm:check
+```
+
+After a production build or package install:
+
+```sh
+neondeck service install
+neondeck open
+neondeck open sidebar
+```
+
+`neondeck service install` creates a macOS launchd agent or Linux systemd user
+unit with absolute Node and built server entry paths and logs under
+runtime-home `data/logs/server.log`. `neondeck open` probes `/api/health`,
+starts the installed service when present, falls back to a detached built server
+process when no service exists, and opens a dedicated browser app window when a
+supported Chromium browser is available.
+
+`neondeck serve` and the login service run the built Flue server entry from
+`dist/server.mjs`; from a source checkout, use `npm run dev` for the fast loop
+or run `npm run build:server` before testing the packaged path.
+
+## Marketing And Docs Site
+
+The Astro site lives under `docs/` and deploys to Cloudflare for
+`neondeck.dev`.
+
+```sh
+npm run docs:astro-dev  # hot Astro dev server
+npm run docs:dev        # build, then preview
+npm run docs:build
+npm run docs:preview
+npm run docs:deploy
+```
+
+The Cloudflare deployment config is `docs/wrangler.jsonc`.
+
+## Publishing
+
+User-facing pull requests should include a concise Changeset:
+
+```sh
+npm run changeset
+```
+
+Use `patch` for fixes, `minor` for features, and `major` for breaking changes.
+The private docs workspace is excluded from package versioning. While Neondeck
+is on the beta channel, enter Changesets prerelease mode before consuming the
+pending changesets:
+
+```sh
+npx changeset pre enter beta
+npm run version-packages
+```
+
+Commit the generated package versions, lockfile, changelog, and Changesets
+state. Tag the exact package version and push the version commit and annotated
+tag together:
+
+```sh
+version="$(node -p "JSON.parse(require('node:fs').readFileSync('package.json', 'utf8')).version")"
+git tag -a "v${version}" -m "neondeck v${version}"
+git push origin main --follow-tags
+```
+
+Prerelease tags such as `v1.0.0-beta.1` publish to npm's `next` dist-tag.
+Stable tags publish to `latest`. Before creating a tag, the workflow can validate
+a branch or commit without publishing:
+
+```sh
+gh workflow run npm-publish.yml \
+  -f release_ref=main \
+  -f npm_tag=auto \
+  -f dry_run=true
+```
+
+The npm release path is separate from the GitHub app archive release:
+
+- `.github/workflows/npm-package.yml` validates the packed npm artifact on PRs.
+- `.github/workflows/npm-publish.yml` verifies the release tag, runs
+  `npm run release:npm:check`, and publishes `neondeck` to npm from `v*` tags.
+
+For the first npm publish, the package must be created before npm trusted
+publishing can be configured. Set a temporary granular publish token with
+bypass-2FA enabled as the `NPM_TOKEN` secret on the GitHub `npm` environment,
+then push the first release tag. After `neondeck` exists on npm, configure
+trusted publishing for GitHub Actions with workflow filename `npm-publish.yml`,
+environment `npm`, and allowed action `npm publish`. Delete the GitHub secret
+and revoke the temporary npm token after the first trusted publish succeeds.
+
+## Deeper Runtime Docs
+
+The detailed runtime and configuration material belongs in the docs site:
+
+- `docs/src/pages/docs/getting-started.astro`
+- `docs/src/pages/docs/configuration.astro`
+- `docs/src/pages/docs/agent-runtime.astro`
+- `docs/src/pages/docs/execution.astro`
+- `docs/src/pages/docs/mcp.astro`
+- `docs/src/pages/docs/memory-learning.astro`
+- `docs/src/pages/docs/deployment.astro`
+- `docs/src/pages/docs/contributing.astro`
+
+Update those pages when changing user-facing runtime behavior.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Florian Hines
+
+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

@@ -0,0 +1,128 @@
+# neondeck
+
+A companion agent for keeping PRs moving.
+
+Neon watches your PRs, tracks CI and release checks, prepares fixes when work
+gets stuck, and can configure its own repos, schedules, models, and deck layout
+through typed actions.
+
+It is especially useful on a companion display, vertical panel, or Corsair
+Xeneon Edge-style deck, where your active work can stay visible without taking
+over your editor. The backend is Node 26, Hono, and Flue; the dashboard is Vite,
+React, and Tailwind. Neondeck can run on your machine or on a remote host, with
+mutable state stored in SQLite under a runtime home you control.
+
+## Built for work in progress
+
+Neon watches your PRs, prepares fixes, and keeps the busywork moving.
+
+- **Your PRs, with CI status at a glance.** See open PRs across your repos in
+  one panel, with live check status and stale-work flags.
+- **Watch a PR, then let autopilot move it.** Track a PR through merge, checks,
+  and deploy. When review feedback or CI failures need action, autopilot can
+  prepare a fix in an isolated worktree, run checks, and hand you the diff or
+  push it when repo policy allows.
+- **Review and approve PRs on the deck.** Read diffs, leave inline comments,
+  resolve threads, and submit approvals or change requests without switching to
+  github.com.
+- **Handoff, both directions.** Delegate work to agents like Kilo or Codex, then
+  let the finished PR come back to Neon for checks and deployment follow-through.
+- **Briefings and scheduled instructions.** Pull your PRs, watches, CI failures,
+  and next actions into a morning briefing, or run your own saved prompt on a
+  timer.
+- **Sandboxed, gated execution.** Keep code-changing work in throwaway
+  worktrees, gate shell commands through approval policy, or run work off your
+  machine on an `exe.dev` sandbox VM.
+- **Memory that learns from your work.** Let Neon remember approved preferences
+  and repo conventions from conversations and PR feedback.
+- **Ask Neon to set up the deck.** Configure repos, models, schedules, layout,
+  and display behavior through typed actions instead of hand-editing every file.
+
+## Project shape
+
+- `src/`: Hono/Flue backend, agents, actions, workflows, persistence, metrics,
+  CLI, and runtime-home setup.
+- `web/`: Vite, React, and Tailwind dashboard for the local companion display.
+- `docs/`: Astro marketing/docs site deployed to Cloudflare for
+  [neondeck.dev](https://neondeck.dev).
+- `config/`: checked-in defaults copied into new runtime homes.
+- `SOUL.md`: default personality/context material for Neon.
+
+## Quick start
+
+Use Node 26.4.0 or newer.
+
+```sh
+npm install
+npm run init
+npm run dev
+```
+
+Open `http://127.0.0.1:5173/`.
+
+The setup wizard prepares a runtime home, configures provider secrets, adds
+local repositories, applies a dashboard preset, and can create initial schedules
+and command preapprovals.
+
+## Runtime home
+
+Mutable local state lives outside the source tree. Neondeck resolves runtime
+home in this order:
+
+```text
+NEONDECK_HOME
+XDG_CONFIG_HOME/neondeck
+~/.config/neondeck
+```
+
+That home contains local secrets, runtime config, repo registration, dashboard
+layout, schedules, skills, and separate SQLite databases for Neondeck app state
+and Flue runtime state.
+
+## Common commands
+
+```sh
+npm run dev              # local backend + dashboard
+npm run cli -- status    # runtime readiness and configured paths
+npm run cli -- doctor    # local diagnostics
+npm run check            # fast local verification
+npm run test:integration # slower workflow coverage
+npm run build            # production dashboard/server + docs build
+npm run docs:astro-dev   # hot dev server for the docs site
+```
+
+After a production build or package install:
+
+```sh
+neondeck service install
+neondeck open
+neondeck open sidebar
+```
+
+## Documentation
+
+- [neondeck.dev](https://neondeck.dev): public site and product docs.
+- [Getting started](https://neondeck.dev/docs/getting-started/): install,
+  secrets, runtime home, dashboard launch, and local app install.
+- [Configuration](https://neondeck.dev/docs/configuration/): runtime config,
+  models, providers, repos, schedules, SOUL, and skills.
+- [Agent runtime](https://neondeck.dev/docs/agent-runtime/): Flue agents,
+  actions, workflows, memory, watches, reports, and scheduled tasks.
+- [Execution environments](https://neondeck.dev/docs/execution/): local and
+  sandboxed execution policy.
+- [MCP servers](https://neondeck.dev/docs/mcp/): MCP registration, OAuth, tool
+  policy, and approvals.
+- [Contributing](https://neondeck.dev/docs/contributing/): roadmap workflow,
+  checks, reviews, and PR expectations.
+- [Development](./DEVELOPMENT.md): repo-local setup, checks, builds, packaging,
+  docs deployment, and publishing notes.
+
+## Status
+
+Neondeck is active local-first infrastructure work. The roadmap lives in
+`.plans/ROADMAP.md`; it is the source of truth for implementation order and
+near-term priorities.
+
+## License
+
+MIT

package/SOUL.md

@@ -0,0 +1,8 @@
+# Soul
+
+name: Neon
+emoji: 🟢
+
+## Vibe
+
+Neon is a calm, technical companion for a developer's side display. It is concise, observant, and practical. It favors short answers, concrete next actions, and clear operational judgment over long explanations.

package/bin/neondeck.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const cliEntry = fileURLToPath(new URL('../src/cli/index.ts', import.meta.url));
+const tsxLoader = import.meta.resolve('tsx');
+const child = spawn(
+  process.execPath,
+  ['--import', tsxLoader, cliEntry, ...process.argv.slice(2)],
+  {
+    stdio: 'inherit',
+    env: process.env,
+  },
+);
+
+child.once('error', (error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});
+
+child.once('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});