fix(setup): Railway-clean onboarding output — summarize skill install, don't stream it (#42)

* fix(install): symlink into an on-PATH dir so `insta` runs immediately

Root cause of 'command not found: insta' after the one-liner: we installed
only to ~/.insta/bin (never on PATH), so the recommended
'curl … | sh && insta project create' chain called insta in a shell whose
PATH the piped script can't change. Railway avoids this by installing where
PATH already looks (and sudo-escalating if needed). Now: after installing to
~/.insta/bin, symlink into a writable on-PATH dir (/usr/local/bin, else
~/.local/bin) so bare 'insta' resolves in the same shell with no reload;
fall back to profile-append + an explicit this-shell export only when no
such dir exists. Verified live: fresh install → 'command -v insta' resolves,
v0.0.13, no manual step.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GMbAe5K1RfwaAcge5inX7P

* fix(setup): Railway-clean onboarding output — summarize skill install, don't stream it

The agent one-liner (curl agents.instacloud.com | sh) shelled `insta setup
agent` out to `npx skills add …` and streamed its clack UI verbatim: a
frame-by-frame clone spinner, an 'Installing to all 73 agents' banner, a
70-line install-path box, and a third-party 'Security Risk Assessment' that
flags our OWN first-party skill as 'Critical Risk'. Next to Railway's two
clean ✓ lines it read noisy and alarming.

Now we CAPTURE the tool's output and print one Railway-style summary line
naming the well-known agents with the long tail rolled into '+N more':

  setting up coding-agent skills … (~20s)
  ✓ Agent skills — Universal (.agents), Claude Code, Windsurf, Factory Droid, Goose, Aider, +47 more
    every coding agent on this machine now knows InstaCloud (review skills before use …)

On failure we still surface the real error (captured tail, minus the expected
no-global-support noise) plus the manual command. Also drops a duplicate
'setting up coding-agent skills …' echo in install.sh. Tests cover the
summarizer against the tool's real boxed output format; 75/75 green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GMbAe5K1RfwaAcge5inX7P

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: tonychang04

install.sh

@@ -139,7 +139,7 @@ fi
 # ---- agent setup (--agents) ----
 if [ "$AGENTS" = "1" ]; then
   echo
-  echo "setting up coding-agent skills …"
+  # `insta setup agent` prints its own "setting up coding-agent skills …" line + clean summary.
   if [ "$YES" = "1" ]; then
     "$INSTALL_DIR/$BIN" setup agent -y || echo "warn: agent setup failed — run: insta setup agent"
   else

src/commands/setup.ts

@@ -8,38 +8,83 @@
 import { spawn } from 'node:child_process'
 import { info } from '../util.js'
 
-// The skills tool reports agents that don't support user-global installs (Eve, PromptScript, …)
-// as red failures. That's expected reality, not a problem with THIS machine — showing red in the
-// first 30s of onboarding erodes trust (Railway's installer reads all-green for a reason).
-// Classify each output line: drop that expected noise, keep everything real.
+// The `skills` tool we shell out to prints a clack UI: a frame-by-frame clone spinner, an
+// "Installing to all N agents" banner, a full N-line install-path box, and a third-party
+// "Security Risk Assessment" that flags our OWN first-party skill as "Critical Risk". Streamed
+// verbatim during onboarding that reads as noisy and alarming — the opposite of Railway's two
+// clean ✓ lines. So we CAPTURE its output and print our own one-line summary instead. This
+// classifier decides which captured lines are worth showing if the install FAILS (surface the
+// real error; drop the expected no-global-support noise).
 export function classifyInstallLine(line: string): 'keep' | 'skip' {
   if (/does not support global skill installation/.test(line)) return 'skip'
   if (/Failed to install \d+/.test(line)) return 'skip'
   return 'keep'
 }
 
-export type Runner = (cmd: string, args: string[]) => Promise<{ ok: boolean }>
+// Map a skill-install target directory to a human agent name. `-a '*'` installs to every agent
+// dir the tool knows (~70+); we name the well-known ones (Railway-style) and roll the long tail
+// into "+N more" rather than dumping every path. Order = display priority.
+const AGENT_NAMES: Array<[RegExp, string]> = [
+  [/\.agents\b/, 'Universal (.agents)'],
+  [/\.claude\b/, 'Claude Code'],
+  [/\.codex\b/, 'OpenAI Codex'],
+  [/\.cursor\b/, 'Cursor'],
+  [/opencode\b/, 'OpenCode'],
+  [/copilot\b/, 'GitHub Copilot'],
+  [/\.gemini\b/, 'Gemini CLI'],
+  [/windsurf\b/, 'Windsurf'],
+  [/\.factory\b/, 'Factory Droid'],
+  [/goose\b/, 'Goose'],
+  [/aider\b/, 'Aider'],
+  [/\.continue\b/, 'Continue'],
+  [/\.roo\b/, 'Roo'],
+  [/kilocode\b/, 'Kilo Code'],
+  [/\.qwen\b/, 'Qwen'],
+]
 
+// Pull install-target paths out of the skills tool's summary lines ("→ ~/.claude/skills/insta")
+// and resolve the well-known ones to names. Returns the total install count + named agents.
+export function parseInstalledAgents(output: string): { count: number; names: string[] } {
+  const paths = new Set<string>()
+  for (const line of output.split('\n')) {
+    const plain = line.replace(/\x1b\[[0-9;]*m/g, '')
+    // The tool boxes each line ("│    → ~/.claude/skills/insta   │"), so don't anchor to EOL.
+    const m = plain.match(/→\s*(\S+)\/skills\/[A-Za-z0-9_-]+/)
+    if (m && m[1]) paths.add(m[1])
+  }
+  const names: string[] = []
+  for (const [re, name] of AGENT_NAMES) {
+    if ([...paths].some((p) => re.test(p))) names.push(name)
+  }
+  return { count: paths.size, names }
+}
+
+// The Railway-style one-liner: a few named agents, the rest as "+N more".
+export function summarizeInstall(output: string): string {
+  const { count, names } = parseInstalledAgents(output)
+  if (count === 0) return '✓ insta skill installed for your coding agents'
+  const shown = names.slice(0, 6)
+  const more = count - shown.length
+  const list = shown.length
+    ? shown.join(', ') + (more > 0 ? `, +${more} more` : '')
+    : `${count} agent${count === 1 ? '' : 's'}`
+  return `✓ Agent skills — ${list}`
+}
+
+export type Runner = (cmd: string, args: string[]) => Promise<{ ok: boolean; output?: string }>
+
+// Capture stdout+stderr silently (don't stream) so we can print our own clean summary. We keep
+// the child's stdin inherited in case the tool ever needs a TTY, but with -y it shouldn't.
 const defaultRunner: Runner = (cmd, args) =>
   new Promise((resolve) => {
-    const env = { ...process.env, AI_AGENT: process.env.AI_AGENT || 'insta', FORCE_COLOR: '1' }
+    const env = { ...process.env, AI_AGENT: process.env.AI_AGENT || 'insta', FORCE_COLOR: '0' }
     const p = spawn(cmd, args, { stdio: ['inherit', 'pipe', 'pipe'], env })
-    let skipped = 0
-    const sift = (chunk: Buffer) => {
-      for (const line of chunk.toString().split('\n')) {
-        // strip ANSI before classifying; print the original line to preserve the tool's styling
-        const plain = line.replace(/\x1b\[[0-9;]*m/g, '')
-        if (classifyInstallLine(plain) === 'skip') { skipped++; continue }
-        if (line.trim()) process.stdout.write(line + '\n')
-      }
-    }
-    p.stdout?.on('data', sift)
-    p.stderr?.on('data', sift)
-    p.on('error', () => resolve({ ok: false }))
-    p.on('close', (code) => {
-      if (skipped) info(`  (skipped ${skipped >= 3 ? 'some' : skipped} agent targets that don't support user-global installs — expected)`)
-      resolve({ ok: code === 0 })
-    })
+    let output = ''
+    const grab = (chunk: Buffer) => { output += chunk.toString() }
+    p.stdout?.on('data', grab)
+    p.stderr?.on('data', grab)
+    p.on('error', () => resolve({ ok: false, output }))
+    p.on('close', (code) => resolve({ ok: code === 0, output }))
   })
 
 // -g = user-level (machine-global); -a '*' = every agent dir the skills tool supports
@@ -50,14 +95,21 @@ export async function setupAgent(opts: { yes?: boolean }, run: Runner = defaultR
   if (!opts.yes && !process.stdout.isTTY) {
     info('non-interactive shell — assuming -y')
   }
-  info('installing the insta skill (user-global, all agents) …')
+  info('setting up coding-agent skills … (~20s)')
   const res = await run('npx', SETUP_ARGS)
   if (!res.ok) {
     info('  skill install failed — install manually with:')
     info('    npx skills add InsForge/insta-skills -s insta -a "*" -g -y --copy')
+    // Surface the REAL error: the captured tail, minus the expected no-global-support noise.
+    const tail = (res.output ?? '')
+      .split('\n')
+      .map((l) => l.replace(/\x1b\[[0-9;]*m/g, '').trimEnd())
+      .filter((l) => l.trim() && classifyInstallLine(l) === 'keep')
+      .slice(-6)
+    for (const l of tail) info('    ' + l)
     process.exitCode = 1
     return
   }
-  info('done — agents on this machine now know InstaCloud.')
-  info('next: `insta login --oauth github` (cloud) or run instad locally (insta-oss), then `insta project create <name>`.')
+  info(summarizeInstall(res.output ?? ''))
+  info('  every coding agent on this machine now knows InstaCloud (review skills before use — they run with full permissions).')
 }

test/setup-agent.test.ts

@@ -3,7 +3,7 @@ import { setupAgent, SETUP_ARGS } from '../src/commands/setup.js'
 
 test('setup agent installs the insta skill user-globally for all agents', async () => {
   const runs: string[][] = []
-  await setupAgent({ yes: true }, async (_cmd, args) => { runs.push(args); return { ok: true } })
+  await setupAgent({ yes: true }, async (_cmd, args) => { runs.push(args); return { ok: true, output: '' } })
   expect(runs).toHaveLength(1)
   expect(runs[0]).toEqual(SETUP_ARGS)
   expect(SETUP_ARGS).toContain('-g')          // user-level, not per-project
@@ -14,7 +14,7 @@ test('setup agent installs the insta skill user-globally for all agents', async
 
 test('failed install sets exit code and prints the manual fallback', async () => {
   const prev = process.exitCode
-  await setupAgent({ yes: true }, async () => ({ ok: false }))
+  await setupAgent({ yes: true }, async () => ({ ok: false, output: '' }))
   expect(process.exitCode).toBe(1)
   process.exitCode = prev
 })

test/setup-output.test.ts

@@ -1,18 +1,50 @@
-// Railway-lesson: the install moment must read all-green. The skills tool prints a red
-// "Failed to install N" for agents that don't support global installs (Eve, PromptScript) —
-// expected noise, not failure. Filter classifies each line: keep real output, drop the
-// expected-noise lines, and summarize what was skipped.
+// Railway-lesson: the install moment must read clean. We CAPTURE the skills tool's clack UI
+// (clone spinner, "Installing to all N agents", the full path box, the third-party security
+// box) and print our own one-line summary instead of streaming it. These tests pin the summary
+// and the error-path classifier (which still decides what to surface if the install FAILS).
 import { test, expect } from 'vitest'
-import { classifyInstallLine } from '../src/commands/setup.js'
+import { classifyInstallLine, parseInstalledAgents, summarizeInstall } from '../src/commands/setup.js'
 
-test('drops expected no-global-support failures and the red banner', () => {
+// Representative slice of what `skills add … -a '*'` actually prints on success — including the
+// box borders the tool wraps each path in (the exact format the parser must tolerate).
+const SAMPLE = `
+●  Installing to all 73 agents
+◇  Installed 1 skill ────────────────────╮
+│                                        │
+│  ✓ insta (copied)                      │
+│    → ~/.agents/skills/insta            │
+│    → ~/.claude/skills/insta            │
+│    → ~/.cursor/skills/insta            │
+│    → ~/.config/goose/skills/insta      │
+│    → ~/.codeium/windsurf/skills/insta  │
+│    → ~/.aider-desk/skills/insta        │
+│    → ~/.kilocode/skills/insta          │
+├────────────────────────────────────────╯
+`
+
+test('summary names the well-known agents and rolls the rest into +N more', () => {
+  const { count, names } = parseInstalledAgents(SAMPLE)
+  expect(count).toBe(7)
+  expect(names).toContain('Claude Code')
+  expect(names).toContain('Cursor')
+  expect(names).toContain('Universal (.agents)')
+  const line = summarizeInstall(SAMPLE)
+  expect(line.startsWith('✓ Agent skills —')).toBe(true)
+  expect(line).toContain('Claude Code')
+  // never dumps raw paths or the scary "73 agents" banner
+  expect(line).not.toContain('skills/insta')
+  expect(line).not.toContain('73 agents')
+})
+
+test('summary degrades gracefully when no paths are parseable', () => {
+  expect(summarizeInstall('some unexpected output')).toBe('✓ insta skill installed for your coding agents')
+})
+
+test('error-path classifier drops expected no-global-support noise', () => {
   expect(classifyInstallLine('✗ insta → Eve: Eve does not support global skill installation')).toBe('skip')
-  expect(classifyInstallLine('✗ insta → PromptScript: PromptScript does not support global skill installation')).toBe('skip')
   expect(classifyInstallLine('■  Failed to install 2')).toBe('skip')
 })
 
-test('keeps real progress and REAL failures', () => {
-  expect(classifyInstallLine('→ ~/.claude/skills/insta')).toBe('keep')
-  expect(classifyInstallLine('✓ Repository cloned')).toBe('keep')
+test('error-path classifier keeps REAL failures', () => {
   expect(classifyInstallLine('✗ insta → Claude Code: EACCES permission denied')).toBe('keep')
 })