Skip to content

feat: add vana connect CLI#56

Open
tnunamak wants to merge 231 commits intomainfrom
feat/connect-cli-v1
Open

feat: add vana connect CLI#56
tnunamak wants to merge 231 commits intomainfrom
feat/connect-cli-v1

Conversation

@tnunamak
Copy link
Member

@tnunamak tnunamak commented Mar 12, 2026

Summary

  • add the first vana CLI slice with connect, sources, status, and setup
  • add managed local runtime/state/log handling plus Personal Server detection/ingest hooks
  • expose runtime and connector registry as SDK modules and bundle the headless runner assets for CLI installs

Details

  • adds CLI entrypoints under src/cli
  • adds connector registry helpers under src/connectors
  • adds CLI state/contracts under src/core
  • adds managed Playwright runtime support under src/runtime
  • adds Personal Server helpers under src/personal-server
  • vendors the Playwright runner into runtime-assets/playwright-runner so setup provisions from vana-connect itself
  • updates package metadata so the package can ship a vana bin and ./cli, ./runtime, ./connectors exports
  • documents the CLI and SDK/runtime split in the README
  • adds the CLI/spec docs under docs/

Verification

  • pnpm build
  • pnpm test
  • node dist/cli/bin.js --help
  • clean-home smoke test:
    • HOME=$(mktemp -d) node dist/cli/bin.js setup --yes
    • status --json reported runtime installed
    • setup log no longer includes any git clone of data-connect

Notes

  • this PR focuses on CLI/runtime ownership inside vana-connect
  • skill updates for Claude/Kimi live in data-connectors and are tracked separately

@vercel
Copy link

vercel bot commented Mar 12, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
connect Ready Ready Preview Mar 18, 2026 7:26am

Request Review

tnunamak and others added 30 commits March 17, 2026 10:47
Replace the verbose section-based connect output with a minimal
phase-aware renderer. The scope manifest (✓ lines appearing as
data is collected) is now the core visual element.

- ConnectRenderer manages temporal phases with spinner-to-checkmark
  transitions via ANSI cursor control
- Remove all section headers (→ Preparing, → Connecting, etc.)
- Remove narration of internal phases
- Integrate @clack/prompts for styled credential inputs and
  source picker, replacing @inquirer/prompts
- Remove ~620 lines of verbose output code and dead functions
- Terminal bell on completion
- Clean single-line errors with one recovery command
- --json mode, exit codes, state updates unchanged

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Remove bracket badges, section arrows, and bullet next-steps from
every command surface. All commands now use the same visual language
as the connect flow: colored text without brackets, bold headings
without arrows, single "Next:" line without bullets.

Primitives changed:
- badge(): brackets removed, just colored text
- section(): arrow removed, just bold heading

Per-command changes:
- sources: auth mode badges removed (group headers suffice),
  descriptions shortened ("Your X" not "Exports your X")
- status: title simplified, single next step
- doctor: arrows removed, badges removed from attention section
- data list/show: sections removed, single next step
- server status: consistent next step format
- all commands: multi-bullet next steps → single "Next:" line

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Make color carry information, not just dim everything:
- Status: "not connected" now warning (was muted)
- Status: sources line uses warning when attention needed
- Next: lines use dedicated next() renderer — "Next:" in muted,
  command in bold. Previously buried in muted detail().
- ConnectRenderer: added next() method matching emitter pattern

Verified already correct (no changes needed):
- Doctor: missing/present checks use warning/success
- Doctor: unavailable capabilities use warning
- Server: healthy/unhealthy uses success/warning
- Sources: recommended uses accent

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Normalize source argument to lowercase so `vana connect GitHub`
works the same as `vana connect github`.

Distinguish checksum mismatch errors from "not available" — show
cache clear + retry command instead of generic "not available"
when the connector exists but the cached copy is stale.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Replace all stale transcripts with current CLI output. Remove
arrow headers, bracket badges, bullet next-steps. Add connect
flow transcripts matching ConnectRenderer format.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
… -rf

When a connector checksum mismatch is detected, automatically clear
the cached connector and re-fetch from the registry. Only show an
error if the retry also fails, and even then suggest checking
network connectivity — never expose internal cache paths or ask
users to run rm -rf.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Source detail: show what data scopes are collected (thesis: make
data visible), remove implementation metadata (version, frequency,
auth mode, company). Remove alarming "new" badge on fresh installs.

Status: show "none connected" instead of "0 connected, 2 need
attention" on fresh installs. Attention count only shown when
the user has connected sources with actual issues.

Sources list: remove group headers and counts. Top 3 sources
expanded with descriptions, rest collapsed to one line. Removes
the wall-of-text listing.

Doctor: humanize checksum errors ("Connector is out of date"),
remove internal capability lines (headed sessions, managed
profiles, screenshots), fix circular next-step to point at logs.

Connect error: honest about verification failures, link to
issue tracker instead of blaming user's network.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
When a connector checksum mismatch triggers auto-retry, force the
re-fetch from the remote registry instead of copying from a local
data-connectors checkout that may have stale files. This fixes the
case where a user has a local data-connectors repo that hasn't
been updated since an upstream connector change.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
The PS API requires POST body to be a JSON object. Connector
scopes like repositories and starred produce arrays, which were
rejected with INVALID_BODY. Now arrays are wrapped as
{ items: [...] } and primitives as { value: ... } before posting.

This fixes the "1/3 scopes synced, 2 failed" issue on GitHub
connect where profile (object) succeeded but repositories and
starred (arrays) failed.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Restore the hand-crafted connect renderer that was accidentally
overwritten by an agent in commit 5029900. The original renderer
(from ae3a674) features a custom heartbeat bloom spinner
(· → ✧ → ✦ double-beat with dark pause) with ANSI cursor control
for in-place repaint — no ora dependency.

Adapted the restored renderer's interface to match current call
sites (title, scopeActive, scopeDone, success, detail, next,
fail, bell, cleanup, pauseForPrompt, resumeAfterPrompt).

Replaced @clack/prompts with @inquirer/prompts for credential
inputs and source picker. Clack's visual chrome (vertical bars,
diamond symbols) violated the design skill's principle of owning
our visual identity.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
When success() or fail() is called, any scope still in "active"
state (mid-spinner) was frozen instead of transitioning to ✓ or ✗.
Now active scopes resolve to done/failed before the final repaint.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Apply Vana brand palette to all inquirer prompts: blue ? prefix,
blue highlight, muted help text, matching the accent/muted/error
colors from vana-app's shadcn.css.

Change scope completion checkmarks from green to Vana accent blue
to match the spinner — blue spinner resolves to blue check with
no jarring color jump.

Remove unused SUCCESS constant from connect renderer.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Blue ✓ for all completion checkmarks (scope lines, success message,
prompt done prefix) — matches the blue spinner with no color jump.
Red ✗ for failures. Success/fail messages now have their prefix
symbol in both TTY and non-TTY modes.

Remove unused VANA_GREEN and SUCCESS constants. Prompt done prefix
uses blue to match connect renderer.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
When a new progress phase starts, the previous active scope now
resolves to ✓ immediately instead of all scopes staying in spinner
state until success() is called at the end. This creates the
progressive checkmark effect: each line transitions from spinner
to ✓ as the next phase begins.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Server sync: per-scope results now use themed ✓/✗ with Vana
accent blue and error red. Journey-aware next step at the end.

Next steps: all remaining emit.info("Next:") calls converted to
emit.next() with extractCommand() helper for consistent formatting.

Path tree: 7 new test cases covering first-time setup, credential
prompts, connector fetch failure, legacy auth without display,
prompt cancellation, and server sync output. 186 tests total.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Phase 1: Extract query functions (queryStatus, querySources) from
CLI command handlers into src/cli/queries.ts. These return the same
typed objects that --json mode serializes, enabling reuse by the
MCP server.

Phase 3: Skills registry mirroring the connector pattern. Flat
top-level skills/ directory with registry.json and SKILL.md files
for connect-data, create-connector, and recipes. Skills are fetched
from GitHub and installed to ~/.claude/skills/ via vana skill install.

New commands: vana skill list, vana skill install <name>,
vana skill show <name>.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Add `vana mcp` command that starts an MCP server over stdio,
making the CLI discoverable by any MCP-compatible agent (Claude
Code, Cursor, Windsurf, etc.).

6 tools: check_status, list_sources, show_data, connect_source,
run_diagnostics, generate_context (placeholder).

MCP SDK lazy-imported. connect_source runs as child process for
stdout isolation.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Connector results are now copied to ~/.dataconnect/results/{source}.json
after collection, so connecting multiple sources preserves all results.
The runtime still writes to last-result.json as a temp file; the CLI
copies to the per-source path.

Previously every connector overwrote the same last-result.json, making
it impossible to inspect data from more than one source.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
The CLI is `vana`, not `dataconnect`. Rename the data home directory
from `~/.dataconnect` to `~/.vana` across all source, tests, and
skill documentation. Rename `getDataConnectHome()` to `getVanaHome()`.

Existing users will need to `mv ~/.dataconnect ~/.vana` once.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Teach agents to generate their next task from connected personal
data. The skill reads ~/.vana/results/*.json, parses timestamps
for recency, applies user guidance from ~/.vana/next-prompt.md,
and generates 1-3 prioritized suggestions.

The config file (~/.vana/next-prompt.md) is the user's control
surface: priorities, standing instructions, and notification
preferences. The user edits it directly or asks the agent to
update it.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
The data-show-github command can fail in CI when no seeded data
exists. Mark it allowFailure: true. Also update the log path
normalizer regex for ~/.vana (was ~/.dataconnect).

Co-Authored-By: Claude Opus 4.6 <[email protected]>
These commands fail in CI where no collected data or browser exists.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
…cripts

Update VHS fixture directory, transcript paths, all documentation
references, and utility scripts to use ~/.vana consistently.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Skill list: one line per skill, "installed" badge in accent blue.
No descriptions (use vana skill show for detail). Matches the
compact list pattern.

Skill install: success line + next step only. No file paths.
Suggests installing the next uninstalled skill instead of
circular vana skill list.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Async/background connect, scheduled collection, SEA stack trace,
stale transcripts, date filtering, data versioning.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Stale SingletonLock after interrupted connect, agent-friendly
credential passing, MCP auth mode check, skill composition
boundaries.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Add IPC mode issue: expose existing file-based requestInput IPC
(pending-input/input-response JSON files) as a CLI mode so agents
can handle credential prompts without interactive stdin.

connect-data skill: check auth mode first, run interactive sources
in foreground (not background), tell user to run legacy sources
themselves.

next-prompt skill: never attempt connections, work with available
data only.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
IPC mode (--ipc): connectors pause and write credential questions
to ~/.vana/pending-input-{runId}.json, then poll for the agent's
response at ~/.vana/input-response-{runId}.json. Enables agents
to handle auth without interactive stdin. 5-minute timeout.

Stale lock cleanup: remove SingletonLock before every browser
launch, preventing "Failed to create ProcessSingleton" errors
after interrupted connects.

MCP auth check: connect_source tool checks authMode before
spawning. Legacy (browser) sources return immediately with
instructions for the user instead of hanging.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
The skill now tells agents to use `vana connect <source> --json --ipc`
which writes credential prompts to files instead of stdin. Agents
poll for pending-input files, ask the user, and write response files.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant