@knpkv/jira-cli 1.2.3 → 1.3.1

package/src/commands/version.ts

@@ -12,7 +12,7 @@ import * as Option from "effect/Option"
 import { Argument as Args, Command, Flag as Options } from "effect/unstable/cli"
 import { JiraApiError } from "../JiraCliError.js"
 import type { Person, Version } from "../VersionService.js"
-import { VersionService } from "../VersionService.js"
+import { planRelatedWorkSync, VersionService } from "../VersionService.js"
 
 /**
  * Return a copy of `version` with every resolved {@link Person.emailAddress}
@@ -105,7 +105,7 @@ const listCommand = Command.make("list", {
     const versions = yield* service.listProjectVersions(project, {
       released,
       unreleased,
-      ...(Option.isSome(max) ? { maxResults: max.value } : {}),
+      ...((Option.isSome(max)) && { maxResults: max.value }),
       customFieldNames: customFields
     })
     if (json) {
@@ -174,6 +174,80 @@ const descriptionOption = Options.string("description").pipe(
   Options.withDescription("New version description")
 )
 
+// === create ===
+
+/**
+ * Jira accepts version dates only as ISO 8601 `yyyy-mm-dd`. Anything else — a
+ * locale format, a timestamp — comes back as a generic 400 that does not name the
+ * offending field, so reject it locally where the message can.
+ */
+export const isIsoDate = (value: string): boolean => {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false
+  // Reject real-looking but non-existent dates (2026-02-30): round-tripping
+  // through Date is the cheapest calendar check.
+  const parsed = new Date(`${value}T00:00:00Z`)
+  return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value
+}
+
+const ensureIsoDate = (flag: string, value: string): Effect.Effect<void, JiraApiError> =>
+  isIsoDate(value) ? Effect.void : Effect.fail(
+    new JiraApiError({ message: `Invalid --${flag} "${value}". Expected an ISO 8601 date (yyyy-mm-dd).` })
+  )
+
+// No `-n` alias: it means `--dry-run` everywhere else in these CLIs, and both
+// `getLayerType` implementations route on `argv.includes("-n")`. Reusing it for
+// a value on a remote-write command is the wrong default.
+const nameOption = Options.string("name").pipe(
+  Options.withDescription("Version name (e.g. \"OOB 100\")")
+)
+const optionalDescriptionOption = Options.string("description").pipe(
+  Options.withAlias("d"),
+  Options.withDescription("Version description"),
+  Options.optional
+)
+const startDateOption = Options.string("start-date").pipe(
+  Options.withDescription("Start date, ISO 8601 (yyyy-mm-dd)"),
+  Options.optional
+)
+const releaseDateOption = Options.string("release-date").pipe(
+  Options.withDescription("Release date, ISO 8601 (yyyy-mm-dd)"),
+  Options.optional
+)
+
+const createCommand = Command.make("create", {
+  project: projectOption,
+  name: nameOption,
+  description: optionalDescriptionOption,
+  startDate: startDateOption,
+  releaseDate: releaseDateOption,
+  json: jsonOption
+}, ({ description, json, name, project, releaseDate, startDate }) =>
+  Effect.gen(function*() {
+    if (Option.isSome(startDate)) yield* ensureIsoDate("start-date", startDate.value)
+    if (Option.isSome(releaseDate)) yield* ensureIsoDate("release-date", releaseDate.value)
+
+    const service = yield* VersionService
+    const version = yield* service.createVersion({
+      projectKey: project,
+      name,
+      ...((Option.isSome(description)) && { description: description.value }),
+      ...((Option.isSome(startDate)) && { startDate: startDate.value }),
+      ...((Option.isSome(releaseDate)) && { releaseDate: releaseDate.value })
+    })
+    if (json) {
+      yield* Console.log(JSON.stringify(version, null, 2))
+      return
+    }
+    yield* Console.log(`Created version ${version.name} (${version.id}) on ${project}`)
+    yield* Console.log(`startDate: ${version.startDate ?? "-"}`)
+    yield* Console.log(`releaseDate: ${version.releaseDate ?? "-"}`)
+    yield* Console.log(`description: ${version.description ?? "-"}`)
+  })).pipe(
+    Command.withDescription(
+      "Remote write: create a new unreleased version on a project (requires manage:jira-project scope)"
+    )
+  )
+
 const updateCommand = Command.make("update", { id: idArg, description: descriptionOption, json: jsonOption }, ({
   description,
   id,
@@ -256,12 +330,94 @@ const relatedWorkAddCommand = Command.make("add", {
     )
   )
 
+const linkOption = Options.string("link").pipe(
+  Options.withAlias("l"),
+  Options.withDescription("Desired link as `title=url` (repeatable). Category comes from --category."),
+  Options.atLeast(0)
+)
+
+const pruneOption = Options.boolean("prune").pipe(
+  Options.withDescription("Also remove links in the category that are not in the desired set")
+)
+
+/**
+ * Reconcile a version's related-work links against a desired set.
+ *
+ * Re-running a release scaffold should not pile up duplicate "Release notes"
+ * links, which is what repeated `add` calls produce. Matching is by URL, the
+ * only stable identity a link has — Jira assigns the id and the title is
+ * editable.
+ */
+const relatedWorkSyncCommand = Command.make("sync", {
+  id: idArg,
+  link: linkOption,
+  category: categoryOption,
+  prune: pruneOption,
+  json: jsonOption
+}, ({ category, id, json, link, prune }) =>
+  Effect.gen(function*() {
+    yield* ensureNumericId(id)
+
+    const desired: Array<{ readonly title: string; readonly url: string }> = []
+    for (const raw of link) {
+      const separator = raw.indexOf("=")
+      // Check the trimmed halves, not the separator position: `" =url"` and
+      // `"title= "` both put a non-empty span either side of the `=` and would
+      // otherwise reach Jira as a link with an empty title or url.
+      const title = separator < 0 ? "" : raw.slice(0, separator).trim()
+      const url = separator < 0 ? "" : raw.slice(separator + 1).trim()
+      if (separator < 0 || title.length === 0 || url.length === 0) {
+        return yield* Effect.fail(
+          new JiraApiError({ message: `Invalid --link ${JSON.stringify(raw)}. Expected title=url.` })
+        )
+      }
+      desired.push({ title, url })
+    }
+    if (desired.length === 0) {
+      return yield* Effect.fail(new JiraApiError({ message: "Pass at least one --link title=url." }))
+    }
+
+    const service = yield* VersionService
+    const existing = yield* service.listRelatedWork(id)
+    const plan = planRelatedWorkSync(existing, desired, { category, prune })
+
+    for (const item of plan.toAdd) {
+      yield* service.addRelatedWork(id, { title: item.title, category, url: item.url })
+    }
+    for (const item of plan.toRemove) {
+      yield* service.deleteRelatedWork(id, item.relatedWorkId)
+    }
+
+    const added = plan.toAdd.map((d) => d.url)
+    const removed = plan.toRemove.map((d) => d.url)
+    if (json) {
+      yield* Console.log(JSON.stringify({ added, kept: plan.kept, removed }, null, 2))
+      return
+    }
+    yield* Console.log(
+      `Version ${id} (${category}): ${added.length} added, ${plan.kept.length} unchanged, ${removed.length} removed`
+    )
+    for (const url of added) yield* Console.log(`  + ${url}`)
+    for (const url of removed) yield* Console.log(`  - ${url}`)
+  })).pipe(
+    // The help text is what a user reads before a remote write, so it has to
+    // say that pruning is opt-in: without --prune nothing is ever removed, and
+    // "reconcile to exactly the given set" reads as a promise that stale links
+    // were cleaned up.
+    Command.withDescription(
+      "Remote write: add any missing related-work links in a category, matched by URL (idempotent); " +
+        "pass --prune to also remove links that are not in the given set"
+    )
+  )
+
 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])
+  Command.withDescription(
+    "List, attach or reconcile version related-work links (Confluence pages on the release report)"
+  ),
+  Command.withSubcommands([relatedWorkListCommand, relatedWorkAddCommand, relatedWorkSyncCommand])
 )
 
 export const versionCommand = Command.make("version").pipe(
   Command.withDescription("Jira version commands"),
-  Command.withSubcommands([listCommand, getCommand, updateCommand, relatedWorkCommand])
+  Command.withSubcommands([listCommand, getCommand, createCommand, updateCommand, relatedWorkCommand])
 )

package/src/index.ts

@@ -6,7 +6,7 @@
 
 export {
   AttachmentService,
-  type AttachmentServiceShape,
+  type AttachmentServiceContract,
   layer as AttachmentServiceLayer,
   type UploadAttachmentInput
 } from "./AttachmentService.js"
@@ -15,7 +15,7 @@ export {
   type Comment,
   type Issue,
   IssueService,
-  type IssueServiceShape,
+  type IssueServiceContract,
   layer as IssueServiceLayer,
   type SearchOptions,
   type SearchResult,
@@ -29,4 +29,14 @@ export {
   type LoginOptions
 } from "./JiraAuth.js"
 export * from "./JiraCliError.js"
-export { layer as MarkdownWriterLayer, MarkdownWriter, type MarkdownWriterShape } from "./MarkdownWriter.js"
+export { layer as MarkdownWriterLayer, MarkdownWriter, type MarkdownWriterContract } from "./MarkdownWriter.js"
+export {
+  type DesiredRelatedWork,
+  layer as VersionServiceLayer,
+  planRelatedWorkSync,
+  type RelatedWork,
+  type RelatedWorkSyncPlan,
+  type Version,
+  VersionService,
+  type VersionServiceContract
+} from "./VersionService.js"

package/src/internal/NodeLayers.ts

@@ -13,5 +13,5 @@ import { makeHttpServerFactory } from "./oauthServer.js"
  * @category Layers
  */
 export const HttpServerFactoryLive = makeHttpServerFactory(
-  (port) => NodeHttpServer.layerServer(createServer, { port })
+  (options) => NodeHttpServer.layerServer(createServer, options)
 )

package/src/internal/frontmatter.ts

@@ -9,6 +9,7 @@
  * @internal
  */
 import { isPreviewableAttachment } from "@knpkv/atlassian-common/attachments"
+import * as Predicate from "effect/Predicate"
 import matter from "gray-matter"
 import * as yaml from "js-yaml"
 import type { Issue } from "../IssueService.js"
@@ -24,9 +25,9 @@ import type { Issue } from "../IssueService.js"
 const yamlEngine = {
   parse: (str: string): object => {
     const parsed = yaml.load(str)
-    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {}
+    return parsed !== null && Predicate.isObjectOrArray(parsed) && !Array.isArray(parsed) ? parsed : {}
   },
-  stringify: (data: object): string => yaml.dump(data)
+  stringify: <Data extends object>(data: Data): string => yaml.dump(data)
 }
 
 /**

package/src/internal/oauthServer.ts

@@ -30,13 +30,25 @@ type HttpServerInstance = Effect.Success<typeof HttpServer.HttpServer>
  * @category Services
  */
 export interface HttpServerFactory {
-  readonly createServerLayer: (port: number) => Layer.Layer<
+  readonly createServerLayer: (options: CallbackServerListenOptions) => Layer.Layer<
     HttpServer.HttpServer,
     HttpServerError.ServeError,
     never
   >
 }
 
+export interface CallbackServerListenOptions {
+  readonly host: "localhost"
+  readonly port: number
+}
+
+export const callbackServerListenOptions = (port: number): CallbackServerListenOptions => ({
+  host: "localhost",
+  port
+})
+
+export const callbackUrl = (port: number): string => `http://localhost:${port}/callback`
+
 /**
  * Tag for the HttpServerFactory service.
  *
@@ -57,7 +69,9 @@ export class HttpServerFactoryTag extends Context.Service<
  * @category Layers
  */
 export const makeHttpServerFactory = (
-  createLayerFn: (port: number) => Layer.Layer<HttpServer.HttpServer, HttpServerError.ServeError, never>
+  createLayerFn: (
+    options: CallbackServerListenOptions
+  ) => Layer.Layer<HttpServer.HttpServer, HttpServerError.ServeError, never>
 ): Layer.Layer<HttpServerFactoryTag> =>
   Layer.succeed(HttpServerFactoryTag, {
     createServerLayer: createLayerFn
@@ -98,7 +112,7 @@ export const startCallbackServer = (
       { readonly context: Context.Context<HttpServer.HttpServer>; readonly port: number },
       OAuthError
     > =>
-      Layer.buildWithScope(factory.createServerLayer(port), serverScope).pipe(
+      Layer.buildWithScope(factory.createServerLayer(callbackServerListenOptions(port)), serverScope).pipe(
         Effect.map((context) => ({ context, port })),
         Effect.catchIf(
           (error) => isAddressInUse(error) && port < MAX_PORT,
@@ -118,29 +132,27 @@ export const startCallbackServer = (
       "/callback",
       (req) =>
         Effect.gen(function*() {
-          const url = new URL(req.url, `http://localhost:${port}`)
+          const url = new URL(req.url, callbackUrl(port))
           const code = url.searchParams.get("code")
           const state = url.searchParams.get("state")
           const error = url.searchParams.get("error")
           const errorDescription = url.searchParams.get("error_description")
 
-          if (error) {
-            yield* Deferred.fail(
-              deferred,
-              new OAuthError({ step: "authorize", cause: errorDescription ?? error })
-            )
+          if (state !== expectedState) {
             return HttpServerResponse.html(
-              "<html><body><h1>Authorization Failed</h1><p>You can close this window.</p></body></html>"
+              "<html><body><h1>Security Error</h1><p>State verification failed.</p></body></html>"
+            ).pipe(
+              HttpServerResponse.setStatus(403)
             )
           }
 
-          if (state !== expectedState) {
+          if (error) {
             yield* Deferred.fail(
               deferred,
-              new OAuthError({ step: "authorize", cause: "State mismatch - possible CSRF attack" })
+              new OAuthError({ step: "authorize", cause: errorDescription ?? error })
             )
             return HttpServerResponse.html(
-              "<html><body><h1>Security Error</h1><p>State verification failed.</p></body></html>"
+              "<html><body><h1>Authorization Failed</h1><p>You can close this window.</p></body></html>"
             )
           }
 

package/src/internal/sync/baseline.ts

@@ -15,7 +15,7 @@ export const parseSyncBaseline = (
 ): Effect.Effect<SyncBaseline, SyncWorkspaceError | SyncValidationError> =>
   Effect.gen(function*() {
     const raw = yield* Effect.try({
-      try: (): unknown => JSON.parse(content),
+      try: () => Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Json))(content),
       catch: (cause) => new SyncWorkspaceError({ message: "Failed to parse Sync Baseline JSON", path, cause })
     })
     const baseline: SyncBaseline = yield* Schema.decodeUnknownEffect(SyncBaselineSchema)(raw).pipe(
@@ -24,4 +24,5 @@ export const parseSyncBaseline = (
     return baseline
   })
 
-export const serializeSyncBaseline = (baseline: SyncBaseline): string => `${JSON.stringify(baseline, null, 2)}\n`
+export const serializeSyncBaseline = (baseline: SyncBaseline): string =>
+  `${JSON.stringify(Schema.encodeSync(SyncBaselineSchema)(baseline), null, 2)}\n`

package/src/internal/sync/config.ts

@@ -28,7 +28,8 @@ export const parseWorkspaceConfig = (
     return config
   })
 
-export const serializeWorkspaceConfig = (config: WorkspaceConfig): string => yaml.dump(config, { lineWidth: 100 })
+export const serializeWorkspaceConfig = (config: WorkspaceConfig): string =>
+  yaml.dump(Schema.encodeSync(WorkspaceConfigSchema)(config), { lineWidth: 100 })
 
 export const makeDefaultWorkspaceConfig = (siteUrl: string): WorkspaceConfig => ({
   version: 1,

package/src/internal/sync/document.ts

@@ -5,6 +5,7 @@
  */
 import { isPreviewableAttachment } from "@knpkv/atlassian-common/attachments"
 import * as Predicate from "effect/Predicate"
+import type * as Schema from "effect/Schema"
 import matter from "gray-matter"
 import * as yaml from "js-yaml"
 import { SyncValidationError } from "../../JiraCliError.js"
@@ -17,19 +18,19 @@ import type {
   UserFieldValue
 } from "./types.js"
 
-const isStringArray = (value: unknown): value is ReadonlyArray<string> =>
-  Array.isArray(value) && value.every((item) => typeof item === "string")
+const isStringArray = <UnparsedInput>(value: UnparsedInput): value is UnparsedInput & ReadonlyArray<string> =>
+  Array.isArray(value) && value.every((item) => Predicate.isString(item))
 
-const isFrontMatterCustomFields = (
-  value: unknown
-): value is IssueDocumentFrontMatter["customFields"] => Predicate.isReadonlyObject(value)
+const isFrontMatterCustomFields = <UnparsedInput>(
+  value: UnparsedInput
+): value is UnparsedInput & IssueDocumentFrontMatter["customFields"] => Predicate.isReadonlyObject(value)
 
 const yamlEngine = {
   parse: (str: string): object => {
     const value = yaml.load(str)
     return Predicate.isReadonlyObject(value) ? value : {}
   },
-  stringify: (data: object): string => yaml.dump(data)
+  stringify: <Data extends object>(data: Data): string => yaml.dump(data)
 }
 
 export const DESCRIPTION_SECTION = "Description"
@@ -88,17 +89,17 @@ const section = (name: string, content: string): string => {
   return normalized.length > 0 ? `## ${name}\n\n${normalized}\n` : `## ${name}\n`
 }
 
-const parseFrontMatter = (path: string, data: Record<string, unknown>): IssueDocumentFrontMatter => {
+const parseFrontMatter = (path: string, data: Record<string, Schema.Json>): IssueDocumentFrontMatter => {
   const requiredString = (key: string): string => {
     const value = data[key]
-    if (typeof value === "string") return value
+    if (Predicate.isString(value)) return value
     return fail(path, `Missing or invalid front matter field "${key}"`)
   }
 
   const nullableString = (key: string): string | null => {
     const value = data[key]
     if (value === null || value === undefined) return null
-    if (typeof value === "string") return value
+    if (Predicate.isString(value)) return value
     return fail(path, `Invalid front matter field "${key}"`)
   }
 
@@ -108,7 +109,7 @@ const parseFrontMatter = (path: string, data: Record<string, unknown>): IssueDoc
     const record = Predicate.isReadonlyObject(value) ? value : fail(path, `Invalid user field "${key}"`)
     const accountId = record["accountId"]
     const displayName = record["displayName"]
-    if (typeof accountId === "string" && typeof displayName === "string") {
+    if (Predicate.isString(accountId) && Predicate.isString(displayName)) {
       return {
         accountId,
         displayName
@@ -244,13 +245,13 @@ const parseAttachmentMetadata = (
     const parsed = JSON.parse(raw)
     if (!Predicate.isReadonlyObject(parsed)) return {}
     return {
-      id: typeof parsed["jiraAttachmentId"] === "string"
+      id: Predicate.isString(parsed["jiraAttachmentId"])
         ? parsed["jiraAttachmentId"]
-        : typeof parsed["id"] === "string"
+        : Predicate.isString(parsed["id"])
         ? parsed["id"]
         : "",
-      mediaType: typeof parsed["mediaType"] === "string" ? parsed["mediaType"] : null,
-      size: typeof parsed["size"] === "number" ? parsed["size"] : null
+      mediaType: Predicate.isString(parsed["mediaType"]) ? parsed["mediaType"] : null,
+      size: Predicate.isNumber(parsed["size"]) ? parsed["size"] : null
     }
   } catch {
     return {}

package/src/internal/sync/fieldValues.ts

@@ -16,7 +16,7 @@ export interface CanonicalFieldValueOptions {
 
 export const explicitClear = null
 
-export const isExplicitClear = (value: unknown): value is null => value === null
+export const isExplicitClear = <UnparsedInput>(value: UnparsedInput): value is UnparsedInput & null => value === null
 
 export const userFieldValue = (accountId: string, displayName: string): UserFieldValue => ({
   accountId,
@@ -44,24 +44,26 @@ export const completeListValue = (
 
 export const makeCompleteListValue = completeListValue
 
-export const isUserFieldValue = (value: unknown): value is UserFieldValue => {
+export const isUserFieldValue = <UnparsedInput>(value: UnparsedInput): value is UnparsedInput & UserFieldValue => {
   if (!Predicate.isReadonlyObject(value)) return false
-  return typeof value["accountId"] === "string" && typeof value["displayName"] === "string"
+  return Predicate.isString(value["accountId"]) && Predicate.isString(value["displayName"])
 }
 
-export const isOptionFieldValue = (value: unknown): value is OptionFieldValue => {
-  if (!Predicate.isReadonlyObject(value) || typeof value["value"] !== "string") return false
+export const isOptionFieldValue = <UnparsedInput>(value: UnparsedInput): value is UnparsedInput & OptionFieldValue => {
+  if (!Predicate.isReadonlyObject(value) || !Predicate.isString(value["value"])) return false
   const id = value["id"]
-  return id === undefined || typeof id === "string"
+  return id === undefined || Predicate.isString(id)
 }
 
-export const isCascadingFieldValue = (value: unknown): value is CascadingFieldValue => {
+export const isCascadingFieldValue = <UnparsedInput>(
+  value: UnparsedInput
+): value is UnparsedInput & CascadingFieldValue => {
   if (!Predicate.isReadonlyObject(value) || !isOptionFieldValue(value["parent"])) return false
   const child = value["child"]
   return child === undefined || isOptionFieldValue(child)
 }
 
-export const isCompleteListValue = (value: unknown): value is CompleteListValue =>
+export const isCompleteListValue = <UnparsedInput>(value: UnparsedInput): value is UnparsedInput & CompleteListValue =>
   Array.isArray(value) && value.every(isCompleteListItem)
 
 export const canonicalFieldOrder = <A extends CompleteListItem>(
@@ -104,7 +106,7 @@ const canonicalFieldValueKey = (
   options: CanonicalFieldValueOptions
 ): string => {
   if (value === null) return "clear:"
-  if (Array.isArray(value)) {
+  if (isCompleteListValue(value)) {
     return `list:${canonicalFieldOrder(value, options).map(completeListItemOrderKey).join("\u0000")}`
   }
   if (isCascadingFieldValue(value)) {
@@ -114,13 +116,13 @@ const canonicalFieldValueKey = (
   }
   if (isUserFieldValue(value)) return userOrderKey(value)
   if (isOptionFieldValue(value)) return optionOrderKey(value)
-  return `${typeof value}:${String(value)}`
+  return scalarOrderKey(value)
 }
 
 const completeListItemOrderKey = (value: CompleteListItem): string => {
   if (isUserFieldValue(value)) return userOrderKey(value)
   if (isOptionFieldValue(value)) return optionOrderKey(value)
-  return `${typeof value}:${String(value)}`
+  return scalarOrderKey(value)
 }
 
 const userOrderKey = (value: UserFieldValue): string =>
@@ -129,15 +131,12 @@ const userOrderKey = (value: UserFieldValue): string =>
 const optionOrderKey = (value: OptionFieldValue): string =>
   `option:${value.value.toLocaleLowerCase("en")}\u0000${value.id ?? ""}`
 
-const isCompleteListItem = (value: unknown): value is CompleteListItem => {
-  switch (typeof value) {
-    case "string":
-    case "number":
-    case "boolean":
-      return true
-    case "object":
-      return isUserFieldValue(value) || isOptionFieldValue(value)
-    default:
-      return false
-  }
+const scalarOrderKey = (value: string | number | boolean): string => {
+  const kind = Predicate.isString(value) ? "string" : Predicate.isNumber(value) ? "number" : "boolean"
+  return `${kind}:${String(value)}`
+}
+
+const isCompleteListItem = <UnparsedInput>(value: UnparsedInput): value is UnparsedInput & CompleteListItem => {
+  return Predicate.isString(value) || Predicate.isNumber(value) || Predicate.isBoolean(value) ||
+    isUserFieldValue(value) || isOptionFieldValue(value)
 }

package/src/internal/sync/manifest.ts

@@ -21,7 +21,7 @@ export const parseSyncManifest = (
 ): Effect.Effect<SyncManifest, SyncWorkspaceError | SyncValidationError> =>
   Effect.gen(function*() {
     const raw = yield* Effect.try({
-      try: (): unknown => JSON.parse(content),
+      try: () => Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Json))(content),
       catch: (cause) => new SyncWorkspaceError({ message: "Failed to parse Sync Manifest JSON", path, cause })
     })
     return yield* Schema.decodeUnknownEffect(SyncManifestSchema)(raw).pipe(

package/src/internal/sync/schemas.ts

@@ -5,7 +5,7 @@
  */
 import * as Effect from "effect/Effect"
 import * as Schema from "effect/Schema"
-import { FIELD_SHAPES } from "./types.js"
+import { FIELD_CONTRACTS } from "./types.js"
 
 const SiteUrl = Schema.String.pipe(
   Schema.check(Schema.isPattern(/^https:\/\/[a-z0-9][a-z0-9-]*\.atlassian\.net$/))
@@ -14,14 +14,14 @@ const SiteUrl = Schema.String.pipe(
 const NonEmptyString = Schema.String.pipe(Schema.check(Schema.isMinLength(1)))
 const FilenameModes: readonly ["convention", "custom"] = ["convention", "custom"]
 
-export const FieldShapeSchema = Schema.Literals(FIELD_SHAPES)
+export const FieldContractSchema = Schema.Literals(FIELD_CONTRACTS)
 
 export const RequestedCustomFieldSchema = Schema.Struct({
   displayName: NonEmptyString,
   fieldId: Schema.optional(NonEmptyString),
-  shape: FieldShapeSchema,
+  form: FieldContractSchema,
   ordered: Schema.optional(Schema.Boolean)
-})
+}).pipe(Schema.encodeKeys({ form: "shape" }))
 
 export const WorkspaceConfigSchema = Schema.Struct({
   version: Schema.Literal(1).pipe(Schema.withDecodingDefaultTypeKey(Effect.succeed(1))),
@@ -82,9 +82,9 @@ export const SyncFieldValueSchema = Schema.Union([
 export const BaselineCustomFieldSchema = Schema.Struct({
   fieldId: NonEmptyString,
   displayName: NonEmptyString,
-  shape: FieldShapeSchema,
+  form: FieldContractSchema,
   value: SyncFieldValueSchema
-})
+}).pipe(Schema.encodeKeys({ form: "shape" }))
 
 export const SyncBaselineSchema = Schema.Struct({
   version: Schema.Literal(1),

package/src/internal/sync/types.ts

@@ -4,7 +4,7 @@
  * @internal
  */
 
-export type FieldShape =
+export type FieldContract =
   | "text"
   | "multilineText"
   | "number"
@@ -15,7 +15,7 @@ export type FieldShape =
   | "user"
   | "cascadingSelect"
 
-export const FIELD_SHAPES: ReadonlyArray<FieldShape> = [
+export const FIELD_CONTRACTS: ReadonlyArray<FieldContract> = [
   "text",
   "multilineText",
   "number",
@@ -30,7 +30,7 @@ export const FIELD_SHAPES: ReadonlyArray<FieldShape> = [
 export interface RequestedCustomField {
   readonly displayName: string
   readonly fieldId?: string | undefined
-  readonly shape: FieldShape
+  readonly form: FieldContract
   readonly ordered?: boolean | undefined
 }
 
@@ -83,7 +83,7 @@ export type SyncFieldValue =
 export interface BaselineCustomField {
   readonly fieldId: string
   readonly displayName: string
-  readonly shape: FieldShape
+  readonly form: FieldContract
   readonly value: SyncFieldValue
 }