@bdsqqq/lnr-cli 1.6.0 → 2.0.0

package/src/generated/template.ts

@@ -0,0 +1,157 @@
+/**
+ * Template command (read-only).
+ * Not generated by codegen — templates use a simpler pattern.
+ */
+
+import "../lib/arktype-config";
+import { type } from "arktype";
+import {
+  getClient,
+  listTemplates,
+  getTemplate,
+  getIssueTemplates,
+  type Template,
+} from "@bdsqqq/lnr-core";
+import { router, procedure } from "../router/trpc";
+import { handleApiError, exitWithError, EXIT_CODES } from "../lib/error";
+import {
+  outputJson,
+  outputQuiet,
+  outputTable,
+  getOutputFormat,
+  truncate,
+  type OutputOptions,
+  type TableColumn,
+} from "../lib/output";
+
+export const listTemplatesInput = type({
+  "team?": type("string").describe("filter by team key"),
+  "type?": type("string").describe("filter by template type (issue, project)"),
+  "json?": type("boolean").describe("output as json"),
+  "quiet?": type("boolean").describe("output ids only"),
+  "verbose?": type("boolean").describe("show all columns"),
+});
+
+export const templateInput = type({
+  name: type("string").configure({ positional: true }).describe("template name or id"),
+  "team?": type("string").describe("team key to scope template lookup"),
+  "json?": type("boolean").describe("output as json"),
+  "quiet?": type("boolean").describe("output ids only"),
+  "verbose?": type("boolean").describe("show all columns"),
+});
+
+type TemplateInput = typeof templateInput.infer;
+
+const templateColumns: TableColumn<Template>[] = [
+  { header: "NAME", value: (t) => truncate(t.name, 30), width: 30 },
+  { header: "TYPE", value: (t) => t.type, width: 10 },
+  { header: "TEAM", value: (t) => t.teamKey ?? "workspace", width: 10 },
+];
+
+const verboseTemplateColumns: TableColumn<Template>[] = [
+  ...templateColumns,
+  { header: "DESCRIPTION", value: (t) => truncate(t.description ?? "-", 40), width: 40 },
+  { header: "ID", value: (t) => t.id, width: 36 },
+];
+
+async function handleListTemplates(
+  input: typeof listTemplatesInput.infer
+): Promise<void> {
+  try {
+    const client = getClient();
+
+    const outputOpts: OutputOptions = {
+      format: input.json ? "json" : input.quiet ? "quiet" : undefined,
+      verbose: input.verbose,
+    };
+    const format = getOutputFormat(outputOpts);
+
+    let templates = await listTemplates(client, input.team);
+
+    if (input.type) {
+      templates = templates.filter(
+        (t) => t.type.toLowerCase() === input.type!.toLowerCase()
+      );
+    }
+
+    if (format === "json") {
+      outputJson(templates);
+      return;
+    }
+
+    if (format === "quiet") {
+      outputQuiet(templates.map((t) => t.id));
+      return;
+    }
+
+    const columns = input.verbose ? verboseTemplateColumns : templateColumns;
+    outputTable(templates, columns, outputOpts);
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+async function handleShowTemplate(
+  name: string,
+  input: TemplateInput
+): Promise<void> {
+  try {
+    const client = getClient();
+
+    const outputOpts: OutputOptions = {
+      format: input.json ? "json" : input.quiet ? "quiet" : undefined,
+      verbose: input.verbose,
+    };
+    const format = getOutputFormat(outputOpts);
+
+    const template = await getTemplate(client, name, input.team);
+
+    if (!template) {
+      exitWithError(
+        `template "${name}" not found`,
+        input.team ? undefined : "try: lnr templates --team <key>",
+        EXIT_CODES.NOT_FOUND
+      );
+    }
+
+    if (format === "json") {
+      outputJson(template);
+      return;
+    }
+
+    if (format === "quiet") {
+      console.log(template.id);
+      return;
+    }
+
+    console.log(`${template.name}`);
+    console.log(`type: ${template.type}`);
+    console.log(`team: ${template.teamKey ?? "workspace"}`);
+    if (template.description) {
+      console.log(`description: ${template.description}`);
+    }
+    console.log(`id: ${template.id}`);
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export const generatedTemplatesRouter = router({
+  templates: procedure
+    .meta({
+      description: "list templates",
+    })
+    .input(listTemplatesInput)
+    .query(async ({ input }) => {
+      await handleListTemplates(input);
+    }),
+
+  template: procedure
+    .meta({
+      description: "show a template",
+    })
+    .input(templateInput)
+    .query(async ({ input }) => {
+      await handleShowTemplate(input.name, input);
+    }),
+});

package/src/hand-crafted/issue.ts

@@ -0,0 +1,27 @@
+/**
+ * Hand-crafted handlers for CLI-only issue features.
+ * These are not backed by Linear's schema — they're pure CLI UX.
+ *
+ * The generator imports these and dispatches to them.
+ * Edit freely; regeneration won't touch this file.
+ */
+
+import { linkGitHubPR, type Issue } from "@bdsqqq/lnr-core";
+import { exitWithError } from "../lib/error";
+
+type Client = Parameters<typeof linkGitHubPR>[0];
+
+/**
+ * --pr: link a GitHub PR URL to the issue
+ */
+export async function handlePr(
+  client: Client,
+  issue: Issue,
+  prUrl: string
+): Promise<void> {
+  const success = await linkGitHubPR(client, issue.id, prUrl);
+  if (!success) {
+    exitWithError(`failed to link pr ${prUrl}`);
+  }
+  console.log(`linked pr ${prUrl} to ${issue.identifier}`);
+}

package/src/lib/adapters/doc.ts

@@ -0,0 +1,14 @@
+import type { Document } from "@bdsqqq/lnr-core";
+import type { DetailSection } from "../renderers/detail";
+
+export function docToDetail(doc: Document): DetailSection[] {
+  const sections: DetailSection[] = [
+    { type: "header", title: doc.title },
+  ];
+
+  if (doc.content) {
+    sections.push({ type: "text", body: doc.content });
+  }
+
+  return sections;
+}

package/src/lib/adapters/index.ts

@@ -0,0 +1,4 @@
+export { issueToDetail } from "./issue";
+export { projectToDetail } from "./project";
+export { labelToDetail } from "./label";
+export { docToDetail } from "./doc";

package/src/lib/adapters/issue.ts

@@ -0,0 +1,32 @@
+import type { Issue } from "@bdsqqq/lnr-core";
+import { formatDate, formatPriority } from "../output";
+import type { DetailSection } from "../renderers/detail";
+
+export function issueToDetail(issue: Issue): DetailSection[] {
+  const fields: { label: string; value: string }[] = [
+    { label: "state", value: issue.state ?? "-" },
+    { label: "assignee", value: issue.assignee ?? "-" },
+    { label: "priority", value: formatPriority(issue.priority) },
+  ];
+
+  if (issue.parentId) {
+    fields.push({ label: "parent", value: issue.parentId });
+  }
+
+  fields.push(
+    { label: "created", value: formatDate(issue.createdAt) },
+    { label: "updated", value: formatDate(issue.updatedAt) },
+    { label: "url", value: issue.url },
+  );
+
+  const sections: DetailSection[] = [
+    { type: "header", title: `${issue.identifier}: ${issue.title}` },
+    { type: "fields", fields },
+  ];
+
+  if (issue.description) {
+    sections.push({ type: "text", body: issue.description });
+  }
+
+  return sections;
+}

package/src/lib/adapters/label.ts

@@ -0,0 +1,20 @@
+import type { Label } from "@bdsqqq/lnr-core";
+import type { DetailSection } from "../renderers/detail";
+
+export function labelToDetail(label: Label): DetailSection[] {
+  const fields: { label: string; value: string }[] = [
+    { label: "id", value: label.id },
+    { label: "color", value: label.color ?? "-" },
+  ];
+
+  const sections: DetailSection[] = [
+    { type: "header", title: label.name },
+    { type: "fields", fields },
+  ];
+
+  if (label.description) {
+    sections.push({ type: "text", body: label.description });
+  }
+
+  return sections;
+}

package/src/lib/adapters/project.ts

@@ -0,0 +1,23 @@
+import type { Project } from "@bdsqqq/lnr-core";
+import { formatDate } from "../output";
+import type { DetailSection } from "../renderers/detail";
+
+export function projectToDetail(project: Project): DetailSection[] {
+  const header: DetailSection = project.description
+    ? { type: "header", title: project.name, subtitle: project.description }
+    : { type: "header", title: project.name };
+
+  const sections: DetailSection[] = [header];
+
+  const fields: { label: string; value: string }[] = [
+    { label: "state", value: project.state ?? "-" },
+    { label: "progress", value: `${Math.round((project.progress ?? 0) * 100)}%` },
+    { label: "target", value: formatDate(project.targetDate) },
+    { label: "started", value: formatDate(project.startDate) },
+    { label: "created", value: formatDate(project.createdAt) },
+  ];
+
+  sections.push({ type: "fields", fields });
+
+  return sections;
+}

package/src/lib/arktype-config.ts

@@ -0,0 +1,18 @@
+/**
+ * arktype configuration for CLI schemas.
+ *
+ * extends ArkEnv.meta to support trpc-cli metadata like `positional`.
+ * MUST be imported before any arktype usage in generated files.
+ *
+ * see: https://arktype.io/docs/configuration
+ */
+
+declare global {
+  interface ArkEnv {
+    meta(): {
+      positional?: boolean;
+    };
+  }
+}
+
+export {};

package/src/lib/command-introspection.ts

@@ -0,0 +1,97 @@
+import "./arktype-config";
+import { appRouter } from "../router/index";
+
+export interface Flag {
+  name: string;
+  type: string;
+  description: string;
+  positional: boolean;
+  required: boolean;
+}
+
+export interface Command {
+  name: string;
+  description: string;
+  aliases: string[];
+  flags: Flag[];
+}
+
+export type SchemaJson = {
+  domain: string;
+  required?: { key: string; value: SchemaValue }[];
+  optional?: { key: string; value: SchemaValue }[];
+};
+
+export type SchemaValue = {
+  domain?: string;
+  meta?: string | { description?: string; positional?: boolean };
+  branches?: { unit?: unknown; meta?: string | { description?: string; positional?: boolean } }[];
+  unit?: unknown;
+};
+
+export const extractMeta = (value: SchemaValue): { description: string; positional: boolean } => {
+  const meta = value.meta ?? value.branches?.[0]?.meta;
+  return typeof meta === "object"
+    ? { description: meta.description ?? "", positional: meta.positional ?? false }
+    : { description: meta ?? "", positional: false };
+};
+
+export const inferType = (value: SchemaValue): string => {
+  if (value.domain) return value.domain === "number" ? "number" : "string";
+  if (value.branches?.some((b) => b.unit === true || b.unit === false)) return "boolean";
+  if (value.unit !== undefined) return typeof value.unit;
+  return "string";
+};
+
+export const parseSchema = (json: SchemaJson): Flag[] => [
+  ...(json.required ?? []).map(({ key, value }) => ({
+    name: key,
+    type: inferType(value),
+    ...extractMeta(value),
+    required: true,
+  })),
+  ...(json.optional ?? []).map(({ key, value }) => ({
+    name: key,
+    type: inferType(value),
+    ...extractMeta(value),
+    required: false,
+  })),
+];
+
+export const camelToKebab = (s: string): string =>
+  s.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+
+interface ProcedureDef {
+  _def: {
+    meta?: { description?: string; aliases?: { command?: string[] } };
+    inputs?: { json: SchemaJson }[];
+  };
+}
+
+function isProcedureDef(value: unknown): value is ProcedureDef {
+  return (
+    (typeof value === "object" || typeof value === "function") &&
+    value !== null &&
+    "_def" in value &&
+    typeof (value as Record<string, unknown>)._def === "object"
+  );
+}
+
+export const buildCommands = (): Command[] => {
+  const procedures = appRouter._def.procedures as Record<string, unknown>;
+
+  return Object.entries(procedures)
+    .filter((entry): entry is [string, ProcedureDef] => isProcedureDef(entry[1]))
+    .map(([name, proc]) => {
+      const meta = proc._def.meta ?? {};
+      const schema = proc._def.inputs?.[0]?.json;
+      const flags = schema ? parseSchema(schema) : [];
+
+      return {
+        name: name.replace(/\./g, " "),
+        description: meta.description ?? "",
+        aliases: meta.aliases?.command ?? [],
+        flags,
+      };
+    });
+};

package/src/lib/dispatch-effects.test.ts

@@ -0,0 +1,297 @@
+import { test, expect, mock, describe, beforeEach } from "bun:test";
+
+const mockUpdateIssue = mock(async () => true);
+const mockGetIssue = mock(
+  async () =>
+    ({
+      id: "I1",
+      identifier: "ENG-1",
+      title: "test",
+      url: "https://linear.app/test",
+      branchName: "eng-1-test",
+      priority: 3,
+      state: "Todo",
+      assignee: "alice",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    }) as const
+);
+const mockClientLabels = mock(async () => ({ nodes: [] }));
+const mockClientIssue = mock(async () => ({
+  team: Promise.resolve({ id: "T1" }),
+  labels: mockClientLabels,
+}));
+const mockGetClient = mock(() => ({
+  issue: mockClientIssue,
+  viewer: Promise.resolve({ id: "U1" }),
+  users: mock(async () => ({
+    nodes: [{ id: "U2", email: "bob@example.com" }],
+  })),
+}));
+const mockListIssues = mock(async () => [
+  {
+    id: "I1",
+    identifier: "ENG-1",
+    title: "test",
+    state: "Todo",
+    assignee: "alice",
+    priority: 3,
+  },
+  {
+    id: "I2",
+    identifier: "ENG-2",
+    title: "test2",
+    state: "Done",
+    assignee: "bob",
+    priority: 1,
+  },
+]);
+const mockPriorityFromString = mock((s: string) => (s === "high" ? 2 : 0));
+const mockGetTeamStates = mock(async () => [
+  { id: "S1", name: "Done" },
+  { id: "S2", name: "Todo" },
+]);
+const mockGetTeamLabels = mock(async () => [
+  { id: "L1", name: "bug" },
+  { id: "L2", name: "feature" },
+]);
+
+const mockOutputJson = mock((..._args: unknown[]) => {});
+const mockOutputQuiet = mock((..._args: unknown[]) => {});
+const mockOutputTable = mock((..._args: unknown[]) => {});
+const mockGetOutputFormat = mock(
+  (opts: { format?: string }) => opts?.format ?? "table"
+);
+
+mock.module("@bdsqqq/lnr-core", () => ({
+  getClient: mockGetClient,
+  getIssue: mockGetIssue,
+  updateIssue: mockUpdateIssue,
+  listIssues: mockListIssues,
+  createIssue: mock(async () => ({
+    id: "I3",
+    identifier: "ENG-3",
+    title: "new",
+  })),
+  archiveIssue: mock(async () => true),
+  findTeamByKeyOrName: mock(async () => ({ id: "T1", key: "ENG" })),
+  getAvailableTeamKeys: mock(async () => ["ENG"]),
+  getTeamLabels: mockGetTeamLabels,
+  resolveAssignee: mock(async () => "U2"),
+  priorityFromString: mockPriorityFromString,
+  resolveStateName: mock(async () => "S1"),
+  resolveIssueIdentifier: mock(async () => "I1"),
+  resolveProjectByName: mock(async () => "P1"),
+  resolveCycleByName: mock(async () => "C1"),
+  resolveMilestoneByName: mock(async () => "M1"),
+  createIssueRelation: mock(async () => true),
+  addComment: mock(async () => true),
+  updateComment: mock(async () => true),
+  replyToComment: mock(async () => true),
+  deleteComment: mock(async () => true),
+  createCommentReaction: mock(async () => true),
+  deleteReaction: mock(async () => true),
+  getIssueComments: mock(async () => ({ comments: [], error: null })),
+  getSubIssues: mock(async () => []),
+  getTeamStates: mockGetTeamStates,
+  subscribeToIssue: mock(async () => true),
+  unsubscribeFromIssue: mock(async () => true),
+  createReaction: mock(async () => true),
+  batchUpdateIssues: mock(async () => ({ success: true, issues: [] })),
+  getConfigValue: mock(() => undefined),
+  linkGitHubPR: mock(async () => true),
+}));
+
+mock.module("./output", () => ({
+  outputJson: mockOutputJson,
+  outputQuiet: mockOutputQuiet,
+  outputTable: mockOutputTable,
+  getOutputFormat: mockGetOutputFormat,
+  formatDate: (d: unknown) => (d ? "2026-01-01" : "-"),
+  formatPriority: (p: unknown) => String(p ?? "-"),
+  truncate: (s: string) => s,
+  formatRelativeTime: () => "1d ago",
+}));
+
+mock.module("./error", () => ({
+  handleApiError: mock((e: unknown) => {
+    throw e;
+  }),
+  exitWithError: mock((msg: string) => {
+    throw new Error(msg);
+  }),
+  EXIT_CODES: { SUCCESS: 0, GENERAL_ERROR: 1, AUTH_ERROR: 2, NOT_FOUND: 3, RATE_LIMITED: 4, PLAN_REQUIRED: 5 },
+}));
+
+mock.module("./renderers/comments", () => ({
+  outputCommentThreads: mock(() => {}),
+  shortcodeToEmoji: mock((s: string) => s),
+  formatReactions: mock(() => ""),
+  wrapText: mock((s: string) => [s]),
+  buildChildMap: mock(() => new Map()),
+}));
+
+mock.module("./renderers/detail", () => ({
+  outputDetail: mock(() => {}),
+}));
+
+mock.module("./adapters", () => ({
+  issueToDetail: mock(() => ({})),
+}));
+
+mock.module("../../hand-crafted/issue", () => ({
+  handlePr: mock(async () => {}),
+}));
+
+mock.module("./arktype-config", () => ({}));
+
+const { generatedIssuesRouter } = await import("../generated/issue");
+
+function resetAll() {
+  mockUpdateIssue.mockClear();
+  mockGetIssue.mockClear();
+  mockGetClient.mockClear();
+  mockClientIssue.mockClear();
+  mockListIssues.mockClear();
+  mockPriorityFromString.mockClear();
+  mockGetTeamStates.mockClear();
+  mockGetTeamLabels.mockClear();
+  mockOutputJson.mockClear();
+  mockOutputQuiet.mockClear();
+  mockOutputTable.mockClear();
+  mockGetOutputFormat.mockClear();
+}
+
+describe("property D: flag → payload effect (issue update)", () => {
+  beforeEach(resetAll);
+
+  test("--title sets title in updateIssue payload", async () => {
+    const caller = generatedIssuesRouter.createCaller({});
+    await caller.issue({ idOrNew: "ENG-1", title: "new title" });
+
+    expect(mockUpdateIssue).toHaveBeenCalled();
+    const payload = (mockUpdateIssue.mock.calls[0] as unknown as unknown[])[2] as Record<string, unknown>;
+    expect(payload.title).toBe("new title");
+  });
+
+  test("--description sets description in updateIssue payload", async () => {
+    const caller = generatedIssuesRouter.createCaller({});
+    await caller.issue({ idOrNew: "ENG-1", description: "some desc" });
+
+    expect(mockUpdateIssue).toHaveBeenCalled();
+    const payload = (mockUpdateIssue.mock.calls[0] as unknown as unknown[])[2] as Record<string, unknown>;
+    expect(payload.description).toBe("some desc");
+  });
+
+  test("--priority passes numeric priority to updateIssue", async () => {
+    const caller = generatedIssuesRouter.createCaller({});
+    await caller.issue({ idOrNew: "ENG-1", priority: "high" });
+
+    expect(mockUpdateIssue).toHaveBeenCalled();
+    const payload = (mockUpdateIssue.mock.calls[0] as unknown as unknown[])[2] as Record<string, unknown>;
+    expect(payload.priority).toBe(2);
+  });
+
+  test("--state resolves to stateId in updateIssue payload", async () => {
+    const caller = generatedIssuesRouter.createCaller({});
+    await caller.issue({ idOrNew: "ENG-1", state: "Done" });
+
+    expect(mockUpdateIssue).toHaveBeenCalled();
+    const payload = (mockUpdateIssue.mock.calls[0] as unknown as unknown[])[2] as Record<string, unknown>;
+    expect(payload.stateId).toBe("S1");
+  });
+});
+
+describe("property E: resolver call discipline (issue update)", () => {
+  beforeEach(resetAll);
+
+  test("--state calls getTeamStates, not getTeamLabels", async () => {
+    const caller = generatedIssuesRouter.createCaller({});
+    await caller.issue({ idOrNew: "ENG-1", state: "Done" });
+
+    expect(mockGetTeamStates).toHaveBeenCalled();
+    expect(mockGetTeamLabels).not.toHaveBeenCalled();
+  });
+
+  test("--label calls getTeamLabels, not getTeamStates", async () => {
+    const caller = generatedIssuesRouter.createCaller({});
+    await caller.issue({ idOrNew: "ENG-1", label: "bug" });
+
+    expect(mockGetTeamLabels).toHaveBeenCalled();
+    expect(mockGetTeamStates).not.toHaveBeenCalled();
+  });
+
+  test("--priority calls priorityFromString, not getTeamStates", async () => {
+    const caller = generatedIssuesRouter.createCaller({});
+    await caller.issue({ idOrNew: "ENG-1", priority: "high" });
+
+    expect(mockPriorityFromString).toHaveBeenCalledWith("high");
+    expect(mockGetTeamStates).not.toHaveBeenCalled();
+    expect(mockGetTeamLabels).not.toHaveBeenCalled();
+  });
+
+  test("no mutation flags → read path, no resolvers called", async () => {
+    const caller = generatedIssuesRouter.createCaller({});
+    await caller.issue({ idOrNew: "ENG-1" });
+
+    expect(mockUpdateIssue).not.toHaveBeenCalled();
+    expect(mockGetTeamStates).not.toHaveBeenCalled();
+    expect(mockGetTeamLabels).not.toHaveBeenCalled();
+    expect(mockPriorityFromString).not.toHaveBeenCalled();
+  });
+});
+
+describe("property F: output-format equivalence (issue list)", () => {
+  beforeEach(resetAll);
+
+  test("json/quiet/table all receive same entity count", async () => {
+    const caller = generatedIssuesRouter.createCaller({});
+
+    await caller.issues({ json: true });
+    const jsonEntities = mockOutputJson.mock.calls[0]?.[0] as unknown[];
+
+    await caller.issues({ quiet: true });
+    const quietIds = mockOutputQuiet.mock.calls[0]?.[0] as string[];
+
+    await caller.issues({});
+    const tableEntities = mockOutputTable.mock.calls[0]?.[0] as unknown[];
+
+    expect(jsonEntities.length).toBe(2);
+    expect(quietIds.length).toBe(2);
+    expect(tableEntities.length).toBe(2);
+  });
+
+  test("json and table receive identical entity set", async () => {
+    const caller = generatedIssuesRouter.createCaller({});
+
+    await caller.issues({ json: true });
+    const jsonEntities = mockOutputJson.mock.calls[0]?.[0] as {
+      identifier: string;
+    }[];
+
+    mockOutputTable.mockClear();
+    await caller.issues({});
+    const tableEntities = mockOutputTable.mock.calls[0]?.[0] as {
+      identifier: string;
+    }[];
+
+    expect(jsonEntities.map((e) => e.identifier)).toEqual(
+      tableEntities.map((e) => e.identifier)
+    );
+  });
+
+  test("quiet receives identifiers matching json entities", async () => {
+    const caller = generatedIssuesRouter.createCaller({});
+
+    await caller.issues({ json: true });
+    const jsonEntities = mockOutputJson.mock.calls[0]?.[0] as {
+      identifier: string;
+    }[];
+
+    mockOutputQuiet.mockClear();
+    await caller.issues({ quiet: true });
+    const quietIds = mockOutputQuiet.mock.calls[0]?.[0] as string[];
+
+    expect(quietIds).toEqual(jsonEntities.map((e) => e.identifier));
+  });
+});