@clankmates/cli 0.1.0

package/src/lib/http.ts

@@ -0,0 +1,138 @@
+import { CliError } from "./errors";
+
+export interface RequestOptions {
+  method?: string;
+  token?: string;
+  body?: unknown;
+  rawBody?: string;
+  headers?: Record<string, string>;
+  accept?: string;
+  contentType?: string;
+}
+
+export interface HttpResponse<T = unknown> {
+  status: number;
+  data: T;
+}
+
+export async function requestJson<T = unknown>(
+  baseUrl: string,
+  path: string,
+  options: RequestOptions = {}
+): Promise<HttpResponse<T>> {
+  const url = new URL(path, ensureTrailingSlash(baseUrl));
+  const headers = new Headers(options.headers);
+  headers.set("accept", options.accept ?? "application/json");
+
+  let body: string | undefined;
+
+  if (options.body !== undefined && options.rawBody !== undefined) {
+    throw new CliError("Request body cannot set both structured and raw payloads.");
+  }
+
+  if (options.rawBody !== undefined) {
+    headers.set("content-type", options.contentType ?? "application/json");
+    body = options.rawBody;
+  } else if (options.body !== undefined) {
+    headers.set("content-type", options.contentType ?? "application/json");
+    body = JSON.stringify(options.body);
+  }
+
+  if (options.token) {
+    headers.set("authorization", `Bearer ${options.token}`);
+  }
+
+  const response = await fetch(url, {
+    method: options.method ?? "GET",
+    headers,
+    body
+  });
+
+  const rawPayload = await response.text();
+
+  if (!response.ok) {
+    throw toCliError(response.status, parsePayload(response, rawPayload, "lenient"));
+  }
+
+  const payload = parsePayload(response, rawPayload, "strict");
+
+  return {
+    status: response.status,
+    data: payload as T
+  };
+}
+
+export async function requestJsonApi<T = unknown>(
+  baseUrl: string,
+  path: string,
+  options: RequestOptions = {}
+): Promise<HttpResponse<T>> {
+  return requestJson<T>(baseUrl, path, {
+    ...options,
+    accept: options.accept ?? "application/vnd.api+json",
+    contentType: options.contentType ?? "application/vnd.api+json"
+  });
+}
+
+function toCliError(status: number, payload: unknown): CliError {
+  const message = extractErrorMessage(payload) ?? `Request failed with status ${status}`;
+  return new CliError(message, 1);
+}
+
+function parsePayload(
+  response: Response,
+  rawPayload: string,
+  mode: "lenient" | "strict"
+): unknown {
+  const contentType = response.headers.get("content-type") ?? "";
+  const isJson = contentType.includes("json");
+
+  if (!isJson || rawPayload.length === 0) {
+    return rawPayload;
+  }
+
+  try {
+    return JSON.parse(rawPayload);
+  } catch (error) {
+    if (mode === "lenient") {
+      return rawPayload;
+    }
+
+    throw new CliError(
+      `Received invalid JSON from server: ${(error as Error).message}`
+    );
+  }
+}
+
+function extractErrorMessage(payload: unknown): string | undefined {
+  if (!payload) {
+    return undefined;
+  }
+
+  if (typeof payload === "string") {
+    return payload;
+  }
+
+  if (typeof payload !== "object") {
+    return undefined;
+  }
+
+  const record = payload as Record<string, unknown>;
+  const errors = record.errors;
+
+  if (Array.isArray(errors) && errors.length > 0 && typeof errors[0] === "object" && errors[0] !== null) {
+    const first = errors[0] as Record<string, unknown>;
+    const title = typeof first.title === "string" ? first.title : undefined;
+    const detail = typeof first.detail === "string" ? first.detail : undefined;
+    const code = typeof first.code === "string" ? first.code : undefined;
+
+    return [title, detail, code ? `code=${code}` : undefined].filter(Boolean).join(": ");
+  }
+
+  const message = typeof record.message === "string" ? record.message : undefined;
+  return message;
+}
+
+function ensureTrailingSlash(baseUrl: string): string {
+  return baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+}

package/src/lib/json_api.ts

@@ -0,0 +1,55 @@
+import { CliError } from "./errors";
+import type { JsonApiDocument, JsonApiResource } from "../types/api";
+
+export interface JsonApiCollectionResult<TAttributes extends object> {
+  items: Array<JsonApiResource<TAttributes>>;
+  nextCursor?: string;
+  prevCursor?: string;
+  meta?: Record<string, unknown>;
+}
+
+export function expectResource<TAttributes extends object>(
+  payload: unknown
+): JsonApiResource<TAttributes> {
+  const document = payload as JsonApiDocument<TAttributes>;
+
+  if (!document || Array.isArray(document.data) || typeof document.data !== "object") {
+    throw new CliError("Expected a JSON:API resource object in response");
+  }
+
+  return document.data;
+}
+
+export function expectCollection<TAttributes extends object>(
+  payload: unknown
+): JsonApiCollectionResult<TAttributes> {
+  const document = payload as JsonApiDocument<TAttributes>;
+
+  if (!document || !Array.isArray(document.data)) {
+    throw new CliError("Expected a JSON:API collection in response");
+  }
+
+  return {
+    items: document.data,
+    nextCursor: extractCursor(document.links?.next),
+    prevCursor: extractCursor(document.links?.prev),
+    meta: document.meta
+  };
+}
+
+function extractCursor(link: string | null | undefined): string | undefined {
+  if (!link) {
+    return undefined;
+  }
+
+  try {
+    const url = new URL(link, "http://placeholder.local");
+    return (
+      url.searchParams.get("page[after]") ??
+      url.searchParams.get("page[cursor]") ??
+      undefined
+    );
+  } catch {
+    return undefined;
+  }
+}

package/src/lib/output.ts

@@ -0,0 +1,199 @@
+import type { OutputMode } from "../types/api";
+
+export interface Io {
+  stdout: (message: string) => void;
+  stderr: (message: string) => void;
+}
+
+export function defaultIo(): Io {
+  return {
+    stdout: (message) => process.stdout.write(`${message}\n`),
+    stderr: (message) => process.stderr.write(`${message}\n`)
+  };
+}
+
+export function printJson(io: Io, value: unknown): void {
+  io.stdout(JSON.stringify(value, null, 2));
+}
+
+export function printValue(io: Io, outputMode: OutputMode, value: unknown): void {
+  if (outputMode === "json") {
+    printJson(io, value);
+    return;
+  }
+
+  if (typeof value === "string") {
+    io.stdout(value);
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      io.stdout("No results.");
+      return;
+    }
+
+    if (isRecordArray(value)) {
+      io.stdout(renderTable(value));
+      return;
+    }
+
+    printJson(io, value);
+    return;
+  }
+
+  if (typeof value === "object" && value !== null) {
+    io.stdout(renderRecord(value as Record<string, unknown>));
+    return;
+  }
+
+  io.stdout(formatCell(value));
+}
+
+function renderTable(rows: Record<string, unknown>[]): string {
+  const columns = collectColumns(rows);
+
+  if (columns.length === 0) {
+    return "";
+  }
+
+  const renderedRows = rows.map((row) =>
+    columns.map((column) => formatTableCell(column, row[column])),
+  );
+  const widths = columns.map((column, index) =>
+    Math.max(
+      column.length,
+      ...renderedRows.map((row) => row[index]!.length),
+    ),
+  );
+
+  return [
+    renderTableLine(columns, widths),
+    renderTableLine(widths.map((width) => "-".repeat(width)), widths),
+    ...renderedRows.map((row) => renderTableLine(row, widths)),
+  ].join("\n");
+}
+
+function renderRecord(value: Record<string, unknown>): string {
+  return Object.entries(value)
+    .map(([key, entry]) => `${key}: ${formatCell(entry)}`)
+    .join("\n");
+}
+
+function isRecordArray(value: unknown[]): value is Record<string, unknown>[] {
+  return value.every(isRecord);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function formatCell(value: unknown): string {
+  if (value === null || value === undefined) {
+    return "";
+  }
+
+  if (typeof value === "string") {
+    return value.replace(/\s+/g, " ").trim();
+  }
+
+  if (typeof value === "object") {
+    return JSON.stringify(value);
+  }
+
+  return String(value);
+}
+
+function collectColumns(rows: Record<string, unknown>[]): string[] {
+  const columns: string[] = [];
+
+  for (const row of rows) {
+    for (const key of Object.keys(row)) {
+      if (!columns.includes(key)) {
+        columns.push(key);
+      }
+    }
+  }
+
+  return columns;
+}
+
+function formatTableCell(column: string, value: unknown): string {
+  if (value === null || value === undefined) {
+    return "";
+  }
+
+  if (typeof value === "string") {
+    const normalized = value.replace(/\s+/g, " ").trim();
+
+    if (isDateColumn(column)) {
+      return formatDateValue(normalized);
+    }
+
+    if (column === "body") {
+      return truncate(normalized, 30);
+    }
+
+    return normalized;
+  }
+
+  if (typeof value === "object") {
+    return JSON.stringify(value);
+  }
+
+  return String(value);
+}
+
+function renderTableLine(cells: string[], widths: number[]): string {
+  return cells
+    .map((cell, index) => cell.padEnd(widths[index]!))
+    .join("  ")
+    .trimEnd();
+}
+
+function isDateColumn(column: string): boolean {
+  return column === "date" || column.endsWith("_at") || /At$/.test(column);
+}
+
+function formatDateValue(value: string): string {
+  const timestamp = Date.parse(value);
+
+  if (Number.isNaN(timestamp)) {
+    return value;
+  }
+
+  return formatLocalTimestamp(new Date(timestamp));
+}
+
+function truncate(value: string, maxLength: number): string {
+  if (value.length <= maxLength) {
+    return value;
+  }
+
+  return `${value.slice(0, maxLength - 3)}...`;
+}
+
+function formatLocalTimestamp(value: Date): string {
+  const year = value.getFullYear();
+  const month = padDatePart(value.getMonth() + 1);
+  const day = padDatePart(value.getDate());
+  const hours = padDatePart(value.getHours());
+  const minutes = padDatePart(value.getMinutes());
+  const seconds = padDatePart(value.getSeconds());
+
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds} ${formatTimezoneOffset(value)}`;
+}
+
+function formatTimezoneOffset(value: Date): string {
+  const offsetMinutes = -value.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? "+" : "-";
+  const absoluteMinutes = Math.abs(offsetMinutes);
+  const hours = padDatePart(Math.floor(absoluteMinutes / 60));
+  const minutes = padDatePart(absoluteMinutes % 60);
+
+  return `${sign}${hours}:${minutes}`;
+}
+
+function padDatePart(value: number): string {
+  return String(value).padStart(2, "0");
+}

package/src/lib/paths.ts

@@ -0,0 +1,18 @@
+import os from "node:os";
+import path from "node:path";
+
+export function getConfigPath(): string {
+  const explicit = process.env.CLANKMATES_CONFIG_PATH;
+
+  if (explicit) {
+    return explicit;
+  }
+
+  const xdg = process.env.XDG_CONFIG_HOME;
+
+  if (xdg) {
+    return path.join(xdg, "clankmates", "config.json");
+  }
+
+  return path.join(os.homedir(), ".config", "clankmates", "config.json");
+}

package/src/lib/skills.ts

@@ -0,0 +1,137 @@
+import { cp, lstat, mkdir, readlink, rm, symlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { CliError } from "./errors";
+
+export type SkillHost = "codex" | "claude" | "both";
+export type SkillInstallMode = "symlink" | "copy";
+
+export interface InstalledSkillTarget {
+  host: Exclude<SkillHost, "both">;
+  mode: SkillInstallMode;
+  sourcePath: string;
+  targetPath: string;
+  status: "installed" | "updated" | "already_installed";
+}
+
+const SKILL_NAME = "clankmates";
+
+export function bundledSkillPath(): string {
+  return fileURLToPath(
+    new URL("../../skills/codex/clankmates", import.meta.url),
+  );
+}
+
+export function resolveSkillHosts(host: string | undefined): Exclude<SkillHost, "both">[] {
+  switch (host ?? "both") {
+    case "codex":
+      return ["codex"];
+    case "claude":
+    case "claude-code":
+      return ["claude"];
+    case "both":
+      return ["codex", "claude"];
+    default:
+      throw new CliError(
+        "Unsupported `--host`. Use `codex`, `claude`, or `both`.",
+        2,
+      );
+  }
+}
+
+export function resolveSkillInstallTarget(host: Exclude<SkillHost, "both">): string {
+  if (host === "codex") {
+    const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+    return path.join(codexHome, "skills", SKILL_NAME);
+  }
+
+  const claudeHome = process.env.CLAUDE_HOME || path.join(os.homedir(), ".claude");
+  return path.join(claudeHome, "skills", SKILL_NAME);
+}
+
+export async function installBundledSkill(input: {
+  host: Exclude<SkillHost, "both">;
+  mode: SkillInstallMode;
+  force: boolean;
+}): Promise<InstalledSkillTarget> {
+  const sourcePath = bundledSkillPath();
+  const targetPath = resolveSkillInstallTarget(input.host);
+  const existing = await readInstallState(targetPath);
+
+  if (existing.exists) {
+    if (input.mode === "symlink" && existing.kind === "symlink" && existing.linkTarget === sourcePath) {
+      return {
+        host: input.host,
+        mode: input.mode,
+        sourcePath,
+        targetPath,
+        status: "already_installed",
+      };
+    }
+
+    if (!input.force) {
+      throw new CliError(
+        `Skill target already exists at ${targetPath}. Re-run with \`--force\` to replace it.`,
+        2,
+      );
+    }
+
+    await rm(targetPath, { recursive: true, force: true });
+  }
+
+  await mkdir(path.dirname(targetPath), { recursive: true });
+
+  if (input.mode === "copy") {
+    await cp(sourcePath, targetPath, { recursive: true });
+  } else {
+    await symlink(sourcePath, targetPath, "dir");
+  }
+
+  return {
+    host: input.host,
+    mode: input.mode,
+    sourcePath,
+    targetPath,
+    status: existing.exists ? "updated" : "installed",
+  };
+}
+
+async function readInstallState(targetPath: string): Promise<{
+  exists: boolean;
+  kind?: "directory" | "symlink" | "file";
+  linkTarget?: string;
+}> {
+  try {
+    const stats = await lstat(targetPath);
+
+    if (stats.isSymbolicLink()) {
+      return {
+        exists: true,
+        kind: "symlink",
+        linkTarget: await readlink(targetPath),
+      };
+    }
+
+    if (stats.isDirectory()) {
+      return {
+        exists: true,
+        kind: "directory",
+      };
+    }
+
+    return {
+      exists: true,
+      kind: "file",
+    };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { exists: false };
+    }
+
+    throw new CliError(
+      `Failed to inspect skill target ${targetPath}: ${(error as Error).message}`,
+    );
+  }
+}