@knpkv/jira-cli 0.3.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knpkv/jira-cli",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "CLI tool to fetch Jira tickets and export to markdown",
   "license": "MIT",
   "author": "knpkv",
@@ -51,12 +51,14 @@
   "dependencies": {
     "@effect/platform-node": "4.0.0-beta.87",
     "gray-matter": "^4.0.3",
-    "@knpkv/agent-skills": "^0.2.0",
+    "js-yaml": "^4.1.0",
+    "@knpkv/agent-skills": "^0.2.1",
     "@knpkv/atlassian-common": "0.3.0",
     "@knpkv/jira-api-client": "0.3.0"
   },
   "devDependencies": {
     "@effect/vitest": "4.0.0-beta.87",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "latest",
     "effect": "4.0.0-beta.87",
     "typescript": "~6.0.3",
@@ -76,6 +78,7 @@
     "build": "tsc",
     "clean": "rimraf dist dist-test .tsbuildinfo",
     "test": "vitest run",
+    "test:integration": "vitest run --config vitest.config.integration.ts",
     "test:watch": "vitest",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",

package/skills/jira/SKILL.md

@@ -11,8 +11,8 @@ Use the `jira` binary for Jira Cloud issue export and release-version workflows.
 
 - Authenticate first with `jira auth status`, `jira auth create`, `jira auth configure`, and `jira auth login`.
 - Use `--json` on version commands when the agent needs structured data.
-- Use numeric version ids for `jira version view`, `jira version set`, and `jira version relatedwork`.
-- Confirm before commands that mutate Jira: `jira version set` and `jira version relatedwork add`.
+- Use numeric version ids for `jira version get`, `jira version update`, and `jira version related-work`.
+- Confirm before remote write commands: `jira version update` and `jira version related-work add`.
 
 ## Authentication
 
@@ -31,21 +31,21 @@ OAuth scopes used by release workflows include `read:jira-work`, `write:jira-wor
 Fetch one issue as markdown:
 
 ```bash
-jira get PROJ-123 --output-dir ./jira-tickets
+jira issue get PROJ-123 --output-dir ./jira-tickets
 ```
 
 Search with JQL:
 
 ```bash
-jira search 'project = PROJ AND status = Done' --output-dir ./jira-tickets
-jira search 'fixVersion = "1.0.0"' --format single --max-results 200
+jira issue search 'project = PROJ AND status = Done' --output-dir ./jira-tickets
+jira issue search 'fixVersion = "1.0.0"' --format single --max-results 200
 ```
 
 Search by fix version:
 
 ```bash
-jira search --by-version "1.0.0" --project PROJ
-jira search --by-version "1.0.0" --project PROJ --format single
+jira issue search --by-version "1.0.0" --project PROJ
+jira issue search --by-version "1.0.0" --project PROJ --format single
 ```
 
 Output formats:
@@ -66,20 +66,20 @@ jira version list --project PROJ --custom-field "Security & Compliance Impact" -
 View a version:
 
 ```bash
-jira version view 10042 --json
+jira version get 10042 --json
 ```
 
 Update a version description:
 
 ```bash
-jira version set 10042 --description "Q3 release"
+jira version update 10042 --description "Q3 release"
 ```
 
 Manage related work links:
 
 ```bash
-jira version relatedwork list 10042 --json
-jira version relatedwork add 10042 --title "Release notes" --url "https://example.atlassian.net/wiki/spaces/PROJ/pages/123" --category Communication
+jira version related-work list 10042 --json
+jira version related-work add 10042 --title "Release notes" --url "https://example.atlassian.net/wiki/spaces/PROJ/pages/123" --category Communication
 ```
 
 ## Agent Workflow

package/src/JiraCliError.ts

@@ -42,3 +42,27 @@ export class WriteError extends Data.TaggedError("WriteError")<{
   readonly message: string
   readonly cause?: unknown
 }> {}
+
+/**
+ * Error when reading or writing Jira Markdown Sync workspace state.
+ *
+ * @category Errors
+ */
+export class SyncWorkspaceError extends Data.TaggedError("SyncWorkspaceError")<{
+  readonly message: string
+  readonly path?: string | undefined
+  readonly cause?: unknown
+}> {}
+
+/**
+ * Error when local Jira Markdown Sync configuration or data fails validation.
+ *
+ * @category Errors
+ */
+export class SyncValidationError extends Data.TaggedError("SyncValidationError")<{
+  readonly message: string
+  readonly issueKey?: string | undefined
+  readonly field?: string | undefined
+  readonly path?: string | undefined
+  readonly cause?: unknown
+}> {}

package/src/SyncWorkspace.ts

@@ -0,0 +1,185 @@
+/**
+ * Local workspace I/O for Jira Markdown Sync.
+ *
+ * @module
+ */
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as FileSystem from "effect/FileSystem"
+import * as Layer from "effect/Layer"
+import * as Path from "effect/Path"
+import { parseSyncBaseline, serializeSyncBaseline } from "./internal/sync/baseline.js"
+import { makeDefaultWorkspaceConfig, parseWorkspaceConfig, serializeWorkspaceConfig } from "./internal/sync/config.js"
+import { makeEmptyManifest, parseSyncManifest, serializeSyncManifest } from "./internal/sync/manifest.js"
+import {
+  baselineFilePath,
+  conventionDocumentPath,
+  resolveWorkspacePaths,
+  type SyncWorkspacePaths
+} from "./internal/sync/paths.js"
+import type { SyncBaseline, SyncManifest, WorkspaceConfig } from "./internal/sync/types.js"
+import { SyncWorkspaceError } from "./JiraCliError.js"
+
+export interface InitWorkspaceInput {
+  readonly root: string
+  readonly siteUrl: string
+}
+
+export interface SyncWorkspaceShape {
+  readonly init: (input: InitWorkspaceInput) => Effect.Effect<SyncWorkspacePaths, SyncWorkspaceError>
+  readonly paths: (root: string, config?: Pick<WorkspaceConfig, "documentsDir">) => Effect.Effect<SyncWorkspacePaths>
+  readonly readConfig: (root: string) => Effect.Effect<WorkspaceConfig, SyncWorkspaceError>
+  readonly writeConfig: (root: string, config: WorkspaceConfig) => Effect.Effect<void, SyncWorkspaceError>
+  readonly readManifest: (root: string) => Effect.Effect<SyncManifest, SyncWorkspaceError>
+  readonly writeManifest: (root: string, manifest: SyncManifest) => Effect.Effect<void, SyncWorkspaceError>
+  readonly readBaseline: (root: string, issueId: string) => Effect.Effect<SyncBaseline, SyncWorkspaceError>
+  readonly writeBaseline: (
+    root: string,
+    baseline: SyncBaseline
+  ) => Effect.Effect<void, SyncWorkspaceError>
+  readonly conventionDocumentPath: (root: string, issueKey: string) => Effect.Effect<string, SyncWorkspaceError>
+}
+
+export class SyncWorkspace extends Context.Service<
+  SyncWorkspace,
+  SyncWorkspaceShape
+>()("@knpkv/jira-cli/SyncWorkspace") {}
+
+const mapWorkspaceError = (message: string, path?: string | undefined) => (cause: unknown) =>
+  new SyncWorkspaceError({ message, path, cause })
+
+const make = Effect.gen(function*() {
+  const fs = yield* FileSystem.FileSystem
+  const path = yield* Path.Path
+
+  const paths: SyncWorkspaceShape["paths"] = (root, config) => Effect.succeed(resolveWorkspacePaths(path, root, config))
+
+  const ensureDir = (dir: string): Effect.Effect<void, SyncWorkspaceError> =>
+    fs.makeDirectory(dir, { recursive: true }).pipe(
+      Effect.mapError(mapWorkspaceError("Failed to create sync workspace directory", dir)),
+      Effect.asVoid
+    )
+
+  const writeFile = (filePath: string, content: string): Effect.Effect<void, SyncWorkspaceError> =>
+    Effect.gen(function*() {
+      const dir = path.dirname(filePath)
+      yield* ensureDir(dir)
+      const tempPath = `${filePath}.tmp.${Date.now()}`
+      yield* fs.writeFileString(tempPath, content).pipe(
+        Effect.mapError(mapWorkspaceError("Failed to write sync workspace file", filePath))
+      )
+      yield* fs.rename(tempPath, filePath).pipe(
+        Effect.mapError(mapWorkspaceError("Failed to replace sync workspace file", filePath))
+      )
+    })
+
+  const readFile = (filePath: string): Effect.Effect<string, SyncWorkspaceError> =>
+    fs.readFileString(filePath).pipe(
+      Effect.mapError(mapWorkspaceError("Failed to read sync workspace file", filePath))
+    )
+
+  const init: SyncWorkspaceShape["init"] = ({ root, siteUrl }) =>
+    Effect.gen(function*() {
+      const config = makeDefaultWorkspaceConfig(siteUrl)
+      const workspacePaths = resolveWorkspacePaths(path, root, config)
+      yield* ensureDir(workspacePaths.documentsDir)
+      yield* ensureDir(workspacePaths.metadataDir)
+      yield* ensureDir(workspacePaths.baselinesDir)
+      yield* ensureDir(workspacePaths.historyDir)
+      yield* writeFile(workspacePaths.configFile, serializeWorkspaceConfig(config))
+      yield* writeFile(workspacePaths.manifestFile, serializeSyncManifest(makeEmptyManifest(siteUrl)))
+      return workspacePaths
+    })
+
+  const readConfig: SyncWorkspaceShape["readConfig"] = (root) =>
+    Effect.gen(function*() {
+      const workspacePaths = resolveWorkspacePaths(path, root)
+      const content = yield* readFile(workspacePaths.configFile)
+      return yield* parseWorkspaceConfig(workspacePaths.configFile, content).pipe(
+        Effect.mapError((cause) =>
+          new SyncWorkspaceError({
+            message: cause.message,
+            path: "path" in cause ? cause.path : workspacePaths.configFile,
+            cause
+          })
+        )
+      )
+    })
+
+  const writeConfig: SyncWorkspaceShape["writeConfig"] = (root, config) =>
+    Effect.gen(function*() {
+      const workspacePaths = resolveWorkspacePaths(path, root, config)
+      yield* ensureDir(workspacePaths.metadataDir)
+      yield* writeFile(workspacePaths.configFile, serializeWorkspaceConfig(config))
+    })
+
+  const readManifest: SyncWorkspaceShape["readManifest"] = (root) =>
+    Effect.gen(function*() {
+      const workspacePaths = resolveWorkspacePaths(path, root)
+      const content = yield* readFile(workspacePaths.manifestFile)
+      return yield* parseSyncManifest(workspacePaths.manifestFile, content).pipe(
+        Effect.mapError((cause) =>
+          new SyncWorkspaceError({
+            message: cause.message,
+            path: "path" in cause ? cause.path : workspacePaths.manifestFile,
+            cause
+          })
+        )
+      )
+    })
+
+  const writeManifest: SyncWorkspaceShape["writeManifest"] = (root, manifest) =>
+    Effect.gen(function*() {
+      const workspacePaths = resolveWorkspacePaths(path, root)
+      yield* ensureDir(workspacePaths.metadataDir)
+      yield* writeFile(workspacePaths.manifestFile, serializeSyncManifest(manifest))
+    })
+
+  const readBaseline: SyncWorkspaceShape["readBaseline"] = (root, issueId) =>
+    Effect.gen(function*() {
+      const workspacePaths = resolveWorkspacePaths(path, root)
+      const filePath = baselineFilePath(path, workspacePaths, issueId)
+      const content = yield* readFile(filePath)
+      return yield* parseSyncBaseline(filePath, content).pipe(
+        Effect.mapError((cause) =>
+          new SyncWorkspaceError({
+            message: cause.message,
+            path: "path" in cause ? cause.path : filePath,
+            cause
+          })
+        )
+      )
+    })
+
+  const writeBaseline: SyncWorkspaceShape["writeBaseline"] = (root, baseline) =>
+    Effect.gen(function*() {
+      const workspacePaths = resolveWorkspacePaths(path, root)
+      const filePath = baselineFilePath(path, workspacePaths, baseline.issueId)
+      yield* ensureDir(workspacePaths.baselinesDir)
+      yield* writeFile(filePath, serializeSyncBaseline(baseline))
+    })
+
+  const getConventionDocumentPath: SyncWorkspaceShape["conventionDocumentPath"] = (root, issueKey) =>
+    Effect.gen(function*() {
+      const config = yield* readConfig(root)
+      const workspacePaths = resolveWorkspacePaths(path, root, config)
+      return conventionDocumentPath(path, workspacePaths, issueKey)
+    })
+
+  return SyncWorkspace.of({
+    init,
+    paths,
+    readConfig,
+    writeConfig,
+    readManifest,
+    writeManifest,
+    readBaseline,
+    writeBaseline,
+    conventionDocumentPath: getConventionDocumentPath
+  })
+})
+
+export const layer: Layer.Layer<SyncWorkspace, never, FileSystem.FileSystem | Path.Path> = Layer.effect(
+  SyncWorkspace,
+  make
+)

package/src/bin.ts

@@ -17,11 +17,10 @@ import {
   AppLayer,
   authCommand,
   AuthOnlyLayer,
-  getCommand,
   getLayerType,
   handleError,
+  issueCommand,
   MinimalLayer,
-  searchCommand,
   versionCommand
 } from "./commands/index.js"
 
@@ -32,17 +31,16 @@ const skillsInstall = makeInstallCommand({
 })
 
 const skillsCommand = Command.make("skills", {}, () => Console.log("Usage: jira skills install")).pipe(
-  Command.withDescription("Agent skill commands"),
+  Command.withDescription("Local write agent skill commands"),
   Command.withSubcommands([skillsInstall])
 )
 
 // === Main command ===
 const jira = Command.make("jira").pipe(
-  Command.withDescription("Fetch Jira tickets and export to markdown"),
+  Command.withDescription("Jira CLI commands"),
   Command.withSubcommands([
     authCommand,
-    getCommand,
-    searchCommand,
+    issueCommand,
     skillsCommand,
     versionCommand
   ])

package/src/commands/get.ts

@@ -1,5 +1,5 @@
 /**
- * `jira get <key>` command — fetches a single issue and writes to Markdown.
+ * `jira issue get <key>` command — fetches a single issue and writes to Markdown.
  *
  * @internal
  */
@@ -39,4 +39,4 @@ export const getCommand = Command.make(
 
       yield* Console.log(`Done.`)
     })
-).pipe(Command.withDescription("Get a single Jira issue by key"))
+).pipe(Command.withDescription("Read-only: get a single Jira issue by key"))

package/src/commands/index.ts

@@ -6,7 +6,6 @@
 
 export { authCommand } from "./auth.js"
 export { handleError } from "./errorHandler.js"
-export { getCommand } from "./get.js"
+export { issueCommand } from "./issue.js"
 export { AppLayer, AuthOnlyLayer, getLayerType, MinimalLayer } from "./layers.js"
-export { searchCommand } from "./search.js"
 export { versionCommand } from "./version.js"

package/src/commands/issue.ts

@@ -0,0 +1,13 @@
+/**
+ * `jira issue` command namespace.
+ *
+ * @internal
+ */
+import { Command } from "effect/unstable/cli"
+import { getCommand } from "./get.js"
+import { searchCommand } from "./search.js"
+
+export const issueCommand = Command.make("issue").pipe(
+  Command.withDescription("Read-only Jira issue commands"),
+  Command.withSubcommands([getCommand, searchCommand])
+)

package/src/commands/layers.ts

@@ -5,7 +5,7 @@
  *
  * - **Lazy layer selection**: {@link getLayerType} inspects CLI arguments from `Stdio` to pick
  *   the smallest layer needed — `"minimal"` for help/version, `"auth"` for auth commands,
- *   `"full"` for search/get (which needs API client + issue service).
+ *   `"full"` for issue/version reads and writes.
  * - **Dummy services**: Auth-only and minimal layers provide dying stubs
  *   for unused services to satisfy the type system without initialization cost.
  *
@@ -147,6 +147,9 @@ export const MinimalLayer = DummyIssueServiceLayer.pipe(
  */
 export const getLayerType = (args: ReadonlyArray<string>): "full" | "auth" | "minimal" => {
   const cmd = args[0]
+  if (args.includes("--help") || args.includes("-h")) {
+    return "minimal"
+  }
   if (cmd === "auth") {
     return "auth"
   }

package/src/commands/search.ts

@@ -1,5 +1,5 @@
 /**
- * `jira search` command — JQL search with multi/single Markdown output.
+ * `jira issue search` command — JQL search with multi/single Markdown output.
  *
  * @internal
  */
@@ -74,8 +74,8 @@ export const searchCommand = Command.make(
         query = jql.value
       } else {
         yield* Console.log("Error: Either a JQL query or --by-version must be provided.")
-        yield* Console.log("Usage: jira search <jql>")
-        yield* Console.log("       jira search --by-version <version>")
+        yield* Console.log("Usage: jira issue search <jql>")
+        yield* Console.log("       jira issue search --by-version <version>")
         return
       }
 
@@ -99,4 +99,4 @@ export const searchCommand = Command.make(
         yield* Console.log(`Exported ${issues.length} file(s) to ${outputDir}/`)
       }
     })
-).pipe(Command.withDescription("Search Jira issues and export to markdown"))
+).pipe(Command.withDescription("Read-only: search Jira issues and export to markdown"))

package/src/commands/version.ts

@@ -1,5 +1,5 @@
 /**
- * `jira version` command — list / view Jira project versions (releases) with
+ * `jira version` command — list / get Jira project versions (releases) with
  * Driver, Contributors and Approver fields resolved to display names, plus
  * mutations: edit the description and manage "Related work" links (the
  * Confluence pages surfaced on a release report).
@@ -126,13 +126,13 @@ const listCommand = Command.make("list", {
         v.approvers.map((a) => `${a.person.displayName}:${a.status}`).join("|") || "-"
       ].join(sep))
     }
-  })).pipe(Command.withDescription("List versions for a Jira project"))
+  })).pipe(Command.withDescription("Read-only: list versions for a Jira project"))
 
-/** Cap on the number of ticket keys listed in the human `view` output. */
+/** Cap on the number of ticket keys listed in the human `get` output. */
 const TICKET_KEYS_LIMIT = 20
 
-const viewCommand = Command.make(
-  "view",
+const getCommand = Command.make(
+  "get",
   { id: idArg, json: jsonOption, emails: emailsOption },
   ({ emails, id, json }) =>
     Effect.gen(function*() {
@@ -154,10 +154,10 @@ const viewCommand = Command.make(
       )
       yield* Console.log(`tickets (${version.tickets.length}): ${formatTicketKeys(version.tickets)}`)
     })
-).pipe(Command.withDescription("Show a single Jira version"))
+).pipe(Command.withDescription("Read-only: get a single Jira version"))
 
 /**
- * Render a version's ticket keys for the human `view`: the first
+ * Render a version's ticket keys for the human `get`: the first
  * {@link TICKET_KEYS_LIMIT} keys, with a `(+M more)` suffix when truncated, or
  * `-` when there are none.
  */
@@ -174,7 +174,7 @@ const descriptionOption = Options.string("description").pipe(
   Options.withDescription("New version description")
 )
 
-const setCommand = Command.make("set", { id: idArg, description: descriptionOption, json: jsonOption }, ({
+const updateCommand = Command.make("update", { id: idArg, description: descriptionOption, json: jsonOption }, ({
   description,
   id,
   json
@@ -190,10 +190,10 @@ const setCommand = Command.make("set", { id: idArg, description: descriptionOpti
     yield* Console.log(`Updated version ${version.name} (${version.id})`)
     yield* Console.log(`description: ${version.description ?? "-"}`)
   })).pipe(
-    Command.withDescription("Update a version's description (requires manage:jira-project scope)")
+    Command.withDescription("Remote write: update a version's description (requires manage:jira-project scope)")
   )
 
-// === relatedwork ===
+// === related-work ===
 
 const titleOption = Options.string("title").pipe(
   Options.withAlias("t"),
@@ -231,7 +231,7 @@ const relatedWorkListCommand = Command.make(
         yield* Console.log([w.category || "-", w.title ?? "-", w.url ?? "-"].join(sep))
       }
     })
-).pipe(Command.withDescription("List a version's related-work links"))
+).pipe(Command.withDescription("Read-only: list a version's related-work links"))
 
 const relatedWorkAddCommand = Command.make("add", {
   id: idArg,
@@ -252,16 +252,16 @@ const relatedWorkAddCommand = Command.make("add", {
     yield* Console.log(`url: ${created.url ?? url}`)
   })).pipe(
     Command.withDescription(
-      "Attach a related-work link (e.g. a Confluence page) to a version (requires manage:jira-project scope)"
+      "Remote write: attach a related-work link (e.g. a Confluence page) to a version (requires manage:jira-project scope)"
     )
   )
 
-const relatedWorkCommand = Command.make("relatedwork").pipe(
+const relatedWorkCommand = Command.make("related-work").pipe(
   Command.withDescription("List or attach version related-work links (Confluence pages on the release report)"),
   Command.withSubcommands([relatedWorkListCommand, relatedWorkAddCommand])
 )
 
 export const versionCommand = Command.make("version").pipe(
-  Command.withDescription("List, view, or edit Jira project versions (releases)"),
-  Command.withSubcommands([listCommand, viewCommand, setCommand, relatedWorkCommand])
+  Command.withDescription("Jira version commands"),
+  Command.withSubcommands([listCommand, getCommand, updateCommand, relatedWorkCommand])
 )

package/src/internal/frontmatter.ts

@@ -9,8 +9,22 @@
  * @internal
  */
 import matter from "gray-matter"
+import * as yaml from "js-yaml"
 import type { Issue } from "../IssueService.js"
 
+/**
+ * `gray-matter` ships a default YAML engine that calls `js-yaml`'s `safeDump`/
+ * `safeLoad`, both removed in `js-yaml` 4. The workspace pins `js-yaml` to 4.x
+ * (security override), so we supply an engine backed by the 4.x `dump`/`load`
+ * API, which is safe by default.
+ *
+ * @internal
+ */
+const yamlEngine = {
+  parse: (str: string): object => (yaml.load(str) as object) ?? {},
+  stringify: (data: object): string => yaml.dump(data)
+}
+
 /**
  * Front-matter data for a Jira issue.
  *
@@ -69,7 +83,7 @@ export const extractFrontMatter = (issue: Issue): IssueFrontMatter => ({
 export const serializeIssue = (issue: Issue): string => {
   const frontMatter = extractFrontMatter(issue)
   const content = buildMarkdownContent(issue)
-  return matter.stringify(content, frontMatter)
+  return matter.stringify(content, frontMatter, { engines: { yaml: yamlEngine } })
 }
 
 /**

package/src/internal/sync/baseline.ts

@@ -0,0 +1,27 @@
+/**
+ * Sync Baseline helpers.
+ *
+ * @internal
+ */
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { SyncValidationError, SyncWorkspaceError } from "../../JiraCliError.js"
+import { SyncBaselineSchema } from "./schemas.js"
+import type { SyncBaseline } from "./types.js"
+
+export const parseSyncBaseline = (
+  path: string,
+  content: string
+): Effect.Effect<SyncBaseline, SyncWorkspaceError | SyncValidationError> =>
+  Effect.gen(function*() {
+    const raw = yield* Effect.try({
+      try: () => JSON.parse(content) as unknown,
+      catch: (cause) => new SyncWorkspaceError({ message: "Failed to parse Sync Baseline JSON", path, cause })
+    })
+    return yield* Schema.decodeUnknownEffect(SyncBaselineSchema)(raw).pipe(
+      Effect.map((baseline) => baseline as SyncBaseline),
+      Effect.mapError((cause) => new SyncValidationError({ message: "Invalid Sync Baseline", path, cause }))
+    )
+  })
+
+export const serializeSyncBaseline = (baseline: SyncBaseline): string => `${JSON.stringify(baseline, null, 2)}\n`