@greeana/jira-dev-workflow 0.1.0

package/README.md

@@ -0,0 +1,293 @@
+# @greeana/jira-dev-workflow
+
+Publishable npm CLI plus Codex skill template for Jira-backed development workflows.
+
+## What it does
+
+- find matching Jira issues for a diff or free text
+- reuse open issues and avoid reusing closed ones
+- create a new issue when no suitable open issue exists
+- prepare commit plans from staged or working-tree changes
+- save the selected Jira issue locally for later commands
+- post implementation comments, reports, and screenshots
+- create git commits with Jira key prefixes
+- import Jira issues from CSV
+
+## Package model
+
+This package is designed to be published as:
+
+```text
+@greeana/jira-dev-workflow
+```
+
+The included Codex skill calls the published CLI through `npx`, so consumers do not need to vendor the source code into each repo.
+
+## Consumer repo layout
+
+Each consumer repo keeps its own local workflow state and secrets under:
+
+```text
+.jira-dev-workflow/config.json
+.jira-dev-workflow/.env.local
+.jira-dev-workflow/state/current-issue.json
+```
+
+The CLI searches upward from the current working directory until it finds `.jira-dev-workflow/`.
+
+See the examples under [`examples/.jira-dev-workflow/`](./examples/.jira-dev-workflow/).
+
+Minimal config:
+
+```json
+{
+  "projectKey": "JDW",
+  "defaultIssueType": "Task",
+  "issueLinkType": "Relates",
+  "commitMessageFormat": "{issueKey} {message}",
+  "searchLimit": 5,
+  "reuseClosedAsRelatedLink": true,
+  "stateFile": "state/current-issue.json"
+}
+```
+
+Minimal env:
+
+```bash
+JIRA_BASE_URL=https://your-company.atlassian.net
+JIRA_EMAIL=your.name@company.com
+JIRA_API_TOKEN=your_jira_api_token
+```
+
+## Local development
+
+```bash
+npm install
+npm test
+node ./bin/jira-dev-workflow.mjs help
+```
+
+Bootstrap the current repo with the local skill and required workflow files:
+
+```bash
+npx -y @greeana/jira-dev-workflow install
+```
+
+Test the skill locally before any npm publish by generating a skill that calls this checkout directly:
+
+```bash
+node ./bin/jira-dev-workflow.mjs install --local
+```
+
+Generate a repo-local skill that keeps using the npm `preview` dist-tag:
+
+```bash
+npx -y @greeana/jira-dev-workflow@preview install --preview
+```
+
+Generate a repo-local skill pinned to an exact published version:
+
+```bash
+npx -y @greeana/jira-dev-workflow@0.1.0-preview.0 install --version 0.1.0-preview.0
+```
+
+This creates:
+
+```text
+.codex/skills/jira-dev-workflow/SKILL.md
+.jira-dev-workflow/config.json
+.jira-dev-workflow/.env.local
+```
+
+It also ensures `.gitignore` contains:
+
+```text
+.jira-dev-workflow/.env.local
+.jira-dev-workflow/state/
+```
+
+## Published CLI examples
+
+Show all commands:
+
+```bash
+npx -y @greeana/jira-dev-workflow help
+```
+
+Install into the current repo:
+
+```bash
+npx -y @greeana/jira-dev-workflow install
+```
+
+Install into the current repo and write the Jira project key up front:
+
+```bash
+npx -y @greeana/jira-dev-workflow install --project-key JDW
+```
+
+Install into the current repo and make the generated skill keep using the npm `preview` tag:
+
+```bash
+npx -y @greeana/jira-dev-workflow@preview install --preview
+```
+
+Install into the current repo and pin the generated skill to an exact published version:
+
+```bash
+npx -y @greeana/jira-dev-workflow@0.1.0-preview.0 install --version 0.1.0-preview.0
+```
+
+Install into the current repo and make the generated skill call a local checkout directly:
+
+```bash
+node /absolute/path/to/jira-dev-workflow/bin/jira-dev-workflow.mjs install --local
+```
+
+Test Jira access:
+
+```bash
+npx -y @greeana/jira-dev-workflow test
+```
+
+Prepare a commit plan from staged changes:
+
+```bash
+npx -y @greeana/jira-dev-workflow prepare-commit --json
+```
+
+Expected interactive flow for agents:
+
+1. User stages changes and asks to prepare a Jira commit.
+2. Agent runs `prepare-commit --json`.
+3. Agent shows matching open issues, or a drafted new issue if no open issue fits, and asks the user which path to take.
+4. Agent does not create an issue, commit, or post back to Jira yet.
+5. After the user selects an issue or approves a new one, the agent previews the final commit message with `commit --dry-run` and asks for confirmation.
+6. Only after explicit confirmation does the agent create the commit.
+7. Posting an implementation comment or attachments back to Jira is a separate confirmation step unless the user explicitly asked for that as part of the workflow.
+
+Prepare a commit plan from working-tree changes:
+
+```bash
+npx -y @greeana/jira-dev-workflow prepare-commit --working-tree --json
+```
+
+Search Jira directly:
+
+```bash
+npx -y @greeana/jira-dev-workflow find --text "qa agent isolation" --json
+```
+
+Create a new Jira issue:
+
+```bash
+npx -y @greeana/jira-dev-workflow create \
+  --summary "Improve QA agent isolation" \
+  --description-file /tmp/issue.md
+```
+
+Create a new Jira issue related to a closed one:
+
+```bash
+npx -y @greeana/jira-dev-workflow create \
+  --summary "Improve QA agent isolation" \
+  --description-file /tmp/issue.md \
+  --related-issue JDW-19
+```
+
+Save the selected issue for later commands:
+
+```bash
+npx -y @greeana/jira-dev-workflow use --issue JDW-23
+```
+
+Show the current saved issue:
+
+```bash
+npx -y @greeana/jira-dev-workflow current
+```
+
+Attach a screenshot or artifact:
+
+```bash
+npx -y @greeana/jira-dev-workflow attach --issue JDW-23 --file /absolute/path/to/screenshot.png
+```
+
+Add an implementation report comment:
+
+```bash
+npx -y @greeana/jira-dev-workflow comment \
+  --issue JDW-23 \
+  --text $'Implemented in:\nhttps://git.example.com/commit/abcdef'
+```
+
+Add a comment with inline screenshots:
+
+```bash
+npx -y @greeana/jira-dev-workflow comment \
+  --issue JDW-23 \
+  --text $'Implementation report:\n\nPrepared commit result:\n\n[[inline-file]]\n\nJira issue after preparation:\n\n[[inline-file]]' \
+  --inline-file /absolute/path/to/screenshot-1.png \
+  --inline-file /absolute/path/to/screenshot-2.png
+```
+
+Inline screenshot placement rules:
+
+- `[[inline-file]]` inserts the next inline screenshot in order.
+- `[[inline-file:2]]` inserts a specific inline screenshot by 1-based index.
+- Place placeholders as their own paragraphs to position screenshots between report sections.
+- If you pass inline screenshots without placeholders, they are appended after the text for backward compatibility.
+
+Preview the final commit message:
+
+```bash
+npx -y @greeana/jira-dev-workflow commit --issue JDW-23 -m "Improve QA agent isolation" --dry-run
+```
+
+Create the git commit:
+
+```bash
+npx -y @greeana/jira-dev-workflow commit --issue JDW-23 -m "Improve QA agent isolation"
+```
+
+Import issues from CSV:
+
+```bash
+npx -y @greeana/jira-dev-workflow import --file .jira-dev-workflow/import.csv
+```
+
+## Codex skill
+
+The portable skill template lives in:
+
+```text
+skill/jira-dev-workflow/SKILL.md
+```
+
+Install it into either:
+
+```text
+~/.codex/skills/jira-dev-workflow/
+```
+
+or:
+
+```text
+.codex/skills/jira-dev-workflow/
+```
+
+The skill assumes the published package name is `@greeana/jira-dev-workflow`. If you publish under a different scope or package name, update the `npx` commands in the skill file.
+
+## Release checklist
+
+1. Update `version` in `package.json`.
+2. Run `npm test`.
+3. Run `npm pack --dry-run` and confirm only the intended files are included.
+4. Confirm `skill/jira-dev-workflow/SKILL.md` still points to `npx -y @greeana/jira-dev-workflow`.
+5. Publish with `npm publish --access public`.
+6. Smoke-test the published package:
+
+```bash
+npx -y @greeana/jira-dev-workflow help
+npx -y @greeana/jira-dev-workflow test
+```

package/bin/jira-dev-workflow.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageDir = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const commandMap = new Map([
+  ["unit", "tests"],
+  ["install", "src/install.ts"],
+  ["test", "src/test-connection.ts"],
+  ["prepare-commit", "src/prepare-commit.ts"],
+  ["find", "src/find-issue.ts"],
+  ["create", "src/create-issue.ts"],
+  ["comment", "src/add-comment.ts"],
+  ["attach", "src/attach-file.ts"],
+  ["use", "src/use-issue.ts"],
+  ["current", "src/show-current-issue.ts"],
+  ["commit", "src/commit-with-issue.ts"],
+  ["import", "src/import-issues.ts"],
+]);
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    showGeneralHelp();
+    process.exitCode = 1;
+    return;
+  }
+
+  const [commandName, ...commandArgs] = args;
+
+  if (!commandName) {
+    showGeneralHelp();
+    process.exitCode = 1;
+    return;
+  }
+
+  if (commandName === "help" || commandName === "-h" || commandName === "--help") {
+    showCommandHelp(commandArgs[0]);
+    return;
+  }
+
+  if (!commandMap.has(commandName)) {
+    console.error(`Unknown jira-dev-workflow command: ${commandName}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (commandArgs[0] === "--help" || commandArgs[0] === "-h") {
+    showCommandHelp(commandName);
+    return;
+  }
+
+  runCommand(commandName, commandArgs);
+}
+
+function runCommand(commandName, commandArgs) {
+  if (commandName === "unit") {
+    const result = spawnSync(process.execPath, ["--import", "tsx", "--test", "tests/**/*.test.ts", ...commandArgs], {
+      cwd: packageDir,
+      stdio: "inherit",
+    });
+    process.exitCode = result.status ?? 1;
+    return;
+  }
+
+  const entry = commandMap.get(commandName);
+
+  if (!entry || entry === "tests") {
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = spawnSync(process.execPath, ["--import", "tsx", entry, ...commandArgs], {
+    cwd: packageDir,
+    stdio: "inherit",
+  });
+
+  process.exitCode = result.status ?? 1;
+}
+
+function showGeneralHelp() {
+  console.log(`Usage: jira-dev-workflow <command> [args...]
+
+Commands:
+  help            Show all commands
+  unit            Run package-local tests
+  install         Scaffold repo-local config and Codex skill
+  test            Check Jira auth and project permissions
+  prepare-commit  Build a staged-diff Jira + commit plan
+  find            Search Jira issues by text or diff
+  create          Create a Jira issue
+  comment         Add a comment to a Jira issue
+  attach          Attach a local file to a Jira issue
+  use             Save the current Jira issue locally
+  current         Show the saved current Jira issue
+  commit          Preview or create a git commit with Jira key
+  import          Import issues from a CSV file
+
+Use:
+  jira-dev-workflow help <command>
+  jira-dev-workflow <command> --help`);
+}
+
+function showCommandHelp(commandName) {
+  switch (commandName) {
+    case undefined:
+    case "":
+    case "help":
+      showGeneralHelp();
+      return;
+    case "unit":
+      console.log(`Usage:
+  jira-dev-workflow unit
+
+Description:
+  Run package-local tests for the Jira workflow CLI.`);
+      return;
+    case "install":
+      console.log(`Usage:
+  jira-dev-workflow install [--project-key KEY] [--local | --preview | --version VERSION] [--force] [--json]
+
+Description:
+  Scaffold the current repo with .jira-dev-workflow config, a repo-local Codex skill,
+  and recommended .gitignore entries.
+
+Parameters:
+  --project-key KEY  Optionally write the Jira project key into the generated config
+  --local            Make the generated skill call this local checkout directly
+  --preview          Make the generated skill call the npm preview dist-tag
+  --version VERSION  Make the generated skill call an exact npm package version
+  --force            Overwrite existing managed files
+  --json             Print the created/updated paths as JSON`);
+      return;
+    case "test":
+      console.log(`Usage:
+  jira-dev-workflow test [--project-key KEY] [--env-file PATH] [--config PATH]
+
+Description:
+  Validate Jira authentication, project visibility, and CREATE_ISSUES permission.
+
+Parameters:
+  --project-key KEY  Override the configured Jira project key
+  --env-file PATH    Load credentials from a different env file
+  --config PATH      Load a different .jira-dev-workflow/config.json file`);
+      return;
+    case "prepare-commit":
+      console.log(`Usage:
+  jira-dev-workflow prepare-commit [--json] [--working-tree|--staged] [--limit N] [--project-key KEY] [--env-file PATH] [--config PATH]
+
+Description:
+  Build a non-destructive commit plan from the current diff. It returns Jira matches,
+  a new issue draft, and commit-message previews.`);
+      return;
+    case "find":
+      console.log(`Usage:
+  jira-dev-workflow find (--text TEXT | --from-diff) [--json] [--working-tree|--staged] [--limit N] [--project-key KEY] [--env-file PATH] [--config PATH]
+
+Description:
+  Search Jira for matching issues by explicit text or by text extracted from the git diff.
+  Closed issues are not reused; they are returned only as related references.`);
+      return;
+    case "create":
+      console.log(`Usage:
+  jira-dev-workflow create --summary TEXT [--description TEXT | --description-file PATH] [--related-issue KEY ...] [--issue-type NAME] [--project-key KEY] [--label NAME ...] [--json] [--no-save] [--env-file PATH] [--config PATH]
+
+Description:
+  Create a new Jira issue and optionally relate it to one or more existing issues.`);
+      return;
+    case "comment":
+      console.log(`Usage:
+  jira-dev-workflow comment [--issue KEY] [--file PATH ...] [--inline-file PATH ...] [--text TEXT | --text-file PATH] [--json] [--env-file PATH] [--config PATH]
+
+Description:
+  Add a Jira comment. Files are attached; inline files are embedded in the comment using
+  the attachment redirect workaround. To place inline images between text sections,
+  put placeholder paragraphs such as [[inline-file]] or [[inline-file:2]] inside the
+  comment text or text file.`);
+      return;
+    case "attach":
+      console.log(`Usage:
+  jira-dev-workflow attach [--issue KEY] --file PATH [--file PATH ...] [--env-file PATH] [--config PATH]
+
+Description:
+  Attach one or more local files to a Jira issue.`);
+      return;
+    case "use":
+      console.log(`Usage:
+  jira-dev-workflow use --issue KEY [--env-file PATH] [--config PATH]
+
+Description:
+  Save an existing Jira issue as the current issue for later commands.`);
+      return;
+    case "current":
+      console.log(`Usage:
+  jira-dev-workflow current [--json] [--config PATH]
+
+Description:
+  Show the locally saved current Jira issue.`);
+      return;
+    case "commit":
+      console.log(`Usage:
+  jira-dev-workflow commit [-m TEXT | --message TEXT] [--issue KEY] [--dry-run] [--config PATH]
+
+Description:
+  Preview or create a git commit prefixed with the Jira issue key.`);
+      return;
+    case "import":
+      console.log(`Usage:
+  jira-dev-workflow import [--file PATH] [--dry-run] [--continue-on-error] [--limit N] [--project-key KEY] [--issue-type NAME] [--env-file PATH] [--config PATH]
+
+Description:
+  Import issues from a CSV file into Jira.`);
+      return;
+    default:
+      console.error(`Unknown jira-dev-workflow command: ${commandName}`);
+      process.exitCode = 1;
+  }
+}
+
+main();

package/examples/.jira-dev-workflow/.env.example

@@ -0,0 +1,3 @@
+JIRA_BASE_URL=https://your-company.atlassian.net
+JIRA_EMAIL=your.name@company.com
+JIRA_API_TOKEN=your_jira_api_token

package/examples/.jira-dev-workflow/config.json

@@ -0,0 +1,9 @@
+{
+  "projectKey": "JDW",
+  "defaultIssueType": "Task",
+  "issueLinkType": "Relates",
+  "commitMessageFormat": "{issueKey} {message}",
+  "searchLimit": 5,
+  "reuseClosedAsRelatedLink": true,
+  "stateFile": "state/current-issue.json"
+}

package/examples/.jira-dev-workflow/import.csv

@@ -0,0 +1,3 @@
+Project Key,Issue Type,Summary,Description,Comment
+JDW,Task,Example issue,"Example long description","Implemented in:
+https://example.com/commit/123"

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@greeana/jira-dev-workflow",
+  "version": "0.1.0",
+  "description": "CLI for Jira-backed development workflows: issue search/create, commit preparation, implementation comments, and imports.",
+  "type": "module",
+  "bin": {
+    "jira-dev-workflow": "./bin/jira-dev-workflow.mjs"
+  },
+  "files": [
+    "bin",
+    "examples",
+    "src",
+    "skill",
+    "README.md",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "test": "node --import tsx --test tests/**/*.test.ts",
+    "install-workflow": "node --import tsx src/install.ts",
+    "test-connection": "node --import tsx src/test-connection.ts",
+    "find": "node --import tsx src/find-issue.ts",
+    "prepare-commit": "node --import tsx src/prepare-commit.ts",
+    "create": "node --import tsx src/create-issue.ts",
+    "comment": "node --import tsx src/add-comment.ts",
+    "attach": "node --import tsx src/attach-file.ts",
+    "use-issue": "node --import tsx src/use-issue.ts",
+    "show-current": "node --import tsx src/show-current-issue.ts",
+    "commit": "node --import tsx src/commit-with-issue.ts",
+    "import-issues": "node --import tsx src/import-issues.ts",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "jira",
+    "codex",
+    "workflow",
+    "cli",
+    "commit"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "tsx": "^4.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.3"
+  }
+}

package/skill/jira-dev-workflow/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: jira-dev-workflow
+description: Use when the user wants to find or create Jira issues for code changes, prepare Jira-linked commits, add implementation reports or screenshots to Jira, or import Jira issues from CSV. This skill orchestrates the published @greeana/jira-dev-workflow CLI through npx, prefers reusing open issues, and when only closed issues match it creates a new issue linked to the closed match.
+---
+
+# Jira Dev Workflow
+
+Use this skill for Jira-aware development workflows.
+
+## Package
+
+This skill expects the published npm CLI to be available through:
+
+`npx -y @greeana/jira-dev-workflow`
+
+If you publish under a different package name or npm scope, update the commands in this file.
+
+## Atomic commands
+
+- `npx -y @greeana/jira-dev-workflow test`
+  Check Jira auth, project access, and issue-creation permission.
+- `npx -y @greeana/jira-dev-workflow prepare-commit --json`
+  Build a commit plan from the current diff: open matches, closed matches, issue draft, and commit-message drafts.
+- `npx -y @greeana/jira-dev-workflow find --text "..." --json`
+  Search Jira directly by text or diff and return ranked issue candidates.
+- `npx -y @greeana/jira-dev-workflow create --summary "..." --description-file <file>`
+  Create a new Jira issue. Add `--related-issue JDW-123` to link a closed related issue.
+- `npx -y @greeana/jira-dev-workflow comment --issue JDW-123 --text "..."`
+  Add a Jira comment, optionally with `--file` attachments or inline screenshots via `--inline-file`.
+- `npx -y @greeana/jira-dev-workflow use --issue JDW-123`
+  Save the selected Jira issue as the current issue for later commands.
+- `npx -y @greeana/jira-dev-workflow current`
+  Show the saved current issue.
+- `npx -y @greeana/jira-dev-workflow attach --issue JDW-123 --file <path>`
+  Attach a local file such as a screenshot to a Jira issue.
+- `npx -y @greeana/jira-dev-workflow commit --issue JDW-123 -m "Short message" --dry-run`
+  Preview the final commit message with Jira key prefixing.
+- `npx -y @greeana/jira-dev-workflow commit --issue JDW-123 -m "Short message"`
+  Create the git commit.
+- `npx -y @greeana/jira-dev-workflow import --file .jira-dev-workflow/import.csv`
+  Import issues from a CSV file.
+
+## Default flow
+
+1. Run `npx -y @greeana/jira-dev-workflow test` if Jira connectivity or permissions are uncertain.
+2. For a commit workflow, start with:
+
+```bash
+npx -y @greeana/jira-dev-workflow prepare-commit --json
+```
+
+3. Use the `openMatches`, `closedMatches`, `issueDraft`, and `commitMessageDrafts` fields to ask the user which issue to use.
+4. If a strong open issue exists and the user picks it, reuse it:
+
+```bash
+npx -y @greeana/jira-dev-workflow use --issue JDW-123
+```
+
+5. If there are no open matches and only closed matches exist, create a new issue and pass the best closed match as `--related-issue`.
+6. If UI or preview evidence is useful, attach screenshots or add an implementation report comment.
+7. Preview the commit message with:
+
+```bash
+npx -y @greeana/jira-dev-workflow commit --issue JDW-123 -m "Short commit message" --dry-run
+```
+
+8. After the user confirms, commit with:
+
+```bash
+npx -y @greeana/jira-dev-workflow commit -m "Short commit message"
+```
+
+## Interaction contract for `prepare commit`
+
+When the user asks to prepare a Jira commit, the agent must treat `prepare-commit` as a planning step, not an execution step.
+
+1. Assume the user has already staged the intended files unless they say otherwise.
+2. Run `npx -y @greeana/jira-dev-workflow prepare-commit --json`.
+3. If `openMatches` contains candidates, present them and ask the user which issue to use, or whether to create a new one instead.
+4. If there are no reusable open matches, present the drafted new-issue summary and description and ask the user whether to create that issue.
+5. Do not create a Jira issue, do not save a current issue, do not commit, and do not post comments while still in the `prepare commit` step.
+6. After the user selects an issue or approves creating a new one, preview the final commit message with `commit --dry-run` and ask for confirmation.
+7. Only create the git commit after explicit user confirmation.
+8. Only post an implementation comment or attach files after the user explicitly asks for that, or clearly confirms a workflow that includes posting after commit.
+
+The intended conversation shape is:
+- User stages changes and asks to prepare a Jira commit.
+- Agent runs `prepare-commit`, shows candidate issues or a new-issue draft, and asks the user to choose.
+- User selects an existing issue or approves creating a new one.
+- Agent shows the final commit message preview and asks for confirmation.
+- User confirms.
+- Agent commits, and only then posts back to Jira if the user asked for posting.
+
+## Important rules
+
+- Do not reuse closed Jira issues.
+- If only closed issues match, create a new issue and relate it to the best closed match.
+- Prefer `npx -y @greeana/jira-dev-workflow prepare-commit --json` for commit workflows because it includes both Jira matches and draft commit text.
+- Use `npx -y @greeana/jira-dev-workflow current` if you need to confirm the selected issue before commit.
+- For commit messages, keep the human part short because the Jira key is prefixed automatically by the workflow.
+- For implementation reports with screenshots, prefer `comment --text-file ... --inline-file ...` and place screenshot markers as standalone paragraphs inside the text:
+  - `[[inline-file]]` inserts the next screenshot in order
+  - `[[inline-file:2]]` inserts a specific screenshot by 1-based index
+  - if no markers are present, inline screenshots are appended after the text
+
+## Local repo setup
+
+This CLI expects repo-local config under:
+
+```text
+.jira-dev-workflow/config.json
+.jira-dev-workflow/.env.local
+```