@greeana/jira-dev-workflow 0.1.0

package/src/prepare-commit.ts

@@ -0,0 +1,197 @@
+import { loadToolEnv, loadWorkflowConfig, readEnv } from "./config";
+import { formatCommitMessage } from "./commit-message";
+import { getDiffContext } from "./git";
+import { searchIssuesForText } from "./issue-search";
+import { createJiraClient } from "./jira-client";
+import { buildIssueDescriptionDraft, buildIssueSummaryDraft } from "./prepare-commit-draft";
+
+type CliOptions = {
+  configPath?: string;
+  envFilePath?: string;
+  json: boolean;
+  limit?: number;
+  projectKeyOverride?: string;
+  staged: boolean;
+};
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  await loadToolEnv(options.envFilePath);
+  const config = await loadWorkflowConfig(options.configPath);
+  const projectKey = options.projectKeyOverride ?? config.projectKey ?? readEnv("JIRA_PROJECT_KEY");
+
+  if (!projectKey) {
+    throw new Error("Set projectKey in .jira-dev-workflow/config.json or pass --project-key.");
+  }
+
+  const diffContext = await getDiffContext({ staged: options.staged });
+  const jira = createJiraClient();
+  const searchLimit = options.limit ?? config.searchLimit;
+  const searchResult = await searchIssuesForText({
+    jira,
+    limit: searchLimit,
+    projectKey,
+    searchText: diffContext.combinedText,
+  });
+
+  const issueSummaryDraft = buildIssueSummaryDraft({
+    changedFiles: diffContext.changedFiles,
+    openMatches: searchResult.openMatches,
+    patchHighlights: diffContext.patchHighlights,
+  });
+  const issueDescriptionDraft = buildIssueDescriptionDraft({
+    changedFiles: diffContext.changedFiles,
+    patchHighlights: diffContext.patchHighlights,
+  });
+
+  const reuseOpenCommitMessageDraft = searchResult.recommendedOpenIssueKey
+    ? formatCommitMessage(
+        config.commitMessageFormat,
+        searchResult.recommendedOpenIssueKey,
+        searchResult.openMatches[0]?.summary || issueSummaryDraft,
+      )
+    : null;
+
+  const createNewCommitMessageDraft = formatCommitMessage(config.commitMessageFormat, "<new-issue-key>", issueSummaryDraft);
+
+  const response = {
+    changedFiles: diffContext.changedFiles,
+    closedMatches: searchResult.closedMatches,
+    commitMessageDrafts: {
+      createNew: createNewCommitMessageDraft,
+      reuseOpen: reuseOpenCommitMessageDraft,
+    },
+    issueDraft: {
+      description: issueDescriptionDraft,
+      relatedClosedIssueKey: searchResult.recommendedClosedIssueKey,
+      summary: issueSummaryDraft,
+    },
+    openMatches: searchResult.openMatches,
+    projectKey,
+    recommendedAction: searchResult.recommendedAction,
+    recommendedClosedIssueKey: searchResult.recommendedClosedIssueKey,
+    recommendedOpenIssueKey: searchResult.recommendedOpenIssueKey,
+    searchTextPreview: diffContext.combinedText.split(/\r?\n/).slice(0, 20),
+    staged: options.staged,
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(response, null, 2));
+    return;
+  }
+
+  console.log(`Prepared commit plan for project ${projectKey}.`);
+  console.log(`Mode: ${options.staged ? "staged changes" : "working tree changes"}`);
+  console.log("");
+  console.log("Changed files:");
+
+  for (const filePath of diffContext.changedFiles) {
+    console.log(`- ${filePath}`);
+  }
+
+  console.log("");
+  console.log(`Recommended action: ${response.recommendedAction}`);
+
+  if (response.openMatches.length > 0) {
+    console.log("");
+    console.log("Open issue candidates:");
+
+    for (const match of response.openMatches) {
+      console.log(`- ${match.issueKey} [score ${match.score}] ${match.summary}`);
+    }
+  }
+
+  if (response.closedMatches.length > 0) {
+    console.log("");
+    console.log("Closed related issues:");
+
+    for (const match of response.closedMatches) {
+      console.log(`- ${match.issueKey} [score ${match.score}] ${match.summary}`);
+    }
+  }
+
+  console.log("");
+  console.log("New issue draft:");
+  console.log(`Summary: ${issueSummaryDraft}`);
+  console.log("Description:");
+  console.log(issueDescriptionDraft);
+
+  console.log("");
+  console.log("Commit message previews:");
+
+  if (reuseOpenCommitMessageDraft) {
+    console.log(`- reuse ${searchResult.recommendedOpenIssueKey}: ${reuseOpenCommitMessageDraft}`);
+  }
+
+  console.log(`- create new: ${createNewCommitMessageDraft}`);
+}
+
+function parseArgs(args: string[]): CliOptions {
+  const options: CliOptions = {
+    json: false,
+    staged: true,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (!arg) {
+      continue;
+    }
+
+    if (arg === "--config") {
+      options.configPath = requireNextValue(args, ++index, "--config");
+      continue;
+    }
+
+    if (arg === "--env-file") {
+      options.envFilePath = requireNextValue(args, ++index, "--env-file");
+      continue;
+    }
+
+    if (arg === "--json") {
+      options.json = true;
+      continue;
+    }
+
+    if (arg === "--limit") {
+      options.limit = Number.parseInt(requireNextValue(args, ++index, "--limit"), 10);
+      continue;
+    }
+
+    if (arg === "--project-key") {
+      options.projectKeyOverride = requireNextValue(args, ++index, "--project-key");
+      continue;
+    }
+
+    if (arg === "--working-tree") {
+      options.staged = false;
+      continue;
+    }
+
+    if (arg === "--staged") {
+      options.staged = true;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return options;
+}
+
+function requireNextValue(args: string[], index: number, flagName: string): string {
+  const value = args[index];
+
+  if (!value) {
+    throw new Error(`Missing value for ${flagName}.`);
+  }
+
+  return value;
+}
+
+void main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exitCode = 1;
+});

package/src/show-current-issue.ts

@@ -0,0 +1,66 @@
+import { loadWorkflowConfig } from "./config";
+import { loadCurrentIssueState } from "./state";
+
+type CliOptions = {
+  configPath?: string;
+  json: boolean;
+};
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const config = await loadWorkflowConfig(options.configPath);
+  const state = await loadCurrentIssueState(config);
+
+  if (!state) {
+    throw new Error("No current issue is stored.");
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(state, null, 2));
+    return;
+  }
+
+  console.log(`${state.issueKey}: ${state.summary ?? "(no summary stored)"}`);
+
+  if (state.url) {
+    console.log(state.url);
+  }
+}
+
+function parseArgs(args: string[]): CliOptions {
+  const options: CliOptions = { json: false };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--config") {
+      options.configPath = requireNextValue(args, ++index, "--config");
+      continue;
+    }
+
+    if (arg === "--json") {
+      options.json = true;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return options;
+}
+
+function requireNextValue(args: string[], index: number, flagName: string): string {
+  const value = args[index];
+
+  if (!value) {
+    throw new Error(`Missing value for ${flagName}.`);
+  }
+
+  return value;
+}
+
+void main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exitCode = 1;
+});

package/src/state.ts

@@ -0,0 +1,36 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import type { WorkflowConfig } from "./config";
+import { resolveStateFilePath } from "./config";
+
+export type CurrentIssueState = {
+  issueKey: string;
+  summary?: string;
+  url?: string;
+};
+
+export async function loadCurrentIssueState(config: WorkflowConfig): Promise<CurrentIssueState | null> {
+  const filePath = resolveStateFilePath(config);
+
+  try {
+    const content = await fs.readFile(filePath, "utf8");
+    return JSON.parse(content) as CurrentIssueState;
+  } catch (error) {
+    if (isFileMissingError(error)) {
+      return null;
+    }
+
+    throw error;
+  }
+}
+
+export async function saveCurrentIssueState(config: WorkflowConfig, state: CurrentIssueState) {
+  const filePath = resolveStateFilePath(config);
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+function isFileMissingError(error: unknown): error is NodeJS.ErrnoException {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}

package/src/test-connection.ts

@@ -0,0 +1,107 @@
+import { loadToolEnv, loadWorkflowConfig, readEnv } from "./config";
+import { createJiraClient } from "./jira-client";
+
+type CliOptions = {
+  configPath?: string;
+  envFilePath?: string;
+  projectKeyOverride?: string;
+};
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  await loadToolEnv(options.envFilePath);
+  const config = await loadWorkflowConfig(options.configPath);
+
+  const projectKey = options.projectKeyOverride ?? config.projectKey ?? readEnv("JIRA_PROJECT_KEY");
+
+  if (!projectKey) {
+    throw new Error("Set projectKey in .jira-dev-workflow/config.json or pass --project-key.");
+  }
+
+  const jira = createJiraClient();
+  const user = await jira.getCurrentUser();
+
+  console.log("Authenticated user:");
+  console.log(`- display name: ${user.displayName ?? "(unknown)"}`);
+  console.log(`- email: ${user.emailAddress ?? "(hidden by Atlassian privacy settings)"}`);
+  console.log(`- account id: ${user.accountId ?? "(unknown)"}`);
+
+  const project = await jira.getProject(projectKey);
+
+  console.log("");
+  console.log("Project access:");
+  console.log(`- key: ${project.key}`);
+  console.log(`- name: ${project.name}`);
+  console.log(`- id: ${project.id}`);
+  console.log(`- type: ${project.projectTypeKey ?? "(unknown)"}`);
+  console.log(`- style: ${project.style ?? "(unknown)"}`);
+
+  const permissions = await jira.getMyPermissions(project.key, ["BROWSE_PROJECTS", "CREATE_ISSUES"]);
+  const browseProjects = permissions.permissions?.BROWSE_PROJECTS?.havePermission ?? false;
+  const createIssues = permissions.permissions?.CREATE_ISSUES?.havePermission ?? false;
+
+  console.log("");
+  console.log("Project permissions:");
+  console.log(`- browse project: ${browseProjects ? "yes" : "no"}`);
+  console.log(`- create issues: ${createIssues ? "yes" : "no"}`);
+
+  if (!browseProjects || !createIssues) {
+    throw new Error(
+      `Jira connection works, but project permissions are insufficient for issue creation. browse=${browseProjects} createIssues=${createIssues}`,
+    );
+  }
+
+  console.log("");
+  console.log(`Connection OK. Ready to work in project ${project.key}.`);
+}
+
+function parseArgs(args: string[]): CliOptions {
+  const options: CliOptions = {};
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (!arg) {
+      continue;
+    }
+
+    if (arg === "--config") {
+      options.configPath = requireNextValue(args, ++index, "--config");
+      continue;
+    }
+
+    if (arg === "--env-file") {
+      options.envFilePath = requireNextValue(args, ++index, "--env-file");
+      continue;
+    }
+
+    if (arg === "--project-key") {
+      options.projectKeyOverride = requireNextValue(args, ++index, "--project-key");
+      continue;
+    }
+
+    if (arg.startsWith("--")) {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+
+    options.projectKeyOverride = arg;
+  }
+
+  return options;
+}
+
+function requireNextValue(args: string[], index: number, flagName: string): string {
+  const value = args[index];
+
+  if (!value) {
+    throw new Error(`Missing value for ${flagName}.`);
+  }
+
+  return value;
+}
+
+void main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exitCode = 1;
+});

package/src/use-issue.ts

@@ -0,0 +1,84 @@
+import { loadToolEnv, loadWorkflowConfig } from "./config";
+import { createJiraClient, getIssueSummary } from "./jira-client";
+import { saveCurrentIssueState } from "./state";
+
+type CliOptions = {
+  configPath?: string;
+  envFilePath?: string;
+  issueKey?: string;
+};
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  await loadToolEnv(options.envFilePath);
+  const config = await loadWorkflowConfig(options.configPath);
+  const issueKey = options.issueKey?.trim();
+
+  if (!issueKey) {
+    throw new Error("Pass --issue.");
+  }
+
+  const jira = createJiraClient();
+  const issue = await jira.getIssue(issueKey);
+  const summary = getIssueSummary(issue);
+  const url = jira.getIssueBrowseUrl(issueKey);
+
+  await saveCurrentIssueState(config, {
+    issueKey,
+    summary,
+    url,
+  });
+
+  console.log(`Selected current issue ${issueKey}: ${summary}`);
+}
+
+function parseArgs(args: string[]): CliOptions {
+  const options: CliOptions = {};
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (!arg) {
+      continue;
+    }
+
+    if (arg === "--config") {
+      options.configPath = requireNextValue(args, ++index, "--config");
+      continue;
+    }
+
+    if (arg === "--env-file") {
+      options.envFilePath = requireNextValue(args, ++index, "--env-file");
+      continue;
+    }
+
+    if (arg === "--issue") {
+      options.issueKey = requireNextValue(args, ++index, "--issue");
+      continue;
+    }
+
+    if (arg.startsWith("--")) {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+
+    options.issueKey = arg;
+  }
+
+  return options;
+}
+
+function requireNextValue(args: string[], index: number, flagName: string): string {
+  const value = args[index];
+
+  if (!value) {
+    throw new Error(`Missing value for ${flagName}.`);
+  }
+
+  return value;
+}
+
+void main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exitCode = 1;
+});

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "src/**/*.ts",
+    "tests/**/*.ts"
+  ]
+}