@andocorp/cli 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# Ando CLI
+
+`ando` is a terminal client for humans and agents.
+
+## Installation
+
+### Quick Install (macOS/Linux)
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/ando-labs/ando/main/apps/cli/install.sh | sh
+```
+
+### Manual Installation
+
+Download the latest binary for your platform from [Releases](https://github.com/ando-labs/ando/releases):
+
+**macOS:**
+- Apple Silicon (M1/M2/M3): `ando-macos-arm64`
+- Intel: `ando-macos-x64`
+
+**Linux:**
+- `ando-linux-x64`
+
+**Windows:**
+- `ando-windows-x64.exe`
+
+After downloading:
+
+```sh
+# macOS/Linux
+chmod +x ando-*
+sudo mv ando-* /usr/local/bin/ando
+
+# Verify installation
+ando --help
+```
+
+### npm (Coming Soon)
+
+```sh
+npm install -g @andocorp/cli
+```
+
+## Development
+
+### Running Locally
+
+```sh
+# run dev
+bun --cwd apps/cli dev
+
+# compile a native binary to apps/cli/dist/ando
+bun compile
+```
+
+### Building for All Platforms
+
+Binaries are built automatically via GitHub Actions on release. To build locally:
+
+```sh
+# Current platform only
+pnpm --filter cli compile
+
+# All platforms (requires GitHub Actions)
+git tag cli-v0.1.0
+git push origin cli-v0.1.0
+```
+
+## Commands
+
+Open the interactive terminal UI:
+
+```sh
+ando
+```
+
+Show help:
+
+```sh
+ando help
+ando --help
+```
+
+List channels:
+
+```sh
+ando list-channels
+ando list-channels --json
+```
+
+List direct-message conversations:
+
+```sh
+ando list-dms
+ando list-dms --json
+```
+
+List messages from a channel, DM, or conversation id:
+
+```sh
+ando list-messages --channel engineering
+ando list-messages --dm alex
+ando list-messages --conversation <conversation-id>
+ando list-messages --channel engineering --limit 20
+ando list-messages -c engineering -n 20 --json
+```
+
+Read a thread by message id:
+
+```sh
+ando thread --message-id <message-id>
+ando thread -m <message-id> --json
+```
+
+Post a new message to a channel, DM, or conversation id:
+
+```sh
+ando post-message --channel engineering --text "hello"
+ando post-message --dm alex --text "want to pair?"
+ando post-message --conversation <conversation-id> --text "status update"
+ando post-message -c engineering -t "hello" --json
+```
+
+Reply inside an existing thread:
+
+```sh
+ando reply --message-id <message-id> --text "on it"
+ando reply -m <message-id> -t "on it" --json
+```
+
+Add a reaction to a message:
+
+```sh
+ando react --message-id <message-id> --emoji 👍
+ando react -m <message-id> -e 👍 --json
+```

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@andocorp/cli",
+  "version": "0.1.0",
+  "description": "Ando CLI - A terminal client for humans and agents",
+  "type": "module",
+  "bin": {
+    "ando": "./src/index.ts"
+  },
+  "scripts": {
+    "compile": "bun build --compile ./src/index.ts --outfile ./dist/ando && chmod +x ./dist/ando",
+    "compile:all": "node scripts/build-all-platforms.js",
+    "dev": "bun run ./src/index.ts",
+    "lint": "pnpm -w exec eslint apps/cli --no-warn-ignored",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ando-labs/ando.git",
+    "directory": "apps/cli"
+  },
+  "keywords": ["cli", "terminal", "chat", "collaboration"],
+  "author": "Ando Labs",
+  "license": "MIT",
+  "files": [
+    "src/**/*.ts",
+    "src/**/*.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ando/shared": "workspace:*",
+    "convex": "^1.34.1",
+    "emojibase-data": "^16.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.4"
+  }
+}

package/src/adapters.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { adaptBootstrap, adaptConversationPage } from "./adapters.js";
+import { createMe, createMembership, createMessage } from "./test-helpers.js";
+
+describe("adapters", () => {
+  it("adapts bootstrap payloads into date-backed objects", () => {
+    const result = adaptBootstrap({
+      me: createMe({
+        created_at: 1_700_000_000_000 as unknown as Date,
+      }) as unknown as Record<string, unknown>,
+      memberships: [
+        createMembership({
+          created_at: 1_700_000_000_000 as unknown as Date,
+        }) as unknown as Record<string, unknown>,
+      ],
+    });
+
+    expect(result.me?.created_at).toBeInstanceOf(Date);
+    expect(result.memberships[0]?.created_at).toBeInstanceOf(Date);
+  });
+
+  it("reverses paginated conversation results into chronological order", () => {
+    const newest = createMessage({
+      id: "message-3",
+      created_at: 3 as unknown as Date,
+    });
+    const middle = createMessage({
+      id: "message-2",
+      created_at: 2 as unknown as Date,
+    });
+    const oldest = createMessage({
+      id: "message-1",
+      created_at: 1 as unknown as Date,
+    });
+
+    const page = adaptConversationPage({
+      page: [newest, middle, oldest],
+      isDone: false,
+      continueCursor: "cursor-2",
+    });
+
+    expect(page.items.map((item) => item.id)).toEqual([
+      "message-1",
+      "message-2",
+      "message-3",
+    ]);
+    expect(page.cursor).toBe("cursor-2");
+    expect(page.hasMore).toBe(true);
+  });
+});

package/src/adapters.ts

@@ -0,0 +1,215 @@
+import * as Shared from "@ando/shared";
+import { ConversationPage, DiscoveredWorkspace, Me, Membership, Message } from "./types.js";
+
+type BootstrapResult = {
+  me: Record<string, unknown> | null;
+  memberships: Record<string, unknown>[];
+};
+
+type ConvexPaginatedResult<T> = {
+  page: T[];
+  isDone: boolean;
+  continueCursor: string;
+};
+
+function adaptTimestamp(value: Date | number | string | null | undefined): Date {
+  if (value instanceof Date) {
+    return value;
+  }
+
+  if (typeof value === "number") {
+    return new Date(value);
+  }
+
+  if (typeof value === "string") {
+    return new Date(value);
+  }
+
+  return new Date(0);
+}
+
+function adaptNullableTimestamp(value: Date | number | string | null | undefined) {
+  if (value == null) {
+    return null;
+  }
+
+  return adaptTimestamp(value);
+}
+
+export function adaptDiscoveredWorkspace(
+  workspace: Shared.Contracts.DiscoveredWorkspace
+): DiscoveredWorkspace {
+  return {
+    ...workspace,
+    created_at: adaptTimestamp(workspace.created_at),
+    updated_at: adaptTimestamp(workspace.updated_at),
+  };
+}
+
+function adaptFile(file: Shared.Contracts.FileExtended): Shared.Contracts.FileExtended {
+  return {
+    ...file,
+    created_at: adaptTimestamp(file.created_at),
+    updated_at: adaptTimestamp(file.updated_at),
+  };
+}
+
+function adaptPreviewMember(member: Shared.Models.Member): Shared.Models.Member {
+  return {
+    ...member,
+    created_at: adaptTimestamp(member.created_at),
+    updated_at: adaptTimestamp(member.updated_at),
+    last_active_at: adaptTimestamp(member.last_active_at),
+    last_caught_up_at: adaptTimestamp(member.last_caught_up_at),
+    archived_at: adaptNullableTimestamp(member.archived_at),
+    onboarding_completed_at: adaptNullableTimestamp(member.onboarding_completed_at),
+    last_summary_at: adaptNullableTimestamp(member.last_summary_at),
+  };
+}
+
+export function adaptMember(member: Shared.Contracts.MemberExtended): Shared.Contracts.MemberExtended {
+  return {
+    ...member,
+    created_at: adaptTimestamp(member.created_at),
+    updated_at: adaptTimestamp(member.updated_at),
+    last_active_at: adaptTimestamp(member.last_active_at),
+    last_caught_up_at: adaptTimestamp(member.last_caught_up_at),
+    archived_at: adaptNullableTimestamp(member.archived_at),
+    onboarding_completed_at: adaptNullableTimestamp(member.onboarding_completed_at),
+    last_summary_at: adaptNullableTimestamp(member.last_summary_at),
+    profile_image_file:
+      member.profile_image_file == null ? null : adaptFile(member.profile_image_file),
+  };
+}
+
+export function adaptConversation(
+  conversation: Shared.Contracts.ConversationExtended
+): Shared.Contracts.ConversationExtended {
+  return {
+    ...conversation,
+    created_at: adaptTimestamp(conversation.created_at),
+    updated_at: adaptTimestamp(conversation.updated_at),
+    last_message_at: adaptNullableTimestamp(conversation.last_message_at),
+    last_summary_at: adaptNullableTimestamp(conversation.last_summary_at),
+    archived_at: adaptNullableTimestamp(conversation.archived_at),
+    preview_members: (conversation.preview_members ?? []).map(adaptPreviewMember),
+    creator_member:
+      conversation.creator_member == null
+        ? null
+        : adaptPreviewMember(conversation.creator_member),
+  };
+}
+
+function adaptThreadSubscription(
+  subscription: Shared.Contracts.ThreadSubscriptionExtended
+): Shared.Contracts.ThreadSubscriptionExtended {
+  return {
+    ...subscription,
+    created_at: adaptTimestamp(subscription.created_at),
+    updated_at: adaptTimestamp(subscription.updated_at),
+    last_seen_at: adaptNullableTimestamp(subscription.last_seen_at),
+    thread_root: {
+      ...subscription.thread_root,
+      created_at: adaptTimestamp(subscription.thread_root.created_at),
+      updated_at: adaptTimestamp(subscription.thread_root.updated_at),
+      edited_at: adaptNullableTimestamp(subscription.thread_root.edited_at),
+      pinned_at: adaptNullableTimestamp(subscription.thread_root.pinned_at),
+      last_reply_at: adaptNullableTimestamp(subscription.thread_root.last_reply_at),
+      archived_at: adaptNullableTimestamp(subscription.thread_root.archived_at),
+    },
+  };
+}
+
+export function adaptMembership(
+  membership: Shared.Contracts.MembershipExtended
+): Membership {
+  return {
+    ...membership,
+    created_at: adaptTimestamp(membership.created_at),
+    updated_at: adaptTimestamp(membership.updated_at),
+    last_seen_at: adaptTimestamp(membership.last_seen_at),
+    member: adaptMember(membership.member),
+    conversation: adaptConversation(membership.conversation),
+    thread_subscriptions: (membership.thread_subscriptions ?? []).map(
+      adaptThreadSubscription
+    ),
+  };
+}
+
+export function adaptMessage(
+  message: Shared.Contracts.ConversationMessageExtended
+): Message {
+  return {
+    ...message,
+    created_at: adaptTimestamp(message.created_at),
+    updated_at: adaptTimestamp(message.updated_at),
+    edited_at: adaptNullableTimestamp(message.edited_at),
+    pinned_at: adaptNullableTimestamp(message.pinned_at),
+    last_reply_at: adaptNullableTimestamp(message.last_reply_at),
+    archived_at: adaptNullableTimestamp(message.archived_at),
+    author: adaptMember(message.author),
+    message_reactions: (message.message_reactions ?? []).map((reaction) => ({
+      ...reaction,
+      created_at: adaptTimestamp(reaction.created_at),
+    })),
+    replies_preview_members: (message.replies_preview_members ?? []).map(
+      adaptPreviewMember
+    ),
+    files: (message.files ?? []).map(adaptFile),
+    thread_root_message:
+      message.thread_root_message == null
+        ? null
+        : {
+            ...message.thread_root_message,
+            created_at: adaptTimestamp(message.thread_root_message.created_at),
+            updated_at: adaptTimestamp(message.thread_root_message.updated_at),
+            edited_at: adaptNullableTimestamp(message.thread_root_message.edited_at),
+            pinned_at: adaptNullableTimestamp(message.thread_root_message.pinned_at),
+            last_reply_at: adaptNullableTimestamp(message.thread_root_message.last_reply_at),
+            archived_at: adaptNullableTimestamp(message.thread_root_message.archived_at),
+          },
+  };
+}
+
+function adaptWorkspace(
+  workspace: Shared.Contracts.WorkspaceExtended
+): Shared.Contracts.WorkspaceExtended {
+  return {
+    ...workspace,
+    created_at: adaptTimestamp(workspace.created_at),
+    updated_at: adaptTimestamp(workspace.updated_at),
+    workspace_invite_link: {
+      ...workspace.workspace_invite_link,
+      created_at: adaptTimestamp(workspace.workspace_invite_link.created_at),
+    },
+  };
+}
+
+export function adaptMe(member: Shared.Contracts.MeExtended): Me {
+  return {
+    ...adaptMember(member),
+    workspace: adaptWorkspace(member.workspace),
+  };
+}
+
+export function adaptBootstrap(result: BootstrapResult) {
+  return {
+    me:
+      result.me == null
+        ? null
+        : adaptMe(result.me as unknown as Shared.Contracts.MeExtended),
+    memberships: result.memberships.map((membership) =>
+      adaptMembership(membership as unknown as Shared.Contracts.MembershipExtended)
+    ),
+  };
+}
+
+export function adaptConversationPage(
+  result: ConvexPaginatedResult<Shared.Contracts.ConversationMessageExtended>
+): ConversationPage {
+  return {
+    items: [...result.page].reverse().map(adaptMessage),
+    cursor: result.isDone ? null : result.continueCursor,
+    hasMore: !result.isDone,
+  };
+}

package/src/args.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { getStringFlag, hasFlag, parseArgs } from "./args.js";
+
+describe("args", () => {
+  it("parses long and short flags with values", () => {
+    const parsed = parseArgs([
+      "list-messages",
+      "--channel",
+      "engineering",
+      "-n",
+      "20",
+      "--json",
+    ]);
+
+    expect(parsed.positionals).toEqual(["list-messages"]);
+    expect(getStringFlag(parsed, "channel", "c")).toBe("engineering");
+    expect(getStringFlag(parsed, "limit", "n")).toBe("20");
+    expect(hasFlag(parsed, "json")).toBe(true);
+  });
+
+  it("parses compact short flags", () => {
+    const parsed = parseArgs(["thread", "-vhm", "message-1"]);
+
+    expect(hasFlag(parsed, "verbose", "v")).toBe(true);
+    expect(hasFlag(parsed, "help", "h")).toBe(true);
+    expect(getStringFlag(parsed, "message-id", "m")).toBe("message-1");
+  });
+});

package/src/args.ts

@@ -0,0 +1,98 @@
+import { ParsedArgs } from "./types.js";
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  const flags = new Map<string, string | true>();
+  const positionals: string[] = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value == null) {
+      continue;
+    }
+
+    if (!value.startsWith("-")) {
+      positionals.push(value);
+      continue;
+    }
+
+    if (value.startsWith("--")) {
+      const [key, inlineValue] = value.slice(2).split("=", 2);
+      if (inlineValue != null) {
+        flags.set(key, inlineValue);
+        continue;
+      }
+
+      const nextValue = argv[index + 1];
+      if (nextValue != null && !nextValue.startsWith("-")) {
+        flags.set(key, nextValue);
+        index += 1;
+      } else {
+        flags.set(key, true);
+      }
+      continue;
+    }
+
+    const shortFlags = value.slice(1);
+    if (shortFlags.length > 1) {
+      for (let shortIndex = 0; shortIndex < shortFlags.length - 1; shortIndex += 1) {
+        const shortFlag = shortFlags[shortIndex];
+        if (shortFlag != null) {
+          flags.set(shortFlag, true);
+        }
+      }
+
+      const lastFlag = shortFlags[shortFlags.length - 1];
+      const nextValue = argv[index + 1];
+      if (lastFlag == null) {
+        continue;
+      }
+
+      if (nextValue != null && !nextValue.startsWith("-")) {
+        flags.set(lastFlag, nextValue);
+        index += 1;
+      } else {
+        flags.set(lastFlag, true);
+      }
+      continue;
+    }
+
+    const nextValue = argv[index + 1];
+    if (nextValue != null && !nextValue.startsWith("-")) {
+      flags.set(shortFlags, nextValue);
+      index += 1;
+    } else {
+      flags.set(shortFlags, true);
+    }
+  }
+
+  return {
+    flags,
+    positionals,
+  };
+}
+
+export function getStringFlag(
+  parsedArgs: ParsedArgs,
+  longName: string,
+  shortName?: string
+) {
+  const longValue = parsedArgs.flags.get(longName);
+  if (typeof longValue === "string") {
+    return longValue;
+  }
+
+  if (shortName == null) {
+    return undefined;
+  }
+
+  const shortValue = parsedArgs.flags.get(shortName);
+  return typeof shortValue === "string" ? shortValue : undefined;
+}
+
+export function hasFlag(
+  parsedArgs: ParsedArgs,
+  longName: string,
+  shortName?: string
+) {
+  return parsedArgs.flags.has(longName) || (shortName != null && parsedArgs.flags.has(shortName));
+}

package/src/cli-helpers.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import * as Shared from "@ando/shared";
+import { compareByRecentActivity, resolveConversation, resolveWorkspace } from "./cli-helpers.js";
+import { createConversation, createMembership } from "./test-helpers.js";
+
+describe("cli helpers", () => {
+  it("resolves a conversation by exact name", () => {
+    const memberships = [
+      createMembership({
+        id: "membership-a",
+        conversation: createConversation({ id: "conversation-a", name: "engineering" }),
+      }),
+    ];
+
+    const result = resolveConversation(memberships, {
+      allowChannels: true,
+      allowDms: true,
+      query: "engineering",
+    });
+
+    expect(result.id).toBe("membership-a");
+  });
+
+  it("throws when a partial conversation match is ambiguous", () => {
+    const memberships = [
+      createMembership({
+        id: "membership-a",
+        conversation: createConversation({ id: "conversation-a", name: "eng-platform" }),
+      }),
+      createMembership({
+        id: "membership-b",
+        conversation: createConversation({ id: "conversation-b", name: "eng-mobile" }),
+      }),
+    ];
+
+    expect(() =>
+      resolveConversation(memberships, {
+        allowChannels: true,
+        allowDms: true,
+        query: "eng",
+      })
+    ).toThrow(/ambiguous/);
+  });
+
+  it("sorts more recent memberships first", () => {
+    const oldMembership = createMembership({
+      id: "old",
+      conversation: createConversation({
+        id: "conversation-old",
+        last_message_at: new Date("2026-04-08T12:00:00.000Z"),
+      }),
+    });
+    const newMembership = createMembership({
+      id: "new",
+      conversation: createConversation({
+        id: "conversation-new",
+        last_message_at: new Date("2026-04-09T12:00:00.000Z"),
+      }),
+    });
+
+    expect(compareByRecentActivity(newMembership, oldMembership)).toBeLessThan(0);
+  });
+
+  it("resolves workspaces by slug", () => {
+    const workspace = {
+      id: "workspace-1",
+      stytch_organization_id: "org-1",
+      name: "Ando",
+      slug: "ando",
+      image_url: null,
+      icon_image_file_id: null,
+      description: null,
+      invite_link_id: "invite-1",
+      created_at: new Date("2026-04-09T12:00:00.000Z"),
+      updated_at: new Date("2026-04-09T12:00:00.000Z"),
+      member_count: 3,
+    } satisfies Shared.Contracts.DiscoveredWorkspace;
+
+    const result = resolveWorkspace([workspace], "ando");
+    expect(result.id).toBe("workspace-1");
+  });
+});