fishladder 0.1.0

package/CLAUDE.md

@@ -0,0 +1,113 @@
+# Fishladder CLI — Project Context for Claude
+
+## What This Is
+
+A CLI tool for the Fishladder app (https://app.ladder.fish). npm package name: `fishladder`, binary: `fish`. Installed via `npm install -g fishladder`.
+
+**Spec document**: The full spec lives in the main Fishladder app repo at `docs/phase-5-cli-tool.md`. This CLI implements Track B of that spec. Track A (the `/cli-auth` backend endpoint) lives in the main app.
+
+**Main app repo**: `github.com/prone/fishladder` — the CLI talks to its `/api/v1/` endpoints.
+
+## Architecture
+
+```
+fishladder-cli/
+  bin/fish.js          — entry point (#!/usr/bin/env node), registers all commands
+  src/
+    auth.js            — login (browser OAuth → local HTTP server → keytar), logout, getToken()
+    api.js             — fetch wrapper with Bearer auth, 401/429 error handling
+    format.js          — table output (cli-table3) + --format json
+    commands/
+      login.js         — fish login (browser OAuth flow)
+      logout.js        — fish logout (remove keychain token)
+      whoami.js        — fish whoami (GET /members)
+      projects.js      — fish projects list (GET /projects)
+      tasks.js         — fish tasks list|create (GET|POST /tasks)
+      feedback.js      — fish feedback list|create (GET|POST /feedback)
+      hiring.js        — fish hiring jobs|candidates|pipeline (GET /jobs, /candidates, /applications)
+```
+
+## Tech Stack
+
+- **Runtime**: Node.js >=18, ESM (`"type": "module"`)
+- **CLI framework**: Commander.js
+- **Secure token storage**: keytar (system keychain — never write tokens to disk)
+- **Output**: chalk (colors), cli-table3 (tables), `--format json` on all list commands
+- **Browser launch**: open (for OAuth login flow)
+- **Tests**: vitest (not yet written)
+
+## Auth Flow
+
+### Browser OAuth (`fish login`)
+1. CLI generates random `state`, finds available port (9876–9885)
+2. Starts local HTTP server on that port
+3. Opens browser to `https://app.ladder.fish/cli-auth?state=<state>&port=<port>`
+4. User authenticates in browser (or is already logged in)
+5. App generates `fl_` prefixed API key, redirects to `http://localhost:<port>/callback?token=<token>&state=<state>`
+6. CLI validates state match, stores token in system keychain via keytar
+
+### Environment variable fallback
+Set `FISHLADDER_API_KEY=fl_<key>` to bypass browser login. Useful for development and CI. The `getToken()` function checks the env var first, then keytar.
+
+### Environment variables
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `FISHLADDER_API_KEY` | (none) | API key fallback — skips keytar |
+| `FISHLADDER_API_URL` | `https://app.ladder.fish/api/v1` | API base URL |
+| `FISHLADDER_AUTH_URL` | `https://app.ladder.fish` | Auth page base URL |
+
+## API
+
+Base URL: `https://app.ladder.fish/api/v1`
+Auth: `Authorization: Bearer fl_<key>`
+Rate limit: 120 req/hour
+Errors: `{ "error": "message" }`
+
+| CLI Command | HTTP | Endpoint |
+|-------------|------|----------|
+| `fish whoami` | GET | `/members` |
+| `fish projects list` | GET | `/projects` |
+| `fish tasks list` | GET | `/tasks?projectId=<id>` |
+| `fish tasks create` | POST | `/tasks` (requires `projectId`, `title`) |
+| `fish feedback list` | GET | `/feedback` |
+| `fish feedback create` | POST | `/feedback` (requires `title`) |
+| `fish hiring jobs` | GET | `/jobs` |
+| `fish hiring candidates` | GET | `/candidates` |
+| `fish hiring pipeline` | GET | `/applications?jobId=<id>` |
+
+## Running / Developing
+
+```bash
+npm install           # install dependencies
+npm link              # link globally so `fish` binary works
+fish --help           # verify it works
+npm test              # run tests (vitest)
+```
+
+To test against a local dev server:
+```bash
+FISHLADDER_API_URL=http://localhost:3000/api/v1 FISHLADDER_API_KEY=fl_<key> fish projects list
+```
+
+## Conventions
+
+- All files are plain `.js` (ESM, no TypeScript, no build step)
+- Every list command supports `--format json` for piping to `jq`
+- Error handling: 401 → "Run: fish login", 429 → show retry-after, other errors → show error message. Never show stack traces to users.
+- Token security: **never** write tokens to plaintext files. Keytar (system keychain) or env var only.
+- Each command file exports a `registerXCommand(program)` function that adds itself to the Commander program
+
+## v2 Commands (not yet built)
+
+The spec (`docs/phase-5-cli-tool.md` in main repo) defines v2 commands to add after v1 is dogfooded:
+- `fish tasks update/complete`
+- `fish feedback analyze` (AI analysis, stdin support)
+- `fish hiring move/hire/reject`
+- Smart syntax: `fish tasks create "Fix bug" @sarah !high #backend due:friday`
+
+## Status
+
+- **v1 commands**: All built and tested end-to-end against live API
+- **Tests**: vitest configured but no test files written yet
+- **npm publish**: Not yet — dogfood internally first (per spec)
+- **Track A (backend)**: Complete — `/cli-auth` page and `/api/cli-auth` endpoint exist in main app

package/bin/fish.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { registerLoginCommand } from '../src/commands/login.js';
+import { registerLogoutCommand } from '../src/commands/logout.js';
+import { registerWhoamiCommand } from '../src/commands/whoami.js';
+import { registerProjectsCommand } from '../src/commands/projects.js';
+import { registerTasksCommand } from '../src/commands/tasks.js';
+import { registerFeedbackCommand } from '../src/commands/feedback.js';
+import { registerHiringCommand } from '../src/commands/hiring.js';
+
+program
+  .name('fish')
+  .description('Fishladder CLI — manage projects, tasks, feedback, and hiring')
+  .version('0.1.0');
+
+registerLoginCommand(program);
+registerLogoutCommand(program);
+registerWhoamiCommand(program);
+registerProjectsCommand(program);
+registerTasksCommand(program);
+registerFeedbackCommand(program);
+registerHiringCommand(program);
+
+program.parse();

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "fishladder",
+  "version": "0.1.0",
+  "description": "Fishladder CLI — manage projects, tasks, feedback, and hiring from your terminal",
+  "type": "module",
+  "bin": {
+    "fish": "./bin/fish.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "keywords": ["fishladder", "cli", "project-management"],
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.1.0",
+    "keytar": "^7.9.0",
+    "open": "^10.1.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.0"
+  }
+}

package/src/api.js

@@ -0,0 +1,41 @@
+import { getToken } from './auth.js';
+
+const BASE = process.env.FISHLADDER_API_URL ?? 'https://app.ladder.fish/api/v1';
+
+export async function request(path, opts = {}) {
+  const token = await getToken();
+
+  if (!token) {
+    console.error('Not logged in. Run: fish login');
+    console.error('Or set FISHLADDER_API_KEY environment variable.');
+    process.exit(1);
+  }
+
+  const res = await fetch(`${BASE}${path}`, {
+    ...opts,
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json',
+      ...opts.headers,
+    },
+  });
+
+  if (res.status === 401) {
+    console.error('Session expired or invalid token. Run: fish login');
+    process.exit(1);
+  }
+
+  if (res.status === 429) {
+    const retryAfter = res.headers.get('Retry-After') ?? '60';
+    console.error(`Rate limit exceeded. Try again in ${retryAfter}s.`);
+    process.exit(1);
+  }
+
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    console.error(`Error ${res.status}: ${body.error ?? 'Unknown error'}`);
+    process.exit(1);
+  }
+
+  return res.json();
+}

package/src/auth.js

@@ -0,0 +1,129 @@
+import crypto from 'node:crypto';
+import http from 'node:http';
+import net from 'node:net';
+import open from 'open';
+
+const SERVICE = 'fishladder';
+const ACCOUNT = 'token';
+const AUTH_BASE = process.env.FISHLADDER_AUTH_URL ?? 'https://app.ladder.fish';
+
+let keytar;
+try {
+  const mod = await import('keytar');
+  keytar = mod.default ?? mod;
+} catch {
+  keytar = null;
+}
+
+async function getKeytarOrFail() {
+  if (!keytar) {
+    console.error('Error: keytar is not available. Install it with: npm install -g keytar');
+    process.exit(1);
+  }
+  return keytar;
+}
+
+function isPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', () => resolve(false));
+    server.once('listening', () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port, '127.0.0.1');
+  });
+}
+
+async function findAvailablePort(start, end) {
+  for (let port = start; port <= end; port++) {
+    if (await isPortAvailable(port)) return port;
+  }
+  return null;
+}
+
+export async function login() {
+  const state = crypto.randomBytes(16).toString('hex');
+
+  const port = await findAvailablePort(9876, 9885);
+  if (!port) {
+    console.error('Error: Could not find an available port (9876-9885).');
+    process.exit(1);
+  }
+
+  const token = await new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, `http://localhost:${port}`);
+
+      if (url.pathname !== '/callback') {
+        res.writeHead(404);
+        res.end('Not found');
+        return;
+      }
+
+      const receivedState = url.searchParams.get('state');
+      const receivedToken = url.searchParams.get('token');
+
+      if (receivedState !== state) {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end('<html><body><h2>Error: state mismatch</h2><p>Please try again.</p></body></html>');
+        server.close();
+        reject(new Error('State mismatch — possible CSRF attempt'));
+        return;
+      }
+
+      if (!receivedToken) {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end('<html><body><h2>Error: no token received</h2></body></html>');
+        server.close();
+        reject(new Error('No token received'));
+        return;
+      }
+
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end('<html><body><h2>Authenticated!</h2><p>You can close this tab and return to your terminal.</p></body></html>');
+      server.close();
+      resolve(receivedToken);
+    });
+
+    server.listen(port, '127.0.0.1', () => {
+      const authUrl = `${AUTH_BASE}/cli-auth?state=${state}&port=${port}`;
+      console.log('Opening browser to authenticate...');
+      console.log(`If the browser doesn't open, visit: ${authUrl}`);
+      open(authUrl);
+    });
+
+    server.on('error', (err) => {
+      reject(new Error(`Local server error: ${err.message}`));
+    });
+
+    // 2 minute timeout
+    setTimeout(() => {
+      server.close();
+      reject(new Error('Login timed out after 2 minutes. Please try again.'));
+    }, 120_000);
+  });
+
+  const kt = await getKeytarOrFail();
+  await kt.setPassword(SERVICE, ACCOUNT, token);
+  console.log('Logged in successfully.');
+}
+
+export async function logout() {
+  const kt = await getKeytarOrFail();
+  const existed = await kt.getPassword(SERVICE, ACCOUNT);
+  await kt.deletePassword(SERVICE, ACCOUNT);
+  if (existed) {
+    console.log('Logged out.');
+  } else {
+    console.log('No active session found.');
+  }
+}
+
+export async function getToken() {
+  // Environment variable fallback (for development / CI)
+  const envKey = process.env.FISHLADDER_API_KEY;
+  if (envKey) return envKey;
+
+  if (!keytar) return null;
+  return keytar.getPassword(SERVICE, ACCOUNT);
+}

package/src/commands/feedback.js

@@ -0,0 +1,69 @@
+import { request } from '../api.js';
+import { formatTable, formatJson } from '../format.js';
+
+export function registerFeedbackCommand(program) {
+  const feedback = program
+    .command('feedback')
+    .description('Manage feedback entries');
+
+  feedback
+    .command('list')
+    .description('List all feedback')
+    .option('--format <format>', 'Output format: table or json', 'table')
+    .action(async (opts) => {
+      const data = await request('/feedback');
+
+      if (opts.format === 'json') {
+        formatJson(data);
+        return;
+      }
+
+      if (data.length === 0) {
+        console.log('No feedback found.');
+        return;
+      }
+
+      formatTable(
+        ['ID', 'Title', 'Impact', 'Status', 'Company'],
+        data.map(f => [
+          f.id.slice(0, 8),
+          truncate(f.title, 40),
+          f.impact ?? '-',
+          f.status ?? '-',
+          truncate(f.company, 20),
+        ])
+      );
+    });
+
+  feedback
+    .command('create <title>')
+    .description('Create a new feedback entry')
+    .option('--details <text>', 'Feedback details')
+    .option('--impact <level>', 'Impact: low, medium, high', 'medium')
+    .option('--company <name>', 'Company name')
+    .option('--format <format>', 'Output format: table or json', 'table')
+    .action(async (title, opts) => {
+      const body = { title };
+
+      if (opts.details) body.details = opts.details;
+      if (opts.impact) body.impact = opts.impact;
+      if (opts.company) body.company = opts.company;
+
+      const entry = await request('/feedback', {
+        method: 'POST',
+        body: JSON.stringify(body),
+      });
+
+      if (opts.format === 'json') {
+        formatJson(entry);
+        return;
+      }
+
+      console.log(`Feedback created: ${entry.title} (${entry.id.slice(0, 8)})`);
+    });
+}
+
+function truncate(str, len) {
+  if (!str) return '-';
+  return str.length > len ? str.slice(0, len - 1) + '…' : str;
+}

package/src/commands/hiring.js

@@ -0,0 +1,106 @@
+import { request } from '../api.js';
+import { formatTable, formatJson } from '../format.js';
+
+export function registerHiringCommand(program) {
+  const hiring = program
+    .command('hiring')
+    .description('Manage hiring / ATS');
+
+  hiring
+    .command('jobs')
+    .description('List open jobs')
+    .option('--format <format>', 'Output format: table or json', 'table')
+    .action(async (opts) => {
+      const data = await request('/jobs');
+
+      if (opts.format === 'json') {
+        formatJson(data);
+        return;
+      }
+
+      if (data.length === 0) {
+        console.log('No jobs found.');
+        return;
+      }
+
+      formatTable(
+        ['ID', 'Title', 'Department', 'Location', 'Status'],
+        data.map(j => [
+          j.id.slice(0, 8),
+          truncate(j.title, 35),
+          truncate(j.department, 15),
+          truncate(j.location, 15),
+          j.status ?? '-',
+        ])
+      );
+    });
+
+  hiring
+    .command('candidates')
+    .description('List all candidates')
+    .option('--format <format>', 'Output format: table or json', 'table')
+    .action(async (opts) => {
+      const data = await request('/candidates');
+
+      if (opts.format === 'json') {
+        formatJson(data);
+        return;
+      }
+
+      if (data.length === 0) {
+        console.log('No candidates found.');
+        return;
+      }
+
+      formatTable(
+        ['ID', 'Name', 'Email', 'Source', 'Location'],
+        data.map(c => [
+          c.id.slice(0, 8),
+          truncate(`${c.firstName} ${c.lastName}`, 25),
+          truncate(c.email, 25),
+          truncate(c.source, 12),
+          truncate(c.location, 15),
+        ])
+      );
+    });
+
+  hiring
+    .command('pipeline')
+    .description('List applications (hiring pipeline)')
+    .option('--job <id>', 'Filter by job ID')
+    .option('--format <format>', 'Output format: table or json', 'table')
+    .action(async (opts) => {
+      const params = new URLSearchParams();
+      if (opts.job) params.set('jobId', opts.job);
+
+      const qs = params.toString();
+      const data = await request(`/applications${qs ? `?${qs}` : ''}`);
+
+      if (opts.format === 'json') {
+        formatJson(data);
+        return;
+      }
+
+      if (data.length === 0) {
+        console.log('No applications found.');
+        return;
+      }
+
+      formatTable(
+        ['ID', 'Job', 'Candidate', 'Stage', 'Status', 'Applied'],
+        data.map(a => [
+          a.id.slice(0, 8),
+          a.jobId.slice(0, 8),
+          a.candidateId.slice(0, 8),
+          a.stageId ? a.stageId.slice(0, 8) : '-',
+          a.status ?? '-',
+          a.appliedAt?.split('T')[0] ?? '-',
+        ])
+      );
+    });
+}
+
+function truncate(str, len) {
+  if (!str) return '-';
+  return str.length > len ? str.slice(0, len - 1) + '…' : str;
+}

package/src/commands/login.js

@@ -0,0 +1,15 @@
+import { login } from '../auth.js';
+
+export function registerLoginCommand(program) {
+  program
+    .command('login')
+    .description('Authenticate with Fishladder via browser')
+    .action(async () => {
+      try {
+        await login();
+      } catch (err) {
+        console.error(`Login failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/logout.js

@@ -0,0 +1,15 @@
+import { logout } from '../auth.js';
+
+export function registerLogoutCommand(program) {
+  program
+    .command('logout')
+    .description('Remove stored authentication token')
+    .action(async () => {
+      try {
+        await logout();
+      } catch (err) {
+        console.error(`Logout failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/projects.js

@@ -0,0 +1,42 @@
+import { request } from '../api.js';
+import { formatTable, formatJson } from '../format.js';
+
+export function registerProjectsCommand(program) {
+  const projects = program
+    .command('projects')
+    .description('Manage roadmap projects');
+
+  projects
+    .command('list')
+    .description('List all projects')
+    .option('--format <format>', 'Output format: table or json', 'table')
+    .action(async (opts) => {
+      const data = await request('/projects');
+
+      if (opts.format === 'json') {
+        formatJson(data);
+        return;
+      }
+
+      if (data.length === 0) {
+        console.log('No projects found.');
+        return;
+      }
+
+      formatTable(
+        ['ID', 'Title', 'Status', 'Start', 'Target'],
+        data.map(p => [
+          p.id.slice(0, 8),
+          truncate(p.title, 40),
+          p.status ?? '-',
+          p.startDate ?? '-',
+          p.targetDate ?? '-',
+        ])
+      );
+    });
+}
+
+function truncate(str, len) {
+  if (!str) return '-';
+  return str.length > len ? str.slice(0, len - 1) + '…' : str;
+}

package/src/commands/tasks.js

@@ -0,0 +1,78 @@
+import { request } from '../api.js';
+import { formatTable, formatJson } from '../format.js';
+
+export function registerTasksCommand(program) {
+  const tasks = program
+    .command('tasks')
+    .description('Manage tracker tasks');
+
+  tasks
+    .command('list')
+    .description('List tasks')
+    .option('--project <id>', 'Filter by project ID')
+    .option('--format <format>', 'Output format: table or json', 'table')
+    .action(async (opts) => {
+      const params = new URLSearchParams();
+      if (opts.project) params.set('projectId', opts.project);
+
+      const qs = params.toString();
+      const data = await request(`/tasks${qs ? `?${qs}` : ''}`);
+
+      if (opts.format === 'json') {
+        formatJson(data);
+        return;
+      }
+
+      if (data.length === 0) {
+        console.log('No tasks found.');
+        return;
+      }
+
+      formatTable(
+        ['ID', 'Title', 'Priority', 'Due', 'Assignee'],
+        data.map(t => [
+          t.id.slice(0, 8),
+          truncate(t.title, 40),
+          t.priority ?? 'none',
+          t.dueDate ?? '-',
+          t.assigneeId ? t.assigneeId.slice(0, 8) : '-',
+        ])
+      );
+    });
+
+  tasks
+    .command('create <title>')
+    .description('Create a new task')
+    .requiredOption('--project <id>', 'Project ID (required)')
+    .option('--assign <userId>', 'Assignee user ID')
+    .option('--priority <level>', 'Priority: none, low, medium, high, urgent', 'none')
+    .option('--due <date>', 'Due date (YYYY-MM-DD)')
+    .option('--format <format>', 'Output format: table or json', 'table')
+    .action(async (title, opts) => {
+      const body = {
+        title,
+        projectId: opts.project,
+      };
+
+      if (opts.assign) body.assigneeId = opts.assign;
+      if (opts.priority) body.priority = opts.priority;
+      if (opts.due) body.dueDate = opts.due;
+
+      const task = await request('/tasks', {
+        method: 'POST',
+        body: JSON.stringify(body),
+      });
+
+      if (opts.format === 'json') {
+        formatJson(task);
+        return;
+      }
+
+      console.log(`Task created: ${task.title} (${task.id.slice(0, 8)})`);
+    });
+}
+
+function truncate(str, len) {
+  if (!str) return '-';
+  return str.length > len ? str.slice(0, len - 1) + '…' : str;
+}

package/src/commands/whoami.js

@@ -0,0 +1,22 @@
+import { request } from '../api.js';
+import { formatTable, formatJson } from '../format.js';
+
+export function registerWhoamiCommand(program) {
+  program
+    .command('whoami')
+    .description('Show authenticated user info')
+    .option('--format <format>', 'Output format: table or json', 'table')
+    .action(async (opts) => {
+      const user = await request('/me');
+
+      if (opts.format === 'json') {
+        formatJson(user);
+        return;
+      }
+
+      formatTable(
+        ['Name', 'Email', 'Role'],
+        [[user.name ?? '-', user.email ?? '-', user.role ?? '-']]
+      );
+    });
+}

package/src/format.js

@@ -0,0 +1,15 @@
+import Table from 'cli-table3';
+import chalk from 'chalk';
+
+export function formatTable(headers, rows) {
+  const table = new Table({
+    head: headers.map(h => chalk.dim(h)),
+    style: { head: [], border: [] },
+  });
+  rows.forEach(row => table.push(row));
+  console.log(table.toString());
+}
+
+export function formatJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}