skyboard-cli 0.1.0

package/README.md

@@ -0,0 +1,148 @@
+# Skyboard CLI (`sb`)
+
+A command-line interface for [Skyboard](https://skyboard.dev), a collaborative kanban board built on [AT Protocol](https://atproto.com/). Manage boards and tasks from your terminal without opening a browser.
+
+## Install
+
+```bash
+npm install -g skyboard-cli
+```
+
+## Quick start
+
+```bash
+sb login alice.bsky.social    # opens browser for AT Protocol OAuth
+sb boards                     # list your boards
+sb use "Sprint Board"         # set default board
+sb cards                      # view all cards
+sb new "Fix login bug"        # create a card
+sb mv 3labc12 done            # move it to Done
+```
+
+## Auth
+
+The CLI uses AT Protocol OAuth with a loopback redirect. Running `sb login` starts a local server, opens your browser for authorization, and stores the session in `~/.config/skyboard/`. Tokens auto-refresh on subsequent commands.
+
+```bash
+sb login alice.bsky.social    # opens browser for OAuth
+sb whoami                     # show handle, DID, and PDS endpoint
+sb logout                     # clear stored session
+```
+
+## Commands
+
+### Board navigation
+
+| Command | Description |
+|---------|-------------|
+| `sb boards` | List all boards (owned + joined) |
+| `sb use <board>` | Set default board for subsequent commands |
+| `sb add <link>` | Join a board by AT URI or web URL |
+| `sb cols` | Show columns with task counts |
+
+`sb use` accepts a board name (fuzzy match), rkey, AT URI, or web URL.
+
+### Card operations
+
+| Command | Description |
+|---------|-------------|
+| `sb cards` | List cards grouped by column |
+| `sb new <title>` | Create a new card |
+| `sb show <ref>` | Show card details, comments, and history |
+| `sb mv <ref> <column>` | Move card to a different column |
+| `sb edit <ref>` | Edit card fields |
+| `sb comment <ref> <text>` | Add a comment |
+| `sb rm <ref>` | Delete a card (owner only) |
+
+### Card references
+
+Cards are referenced by **TID rkey prefix**, similar to git short hashes. `sb cards` shows 7-character truncated rkeys. A minimum of 4 characters is required; if the prefix is ambiguous, the CLI lists the matches.
+
+```
+sb cards
+  To Do
+    3labc12  Fix login bug
+    3labc13  Update docs
+
+sb show 3labc12       # exact prefix
+sb mv 3lab done       # shorter prefix, if unambiguous
+```
+
+### Column matching
+
+Columns can be referenced by:
+- **Exact name** (case-insensitive): `"In Progress"`
+- **Name prefix**: `in` matches `In Progress`
+- **1-based index**: `2` (from `sb cols` output)
+
+### Filters
+
+```bash
+sb cards -c "In Progress"     # filter by column
+sb cards -l "bug"             # filter by label
+sb cards -s "login"           # search title and description
+```
+
+### Creating and editing
+
+```bash
+sb new "Fix login bug"                        # create in first column
+sb new "Update docs" -c done -d "Add examples"  # specify column and description
+
+sb edit 3lab -t "New title"                   # edit title
+sb edit 3lab -d "New description"             # edit description
+sb edit 3lab -l bug -l urgent                 # set labels
+```
+
+## JSON output
+
+All commands support `--json` for machine-readable output:
+
+```bash
+sb cards --json | jq '.[].cards[].title'
+sb boards --json
+sb whoami --json
+```
+
+## Claude Code plugin
+
+The `sb` CLI includes a [Claude Code](https://claude.ai/code) plugin so you can manage boards directly from a Claude Code conversation using `/sb:cards`, `/sb:new`, `/sb:mv`, etc.
+
+### Install the plugin
+
+```bash
+# Add the marketplace (once)
+/plugin marketplace add /path/to/skyboard
+
+# Install the plugin
+/plugin install sb@skyboard
+```
+
+Or from the terminal:
+
+```bash
+claude plugin marketplace add /path/to/skyboard
+claude plugin install sb@skyboard --scope user
+```
+
+Restart Claude Code after installing. All 15 `sb` commands are available as skills (e.g. `/sb:status`, `/sb:cards`, `/sb:new`).
+
+## How it works
+
+The CLI authenticates via OAuth and talks directly to AT Protocol PDS endpoints — there is no local database. Each command fetches fresh data from the board owner's PDS and all trusted participants, runs the same `materializeTasks()` per-field LWW merge logic as the web app, and displays the result.
+
+Write commands (`new`, `mv`, `edit`, `comment`) create AT Protocol records in your PDS. The web app picks these up in real time via Jetstream, and other CLI users see them on their next command.
+
+## Config
+
+Session and config are stored in `~/.config/skyboard/`:
+
+| File | Purpose |
+|------|---------|
+| `session.json` | Current user (DID, handle, PDS endpoint) |
+| `auth/` | OAuth session tokens (mode 0600) |
+| `config.json` | Default board and known boards list |
+
+## License
+
+GPL-3.0-only

package/bin/sb.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/index.js";

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "skyboard-cli",
+  "version": "0.1.0",
+  "description": "CLI for Skyboard – a collaborative kanban board on AT Protocol",
+  "author": {
+    "name": "Tim Disney"
+  },
+  "type": "module",
+  "bin": {
+    "sb": "./bin/sb.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@atproto/api": "^0.13.20",
+    "@atproto/common-web": "^0.4.0",
+    "@atproto/oauth-client-node": "^0.3.7",
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "fractional-indexing": "^3.2.0",
+    "open": "^10.1.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.0"
+  }
+}

package/src/__tests__/auth-state.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { OWNER_DID, USER_DID, BOARD_RKEY } from "./helpers.js";
+
+// Mock config module
+const mockLoadAuthInfo = vi.fn();
+const mockClearDefaultBoard = vi.fn();
+const mockGetDefaultBoard = vi.fn();
+
+vi.mock("../lib/config.js", () => ({
+  loadAuthInfo: (...args: unknown[]) => mockLoadAuthInfo(...args),
+  clearDefaultBoard: (...args: unknown[]) => mockClearDefaultBoard(...args),
+  getDefaultBoard: (...args: unknown[]) => mockGetDefaultBoard(...args),
+}));
+
+// Mock auth module
+const mockLogin = vi.fn();
+const mockLogout = vi.fn();
+
+vi.mock("../lib/auth.js", () => ({
+  login: (...args: unknown[]) => mockLogin(...args),
+  logout: (...args: unknown[]) => mockLogout(...args),
+}));
+
+import { logoutCommand } from "../commands/logout.js";
+import { loginCommand } from "../commands/login.js";
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  vi.spyOn(console, "log").mockImplementation(() => {});
+  vi.spyOn(console, "error").mockImplementation(() => {});
+});
+
+describe("logoutCommand", () => {
+  it("clears the default board on logout", () => {
+    mockLoadAuthInfo.mockReturnValue({
+      did: OWNER_DID,
+      handle: "owner.test",
+      service: "https://pds.example.com",
+    });
+
+    logoutCommand();
+
+    expect(mockLogout).toHaveBeenCalledOnce();
+    expect(mockClearDefaultBoard).toHaveBeenCalledOnce();
+  });
+
+  it("does not clear board if not logged in", () => {
+    mockLoadAuthInfo.mockReturnValue(null);
+
+    logoutCommand();
+
+    expect(mockLogout).not.toHaveBeenCalled();
+    expect(mockClearDefaultBoard).not.toHaveBeenCalled();
+  });
+});
+
+describe("loginCommand", () => {
+  it("clears the default board when switching to a different account", async () => {
+    mockLoadAuthInfo.mockReturnValue({
+      did: OWNER_DID,
+      handle: "owner.test",
+      service: "https://pds.example.com",
+    });
+    mockLogin.mockResolvedValue({ did: USER_DID, handle: "user.test" });
+
+    await loginCommand("user.test");
+
+    expect(mockClearDefaultBoard).toHaveBeenCalledOnce();
+  });
+
+  it("does not clear the default board when logging in as the same account", async () => {
+    mockLoadAuthInfo.mockReturnValue({
+      did: OWNER_DID,
+      handle: "owner.test",
+      service: "https://pds.example.com",
+    });
+    mockLogin.mockResolvedValue({ did: OWNER_DID, handle: "owner.test" });
+
+    await loginCommand("owner.test");
+
+    expect(mockClearDefaultBoard).not.toHaveBeenCalled();
+  });
+
+  it("does not clear the default board on first login (no previous auth)", async () => {
+    mockLoadAuthInfo.mockReturnValue(null);
+    mockLogin.mockResolvedValue({ did: OWNER_DID, handle: "owner.test" });
+
+    await loginCommand("owner.test");
+
+    expect(mockClearDefaultBoard).not.toHaveBeenCalled();
+  });
+
+  it("does not clear the default board if login fails", async () => {
+    mockLoadAuthInfo.mockReturnValue({
+      did: OWNER_DID,
+      handle: "owner.test",
+      service: "https://pds.example.com",
+    });
+    mockLogin.mockRejectedValue(new Error("OAuth failed"));
+
+    const exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
+      throw new Error("process.exit");
+    }) as any);
+
+    await expect(loginCommand("user.test")).rejects.toThrow("process.exit");
+
+    expect(mockClearDefaultBoard).not.toHaveBeenCalled();
+
+    exitSpy.mockRestore();
+  });
+});

package/src/__tests__/card-ref.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from "vitest";
+import { resolveCardRef } from "../lib/card-ref.js";
+import { makeMaterializedTask, TASK_RKEY_1, TASK_RKEY_2, TASK_RKEY_3 } from "./helpers.js";
+
+describe("resolveCardRef", () => {
+  const tasks = [
+    makeMaterializedTask({ rkey: TASK_RKEY_1, title: "First Task" }),
+    makeMaterializedTask({ rkey: TASK_RKEY_2, title: "Second Task" }),
+    makeMaterializedTask({ rkey: TASK_RKEY_3, title: "Third Task" }),
+  ];
+
+  it("matches a task by 4+ character rkey prefix", () => {
+    // TASK_RKEY_1 = "3jui7a2zbbb22" — need enough chars to disambiguate from TASK_RKEY_2 "3jui7a2zbbb33"
+    const result = resolveCardRef(TASK_RKEY_1.slice(0, 12), tasks);
+    expect(result.rkey).toBe(TASK_RKEY_1);
+  });
+
+  it("matches a task by full rkey", () => {
+    const result = resolveCardRef(TASK_RKEY_2, tasks);
+    expect(result.rkey).toBe(TASK_RKEY_2);
+  });
+
+  it("throws on too-short prefix (< 4 chars)", () => {
+    expect(() => resolveCardRef("3ju", tasks)).toThrow("too short");
+  });
+
+  it("throws when no task matches", () => {
+    expect(() => resolveCardRef("zzzz", tasks)).toThrow('No card found');
+  });
+
+  it("throws on ambiguous match with list of candidates", () => {
+    // TASK_RKEY_1 = "3jui7a2zbbb22", TASK_RKEY_2 = "3jui7a2zbbb33"
+    // They share prefix "3jui7a2zbbb"
+    expect(() => resolveCardRef("3jui7a2zbbb", tasks)).toThrow("Ambiguous");
+  });
+
+  it("resolves unambiguous prefix that partially overlaps", () => {
+    // TASK_RKEY_3 = "3jui7a2zbcc44" — prefix "3jui7a2zbcc" is unique
+    const result = resolveCardRef("3jui7a2zbcc", tasks);
+    expect(result.rkey).toBe(TASK_RKEY_3);
+  });
+});

package/src/__tests__/column-match.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "vitest";
+import { resolveColumn } from "../lib/column-match.js";
+import { COLUMNS } from "./helpers.js";
+
+describe("resolveColumn", () => {
+  // COLUMNS: To Do (0), In Progress (1), Done (2)
+
+  it("matches by 1-based numeric index", () => {
+    expect(resolveColumn("1", COLUMNS)).toEqual(COLUMNS[0]); // To Do
+    expect(resolveColumn("2", COLUMNS)).toEqual(COLUMNS[1]); // In Progress
+    expect(resolveColumn("3", COLUMNS)).toEqual(COLUMNS[2]); // Done
+  });
+
+  it("matches by exact name (case-insensitive)", () => {
+    expect(resolveColumn("To Do", COLUMNS)).toEqual(COLUMNS[0]);
+    expect(resolveColumn("to do", COLUMNS)).toEqual(COLUMNS[0]);
+    expect(resolveColumn("IN PROGRESS", COLUMNS)).toEqual(COLUMNS[1]);
+    expect(resolveColumn("done", COLUMNS)).toEqual(COLUMNS[2]);
+  });
+
+  it("matches by prefix", () => {
+    expect(resolveColumn("Do", COLUMNS)).toEqual(COLUMNS[2]); // "Done" unique prefix
+  });
+
+  it("matches by substring", () => {
+    expect(resolveColumn("Prog", COLUMNS)).toEqual(COLUMNS[1]); // "In Progress"
+  });
+
+  it("throws on ambiguous prefix match", () => {
+    // Columns with ambiguous prefixes
+    const cols = [
+      { id: "a", name: "Alpha One", order: 0 },
+      { id: "b", name: "Alpha Two", order: 1 },
+    ];
+    expect(() => resolveColumn("Alpha", cols)).toThrow("Ambiguous");
+  });
+
+  it("throws on ambiguous substring match", () => {
+    const cols = [
+      { id: "a", name: "Pre-Review", order: 0 },
+      { id: "b", name: "Post-Review", order: 1 },
+    ];
+    // "Review" is a substring of both but not a prefix of either
+    expect(() => resolveColumn("Review", cols)).toThrow("Ambiguous");
+  });
+
+  it("throws on no match with available columns", () => {
+    expect(() => resolveColumn("Nonexistent", COLUMNS)).toThrow("No column matching");
+    expect(() => resolveColumn("Nonexistent", COLUMNS)).toThrow("To Do");
+  });
+
+  it("ignores out-of-range numeric index", () => {
+    // "0" is out of 1-based range, and doesn't match any name
+    expect(() => resolveColumn("0", COLUMNS)).toThrow("No column matching");
+    expect(() => resolveColumn("99", COLUMNS)).toThrow("No column matching");
+  });
+});