skyboard-cli 0.1.0

package/src/commands/whoami.ts

@@ -0,0 +1,22 @@
+import { loadAuthInfo } from "../lib/config.js";
+import chalk from "chalk";
+
+export function whoamiCommand(opts: { json?: boolean }): void {
+  const info = loadAuthInfo();
+  if (!info) {
+    if (opts.json) {
+      console.log(JSON.stringify({ loggedIn: false }));
+    } else {
+      console.log("Not logged in. Run `sb login <handle>` first.");
+    }
+    return;
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify({ loggedIn: true, ...info }, null, 2));
+  } else {
+    console.log(`${chalk.bold("Handle:")}  ${info.handle}`);
+    console.log(`${chalk.bold("DID:")}     ${info.did}`);
+    console.log(`${chalk.bold("PDS:")}     ${info.service}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { loginCommand } from "./commands/login.js";
+import { logoutCommand } from "./commands/logout.js";
+import { whoamiCommand } from "./commands/whoami.js";
+import { statusCommand } from "./commands/status.js";
+import { boardsCommand } from "./commands/boards.js";
+import { useCommand } from "./commands/use.js";
+import { addCommand } from "./commands/add.js";
+import { colsCommand } from "./commands/cols.js";
+import { cardsCommand } from "./commands/cards.js";
+import { showCommand } from "./commands/show.js";
+import { newCommand } from "./commands/new.js";
+import { mvCommand } from "./commands/mv.js";
+import { editCommand } from "./commands/edit.js";
+import { commentCommand } from "./commands/comment.js";
+import { rmCommand } from "./commands/rm.js";
+
+const program = new Command();
+
+program
+  .name("sb")
+  .description("Skyboard CLI — manage kanban boards on AT Protocol")
+  .version("0.1.0");
+
+// Auth commands
+program
+  .command("login")
+  .description("Log in via AT Protocol OAuth (opens browser)")
+  .argument("<handle>", "Your AT Protocol handle (e.g. alice.bsky.social)")
+  .action(loginCommand);
+
+program
+  .command("logout")
+  .description("Log out and clear stored session")
+  .action(logoutCommand);
+
+program
+  .command("whoami")
+  .description("Show current authenticated user")
+  .option("--json", "Output as JSON")
+  .action(whoamiCommand);
+
+program
+  .command("status")
+  .description("Show current auth state and board summary")
+  .option("--json", "Output as JSON")
+  .action(statusCommand);
+
+// Board navigation
+program
+  .command("boards")
+  .description("List all boards (owned + joined)")
+  .option("--json", "Output as JSON")
+  .action(boardsCommand);
+
+program
+  .command("use")
+  .description("Set default board for subsequent commands")
+  .argument("<board>", "Board name, rkey, AT URI, or web URL")
+  .action(useCommand);
+
+program
+  .command("add")
+  .description("Join a board by AT URI or web URL")
+  .argument("<link>", "AT URI or web URL of the board")
+  .action(addCommand);
+
+program
+  .command("cols")
+  .description("Show columns for the current board")
+  .option("--board <ref>", "Override default board")
+  .option("--json", "Output as JSON")
+  .action(colsCommand);
+
+// Card operations
+program
+  .command("cards")
+  .description("List cards grouped by column")
+  .option("-c, --column <column>", "Filter by column (name, prefix, or number)")
+  .option("-l, --label <label>", "Filter by label name")
+  .option("-s, --search <text>", "Search in title and description")
+  .option("--board <ref>", "Override default board")
+  .option("--json", "Output as JSON")
+  .action(cardsCommand);
+
+program
+  .command("new")
+  .description("Create a new card")
+  .argument("<title>", "Card title")
+  .option("-c, --column <column>", "Target column (default: first column)")
+  .option("-d, --description <desc>", "Card description")
+  .option("--board <ref>", "Override default board")
+  .option("--json", "Output as JSON")
+  .action(newCommand);
+
+program
+  .command("show")
+  .description("Show card details, comments, and history")
+  .argument("<ref>", "Card reference (rkey prefix, min 4 chars)")
+  .option("--board <ref>", "Override default board")
+  .option("--json", "Output as JSON")
+  .action(showCommand);
+
+program
+  .command("mv")
+  .description("Move a card to a different column")
+  .argument("<ref>", "Card reference (rkey prefix)")
+  .argument("<column>", "Target column (name, prefix, or number)")
+  .option("--board <ref>", "Override default board")
+  .option("--json", "Output as JSON")
+  .action(mvCommand);
+
+program
+  .command("edit")
+  .description("Edit card fields")
+  .argument("<ref>", "Card reference (rkey prefix)")
+  .option("-t, --title <title>", "New title")
+  .option("-d, --description <desc>", "New description")
+  .option("-l, --label <label...>", "Set labels (by name)")
+  .option("--board <ref>", "Override default board")
+  .option("--json", "Output as JSON")
+  .action(editCommand);
+
+program
+  .command("comment")
+  .description("Add a comment to a card")
+  .argument("<ref>", "Card reference (rkey prefix)")
+  .argument("<text>", "Comment text")
+  .option("--board <ref>", "Override default board")
+  .option("--json", "Output as JSON")
+  .action(commentCommand);
+
+program
+  .command("rm")
+  .description("Delete a card (owner only)")
+  .argument("<ref>", "Card reference (rkey prefix)")
+  .option("-f, --force", "Skip confirmation")
+  .option("--board <ref>", "Override default board")
+  .option("--json", "Output as JSON")
+  .action(rmCommand);
+
+program.parse();

package/src/lib/auth.ts

@@ -0,0 +1,244 @@
+import { Agent } from "@atproto/api";
+import { NodeOAuthClient } from "@atproto/oauth-client-node";
+import type { NodeSavedSession, NodeSavedState } from "@atproto/oauth-client-node";
+import { requestLocalLock } from "@atproto/oauth-client";
+import { createServer } from "node:http";
+import {
+  writeStateFile,
+  readStateFile,
+  deleteStateFile,
+  writeSessionFile,
+  readSessionFile,
+  deleteSessionFile,
+  loadAuthInfo,
+  saveAuthInfo,
+  clearAuthInfo,
+} from "./config.js";
+
+const OAUTH_SCOPE =
+  "atproto repo:dev.skyboard.board repo:dev.skyboard.task repo:dev.skyboard.op repo:dev.skyboard.trust repo:dev.skyboard.comment repo:dev.skyboard.approval repo:dev.skyboard.reaction";
+
+// File-based stores implementing the NodeOAuthClient interfaces
+const stateStore = {
+  async set(key: string, state: NodeSavedState): Promise<void> {
+    writeStateFile(key, state);
+  },
+  async get(key: string): Promise<NodeSavedState | undefined> {
+    return readStateFile(key) as NodeSavedState | undefined;
+  },
+  async del(key: string): Promise<void> {
+    deleteStateFile(key);
+  },
+};
+
+const sessionStore = {
+  async set(sub: string, session: NodeSavedSession): Promise<void> {
+    writeSessionFile(sub, session);
+  },
+  async get(sub: string): Promise<NodeSavedSession | undefined> {
+    return readSessionFile(sub) as NodeSavedSession | undefined;
+  },
+  async del(sub: string): Promise<void> {
+    deleteSessionFile(sub);
+  },
+};
+
+function createOAuthClient(port: number): NodeOAuthClient {
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+  return new NodeOAuthClient({
+    clientMetadata: {
+      client_id: `http://localhost?redirect_uri=${encodeURIComponent(redirectUri)}&scope=${encodeURIComponent(OAUTH_SCOPE)}`,
+      client_name: "Skyboard CLI",
+      redirect_uris: [redirectUri],
+      scope: OAUTH_SCOPE,
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none",
+      application_type: "native",
+      dpop_bound_access_tokens: true,
+    },
+    stateStore,
+    sessionStore,
+    requestLock: requestLocalLock,
+  });
+}
+
+/**
+ * Find a free port by binding to port 0.
+ */
+async function findFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.listen(0, "127.0.0.1", () => {
+      const addr = srv.address();
+      if (addr && typeof addr === "object") {
+        const port = addr.port;
+        srv.close(() => resolve(port));
+      } else {
+        srv.close(() => reject(new Error("Could not determine port")));
+      }
+    });
+    srv.on("error", reject);
+  });
+}
+
+/**
+ * Perform OAuth loopback login. Opens browser for authorization,
+ * starts a local HTTP server for the callback.
+ * Returns the DID and handle of the authenticated user.
+ */
+export async function login(handle: string): Promise<{ did: string; handle: string }> {
+  const port = await findFreePort();
+  const client = createOAuthClient(port);
+
+  const authUrl = await client.authorize(handle, {
+    scope: OAUTH_SCOPE,
+  });
+
+  // Start callback server
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      server.close();
+      reject(new Error("Login timed out after 120 seconds"));
+    }, 120_000);
+
+    const server = createServer(async (req, res) => {
+      if (!req.url?.startsWith("/callback")) {
+        res.writeHead(404);
+        res.end("Not found");
+        return;
+      }
+
+      try {
+        const url = new URL(req.url, `http://127.0.0.1:${port}`);
+        const { session } = await client.callback(url.searchParams);
+
+        const did = session.did;
+        // Resolve handle from DID
+        const agent = new Agent(session);
+        let resolvedHandle = handle;
+        try {
+          const profile = await agent.getProfile({ actor: did });
+          resolvedHandle = profile.data.handle;
+        } catch {
+          // Use the provided handle as fallback
+        }
+
+        // Find the PDS endpoint for this DID
+        let service = "https://bsky.social";
+        try {
+          const didDoc = await resolveDIDDocument(did);
+          if (didDoc) {
+            const services = (didDoc as Record<string, unknown>).service as
+              | Array<{ id: string; type: string; serviceEndpoint: string }>
+              | undefined;
+            const pds = services?.find(
+              (s) => s.id === "#atproto_pds" || s.type === "AtprotoPersonalDataServer",
+            );
+            if (pds?.serviceEndpoint) {
+              service = pds.serviceEndpoint;
+            }
+          }
+        } catch {
+          // fallback to default
+        }
+
+        saveAuthInfo({ did, handle: resolvedHandle, service });
+
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(`
+          <html><body style="font-family: system-ui; text-align: center; padding: 40px;">
+            <h2>Logged in to Skyboard CLI</h2>
+            <p>You can close this tab and return to your terminal.</p>
+          </body></html>
+        `);
+
+        clearTimeout(timeout);
+        server.close();
+        resolve({ did, handle: resolvedHandle });
+      } catch (err) {
+        res.writeHead(500, { "Content-Type": "text/html" });
+        res.end(`
+          <html><body style="font-family: system-ui; text-align: center; padding: 40px;">
+            <h2>Login failed</h2>
+            <p>${err instanceof Error ? err.message : "Unknown error"}</p>
+          </body></html>
+        `);
+        clearTimeout(timeout);
+        server.close();
+        reject(err);
+      }
+    });
+
+    server.listen(port, "127.0.0.1", async () => {
+      // Open browser
+      try {
+        const open = (await import("open")).default;
+        await open(authUrl.toString());
+        console.log(`\nOpened browser for login. Waiting for authorization...`);
+        console.log(`If the browser didn't open, visit:\n${authUrl.toString()}\n`);
+      } catch {
+        console.log(`\nOpen this URL in your browser to log in:\n${authUrl.toString()}\n`);
+      }
+    });
+  });
+}
+
+/**
+ * Get an authenticated Agent for the currently logged-in user.
+ * Restores the OAuth session and returns an Agent that auto-refreshes tokens.
+ */
+export async function getAgent(): Promise<{ agent: Agent; did: string; handle: string } | null> {
+  const authInfo = loadAuthInfo();
+  if (!authInfo) return null;
+
+  try {
+    // We need to create a client to restore the session.
+    // Since we don't know the original port, use a dummy port — session
+    // restoration doesn't need the redirect_uri to match.
+    const client = createOAuthClient(0);
+    const session = await client.restore(authInfo.did);
+    const agent = new Agent(session);
+    return { agent, did: authInfo.did, handle: authInfo.handle };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Require authentication — exit with error if not logged in.
+ */
+export async function requireAgent(): Promise<{ agent: Agent; did: string; handle: string }> {
+  const result = await getAgent();
+  if (!result) {
+    console.error("Not logged in. Run `sb login <handle>` first.");
+    process.exit(1);
+  }
+  return result;
+}
+
+export function logout(): void {
+  const authInfo = loadAuthInfo();
+  if (authInfo) {
+    deleteSessionFile(authInfo.did);
+  }
+  clearAuthInfo();
+}
+
+async function resolveDIDDocument(did: string): Promise<unknown | null> {
+  try {
+    if (did.startsWith("did:plc:")) {
+      const res = await fetch(`https://plc.directory/${did}`);
+      if (!res.ok) return null;
+      return await res.json();
+    } else if (did.startsWith("did:web:")) {
+      const host = did.slice("did:web:".length).replaceAll(":", "/");
+      const res = await fetch(`https://${host}/.well-known/did.json`);
+      if (!res.ok) return null;
+      return await res.json();
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/lib/card-ref.ts

@@ -0,0 +1,32 @@
+import type { MaterializedTask } from "./types.js";
+
+const MIN_PREFIX_LEN = 4;
+
+/**
+ * Resolve a card reference (TID rkey prefix) to a unique task.
+ * Returns the matching task, or throws with a helpful message if
+ * ambiguous or not found.
+ */
+export function resolveCardRef(
+  ref: string,
+  tasks: MaterializedTask[],
+): MaterializedTask {
+  if (ref.length < MIN_PREFIX_LEN) {
+    throw new Error(`Card reference too short (min ${MIN_PREFIX_LEN} chars): ${ref}`);
+  }
+
+  const matches = tasks.filter((t) => t.rkey.startsWith(ref));
+
+  if (matches.length === 0) {
+    throw new Error(`No card found matching "${ref}"`);
+  }
+
+  if (matches.length > 1) {
+    const list = matches
+      .map((t) => `  ${t.rkey.slice(0, 7)}  ${t.effectiveTitle}`)
+      .join("\n");
+    throw new Error(`Ambiguous reference "${ref}". Matches:\n${list}`);
+  }
+
+  return matches[0];
+}

package/src/lib/column-match.ts

@@ -0,0 +1,45 @@
+import type { Column } from "./types.js";
+
+/**
+ * Match a column reference (name, prefix, or 1-based index) to a column.
+ * Throws with a helpful message if no match found.
+ */
+export function resolveColumn(
+  ref: string,
+  columns: Column[],
+): Column {
+  const sorted = [...columns].sort((a, b) => a.order - b.order);
+
+  // Try numeric index (1-based)
+  const idx = parseInt(ref, 10);
+  if (!isNaN(idx) && idx >= 1 && idx <= sorted.length) {
+    return sorted[idx - 1];
+  }
+
+  // Try exact match (case-insensitive)
+  const exact = sorted.find((c) => c.name.toLowerCase() === ref.toLowerCase());
+  if (exact) return exact;
+
+  // Try prefix match
+  const prefixMatches = sorted.filter((c) =>
+    c.name.toLowerCase().startsWith(ref.toLowerCase()),
+  );
+  if (prefixMatches.length === 1) return prefixMatches[0];
+  if (prefixMatches.length > 1) {
+    const list = prefixMatches.map((c, i) => `  ${i + 1}. ${c.name}`).join("\n");
+    throw new Error(`Ambiguous column "${ref}". Matches:\n${list}`);
+  }
+
+  // Try substring match
+  const subMatches = sorted.filter((c) =>
+    c.name.toLowerCase().includes(ref.toLowerCase()),
+  );
+  if (subMatches.length === 1) return subMatches[0];
+  if (subMatches.length > 1) {
+    const list = subMatches.map((c, i) => `  ${i + 1}. ${c.name}`).join("\n");
+    throw new Error(`Ambiguous column "${ref}". Matches:\n${list}`);
+  }
+
+  const allCols = sorted.map((c, i) => `  ${i + 1}. ${c.name}`).join("\n");
+  throw new Error(`No column matching "${ref}". Available columns:\n${allCols}`);
+}

package/src/lib/config.ts

@@ -0,0 +1,182 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export interface BoardRef {
+  did: string;
+  rkey: string;
+  name: string;
+}
+
+export interface Config {
+  defaultBoard?: BoardRef;
+  knownBoards: BoardRef[];
+}
+
+const CONFIG_DIR = join(homedir(), ".config", "skyboard");
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+const AUTH_DIR = join(CONFIG_DIR, "auth");
+const STATE_DIR = join(CONFIG_DIR, "state");
+
+export function getConfigDir(): string {
+  return CONFIG_DIR;
+}
+
+export function getAuthDir(): string {
+  return AUTH_DIR;
+}
+
+export function getStateDir(): string {
+  return STATE_DIR;
+}
+
+function ensureConfigDir(): void {
+  mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+}
+
+function ensureAuthDir(): void {
+  ensureConfigDir();
+  mkdirSync(AUTH_DIR, { recursive: true, mode: 0o700 });
+}
+
+function ensureStateDir(): void {
+  ensureConfigDir();
+  mkdirSync(STATE_DIR, { recursive: true, mode: 0o700 });
+}
+
+export function loadConfig(): Config {
+  ensureConfigDir();
+  if (!existsSync(CONFIG_PATH)) {
+    return { knownBoards: [] };
+  }
+  try {
+    const raw = readFileSync(CONFIG_PATH, "utf-8");
+    return JSON.parse(raw) as Config;
+  } catch {
+    return { knownBoards: [] };
+  }
+}
+
+export function saveConfig(config: Config): void {
+  ensureConfigDir();
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), {
+    mode: 0o600,
+  });
+}
+
+export function setDefaultBoard(board: BoardRef): void {
+  const config = loadConfig();
+  config.defaultBoard = board;
+  if (!config.knownBoards.some((b) => b.did === board.did && b.rkey === board.rkey)) {
+    config.knownBoards.push(board);
+  }
+  saveConfig(config);
+}
+
+export function getDefaultBoard(): BoardRef | undefined {
+  return loadConfig().defaultBoard;
+}
+
+export function clearDefaultBoard(): void {
+  const config = loadConfig();
+  delete config.defaultBoard;
+  saveConfig(config);
+}
+
+export function addKnownBoard(board: BoardRef): void {
+  const config = loadConfig();
+  if (!config.knownBoards.some((b) => b.did === board.did && b.rkey === board.rkey)) {
+    config.knownBoards.push(board);
+  }
+  saveConfig(config);
+}
+
+// File-based state store for OAuth CSRF tokens
+export function writeStateFile(key: string, data: unknown): void {
+  ensureStateDir();
+  writeFileSync(join(STATE_DIR, `${key}.json`), JSON.stringify(data), {
+    mode: 0o600,
+  });
+}
+
+export function readStateFile(key: string): unknown | undefined {
+  const path = join(STATE_DIR, `${key}.json`);
+  if (!existsSync(path)) return undefined;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return undefined;
+  }
+}
+
+export function deleteStateFile(key: string): void {
+  const path = join(STATE_DIR, `${key}.json`);
+  try {
+    unlinkSync(path);
+  } catch {
+    // ignore
+  }
+}
+
+// File-based session store for OAuth sessions
+export function writeSessionFile(sub: string, data: unknown): void {
+  ensureAuthDir();
+  const filename = Buffer.from(sub).toString("base64url");
+  writeFileSync(join(AUTH_DIR, `${filename}.json`), JSON.stringify(data), {
+    mode: 0o600,
+  });
+}
+
+export function readSessionFile(sub: string): unknown | undefined {
+  const filename = Buffer.from(sub).toString("base64url");
+  const path = join(AUTH_DIR, `${filename}.json`);
+  if (!existsSync(path)) return undefined;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return undefined;
+  }
+}
+
+export function deleteSessionFile(sub: string): void {
+  const filename = Buffer.from(sub).toString("base64url");
+  const path = join(AUTH_DIR, `${filename}.json`);
+  try {
+    unlinkSync(path);
+  } catch {
+    // ignore
+  }
+}
+
+// Simple auth info storage (which DID is logged in)
+const AUTH_INFO_PATH = join(CONFIG_DIR, "session.json");
+
+export interface AuthInfo {
+  did: string;
+  handle: string;
+  service: string;
+}
+
+export function loadAuthInfo(): AuthInfo | null {
+  if (!existsSync(AUTH_INFO_PATH)) return null;
+  try {
+    return JSON.parse(readFileSync(AUTH_INFO_PATH, "utf-8")) as AuthInfo;
+  } catch {
+    return null;
+  }
+}
+
+export function saveAuthInfo(info: AuthInfo): void {
+  ensureConfigDir();
+  writeFileSync(AUTH_INFO_PATH, JSON.stringify(info, null, 2), {
+    mode: 0o600,
+  });
+}
+
+export function clearAuthInfo(): void {
+  try {
+    unlinkSync(AUTH_INFO_PATH);
+  } catch {
+    // ignore
+  }
+}