@aemonge-dev/pi-stardeck 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andres Monge <andres@aemonge.com>
+
+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,3 +1,240 @@
-# Temporary Holding Version
+# pi-stardeck
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Vim- and tmux-inspired command deck for
+[Pi](https://pi.dev): lifecycle context, external-Neovim prompt
+composition, Vim command handling, and responsive operational telemetry in one package.
+
+![Pi cockpit header demonstration](docs/assets/pi-stardeck.gif)
+
+> [!IMPORTANT]
+> The best experience is **Pi in regular mode inside `nvim +terminal`**, with a blocking
+> Neovim bridge configured as Pi's `externalEditor`. Pi fullscreen reserves a three-row
+> editor slot and is not the target layout.
+
+## The cockpit
+
+```text
+Header Deck ◀── bounded lifecycle, work, project, model, and resource context
+    │
+    └── bottom separator ◀── live Vim Normal / Visual / EX / Insert feedback
+
+zero-row Vim command surface ── Insert transition ──▶ Neovim prompt.md
+                             ◀── :x + auto-submit ───┘
+
+responsive Footer ◀── model, quota, context, cost, Git, and capability telemetry
+```
+
+The package composes four bounded modules in dependency-safe order:
+
+- **Fancy Footer** — responsive model, quota, context, cost, Git, and resource telemetry;
+- **Status provider** — lifecycle, OpenSpec, Session Work, and diagnostic state;
+- **Header Deck** — current activity, focus, project state, and compact telemetry.
+  Companion extensions surface as leading telemetry icons:
+
+  | Chip | Extension | Meaning |
+  | --- | --- | --- |
+  | `[↻ ▤]` recall + records | `engram` | persistent memory store |
+  | `⌬` benzene | `graphify` | knowledge graph |
+  | `⛨` shield | `appa` / `pi-openappa` | tool-call guard |
+
+  Cyan means healthy, orange means warn, error, or not reporting.
+
+Optional Git, OpenSpec, Devbox, tmux, Neovim, provider-quota, and Nerd Font capabilities
+fail soft when absent. Pi core remains the API authority.
+
+## Recommended setup
+
+### Requirements
+
+- Node.js 24 or newer;
+- a current Pi installation;
+- Neovim for the recommended workflow;
+- one blocking `externalEditor` executable that accepts the temporary Markdown file as
+  its only argument, opens it in the enclosing Neovim instance, and exits when that
+  buffer closes.
+
+The bridge is deliberately not shipped: connecting to a private Neovim server is
+machine-specific and belongs in your trusted user configuration.
+
+Configure the bridge through Pi's global `~/.pi/agent/settings.json` or `/settings`:
+
+```json
+{
+  "externalEditor": "/absolute/path/to/your/blocking-nvim-bridge"
+}
+```
+
+The current adapter invokes that setting as one executable without a shell. Put arguments
+inside your bridge script rather than appending shell text to `externalEditor`.
+
+Start Neovim, open a terminal, and run Pi in regular mode:
+
+```vim
+:terminal
+```
+
+```bash
+pi --tui-mode regular
+```
+
+### Optional Ctrl-E mapping
+
+Current Pi defaults `app.editor.external` to Ctrl-G. The validated cockpit uses Ctrl-E;
+this remains your user-owned Pi configuration:
+
+```json
+{
+  "app.editor.external": "ctrl+e"
+}
+```
+
+Place that in `~/.pi/agent/keybindings.json`, then run `/reload`. The package never edits
+Pi or Neovim configuration automatically.
+
+## Prompt workflow
+
+The consolidated surface starts in Normal and renders zero native prompt rows.
+
+1. Press `i`, `a`, `I`, `A`, `o`, `O`, `s`, `S`, `C`, a supported change command, or
+   Pi's configured external-editor shortcut.
+2. The Header Deck shows Insert while Neovim owns the handoff.
+3. Compose in the temporary `prompt.md` buffer.
+4. Use `:x` or `:wq` after writing to return and submit exactly once.
+
+Submission follows the last explicit write—not a content comparison:
+
+- edited `:x` or `:wq` submits;
+- unchanged `:x` that performs no write submits nothing;
+- `:q!` without a write submits nothing;
+- `:w`, further unsaved edits, then `:q!` submits the last saved bytes;
+- failed, inactive, and duplicate handoffs never submit.
+
+Normal, Visual, and EX commands still operate on the hidden draft. Ordinary terminal
+scrollback navigation and text selection belong to the enclosing Neovim terminal buffer.
+Restoring outer Neovim's terminal Insert state after the prompt closes also remains
+Neovim configuration.
+
+## Health check
+
+Run the read-only health report directly:
+
+```text
+/stardeck-health
+```
+
+Or through the exact Pi EX-command bridge from Normal mode:
+
+```vim
+:stardeck-health
+```
+
+The bounded report classifies package registration, interactive TUI, external-editor
+readiness, recommended Neovim topology, and optional local capabilities as `PASS`,
+`WARN`, or `INFO`. It does not execute the configured editor or expose commands,
+settings, endpoints, environment values, credentials, or absolute paths.
+
+## Installation
+
+The package is MIT-licensed and published as `@aemonge-dev/pi-stardeck`.
+Review extensions before installation because Pi packages execute with user
+permissions. The command below works from any directory; it does not require
+cloning this repository.
+
+### From npm
+
+Install the cockpit extension through Pi:
+
+```bash
+pi install npm:@aemonge-dev/pi-stardeck
+```
+
+Do not load this package alongside the four legacy component package entries.
+Inspect `pi list`, then remove or disable duplicates as one reviewed user
+action. `npm link` is not Pi's package-registration mechanism.
+
+### Publish runbook (maintainer)
+
+Publishing is a maintainer action with maintainer credentials, never part of
+automated checks. From the repository root:
+
+```bash
+npm install --package-lock-only
+npm publish --access public
+```
+
+The scoped package name requires `--access public`; the lockfile refresh
+keeps `npm ci` reproducible after an identity change.
+
+### Local path (development)
+
+From the repository root:
+
+```bash
+npm ci
+npm run check
+pi install "$(pwd -P)"
+```
+
+### Pinned private Git source
+
+After the repository has an authorized remote, install an immutable tag or
+commit:
+
+```bash
+pi install git:<host>/<owner>/pi-stardeck@<tag-or-commit>
+```
+
+A pinned ref does not move during ordinary package updates.
+
+### Rollback
+
+Keep the previous source/ref before changing installation. To remove the npm
+installation:
+
+```bash
+pi remove npm:@aemonge-dev/pi-stardeck
+```
+
+For local-path installations, pass the absolute path to `pi remove` instead.
+Restore the previous package entries only after confirming this package has
+been removed; never keep both cockpit registrations active.
+
+## Reproducible VHS demo
+
+The checked-in tape simulates a fresh machine: the published package
+installs into an isolated throwaway `HOME` with a user-local npm prefix, and
+a clean offline Pi session runs the `/stardeck-health` report through Pi
+Vim's Normal-mode EX bridge. No provider,
+session, credential, or private editor bridge is involved. From the
+repository root, run:
+
+```bash
+vhs demo/pi-stardeck.tape
+```
+
+It writes `docs/assets/pi-stardeck.gif` using VHS's explicit Gruvbox
+Light terminal theme and a compact frame that keeps the cockpit prominent.
+Review the entire recording for private paths, notifications, or terminal
+history before committing it. The single reviewed GIF is the project's
+explicit demo-asset exception; ordinary screenshots and private runtime
+captures remain excluded.
+
+## Development
+
+```bash
+npm run check:package
+npm run check:package:load
+npm run check
+```
+
+The package gate constrains shipped paths, creates real tarballs only under temporary
+ignored directories, extracts them, and loads them through credential-free offline Pi.
+It never initializes another Git/Rustory repository or mutates Pi settings.
+
+See:
+
+- [`docs/architecture.md`](docs/architecture.md) — package and privacy boundaries;
+- [`docs/development.md`](docs/development.md) — focused checks and local development;
+- [`licenses/README.md`](licenses/README.md) — upstream licenses and provenance;
+- [`packages/pi-vim-top-border/README.md`](packages/pi-vim-top-border/README.md) — complete
+  Vim command reference.

package/demo/pi-stardeck.tape

@@ -0,0 +1,59 @@
+# Run from the pi-stardeck repository root.
+# Requires Pi, npm, and VHS; the recording installs the published package
+# into an isolated throwaway HOME, so it never touches real settings,
+# sessions, providers, or the private editor bridge.
+
+Output docs/assets/pi-stardeck.gif
+
+Set Shell "bash"
+Set Theme "Gruvbox Light"
+Set Width 1400
+Set Height 520
+Set Padding 20
+Set FontSize 24
+Set TypingSpeed 35ms
+Set Framerate 30
+Set PlaybackSpeed 1
+
+# Simulate a fresh machine: everything installs into a fixed throwaway HOME
+# under /tmp with a user-local npm prefix. The path is wiped at the start of
+# every run, so failed renders never accumulate. The real npm download cache
+# stays attached so the recording does not stall on a cold cache. Keep setup
+# out of the recording.
+Hide
+Type "export DEMO_HOME=/tmp/pi-stardeck-demo && rm -rf $DEMO_HOME && mkdir -p $DEMO_HOME && export NPM_CACHE_KEEP=$HOME/.npm && export HOME=$DEMO_HOME && export NPM_CONFIG_PREFIX=$HOME/.npm-global && export npm_config_cache=$NPM_CACHE_KEEP && export PATH=$NPM_CONFIG_PREFIX/bin:$PATH && clear"
+Enter
+Wait
+Show
+
+# Install the cockpit through Pi's package manager.
+# Long work sleeps hidden; the visible Wait commands then match instantly
+# against output that is already on screen — nothing races the recording.
+Type "pi install npm:@aemonge-dev/pi-stardeck"
+Enter
+Hide
+Sleep 15s
+Show
+Wait+Screen@30s /Installed npm:@aemonge-dev\/pi-stardeck/
+Sleep 1s
+
+# Launch a clean cockpit session from the fresh install.
+Type "clear && pi --offline --no-session --no-context-files --tui-mode regular"
+Enter
+Hide
+Sleep 12s
+Show
+Wait+Screen@60s /waiting/
+Sleep 4s
+
+# Exercise a real ephemeral title change without creating a session.
+Type ":name Public cockpit demo"
+Enter
+Wait+Screen /Public cockpit demo/
+Sleep 3s
+
+# Dispatch the credential-free health report through Pi Vim's Normal-mode EX bridge.
+Type ":stardeck-health"
+Enter
+Wait+Screen /pi-stardeck health/
+Sleep 5s

package/docs/architecture.md

@@ -0,0 +1,103 @@
+# Architecture
+
+## Current imported composition
+
+The baseline is one Pi package identity with four existing extension factories:
+
+```text
+root package manifest
+├── Fancy Footer telemetry provider
+├── status and focus producer
+├── Header Deck and telemetry producer
+└── focused zero-row Vim command surface and external-editor consumer
+```
+
+The manifest lists exact entrypoints rather than flattening approximately 36,000 lines
+into one file. Pi loads the package as one source; the modules continue to coordinate
+through the event protocols that already isolate them.
+
+Startup order is intentional:
+
+1. Fancy Footer subscribes to widget snapshots.
+2. Status registers focus tools and publishes lifecycle/work snapshots.
+3. Context Header consumes status and supplies the Header Deck renderer.
+4. Pi Vim installs the focused editor component, renders that deck with its live mode,
+   and routes composition through the external-editor adapter.
+
+Taskflow remains a separate optional Pi package. Its bounded runtime events are consumed
+when present; it is not a dependency of this package.
+
+## Stable protocol seams
+
+The imported modules currently coordinate through:
+
+- `pi-fancy-footer:widget` — complete protocol-1 widget snapshots;
+- `pi-fancy-footer:ready` — consumer readiness and producer republish;
+- `galactica-status:header` — bounded lifecycle, selection, suggestion, and active-run
+  snapshots;
+- `galactica-status:prompt-row` — prompt-rail telemetry;
+- `pi-vim:mode-change` — bounded editor mode events;
+- `pi-mcp-adapter/status/v1` — optional MCP availability.
+
+These channels are compatibility boundaries. Consolidation may centralize their types
+but must not silently change semantics or permit sensitive payloads. Selection is an
+additive protocol-1 projection of explicit OpenSpec, Goal, or Session Work state;
+suggestion is controlled vocabulary rather than generated prose. Active-run telemetry
+contains only bounded child and subagent counts derived from Pi lifecycle events. It
+never carries prompts, names, process identities, arguments, or child output. The deck
+renders these as a fixed operational row above a bounded full-width selection canvas.
+Its presentation keeps live runtime and the bold lifecycle anchor blue, uses regular
+blue for explicit selection, and keeps ordinary activity neutral. Recovery activity and
+its direction return to blue together; other ordinary direction remains green.
+Incomplete progress stays neutral and right-aligned, while yellow/red remain reserved
+for attention and blocked states.
+
+## Target module shape
+
+The consolidation Plan should evolve toward bounded ownership such as:
+
+```text
+src/
+├── index.ts              # composition root only
+├── editor/               # modes, motions, operators, clipboard
+├── external-editor/      # Pi action adapter, not private bridge logic
+├── header/               # lifecycle and focus rendering
+├── footer/               # responsive renderer and provider state
+├── deck-surface/         # Header Deck renderer and live mode context
+├── status/               # normalized project/runtime state
+├── adapters/             # optional OpenSpec, Taskflow, Devbox, MCP
+├── config/               # namespace, presets, legacy compatibility
+└── compatibility/        # feature-detected Pi API boundaries
+```
+
+This is a direction, not permission to move files. Each confirmed Task should preserve a
+runnable boundary and keep the imported trees available for comparison until their role
+is deliberately retired.
+
+## External editor boundary
+
+The consolidated package selects Pi Vim's explicit `external-editor-only` surface. The
+focused `ModalEditor` remains the input and hidden-draft authority, but in regular Pi
+mode its render path returns only the Header Deck: no prompt text, editor frame, cursor,
+or autocomplete rows. Pi's fullscreen layout reserves a core three-row editor slot, so
+fullscreen may retain blank space and is not the target workflow.
+
+The existing `PromptExternalEditor` adapter remains the single handoff used by direct
+Ctrl-E and automatic Insert-producing commands. It resolves the already configured
+external editor and owns the private temporary prompt file; this package does not alter
+Neovim configuration or duplicate the private Neovim bridge. A centralized
+`setMode('insert')` interception keeps the external-only surface's command state in
+Normal, queues one request, and flushes it after the current command finishes mutating
+cursor and draft text. While the handoff is active, the live deck rail resolves visually
+to Insert without recursively changing command state.
+
+Before launch, the adapter assigns the temporary file a known modification-time
+sentinel. A successful exit whose file metadata moved away from that sentinel proves an
+explicit write, including a same-content write. The returned saved bytes then submit
+exactly once through the editor's ordinary Enter path. An unwritten exit, failed launch,
+inactive controller, or duplicate request returns to Normal feedback without sending.
+If a user writes, keeps editing, then exits without saving again, the last written bytes
+are the honest submission boundary. Normal, Visual, and EX dispatch continue through the
+focused custom editor, while previously unsupported Vim commands remain unsupported.
+Restoring the enclosing Neovim terminal's `startinsert` mode remains Neovim configuration
+and is intentionally outside this package.

package/docs/development.md

@@ -0,0 +1,128 @@
+# Development
+
+## Standalone boundary
+
+Work from the standalone repository and confirm its current integrity:
+
+```bash
+cd /home/aemonge/projects/pi-stardeck
+pwd -P
+git status --short
+npm run check:baseline
+```
+
+The exact import is preserved at Git commit `9d7bb84` and in
+`baseline/imported-source.sha256`. Current intentional package files are tracked by
+`baseline/source.sha256`; update that manifest only inside a confirmed Task after focused
+checks pass.
+
+## Dependencies
+
+The root package is the only dependency-install boundary. Pi provides the four runtime
+peers used by the extensions:
+
+- `@earendil-works/pi-ai`;
+- `@earendil-works/pi-coding-agent`;
+- `@earendil-works/pi-tui`;
+- `typebox`.
+
+Development uses one root `package-lock.json`; workspace-local lockfiles and
+`node_modules` are not part of the project. After the cache has been populated, reproduce
+the exact tree without network access:
+
+```bash
+npm ci --offline --ignore-scripts --no-audit --no-fund
+```
+
+Do not weaken peer contracts, copy Pi's installation tree, or commit generated
+dependencies.
+
+## Verification
+
+Nearest focused commands remain available:
+
+```bash
+npm run test:status
+npm run test:stardeck
+npm run test:footer
+npm run test:vim
+npm run test:components
+```
+
+The complete deterministic gate is:
+
+```bash
+npm run check
+```
+
+It verifies current and imported integrity, the packed-file allowlist, a real temporary
+artifact extraction and credential-free offline Pi load, formatting, Biome and ESLint,
+strict TypeScript, repository tooling tests, every component suite, and schema-aware
+OpenSpec planning state. The package checks are also available independently:
+
+````bash
+npm run check:package
+npm run check:package:load
+``` Formatter writes are separate and explicit:
+
+```bash
+npm run format
+npm run format:check
+````
+
+`npm run check:openspec` treats `skip_specs: true` only as a planning-schema contract for
+completed `ramona-idea` and `ramona-plan` artifacts. Every other change is delegated to
+upstream strict OpenSpec validation.
+
+## Isolated Pi loading
+
+The normal Pi settings may still load the original Galactica packages. Avoid duplicate
+commands, event listeners and editor registration by disabling normal discovery during a
+probe:
+
+```bash
+pi --offline --no-extensions -e "$(pwd -P)" --list-models
+```
+
+Use a bounded interactive session only when its manual checks are declared. Do not make
+provider requests merely to prove package loading.
+
+After parity validation and exact `ALLOW PI CONFIG` authority, install the local package
+with:
+
+```bash
+pi install "$(pwd -P)"
+```
+
+Then remove or disable the four legacy package entries as one reviewed migration. Do not
+use `npm link`; Pi local paths are already linked without copying.
+
+## Packaging
+
+`npm run check:package` wraps `npm pack --dry-run --json --ignore-scripts` and rejects
+planning records, tests, baselines, agent instructions, development configuration,
+private settings, and credentials. `npm run check:package:load` creates the actual
+artifact only in a temporary directory, extracts it, and invokes that package through Pi
+with a fresh HOME, no session, no discovered extensions, no credential environment, and
+o network.
+
+The private package is not authorized for npm publication or remote Git push. Optional
+capabilities remain fixture-covered without initializing an auxiliary Git or Rustory
+repository.
+
+## VHS demonstration
+
+The demo source is `demo/pi-stardeck.tape`. VHS is intentionally not a project
+runtime or development dependency. The public header-led recording hides routine
+startup, runs Pi directly, and does not require the private Neovim bridge:
+
+```bash
+vhs demo/pi-stardeck.tape
+```
+
+The tape uses offline, sessionless Pi, applies an ephemeral public title, and dispatches
+`:stardeck-health` through Pi Vim's Normal-mode EX bridge rather than sending a provider
+prompt. It pins VHS's Gruvbox Light terminal theme, uses compact header-led framing, and
+waits for stable screen text instead of relying only on launch timing. Human must review
+`docs/assets/pi-stardeck.gif` for private runtime content before its final
+Task-boundary commit.

package/licenses/README.md

@@ -0,0 +1,17 @@
+# Licenses and provenance
+
+`pi-stardeck` is private and currently marked `UNLICENSED` as a whole. Imported
+third-party-derived components retain their own licenses:
+
+- `pi-vim-LICENSE` covers the imported `pi-vim-top-border` descendant;
+- `pi-fancy-footer-LICENSE` covers the imported Fancy Footer fork.
+
+The same license text remains beside each imported source. Local modifications are
+recorded in:
+
+- `packages/pi-vim-top-border/LOCAL-CHANGES.md`;
+- `packages/pi-fancy-footer-full-palette/LOCAL-CHANGES.md`.
+
+Do not remove or replace these notices when consolidating or packing the source. A
+future public release requires an explicit project-level licensing decision in addition
+to retaining upstream attribution.

package/licenses/pi-fancy-footer-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthias Vallentin
+
+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/licenses/pi-vim-LICENSE

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