@knpkv/jira-cli 1.2.2 → 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

@@ -3,9 +3,9 @@
  *
  * **Mental model**
  *
- * - **Deferred-coordinated lifecycle**: {@link startCallbackServer} returns a `codePromise`
- *   (Deferred) and a `shutdown` effect. The server validates the CSRF `state` parameter
- *   and resolves the Deferred with the authorization code.
+ * - **Scope-owned lifecycle**: {@link startCallbackServer} returns a `codePromise`
+ *   (Deferred). The server validates the CSRF `state` parameter, resolves the
+ *   Deferred with the authorization code, and stops when its enclosing scope closes.
  * - **Port auto-discovery**: Tries default port 8585, increments on conflict.
  *
  * @internal
@@ -14,10 +14,9 @@ import { OAuthError } from "@knpkv/atlassian-common/auth"
 import * as Context from "effect/Context"
 import * as Deferred from "effect/Deferred"
 import * as Effect from "effect/Effect"
-import * as Exit from "effect/Exit"
-import * as Fiber from "effect/Fiber"
 import * as Layer from "effect/Layer"
-import * as Scope from "effect/Scope"
+import * as Schema from "effect/Schema"
+import type * as Scope from "effect/Scope"
 import { HttpRouter, HttpServer, HttpServerResponse } from "effect/unstable/http"
 import type * as HttpServerError from "effect/unstable/http/HttpServerError"
 
@@ -31,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.
  *
@@ -58,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
@@ -70,38 +83,42 @@ export const makeHttpServerFactory = (
 export interface CallbackServerResult {
   /** Promise that resolves with the authorization code */
   readonly codePromise: Effect.Effect<string, OAuthError>
-  /** Shutdown the callback server */
-  readonly shutdown: Effect.Effect<void, never>
   /** The port the server is listening on */
   readonly port: number
 }
 
+const AddressInUseCause = Schema.Struct({
+  code: Schema.Literal("EADDRINUSE")
+})
+
+const isAddressInUse = (error: HttpServerError.ServeError): boolean => Schema.is(AddressInUseCause)(error.cause)
+
 /**
  * Start a local HTTP server to receive OAuth callback.
  *
  * @param expectedState - The state parameter to verify against CSRF
- * @returns Server control interface with code promise, shutdown, and port
+ * @returns Server control interface with code promise and port
  *
  * @category OAuth
  */
 export const startCallbackServer = (
   expectedState: string
-): Effect.Effect<CallbackServerResult, OAuthError, HttpServerFactoryTag> =>
+): Effect.Effect<CallbackServerResult, OAuthError, HttpServerFactoryTag | Scope.Scope> =>
   Effect.gen(function*() {
     const factory = yield* HttpServerFactoryTag
     const deferred = yield* Deferred.make<string, OAuthError>()
-    const serverScope = yield* Scope.make()
+    const serverScope = yield* Effect.scope
     const buildServerContext = (port: number): Effect.Effect<
       { 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.catchCause((cause) =>
-          port < MAX_PORT
-            ? buildServerContext(port + 1)
-            : Effect.fail(new OAuthError({ step: "authorize", cause }))
-        )
+        Effect.catchIf(
+          (error) => isAddressInUse(error) && port < MAX_PORT,
+          () => buildServerContext(port + 1)
+        ),
+        Effect.mapError((cause) => new OAuthError({ step: "authorize", cause }))
       )
     const { context: serverContext } = yield* buildServerContext(DEFAULT_PORT)
     const server: HttpServerInstance = Context.get(serverContext, HttpServer.HttpServer)
@@ -115,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>"
             )
           }
 
@@ -159,18 +174,13 @@ export const startCallbackServer = (
     )
     const app = router.asHttpEffect()
 
-    const serverFiber = yield* HttpServer.serveEffect(app).pipe(
+    yield* HttpServer.serveEffect(app).pipe(
       Effect.provide(serverContext),
-      Effect.provideService(Scope.Scope, serverScope),
-      Effect.forkIn(serverScope)
+      Effect.forkScoped
     )
 
     return {
       codePromise: Deferred.await(deferred),
-      shutdown: Effect.gen(function*() {
-        yield* Fiber.interrupt(serverFiber)
-        yield* Scope.close(serverScope, Exit.void)
-      }),
       port
     }
   })

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(