@runwingman/flightdeck-cli 0.2.0

package/Dockerfile

@@ -0,0 +1,21 @@
+FROM node:20-bookworm-slim
+
+WORKDIR /workspace
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends python3 make g++ \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY package.json package.json
+COPY src/ src/
+COPY README.md README.md
+COPY LICENSE LICENSE
+
+RUN npm install --omit=dev
+RUN npm link
+
+ENV FLIGHTDECK_CLI_STATE_DIR=/state
+VOLUME ["/state"]
+
+ENTRYPOINT ["flightdeck-cli"]
+CMD ["--help"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Humans Institute
+
+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,353 @@
+# FlightDeck CLI
+
+FlightDeck CLI is the command line tool that agents and operators use to interact with Wingman workspaces through Tower. It provides local SQLite-backed access to tasks, chat, docs, storage, flows, approvals, and more.
+
+## Runtime Support
+
+FlightDeck CLI currently supports `Node.js` only.
+
+- Use the installed `flightdeck-cli` binary, `npx @runwingman/flightdeck-cli ...`, or `node src/cli.js ...`
+- Do not run the CLI with `bun`
+
+The reason is the local SQLite layer currently uses `better-sqlite3`, and Bun execution can fail with native addon / ABI mismatches even when the rest of the CLI is otherwise fine.
+
+## Quickstart
+
+### 1. Install
+
+```bash
+# One-line installer
+curl -fsSL https://raw.githubusercontent.com/humansinstitute/wingman-yoke/main/install.sh | bash
+
+# From npm
+npm install -g @runwingman/flightdeck-cli
+
+# Or run directly
+npx @runwingman/flightdeck-cli --help
+```
+
+For local development:
+
+```bash
+git clone https://github.com/humansinstitute/wingman-yoke.git
+cd wingman-yoke
+npm install
+```
+
+**Requires Node >= 20.** The installer tries `npm` first and falls back to GitHub until the npm package is published. Set `FLIGHTDECK_CLI_INSTALL_METHOD=git` to force the GitHub path.
+
+### 2. Set your identity
+
+```bash
+export FLIGHTDECK_CLI_NSEC=nsec1...
+```
+
+When FlightDeck CLI runs inside a Wingmen-managed agent session, it can also resolve the per-session bot key automatically from Wingmen using `WINGMAN_URL` + `SESSION_ID`, or directly from `AGENT_NSEC` if that env var is injected into the session.
+
+### 3. Initialize with a connection token
+
+```bash
+flightdeck-cli init --token "<connection_token>"
+```
+
+You can also pass the full Agent Connect JSON package — FlightDeck CLI extracts `.connection_token` automatically.
+
+### 4. Sync workspace data
+
+```bash
+flightdeck-cli sync
+```
+
+This pulls workspace records into your local SQLite mirror at `./.flightdeck-cli/flightdeck-cli.db` under the folder where you run the CLI.
+
+### 5. Start working
+
+```bash
+# Check connection status
+flightdeck-cli status
+
+# List and manage tasks
+flightdeck-cli tasks list
+flightdeck-cli tasks create --title "New task"
+flightdeck-cli tasks comment <task-id> --body "Update here"
+
+# Chat
+flightdeck-cli chat channels
+flightdeck-cli chat send <channel-id> --body "Hello"
+
+# Docs
+flightdeck-cli docs list
+flightdeck-cli docs create --title "Notes" --content "hello world"
+```
+
+> **Tip:** When running from a local clone, replace `flightdeck-cli` with `node src/cli.js`. Do not use `bun src/cli.js`.
+
+The legacy `wingman-yoke` binary remains available during the rename window.
+
+## State
+
+By default, state lives in:
+
+- `./.flightdeck-cli/flightdeck-cli.db` — local SQLite mirror for the current working directory
+- `./.flightdeck-cli/config.json` — workspace config for the current working directory
+
+Environment variables:
+
+- `FLIGHTDECK_CLI_STATE_DIR` — override state directory explicitly, including a shared/global path if you want one
+- `FLIGHTDECK_CLI_NSEC` — explicit agent/operator identity override
+- `AGENT_NSEC` — per-agent secret injected by Wingmen sessions
+- `WINGMAN_URL` + `SESSION_ID` — lets FlightDeck CLI fetch the current session bot key from the running Wingmen server
+
+Compatibility fallbacks (`WINGMAN_YOKE_STATE_DIR`, `WINGMAN_YOKE_NSEC`, `./.wingman-yoke`, `yoke.db`, `WINGMAN_AP_STATE_DIR`, `WINGMAN_AUTOPILOT_NSEC`, `autopilot.db`, Bitwarden `wm21-nostr`) are still supported.
+
+## Docker
+
+Build the local image:
+
+```bash
+docker build -t runwingman/flightdeck-cli .
+```
+
+Run with mounted state:
+
+```bash
+docker run --rm \
+  -e FLIGHTDECK_CLI_NSEC="$FLIGHTDECK_CLI_NSEC" \
+  -e FLIGHTDECK_CLI_STATE_DIR=/state \
+  -v flightdeck-cli-state:/state \
+  runwingman/flightdeck-cli sync
+```
+
+## Command Reference
+
+```bash
+node src/cli.js status
+node src/cli.js getLatest
+
+node src/cli.js tasks list
+node src/cli.js tasks create --title "New task"
+node src/cli.js tasks update <task-id> --state in_progress
+node src/cli.js tasks comment <task-id> --body "Looks good"
+node src/cli.js tasks reply <comment-id> --body "Following up"
+node src/cli.js tasks comment-image <task-id> --file ./image.png --body "See this"
+node src/cli.js tasks voice <task-id> --file ./voice.aiff --body "Voice note"
+
+node src/cli.js chat channels
+node src/cli.js chat create --title "FlightDeck temp"
+node src/cli.js chat messages <channel-id>
+node src/cli.js chat context --channel <channel-id> --format json
+node src/cli.js chat history --channel <channel-id> --thread <thread-id> --format json
+node src/cli.js chat search --query "term" --format json
+node src/cli.js chat search --query "find previous budget chats" --deep --reference thread:<thread-id> --format json
+node src/cli.js chat related --format json
+node src/cli.js chat related --deep --format json
+node src/cli.js chat reply-current --body "Reply" --format json
+node src/cli.js chat send <channel-id> --body "Hello"
+node src/cli.js chat reply <channel-id> --thread <message-id> --body "Reply"
+node src/cli.js chat image <channel-id> --file ./image.png --body "Screenshot"
+node src/cli.js chat voice <channel-id> --file ./voice.aiff --body "Voice note"
+
+node src/cli.js docs list
+node src/cli.js docs create --title "Scratch doc" --content "hello"
+node src/cli.js docs show <doc-id>
+node src/cli.js docs update <doc-id> --content-file ./doc.md
+node src/cli.js directories create --title "Projects"
+node src/cli.js directories list
+node src/cli.js directories show <directory-id>
+node src/cli.js directories update <directory-id> --title "Renamed"
+node src/cli.js docs comment <doc-id> --body "Needs work" --line 12
+node src/cli.js docs reply <comment-id> --body "Updated"
+node src/cli.js docs comment-image <doc-id> --file ./image.png --line 12
+node src/cli.js docs voice <doc-id> --file ./voice.aiff --line 12
+
+node src/cli.js scopes create --title "Flight Deck" --level product
+node src/cli.js scopes list
+node src/cli.js scopes show <scope-id>
+node src/cli.js scopes update <scope-id> --title "Flight Deck Core"
+
+node src/cli.js storage upload ./image.png
+node src/cli.js audio list
+node src/cli.js audio show <audio-note-id>
+node src/cli.js audio update-transcript <audio-note-id> --transcript "Transcript text"
+```
+
+## Agent Chat Runtime Tools
+
+Phase 03 adds bot-friendly chat runtime commands. These commands persist a local "current chat context" in the SQLite mirror so Wingmen can bootstrap a session once, then use follow-up commands without custom shell glue. Runtime commands only support `--format json` in Phase 03 and default to JSON even without the global `--json` flag.
+
+Context resolution order:
+
+- explicit `--message`
+- explicit `--thread`
+- explicit `--channel` with the most recently active local thread in that channel
+- last stored runtime context from local SQLite
+
+### `chat context --format json`
+
+Returns the active channel/thread context with participants and the latest few local thread messages.
+
+```json
+{
+  "channel_id": "chan_123",
+  "thread_id": "msg_root_1",
+  "participants": ["npub1bot...", "npub1user..."],
+  "recent_messages": [
+    {
+      "message_id": "msg_root_1",
+      "parent_message_id": null,
+      "sender_npub": "npub1user...",
+      "body": "@wingman can you review this?",
+      "attachments": [],
+      "updated_at": "2026-04-08T10:00:00.000Z"
+    }
+  ]
+}
+```
+
+### `chat history --format json`
+
+Returns paged local thread history for the active context. The first call returns the latest page in arrival order. Pass the returned cursor back in to page further back.
+
+```json
+{
+  "channel_id": "chan_123",
+  "thread_id": "msg_root_1",
+  "messages": [
+    {
+      "message_id": "msg_reply_2",
+      "parent_message_id": "msg_root_1",
+      "sender_npub": "npub1bot...",
+      "body": "I found the issue in the runtime helper.",
+      "attachments": [],
+      "updated_at": "2026-04-08T10:03:00.000Z"
+    }
+  ],
+  "cursor": "offset:20"
+}
+```
+
+### `chat search --format json`
+
+Phase 05 keeps the Phase 04 workspace-local behavior and adds two bounded enhancements:
+
+- `--reference` accepts exact `message:`, `thread:`, `channel:`, or `mention:` hints for direct lookup
+- `--deep` adds bounded thread-level summaries with the top matching message snippets per thread
+
+```json
+{
+  "query": "find previous budget chats",
+  "references": [
+    {
+      "reference": "thread:msg_root_9",
+      "kind": "thread",
+      "channel_id": "chan_999",
+      "channel_title": "Budget Archive",
+      "thread_id": "msg_root_9",
+      "root_message_id": "msg_root_9",
+      "last_message_id": "msg_reply_11",
+      "message_count": 3,
+      "updated_at": "2026-04-07T19:12:00.000Z",
+      "summary": "Previous discussion about the same rollout.",
+      "participants": ["npub1bot...", "npub1user..."]
+    }
+  ],
+  "results": [
+    {
+      "message_id": "msg_reply_2",
+      "channel_id": "chan_123",
+      "channel_title": "Agent Chat",
+      "thread_id": "msg_root_1",
+      "parent_message_id": "msg_root_1",
+      "sender_npub": "npub1bot...",
+      "body": "I found the issue in the runtime helper.",
+      "updated_at": "2026-04-08T10:03:00.000Z",
+      "scope": "current_thread"
+    }
+  ],
+  "threads": [
+    {
+      "channel_id": "chan_123",
+      "channel_title": "Agent Chat",
+      "thread_id": "msg_root_1",
+      "root_message_id": "msg_root_1",
+      "last_message_id": "msg_reply_2",
+      "message_count": 4,
+      "updated_at": "2026-04-08T10:03:00.000Z",
+      "summary": "Please review the runtime helper rollout.",
+      "participants": ["npub1bot...", "npub1user..."],
+      "scope": "current_thread",
+      "matching_messages": [
+        {
+          "message_id": "msg_reply_2",
+          "sender_npub": "npub1bot...",
+          "body": "I found the issue in the runtime helper.",
+          "updated_at": "2026-04-08T10:03:00.000Z"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### `chat related --format json`
+
+Phase 05 keeps the Phase 04 cross-chat behavior and adds `--deep`, which includes bounded supporting message snippets from each related thread.
+
+```json
+{
+  "message_id": "msg_reply_2",
+  "related_threads": [
+    {
+      "channel_id": "chan_123",
+      "channel_title": "Agent Chat",
+      "thread_id": "msg_root_9",
+      "root_message_id": "msg_root_9",
+      "last_message_id": "msg_reply_11",
+      "message_count": 3,
+      "updated_at": "2026-04-07T19:12:00.000Z",
+      "summary": "Previous discussion about the same rollout.",
+      "participants": ["npub1bot...", "npub1user..."],
+      "match_score": 24,
+      "relation": {
+        "same_channel": false,
+        "shared_terms": ["budget", "rollout"],
+        "shared_participants": ["npub1bot...", "npub1user..."]
+      },
+      "matching_messages": [
+        {
+          "message_id": "msg_reply_11",
+          "sender_npub": "npub1user...",
+          "body": "Budget notes from the earlier rollout are here.",
+          "updated_at": "2026-04-07T19:10:00.000Z"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### `chat reply-current --format json`
+
+Replies into the active thread root stored in local runtime context, then updates that local context to the newly sent bot message.
+
+```json
+{
+  "channel_id": "chan_123",
+  "thread_id": "msg_root_1",
+  "message_id": "msg_bot_reply_3",
+  "status": "sent"
+}
+```
+
+## Development
+
+```bash
+# Run commands locally
+node src/cli.js status
+node src/cli.js sync
+
+# Run tests
+npm test
+```
+
+Schema compatibility is part of the FlightDeck CLI test suite. It validates supported outbound families against the published Flight Deck manifests in `../sb-publisher/schemas/flightdeck`.

package/docs/to_fdcli.md

@@ -0,0 +1,78 @@
+# FlightDeck CLI Rollout
+
+Yoke is becoming FlightDeck CLI so it can be installed reliably in local shells, CI jobs, and many Docker containers without cloning this repository in each environment.
+
+## Package name
+
+Use **FlightDeck CLI** as the product name.
+
+Use `@runwingman/flightdeck-cli` as the npm package name. Keep `flightdeck-cli` as the executable name.
+
+Keep `wingman-yoke` as a compatibility executable during the migration.
+
+## Phase 1: Additive rename and compatibility
+
+- Update visible CLI branding to FlightDeck CLI.
+- Add the `flightdeck-cli` binary while keeping the existing `wingman-yoke` binary.
+- Add preferred environment variables:
+  - `FLIGHTDECK_CLI_NSEC`
+  - `FLIGHTDECK_CLI_STATE_DIR`
+  - `FLIGHTDECK_CLI_ALLOW_STORAGE_KEY_GUESS`
+  - `FLIGHTDECK_CLI_AUDIO_S3_INPUT`
+- Keep old variables working:
+  - `WINGMAN_YOKE_NSEC`
+  - `WINGMAN_YOKE_STATE_DIR`
+  - `WINGMAN_YOKE_ALLOW_STORAGE_KEY_GUESS`
+  - `WINGMAN_YOKE_AUDIO_S3_INPUT`
+- Move the default local state directory to `./.flightdeck-cli` for new installs.
+- Continue reading existing `./.wingman-yoke` and legacy `./.wingman-ap` state directories.
+- Update README and command examples to prefer `flightdeck-cli`.
+
+## Phase 2: npm distribution
+
+- Rename package metadata to `@runwingman/flightdeck-cli`.
+- Include both npm bin names:
+  - `flightdeck-cli`
+  - `wingman-yoke`
+- Verify package contents with `npm pack --dry-run`.
+- Verify installability with a packed tarball:
+
+```bash
+npm pack
+npm install -g ./runwingman-flightdeck-cli-*.tgz
+flightdeck-cli --help
+wingman-yoke --help
+```
+
+- Publish the new package when registry ownership is ready.
+- Keep the old package as a compatibility alias or deprecated shim after the new package is live.
+
+## Phase 3: Docker and script installs
+
+- Add a Debian-based Dockerfile using Node 20 so native dependencies such as `better-sqlite3` build and load predictably.
+- Prefer mounted state in Docker:
+
+```bash
+docker run --rm \
+  -e FLIGHTDECK_CLI_NSEC="$FLIGHTDECK_CLI_NSEC" \
+  -e FLIGHTDECK_CLI_STATE_DIR=/state \
+  -v flightdeck-cli-state:/state \
+  runwingman/flightdeck-cli sync
+```
+
+- Update `install.sh` to try npm first and fall back to git until the npm package is published.
+- Keep a git install method for development or pre-publish testing.
+- Create `flightdeck-cli` as the primary command and keep `wingman-yoke` available for existing automation.
+
+## Release checklist
+
+- `npm test`
+- `npm pack --dry-run`
+- install packed tarball in a temporary environment
+- `flightdeck-cli --help`
+- `wingman-yoke --help`
+- Docker build smoke test
+
+## Deprecation policy
+
+Do not remove the old binary or old environment variables until downstream agent and Docker workflows have moved to FlightDeck CLI. At that point, emit warnings first, then remove compatibility in a later major version.

package/install.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# FlightDeck CLI installer
+# Usage: curl -fsSL https://raw.githubusercontent.com/humansinstitute/wingman-yoke/main/install.sh | bash
+
+PACKAGE="${FLIGHTDECK_CLI_PACKAGE:-@runwingman/flightdeck-cli}"
+VERSION="${FLIGHTDECK_CLI_VERSION:-latest}"
+INSTALL_METHOD="${FLIGHTDECK_CLI_INSTALL_METHOD:-npm}"
+REPO="${FLIGHTDECK_CLI_REPO:-humansinstitute/wingman-yoke}"
+INSTALL_DIR="${FLIGHTDECK_CLI_INSTALL_DIR:-${WINGMAN_YOKE_INSTALL_DIR:-$HOME/.flightdeck-cli}}"
+BIN_DIR="${FLIGHTDECK_CLI_BIN_DIR:-/usr/local/bin}"
+FLIGHTDECK_BIN_LINK="$BIN_DIR/flightdeck-cli"
+YOKE_BIN_LINK="$BIN_DIR/wingman-yoke"
+
+echo "Installing FlightDeck CLI..."
+
+command -v node >/dev/null 2>&1 || { echo "Error: Node.js >= 20 is required. Install from https://nodejs.org"; exit 1; }
+
+NODE_MAJOR=$(node -e "console.log(process.versions.node.split('.')[0])")
+if [ "$NODE_MAJOR" -lt 20 ]; then
+  echo "Error: Node.js >= 20 required (found v$(node -v))"
+  exit 1
+fi
+
+command -v npm >/dev/null 2>&1 || { echo "Error: npm is required"; exit 1; }
+
+link_git_install() {
+  local source_bin="$INSTALL_DIR/src/cli.js"
+  chmod +x "$source_bin"
+
+  if [ -w "$BIN_DIR" ]; then
+    ln -sf "$source_bin" "$FLIGHTDECK_BIN_LINK"
+    ln -sf "$source_bin" "$YOKE_BIN_LINK"
+  else
+    echo "Creating symlinks requires sudo..."
+    sudo ln -sf "$source_bin" "$FLIGHTDECK_BIN_LINK"
+    sudo ln -sf "$source_bin" "$YOKE_BIN_LINK"
+  fi
+}
+
+install_from_git() {
+  command -v git >/dev/null 2>&1 || { echo "Error: git is required for FLIGHTDECK_CLI_INSTALL_METHOD=git"; exit 1; }
+
+  if [ -d "$INSTALL_DIR" ]; then
+    echo "Removing previous install at $INSTALL_DIR..."
+    rm -rf "$INSTALL_DIR"
+  fi
+
+  echo "Cloning from github.com/$REPO..."
+  git clone --depth 1 "https://github.com/$REPO.git" "$INSTALL_DIR" 2>&1 | tail -1
+
+  echo "Installing dependencies (this compiles better-sqlite3)..."
+  cd "$INSTALL_DIR"
+  npm install --omit=dev 2>&1 | tail -3
+
+  link_git_install
+}
+
+install_from_npm() {
+  if [ "$VERSION" = "latest" ]; then
+    npm install -g "$PACKAGE"
+  else
+    npm install -g "$PACKAGE@$VERSION"
+  fi
+}
+
+if [ "$INSTALL_METHOD" = "git" ]; then
+  install_from_git
+else
+  if ! install_from_npm; then
+    echo "npm install failed for $PACKAGE@$VERSION."
+    echo "Falling back to git install from github.com/$REPO..."
+    install_from_git
+  fi
+fi
+
+echo ""
+echo "FlightDeck CLI installed successfully."
+echo "  Command: flightdeck-cli --help"
+echo "  Legacy:  wingman-yoke --help"
+echo ""
+echo "Quick start:"
+echo "  export FLIGHTDECK_CLI_NSEC=<your-nsec>"
+echo "  flightdeck-cli init --token <connection_token>"
+echo "  flightdeck-cli sync"

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@runwingman/flightdeck-cli",
+  "version": "0.2.0",
+  "description": "FlightDeck CLI for Coworker v4 / SuperBased workspaces",
+  "type": "module",
+  "license": "MIT",
+  "author": "Humans Institute",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/humansinstitute/wingman-yoke.git"
+  },
+  "homepage": "https://github.com/humansinstitute/wingman-yoke#readme",
+  "bugs": {
+    "url": "https://github.com/humansinstitute/wingman-yoke/issues"
+  },
+  "keywords": [
+    "wingman",
+    "flightdeck",
+    "cli",
+    "coworker",
+    "superbased",
+    "nostr"
+  ],
+  "bin": {
+    "flightdeck-cli": "src/cli.js",
+    "wingman-yoke": "src/cli.js"
+  },
+  "files": [
+    "src/",
+    "docs/to_fdcli.md",
+    "install.sh",
+    "Dockerfile",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/cli.js",
+    "dev": "node src/cli.js",
+    "check": "node src/cli.js --help",
+    "pack:dry-run": "npm pack --dry-run",
+    "smoke:bin": "node src/cli.js --help",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@nostr-superbased/core": "0.1.0",
+    "better-sqlite3": "^11.8.1",
+    "commander": "^13.1.0",
+    "nostr-tools": "^2.17.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}