@knpkv/atlassian-common 1.8.0 → 1.9.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @knpkv/atlassian-common
 
+## 1.9.1
+
+### Patch Changes
+
+- [#579](https://github.com/knpkv/npm/pull/579) [`61c930e`](https://github.com/knpkv/npm/commit/61c930e88f4a9d735522d6c7b052b72d13450a6f) Thanks [@konopkov](https://github.com/konopkov)! - Tests typecheck as part of `check`. `externalizeAdfMetadata` returns the sidecar type `hydrateAdfMetadata` takes.
+
+## 1.9.0
+
+### Minor Changes
+
+- [#479](https://github.com/knpkv/npm/pull/479) [`1ef1847`](https://github.com/knpkv/npm/commit/1ef1847c867f83de237dec1c454b6bb5e40183ef) Thanks [@konopkov](https://github.com/konopkov)! - One error report for every Atlassian CLI (`jira`, `confluence`, `atlassian`), from the new `@knpkv/atlassian-common/cli` subpath (`handleCliError`, `withCliErrorHandling`, `Verbose`, `commandArgs`, `verboseRequested`).
+
+  - A failed command prints the error's message; a defect prints `Error: <message>`. The full cause, with stack traces, prints only with the new global `--verbose` flag or `DEBUG=1`.
+  - jira: stderr no longer prints the pretty-printed cause and stack trace by default.
+  - atlassian: tagged errors print their message instead of `String(error)`, and defects are reported too.
+  - Help and usage errors that the CLI already rendered are not printed a second time. Exit codes are unchanged.
+
 ## 1.8.0
 
 ### Minor Changes

package/dist/bin.js

@@ -6,6 +6,7 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Stdio from "effect/Stdio";
 import pkg from "../package.json" with { type: "json" };
+import { Verbose, withCliErrorHandling } from "./cli/index.js";
 import { HomeDirectoryLive, inspectAllToolProfiles, migrateLegacyProfiles, refreshActiveProfiles, useProfileForAllTools } from "./config/index.js";
 const profileArg = Args.String("profile").pipe(Args.withDescription("Profile ID, name, site URL, cloud ID, or account ID"));
 const printStatuses = (statuses) => Effect.gen(function* () {
@@ -47,12 +48,12 @@ const profiles = Command.make("profiles").pipe(Command.withDescription("Manage s
 const authRefresh = Command.make("refresh", {}, () => refreshActiveProfiles().pipe(Effect.flatMap(printStatuses)))
     .pipe(Command.withDescription("Refresh expired active OAuth tokens"));
 const auth = Command.make("auth").pipe(Command.withDescription("Manage Atlassian authentication"), Command.withSubcommands([authRefresh]));
-const atlassian = Command.make("atlassian", {}, () => Console.log("Usage: atlassian profiles|auth")).pipe(Command.withDescription("Unified Atlassian profile manager"), Command.withSubcommands([profiles, auth]));
+const atlassian = Command.make("atlassian", {}, () => Console.log("Usage: atlassian profiles|auth")).pipe(Command.withDescription("Unified Atlassian profile manager"), Command.withGlobalFlags([Verbose]), Command.withSubcommands([profiles, auth]));
 const cli = Command.runWith(atlassian, { version: pkg.version });
 const program = Effect.gen(function* () {
     const stdio = yield* Stdio.Stdio;
     const args = yield* stdio.args;
     return yield* cli(args);
-}).pipe(Effect.provide(Layer.mergeAll(NodeServices.layer, NodeHttpClient.layerFetch, HomeDirectoryLive)), Effect.catch((error) => Console.error(String(error)).pipe(Effect.andThen(Effect.fail(error)))));
+}).pipe(withCliErrorHandling, Effect.provide(Layer.mergeAll(NodeServices.layer, NodeHttpClient.layerFetch, HomeDirectoryLive)));
 NodeRuntime.runMain(program, { disableErrorReporting: true });
 //# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * How an Atlassian command-line tool reports a failed run.
+ *
+ * **Mental model**
+ *
+ * - **The message is the report.** A failure prints its message; a defect prints `Error: <message>`;
+ *   an interruption prints `Interrupted`. The full cause, with stack traces, is for whoever asked for
+ *   it: `--verbose`, or `DEBUG=1` in the environment.
+ * - **What the CLI already showed is not repeated.** `Command.runWith` renders help and usage errors
+ *   itself and then fails with them, so those reasons are skipped unless verbose.
+ * - **The exit code is untouched.** The cause is reported and re-failed as it was, so a help request
+ *   still exits 0 and every failure still exits non-zero.
+ *
+ * @module
+ */
+import * as Cause from "effect/Cause";
+import { GlobalFlag } from "effect/cli";
+import * as Effect from "effect/Effect";
+import * as Stdio from "effect/Stdio";
+/** `--verbose`: print the full cause, with stack traces, when a command fails. Register on the root command. */
+export declare const Verbose: GlobalFlag.Setting<"verbose", boolean>;
+/** Whether `args` turn {@link Verbose} on, as the flag parser would read them. */
+export declare const verboseFlagIn: (args: ReadonlyArray<string>) => boolean;
+/**
+ * `args` without the {@link Verbose} flag and the value it consumed, for code that routes on the
+ * command words before the CLI parses them, such as choosing which service layer to build.
+ */
+export declare const commandArgs: (args: ReadonlyArray<string>) => ReadonlyArray<string>;
+/** `--verbose` in `args`, or `DEBUG=1`. Only `1`: `DEBUG` is also the debug package's namespace list. */
+export declare const verboseRequested: (args: ReadonlyArray<string>) => Effect.Effect<boolean>;
+/** Print a failed run's cause to stderr: each failure's message, or the full cause when verbose. */
+export declare const handleCliError: <E>(cause: Cause.Cause<E>, options: {
+    readonly verbose: boolean;
+}) => Effect.Effect<void>;
+/**
+ * Report a CLI program's failure with {@link handleCliError} and fail with the same cause. Apply it
+ * before providing `Stdio`, which it reads the arguments from.
+ */
+export declare const withCliErrorHandling: <A, E, R>(program: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R | Stdio.Stdio>;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,EAAkB,UAAU,EAAE,MAAM,YAAY,CAAA;AAGvD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAErC,gHAAgH;AAChH,eAAO,MAAM,OAAO,wCAKlB,CAAA;AAiDF,kFAAkF;AAClF,eAAO,MAAM,aAAa,SAAU,aAAa,CAAC,MAAM,CAAC,KAAG,OAA6C,CAAA;AAEzG;;;GAGG;AACH,eAAO,MAAM,WAAW,SAAU,aAAa,CAAC,MAAM,CAAC,KAAG,aAAa,CAAC,MAAM,CAA2B,CAAA;AAEzG,yGAAyG;AACzG,eAAO,MAAM,gBAAgB,SAAU,aAAa,CAAC,MAAM,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAMtC,CAAA;AAc9C,oGAAoG;AACpG,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,KAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAS3F,CAAA;AASzB;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,WACjC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC9B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAC0E,CAAA"}

package/dist/cli/index.js

@@ -0,0 +1,115 @@
+/**
+ * How an Atlassian command-line tool reports a failed run.
+ *
+ * **Mental model**
+ *
+ * - **The message is the report.** A failure prints its message; a defect prints `Error: <message>`;
+ *   an interruption prints `Interrupted`. The full cause, with stack traces, is for whoever asked for
+ *   it: `--verbose`, or `DEBUG=1` in the environment.
+ * - **What the CLI already showed is not repeated.** `Command.runWith` renders help and usage errors
+ *   itself and then fails with them, so those reasons are skipped unless verbose.
+ * - **The exit code is untouched.** The cause is reported and re-failed as it was, so a help request
+ *   still exits 0 and every failure still exits non-zero.
+ *
+ * @module
+ */
+import * as Cause from "effect/Cause";
+import { CliError, Flag, GlobalFlag } from "effect/cli";
+import * as Config from "effect/Config";
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Predicate from "effect/Predicate";
+import * as Stdio from "effect/Stdio";
+/** `--verbose`: print the full cause, with stack traces, when a command fails. Register on the root command. */
+export const Verbose = GlobalFlag.Setting("verbose")({
+    flag: Flag.Boolean("verbose").pipe(Flag.withDefault(false), Flag.withDescription("Print the full cause, with stack traces, when a command fails"))
+});
+const truthy = new Set(["true", "1", "y", "yes", "on"]);
+const falsy = new Set(["false", "0", "n", "no", "off"]);
+/** Exactly the literals `effect/cli` accepts for a boolean: lowercase only, so `FALSE` is not one. */
+const booleanLiteral = (token) => token === undefined ? undefined : truthy.has(token) ? true : falsy.has(token) ? false : undefined;
+/**
+ * Read {@link Verbose} out of `args` the way `effect/cli` parses a boolean flag: only before `--`;
+ * `--verbose` may take a following boolean literal (`--verbose false`), `--verbose=<boolean>` and
+ * `--no-verbose` are the other spellings, and the first occurrence decides the value.
+ */
+const scanVerbose = (args) => {
+    const end = args.indexOf("--");
+    const head = end === -1 ? args : args.slice(0, end);
+    const tail = end === -1 ? [] : args.slice(end);
+    const rest = [];
+    let verbose;
+    const settle = (value) => {
+        if (verbose === undefined)
+            verbose = value;
+    };
+    for (let index = 0; index < head.length; index++) {
+        const token = head[index];
+        if (token === "--verbose") {
+            const literal = booleanLiteral(head[index + 1]);
+            if (literal !== undefined)
+                index++;
+            settle(literal ?? true);
+        }
+        else if (token === "--no-verbose") {
+            settle(false);
+        }
+        else if (token.startsWith("--verbose=")) {
+            // A value that is not a boolean makes the parser fail; it never turns verbose on.
+            const literal = booleanLiteral(token.slice("--verbose=".length));
+            if (literal !== undefined)
+                settle(literal);
+        }
+        else {
+            rest.push(token);
+        }
+    }
+    return { rest: [...rest, ...tail], verbose };
+};
+/** Whether `args` turn {@link Verbose} on, as the flag parser would read them. */
+export const verboseFlagIn = (args) => scanVerbose(args).verbose === true;
+/**
+ * `args` without the {@link Verbose} flag and the value it consumed, for code that routes on the
+ * command words before the CLI parses them, such as choosing which service layer to build.
+ */
+export const commandArgs = (args) => scanVerbose(args).rest;
+/** `--verbose` in `args`, or `DEBUG=1`. Only `1`: `DEBUG` is also the debug package's namespace list. */
+export const verboseRequested = (args) => verboseFlagIn(args)
+    ? Effect.succeed(true)
+    : Effect.gen(function* () {
+        const debug = yield* Config.option(Config.String("DEBUG"));
+        return Option.getOrUndefined(debug) === "1";
+    }).pipe(Effect.orElseSucceed(() => false));
+const describe = (error) => {
+    if (Predicate.hasProperty(error, "message") && Predicate.isString(error.message) && error.message !== "") {
+        return error.message;
+    }
+    if (Predicate.hasProperty(error, "_tag") && Predicate.isString(error._tag))
+        return error._tag;
+    return String(error);
+};
+/** `Command.runWith` prints help and user errors itself before failing with them; nothing else. */
+const renderedByRunner = (error) => CliError.isCliError(error) && (error._tag === "ShowHelp" || error._tag === "UserError");
+/** Print a failed run's cause to stderr: each failure's message, or the full cause when verbose. */
+export const handleCliError = (cause, options) => options.verbose
+    ? Console.error(Cause.pretty(cause))
+    : Effect.forEach(cause.reasons, (reason) => {
+        if (Cause.isFailReason(reason)) {
+            return renderedByRunner(reason.error) ? Effect.void : Console.error(describe(reason.error));
+        }
+        if (Cause.isDieReason(reason))
+            return Console.error(`Error: ${describe(reason.defect)}`);
+        return Console.error("Interrupted");
+    }, { discard: true });
+const reportFailure = (cause) => Effect.gen(function* () {
+    const stdio = yield* Stdio.Stdio;
+    const verbose = yield* stdio.args.pipe(Effect.flatMap(verboseRequested), Effect.orElseSucceed(() => false));
+    yield* handleCliError(cause, { verbose });
+});
+/**
+ * Report a CLI program's failure with {@link handleCliError} and fail with the same cause. Apply it
+ * before providing `Stdio`, which it reads the arguments from.
+ */
+export const withCliErrorHandling = (program) => program.pipe(Effect.catchCause((cause) => reportFailure(cause).pipe(Effect.andThen(Effect.failCause(cause)))));
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knpkv/atlassian-common",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "description": "Shared utilities for Atlassian tools (AST, serializers, auth, config)",
   "license": "MIT",
   "author": "knpkv",
@@ -42,6 +42,10 @@
       "import": "./dist/auth/index.js",
       "types": "./dist/auth/index.d.ts"
     },
+    "./cli": {
+      "import": "./dist/cli/index.js",
+      "types": "./dist/cli/index.d.ts"
+    },
     "./cli-auth": {
       "import": "./dist/cli-auth/index.js",
       "types": "./dist/cli-auth/index.d.ts"
@@ -99,6 +103,6 @@
     "test:watch": "vitest",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit && tsc -p test/tsconfig.json --noEmit"
   }
 }

package/src/bin.ts

@@ -6,6 +6,7 @@ import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
 import * as Stdio from "effect/Stdio"
 import pkg from "../package.json" with { type: "json" }
+import { Verbose, withCliErrorHandling } from "./cli/index.js"
 import {
   HomeDirectoryLive,
   inspectAllToolProfiles,
@@ -90,6 +91,7 @@ const auth = Command.make("auth").pipe(
 
 const atlassian = Command.make("atlassian", {}, () => Console.log("Usage: atlassian profiles|auth")).pipe(
   Command.withDescription("Unified Atlassian profile manager"),
+  Command.withGlobalFlags([Verbose]),
   Command.withSubcommands([profiles, auth])
 )
 
@@ -99,15 +101,13 @@ const program = Effect.gen(function*() {
   const args = yield* stdio.args
   return yield* cli(args)
 }).pipe(
+  withCliErrorHandling,
   Effect.provide(
     Layer.mergeAll(
       NodeServices.layer,
       NodeHttpClient.layerFetch,
       HomeDirectoryLive
     )
-  ),
-  Effect.catch(<UnparsedInput>(error: UnparsedInput) =>
-    Console.error(String(error)).pipe(Effect.andThen(Effect.fail(error)))
   )
 )
 

package/src/cli/index.ts

@@ -0,0 +1,136 @@
+/**
+ * How an Atlassian command-line tool reports a failed run.
+ *
+ * **Mental model**
+ *
+ * - **The message is the report.** A failure prints its message; a defect prints `Error: <message>`;
+ *   an interruption prints `Interrupted`. The full cause, with stack traces, is for whoever asked for
+ *   it: `--verbose`, or `DEBUG=1` in the environment.
+ * - **What the CLI already showed is not repeated.** `Command.runWith` renders help and usage errors
+ *   itself and then fails with them, so those reasons are skipped unless verbose.
+ * - **The exit code is untouched.** The cause is reported and re-failed as it was, so a help request
+ *   still exits 0 and every failure still exits non-zero.
+ *
+ * @module
+ */
+import * as Cause from "effect/Cause"
+import { CliError, Flag, GlobalFlag } from "effect/cli"
+import * as Config from "effect/Config"
+import * as Console from "effect/Console"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import * as Stdio from "effect/Stdio"
+
+/** `--verbose`: print the full cause, with stack traces, when a command fails. Register on the root command. */
+export const Verbose = GlobalFlag.Setting("verbose")({
+  flag: Flag.Boolean("verbose").pipe(
+    Flag.withDefault(false),
+    Flag.withDescription("Print the full cause, with stack traces, when a command fails")
+  )
+})
+
+const truthy = new Set(["true", "1", "y", "yes", "on"])
+const falsy = new Set(["false", "0", "n", "no", "off"])
+
+/** Exactly the literals `effect/cli` accepts for a boolean: lowercase only, so `FALSE` is not one. */
+const booleanLiteral = (token: string | undefined): boolean | undefined =>
+  token === undefined ? undefined : truthy.has(token) ? true : falsy.has(token) ? false : undefined
+
+interface VerboseScan {
+  /** The value the flag parser settles on, or undefined when the flag is absent. */
+  readonly verbose: boolean | undefined
+  /** `args` with every token the flag consumed removed. */
+  readonly rest: ReadonlyArray<string>
+}
+
+/**
+ * Read {@link Verbose} out of `args` the way `effect/cli` parses a boolean flag: only before `--`;
+ * `--verbose` may take a following boolean literal (`--verbose false`), `--verbose=<boolean>` and
+ * `--no-verbose` are the other spellings, and the first occurrence decides the value.
+ */
+const scanVerbose = (args: ReadonlyArray<string>): VerboseScan => {
+  const end = args.indexOf("--")
+  const head = end === -1 ? args : args.slice(0, end)
+  const tail = end === -1 ? [] : args.slice(end)
+  const rest: Array<string> = []
+  let verbose: boolean | undefined
+  const settle = (value: boolean) => {
+    if (verbose === undefined) verbose = value
+  }
+  for (let index = 0; index < head.length; index++) {
+    const token = head[index]!
+    if (token === "--verbose") {
+      const literal = booleanLiteral(head[index + 1])
+      if (literal !== undefined) index++
+      settle(literal ?? true)
+    } else if (token === "--no-verbose") {
+      settle(false)
+    } else if (token.startsWith("--verbose=")) {
+      // A value that is not a boolean makes the parser fail; it never turns verbose on.
+      const literal = booleanLiteral(token.slice("--verbose=".length))
+      if (literal !== undefined) settle(literal)
+    } else {
+      rest.push(token)
+    }
+  }
+  return { rest: [...rest, ...tail], verbose }
+}
+
+/** Whether `args` turn {@link Verbose} on, as the flag parser would read them. */
+export const verboseFlagIn = (args: ReadonlyArray<string>): boolean => scanVerbose(args).verbose === true
+
+/**
+ * `args` without the {@link Verbose} flag and the value it consumed, for code that routes on the
+ * command words before the CLI parses them, such as choosing which service layer to build.
+ */
+export const commandArgs = (args: ReadonlyArray<string>): ReadonlyArray<string> => scanVerbose(args).rest
+
+/** `--verbose` in `args`, or `DEBUG=1`. Only `1`: `DEBUG` is also the debug package's namespace list. */
+export const verboseRequested = (args: ReadonlyArray<string>): Effect.Effect<boolean> =>
+  verboseFlagIn(args)
+    ? Effect.succeed(true)
+    : Effect.gen(function*() {
+      const debug = yield* Config.option(Config.String("DEBUG"))
+      return Option.getOrUndefined(debug) === "1"
+    }).pipe(Effect.orElseSucceed(() => false))
+
+const describe = <E>(error: E): string => {
+  if (Predicate.hasProperty(error, "message") && Predicate.isString(error.message) && error.message !== "") {
+    return error.message
+  }
+  if (Predicate.hasProperty(error, "_tag") && Predicate.isString(error._tag)) return error._tag
+  return String(error)
+}
+
+/** `Command.runWith` prints help and user errors itself before failing with them; nothing else. */
+const renderedByRunner = <E>(error: E): boolean =>
+  CliError.isCliError(error) && (error._tag === "ShowHelp" || error._tag === "UserError")
+
+/** Print a failed run's cause to stderr: each failure's message, or the full cause when verbose. */
+export const handleCliError = <E>(cause: Cause.Cause<E>, options: { readonly verbose: boolean }): Effect.Effect<void> =>
+  options.verbose
+    ? Console.error(Cause.pretty(cause))
+    : Effect.forEach(cause.reasons, (reason) => {
+      if (Cause.isFailReason(reason)) {
+        return renderedByRunner(reason.error) ? Effect.void : Console.error(describe(reason.error))
+      }
+      if (Cause.isDieReason(reason)) return Console.error(`Error: ${describe(reason.defect)}`)
+      return Console.error("Interrupted")
+    }, { discard: true })
+
+const reportFailure = <E>(cause: Cause.Cause<E>): Effect.Effect<void, never, Stdio.Stdio> =>
+  Effect.gen(function*() {
+    const stdio = yield* Stdio.Stdio
+    const verbose = yield* stdio.args.pipe(Effect.flatMap(verboseRequested), Effect.orElseSucceed(() => false))
+    yield* handleCliError(cause, { verbose })
+  })
+
+/**
+ * Report a CLI program's failure with {@link handleCliError} and fail with the same cause. Apply it
+ * before providing `Stdio`, which it reads the arguments from.
+ */
+export const withCliErrorHandling = <A, E, R>(
+  program: Effect.Effect<A, E, R>
+): Effect.Effect<A, E, R | Stdio.Stdio> =>
+  program.pipe(Effect.catchCause((cause) => reportFailure(cause).pipe(Effect.andThen(Effect.failCause(cause)))))

package/test/ApiUpdateWorkflows.test.ts

@@ -45,9 +45,11 @@ const PackageManifest = Schema.Struct({
 
 // Public generated subpaths or generated export targets declare the contract;
 // package names and consumer dependencies do not.
+const isJsonArray = Schema.is(Schema.Array(Schema.Json))
+
 const exposesGeneratedContract = (exports: Schema.Json): boolean => {
   if (Predicate.isString(exports)) return /(?:^|\/)generated(?:\/|$)/u.test(exports)
-  if (Array.isArray(exports)) return exports.some(exposesGeneratedContract)
+  if (isJsonArray(exports)) return exports.some(exposesGeneratedContract)
   if (!isRecord(exports)) return false
   return Object.entries(exports).some(([name, target]) =>
     /^\.\/generated(?:\/|$)/u.test(name) || exposesGeneratedContract(target)
@@ -178,7 +180,7 @@ const inspectApiUpdateWorkflows = Effect.fn("ApiUpdateWorkflows.inspectApiUpdate
   }
   const workflowRoot = path.join(root, ".github/workflows")
   const diagnostics: Array<string> = []
-  for (const name of (yield* fileSystem.readDirectory(workflowRoot)).toSorted()) {
+  for (const name of [...(yield* fileSystem.readDirectory(workflowRoot))].sort()) {
     if (!/-api-update\.ya?ml$/u.test(name)) continue
     const source = yield* fileSystem.readFileString(path.join(workflowRoot, name))
     for (const diagnostic of patchGuidanceDiagnostics(source, generatedClientNames)) {

package/test/AuthProfiles.test.ts

@@ -2,10 +2,11 @@ import { describe, expect, it } from "@effect/vitest"
 import { ConfigProvider, Effect, Layer } from "effect"
 import * as FileSystem from "effect/FileSystem"
 import * as Path from "effect/Path"
-import { SystemError } from "effect/PlatformError"
+import { PlatformError, SystemError } from "effect/PlatformError"
 import {
   deleteProfileBySelector,
   HomeDirectoryLive,
+  type HomeDirectoryTag,
   loadActiveProfileToken,
   loadProfiles,
   type OAuthToken,
@@ -21,7 +22,9 @@ const profilesPath = `${basePath}/profiles.json`
 
 const fsError = (method: string) =>
   Effect.fail(
-    new SystemError({ _tag: "NotFound", module: "FileSystem", method, description: "mock not found" })
+    new PlatformError(
+      new SystemError({ _tag: "NotFound", module: "FileSystem", method, description: "mock not found" })
+    )
   )
 
 const makeToken = (n: number): OAuthToken => ({
@@ -57,7 +60,7 @@ const makeMockFS = (files: Record<string, string> = {}) => {
 
   return {
     store,
-    layer: Layer.succeed(FileSystem.FileSystem, FileSystem.FileSystem.of(partial))
+    layer: FileSystem.layerNoop(partial)
   }
 }
 
@@ -66,7 +69,7 @@ const ConfigProviderLive = ConfigProvider.layer(
 )
 
 const run = <A>(
-  effect: Effect.Effect<A, unknown, FileSystem.FileSystem | Path.Path>,
+  effect: Effect.Effect<A, unknown, FileSystem.FileSystem | Path.Path | HomeDirectoryTag>,
   files?: Record<string, string>
 ) => {
   const mock = makeMockFS(files)

package/test/ProfileManager.test.ts

@@ -6,10 +6,11 @@ import * as Fiber from "effect/Fiber"
 import * as FileSystem from "effect/FileSystem"
 import { HttpClient, HttpClientResponse } from "effect/http"
 import * as Path from "effect/Path"
-import { SystemError } from "effect/PlatformError"
+import { PlatformError, SystemError } from "effect/PlatformError"
 import {
   type AtlassianToolDefinition,
   HomeDirectoryLive,
+  type HomeDirectoryTag,
   inspectAllToolProfiles,
   migrateLegacyProfiles,
   MissingOAuthConfigError,
@@ -39,7 +40,11 @@ const sharedStoreTools: ReadonlyArray<AtlassianToolDefinition> = [
 ]
 
 const fsError = (method: string) =>
-  Effect.fail(new SystemError({ _tag: "NotFound", module: "FileSystem", method, description: "mock not found" }))
+  Effect.fail(
+    new PlatformError(
+      new SystemError({ _tag: "NotFound", module: "FileSystem", method, description: "mock not found" })
+    )
+  )
 
 const makeToken = (n: number, scope = "read:me offline_access", expiresAt = Date.now() + 60_000): OAuthToken => ({
   access_token: `access-${n}`,
@@ -69,13 +74,13 @@ const makeMockFS = () => {
   }
   return {
     store,
-    layer: Layer.succeed(FileSystem.FileSystem, FileSystem.FileSystem.of(partial))
+    layer: FileSystem.layerNoop(partial)
   }
 }
 
 const ConfigProviderLive = ConfigProvider.layer(ConfigProvider.fromEnv({ env: { HOME: TEST_HOME } }))
 
-const run = async <A>(effect: Effect.Effect<A, unknown, FileSystem.FileSystem | Path.Path>) => {
+const run = async <A>(effect: Effect.Effect<A, unknown, FileSystem.FileSystem | Path.Path | HomeDirectoryTag>) => {
   const mock = makeMockFS()
   const layer = Layer.mergeAll(mock.layer, Path.layer, HomeDirectoryLive, ConfigProviderLive)
   const result = await Effect.runPromise(effect.pipe(Effect.provide(layer)))
@@ -242,7 +247,10 @@ describe("ProfileManager", () => {
         Effect.gen(function*() {
           yield* saveProfileToken("tool-a", makeToken(1, "read:me offline_access", Date.now() - 1_000))
           return yield* refreshActiveProfiles([tools[0]!])
-        })
+        }).pipe(
+          // The refresh fails on configuration before any request; a request would be a regression.
+          Effect.provideService(HttpClient.HttpClient, HttpClient.make(() => Effect.die("no request expected")))
+        )
       )
     ).rejects.toBeInstanceOf(MissingOAuthConfigError)
   })

package/test/PublicExports.test.ts

@@ -1,3 +1,4 @@
+import { describe, expect, it } from "@effect/vitest"
 import { JIRA_PROPOSAL_SCOPES, JIRA_SCOPES } from "../src/auth/index.js"
 import { JIRA_PROPOSAL_REQUIRED_SCOPES, JIRA_REQUIRED_SCOPES } from "../src/config/index.js"
 

package/test/cli.errorHandling.test.ts

@@ -0,0 +1,145 @@
+/** @effect-diagnostics strictEffectProvide:skip-file */
+/**
+ * How every Atlassian CLI reports a failed run: the message by default, the full cause when asked,
+ * nothing for what `Command.runWith` already rendered, and the exit unchanged.
+ */
+import { NodeServices } from "@effect/platform-node"
+import { describe, expect, it } from "@effect/vitest"
+import { ConfigProvider } from "effect"
+import * as Cause from "effect/Cause"
+import { Argument, CliError, Command } from "effect/cli"
+import * as Console from "effect/Console"
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import * as Schema from "effect/Schema"
+import * as Stdio from "effect/Stdio"
+import {
+  commandArgs,
+  handleCliError,
+  Verbose,
+  verboseFlagIn,
+  verboseRequested,
+  withCliErrorHandling
+} from "../src/cli/index.js"
+
+class ProfileGone extends Schema.TaggedError<ProfileGone>()("ProfileGone", { message: Schema.String }) {}
+class Bare extends Schema.TaggedError<Bare>()("Bare", {}) {}
+
+const stderrOf = <E>(cause: Cause.Cause<E>, verbose: boolean) =>
+  Effect.gen(function*() {
+    const lines: Array<string> = []
+    const capture: Console.Console = Object.assign(Object.create(console), {
+      error: (...parts: ReadonlyArray<unknown>) => lines.push(parts.join(" "))
+    })
+    yield* handleCliError(cause, { verbose }).pipe(Effect.provideService(Console.Console, capture))
+    return lines
+  })
+
+describe("handleCliError", () => {
+  it.effect("prints a failure's message, a bare tagged error's tag, a defect and an interruption", () =>
+    Effect.gen(function*() {
+      expect(yield* stderrOf(Cause.fail(new ProfileGone({ message: "Profile not found: x" })), false)).toEqual([
+        "Profile not found: x"
+      ])
+      expect(yield* stderrOf(Cause.fail(new Bare()), false)).toEqual(["Bare"])
+      expect(yield* stderrOf(Cause.die(new Error("boom")), false)).toEqual(["Error: boom"])
+      expect(yield* stderrOf(Cause.interrupt(), false)).toEqual(["Interrupted"])
+    }))
+
+  it.effect("skips what Command.runWith already rendered", () =>
+    Effect.gen(function*() {
+      const help = new CliError.ShowHelp({ commandPath: ["jira"], errors: [] })
+      expect(yield* stderrOf(Cause.fail(help), false)).toEqual([])
+    }))
+
+  it.effect("prints the full cause, stack included, when verbose", () =>
+    Effect.gen(function*() {
+      const lines = yield* stderrOf(Cause.die(new Error("boom")), true)
+      expect(lines.join("\n")).toContain("boom")
+      expect(lines.join("\n")).toContain("at ")
+    }))
+})
+
+describe("verbose", () => {
+  // The scanner runs before the CLI parses, so it must agree with the parser it stands in for.
+  const parsed = (args: ReadonlyArray<string>) =>
+    Effect.gen(function*() {
+      const seen: Array<boolean> = []
+      const probe = Command.make("probe", { words: Argument.String("word").pipe(Argument.variadic()) }, () =>
+        Effect.gen(function*() {
+          seen.push(yield* Verbose)
+        }))
+      const root = Command.make("tool").pipe(Command.withSubcommands([probe]), Command.withGlobalFlags([Verbose]))
+      const exit = yield* Command.runWith(root, { version: "0" })(args).pipe(
+        Effect.provide(NodeServices.layer),
+        Effect.exit
+      )
+      return { exit, verbose: seen[0] }
+    })
+
+  it.effect("reads --verbose and routes the command words exactly as the parser does", () =>
+    Effect.gen(function*() {
+      const cases: ReadonlyArray<ReadonlyArray<string>> = [
+        ["probe", "x"],
+        ["--verbose", "probe", "x"],
+        ["--verbose", "false", "probe", "x"],
+        ["--verbose", "true", "probe", "x"],
+        ["--verbose=false", "probe", "x"],
+        ["--verbose=yes", "probe", "x"],
+        ["probe", "x", "--verbose"],
+        ["--verbose", "--no-verbose", "probe", "x"],
+        ["--no-verbose", "--verbose", "probe", "x"],
+        ["probe", "--", "--verbose"],
+        ["probe", "x", "--verbose", "FALSE"],
+        ["probe", "x", "--verbose", "True"]
+      ]
+      for (const args of cases) {
+        const { exit, verbose } = yield* parsed(args)
+        expect(Exit.isSuccess(exit), JSON.stringify(args)).toBe(true)
+        expect(verboseFlagIn(args), JSON.stringify(args)).toBe(verbose)
+        expect(commandArgs(args)[0], JSON.stringify(args)).toBe("probe")
+        // A literal the parser does not consume stays a positional word.
+        for (const word of ["FALSE", "True"]) {
+          if (args.includes(word)) expect(commandArgs(args), JSON.stringify(args)).toContain(word)
+        }
+      }
+    }))
+
+  it.effect("does not report verbose for a value the parser rejects, and the rejection is printed", () =>
+    Effect.gen(function*() {
+      expect(verboseFlagIn(["--verbose=bogus", "probe"])).toBe(false)
+      expect(verboseFlagIn(["--verbose=FALSE", "probe"])).toBe(false)
+      const { exit } = yield* parsed(["--verbose=bogus", "probe", "x"])
+      expect(Exit.isFailure(exit)).toBe(true)
+      if (Exit.isFailure(exit)) {
+        const lines = yield* stderrOf(exit.cause, false)
+        expect(lines).toHaveLength(1)
+        expect(lines[0]).toContain("bogus")
+      }
+    }))
+
+  it.effect("turns on for DEBUG=1 only", () =>
+    Effect.gen(function*() {
+      const withEnv = (env: Record<string, string>) =>
+        verboseRequested([]).pipe(Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnv({ env }))))
+      expect(yield* withEnv({ DEBUG: "1" })).toBe(true)
+      expect(yield* withEnv({ DEBUG: "express:*" })).toBe(false)
+      expect(yield* withEnv({})).toBe(false)
+    }))
+
+  it.effect("reports with --verbose from the arguments, and fails with the same cause", () =>
+    Effect.gen(function*() {
+      const lines: Array<string> = []
+      const capture: Console.Console = Object.assign(Object.create(console), {
+        error: (...parts: ReadonlyArray<unknown>) => lines.push(parts.join(" "))
+      })
+      const failure = new ProfileGone({ message: "Profile not found: x" })
+      const exit = yield* withCliErrorHandling(Effect.fail(failure)).pipe(
+        Effect.provideService(Console.Console, capture),
+        Effect.provide(Stdio.layerTest({ args: Effect.succeed(["auth", "use", "x", "--verbose"]) })),
+        Effect.exit
+      )
+      expect(Exit.isFailure(exit) && Cause.squash(exit.cause)).toBe(failure)
+      expect(lines.join("\n")).toContain("ProfileGone")
+    }))
+})

package/test/cliAuth.authCommand.test.ts

@@ -73,7 +73,6 @@ const launchers = (opens: boolean) =>
           isRunning: Effect.succeed(false),
           kill: () => Effect.void,
           pid: ChildProcessSpawner.ProcessId(1),
-          reref: Effect.void,
           stderr: Stream.empty,
           stdin: Sink.drain,
           stdout: Stream.empty,

package/test/cliAuth.guardrails.test.ts

@@ -4,6 +4,7 @@ import { describe, expect, it } from "@effect/vitest"
 import * as Effect from "effect/Effect"
 import * as FileSystem from "effect/FileSystem"
 import * as Path from "effect/Path"
+import * as Predicate from "effect/Predicate"
 import { ChildProcess, ChildProcessSpawner } from "effect/process"
 import * as Schema from "effect/Schema"
 import * as Stream from "effect/Stream"
@@ -19,10 +20,11 @@ const Findings = Schema.fromJsonString(Schema.Array(Schema.Struct({ file: Schema
 describe("CLI auth guardrails", () => {
   for (const [name, config] of Object.entries(configs)) {
     it(`${name} resolves CLI auth from source rather than stale build output`, () => {
-      expect(config.resolve?.alias).toHaveProperty(
-        "@knpkv/atlassian-common/cli-auth",
-        new URL("../src/cli-auth/index.ts", import.meta.url).pathname
-      )
+      const aliases = config.resolve?.alias
+      const entries = Array.isArray(aliases) ? aliases : []
+      const specifier = "@knpkv/atlassian-common/cli-auth"
+      const cliAuth = entries.find(({ find }) => Predicate.isString(find) ? find === specifier : find.test(specifier))
+      expect(cliAuth?.replacement).toBe(new URL("../src/cli-auth/index.ts", import.meta.url).pathname)
     })
   }
 

package/test/cliAuth.login.test.ts

@@ -118,7 +118,6 @@ const failingLaunchers = (launched: Deferred.Deferred<string>, attempts: Ref.Ref
           isRunning: Effect.succeed(false),
           kill: () => Effect.void,
           pid: ChildProcessSpawner.ProcessId(1),
-          reref: Effect.void,
           stderr: Stream.empty,
           stdin: Sink.drain,
           stdout: Stream.empty,

package/test/cliAuth.openBrowser.test.ts

@@ -32,7 +32,6 @@ const launchers = (outcomes: Readonly<Record<string, number>>, attempts: Array<s
         isRunning: Effect.succeed(false),
         kill: () => Effect.void,
         pid: ChildProcessSpawner.ProcessId(1),
-        reref: Effect.void,
         stderr: Stream.empty,
         stdin: Sink.drain,
         stdout: Stream.empty,

package/test/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "composite": false,
+    "declaration": false,
+    "declarationMap": false,
+    "rootDir": "../../..",
+    "outDir": null,
+    "tsBuildInfoFile": null
+  },
+  "include": ["../src", "."],
+  "exclude": []
+}

package/vitest.config.ts

@@ -1,6 +1,8 @@
 import { defineConfig } from "vitest/config"
+import { workspaceSourceAlias } from "../../vitest.workspace-sources.ts"
 
 export default defineConfig({
+  resolve: { alias: [...workspaceSourceAlias] },
   test: {
     include: ["test/**/*.test.ts"],
     globals: true,