@agentxm/client-core 0.1.6

package/dist/src/unstable/cli-runtime/handle-error.js

@@ -0,0 +1,87 @@
+import { CliError } from "effect/unstable/cli";
+import { isEffectCliExit } from "./effect-cli-exit.js";
+import { makeJsonErrorEnvelope } from "./json-envelope.js";
+const writeStderr = (message) => {
+    process.stderr.write(message.endsWith("\n") ? message : `${message}\n`);
+};
+/**
+ * Pure error classification — determines exit code and output without side effects.
+ *
+ * Channel routing per format:
+ * - text:        human-readable to stderr only (no stdout pollution)
+ * - json:        typed error JSON to stdout + brief message to stderr
+ * Exit codes:
+ * - ShowHelp (no errors) → 0 (help successfully displayed)
+ * - ShowHelp (with errors) → 1 (help displayed due to usage error)
+ * - EffectCliExit → custom exit code
+ * - CliError → 2 (usage/validation — bad flags, missing args)
+ * - Other → 1 (application/runtime)
+ */
+export const classifyError = (error, format) => {
+    if (isEffectCliExit(error)) {
+        return { exitCode: error.exitCode };
+    }
+    if (CliError.isCliError(error)) {
+        if (error._tag === "ShowHelp") {
+            return { exitCode: error.errors.length > 0 ? 1 : 0 };
+        }
+        if (format !== "text") {
+            const message = "errors" in error && Array.isArray(error.errors) && error.errors.length > 0
+                ? error.errors.map((e) => e.message ?? String(e)).join("; ")
+                : error.message;
+            return {
+                exitCode: 2,
+                output: {
+                    channel: "stdout",
+                    content: JSON.stringify(makeJsonErrorEnvelope({
+                        code: "USAGE_ERROR",
+                        message,
+                        exitCode: 2,
+                    }), null, 2) + "\n",
+                },
+            };
+        }
+        return { exitCode: 2 };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error instanceof Error && "code" in error ? String(error.code) : "UNKNOWN_ERROR";
+    if (format === "text") {
+        return {
+            exitCode: 1,
+            output: { channel: "stderr", content: `\u2717 ${message}` },
+        };
+    }
+    return {
+        exitCode: 1,
+        output: {
+            channel: "stdout",
+            content: JSON.stringify(makeJsonErrorEnvelope({
+                code,
+                message,
+                exitCode: 1,
+            }), null, 2) + "\n",
+        },
+        stderrMessage: `\u2717 ${message}`,
+    };
+};
+/**
+ * Error routing based on output mode.
+ *
+ * Classifies the error, writes output to the appropriate channel, and exits.
+ */
+export const handleError = (error, format) => {
+    const result = classifyError(error, format);
+    if (result.output) {
+        if (result.output.channel === "stdout") {
+            process.stdout.write(result.output.content);
+            if (result.stderrMessage) {
+                writeStderr(result.stderrMessage);
+            }
+        }
+        else {
+            writeStderr(result.output.content);
+        }
+    }
+    process.exit(result.exitCode);
+};
+//# sourceMappingURL=handle-error.js.map

package/dist/src/unstable/cli-runtime/handle-error.js.map

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

package/dist/src/unstable/cli-runtime/index.d.ts

@@ -0,0 +1,16 @@
+export type { OutputFormat, ProgressEvent, LogEvent, ErrorEvent, StreamEvent, } from "./output-mode.js";
+export { ProgressEventSchema, LogEventSchema, ErrorEventSchema, emitEvent } from "./output-mode.js";
+export { JsonSchemaVersion, JsonSchemaVersionSchema, JsonErrorEnvelopeSchema, makeJsonErrorEnvelope, makeJsonErrorEnvelopeFromAppError, type JsonErrorEnvelope, } from "./json-envelope.js";
+export { makeCommandDocument, makeCommandDocumentSchema, type CommandDocument, } from "./command-document.js";
+export { EffectCliExit, effectCliExit, isEffectCliExit } from "./effect-cli-exit.js";
+export { resolveFormatFromArgv, resolveFormat } from "./resolve-format.js";
+export { handleError, classifyError, type ErrorClassification } from "./handle-error.js";
+export { withGracefulShutdown } from "./graceful-shutdown.js";
+export { removeBuiltInFlag } from "./effect-cli-builtins.js";
+export { runCliMain, resolveCliContext, type CliMainContext } from "./run-cli-main.js";
+export { makeCliTelemetryLayer, type CliTelemetryConfigService } from "./telemetry-layer.js";
+export { type CliRuntimeFoundation, type WithCliRuntimeOptions, withCliRuntime, type ExpectedCliError, makeFoundationLayer, resolveCliFormat, withCliErrorHandling, } from "./runtime-envelope.js";
+export { trackCliCommand, trackCliCommandCompleted, reportCliDefect, reportCliError, setCommandSemanticProperties, getCommandSemanticProperties, CommandSemanticProperties, CommandSemanticPropertiesLive, type CommandSemanticPropertiesService, type CliCommandTelemetryOptions, type CliCommandCompletedOptions, } from "./telemetry.js";
+export { CommandArgv, type CommandArgvService, withArgvTracking, serializeArgv, extractParamKinds, } from "./command-argv.js";
+export { summarizeCommandOutcome, type CommandOutcomeSummary, type CommandOutcome, type SubjectType, type SourceKind, } from "./command-summary.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/unstable/cli-runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/unstable/cli-runtime/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,UAAU,EACV,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpG,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,iCAAiC,EACjC,KAAK,iBAAiB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,KAAK,eAAe,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACrF,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACzF,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACvF,OAAO,EAAE,qBAAqB,EAAE,KAAK,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAC7F,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,cAAc,EACd,KAAK,gBAAgB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,4BAA4B,EAC5B,4BAA4B,EAC5B,yBAAyB,EACzB,6BAA6B,EAC7B,KAAK,gCAAgC,EACrC,KAAK,0BAA0B,EAC/B,KAAK,0BAA0B,GAChC,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,WAAW,EACX,KAAK,kBAAkB,EACvB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,UAAU,GAChB,MAAM,sBAAsB,CAAC"}

package/dist/src/unstable/cli-runtime/index.js

@@ -0,0 +1,15 @@
+export { ProgressEventSchema, LogEventSchema, ErrorEventSchema, emitEvent } from "./output-mode.js";
+export { JsonSchemaVersion, JsonSchemaVersionSchema, JsonErrorEnvelopeSchema, makeJsonErrorEnvelope, makeJsonErrorEnvelopeFromAppError, } from "./json-envelope.js";
+export { makeCommandDocument, makeCommandDocumentSchema, } from "./command-document.js";
+export { EffectCliExit, effectCliExit, isEffectCliExit } from "./effect-cli-exit.js";
+export { resolveFormatFromArgv, resolveFormat } from "./resolve-format.js";
+export { handleError, classifyError } from "./handle-error.js";
+export { withGracefulShutdown } from "./graceful-shutdown.js";
+export { removeBuiltInFlag } from "./effect-cli-builtins.js";
+export { runCliMain, resolveCliContext } from "./run-cli-main.js";
+export { makeCliTelemetryLayer } from "./telemetry-layer.js";
+export { withCliRuntime, makeFoundationLayer, resolveCliFormat, withCliErrorHandling, } from "./runtime-envelope.js";
+export { trackCliCommand, trackCliCommandCompleted, reportCliDefect, reportCliError, setCommandSemanticProperties, getCommandSemanticProperties, CommandSemanticProperties, CommandSemanticPropertiesLive, } from "./telemetry.js";
+export { CommandArgv, withArgvTracking, serializeArgv, extractParamKinds, } from "./command-argv.js";
+export { summarizeCommandOutcome, } from "./command-summary.js";
+//# sourceMappingURL=index.js.map

package/dist/src/unstable/cli-runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/unstable/cli-runtime/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpG,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,iCAAiC,GAElC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,mBAAmB,EACnB,yBAAyB,GAE1B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACrF,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,aAAa,EAA4B,MAAM,mBAAmB,CAAC;AACzF,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAuB,MAAM,mBAAmB,CAAC;AACvF,OAAO,EAAE,qBAAqB,EAAkC,MAAM,sBAAsB,CAAC;AAC7F,OAAO,EAGL,cAAc,EAEd,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,4BAA4B,EAC5B,4BAA4B,EAC5B,yBAAyB,EACzB,6BAA6B,GAI9B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,WAAW,EAEX,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,uBAAuB,GAKxB,MAAM,sBAAsB,CAAC"}

package/dist/src/unstable/cli-runtime/json-envelope.d.ts

@@ -0,0 +1,23 @@
+import * as Schema from "effect/Schema";
+import type { AppError } from "../app-error/index.js";
+export declare const JsonSchemaVersion = 1;
+export declare const JsonSchemaVersionSchema: Schema.Literal<1>;
+export declare const JsonErrorEnvelopeSchema: Schema.Struct<{
+    readonly _version: Schema.Literal<1>;
+    readonly type: Schema.Literal<"error">;
+    readonly code: Schema.String;
+    readonly message: Schema.String;
+    readonly details: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly howToFix: Schema.optional<Schema.String>;
+    readonly exitCode: Schema.Number;
+}>;
+export type JsonErrorEnvelope = typeof JsonErrorEnvelopeSchema.Type;
+export declare const makeJsonErrorEnvelope: (args: {
+    readonly code: string;
+    readonly message: string;
+    readonly details?: ReadonlyArray<string>;
+    readonly howToFix?: string;
+    readonly exitCode: number;
+}) => JsonErrorEnvelope;
+export declare const makeJsonErrorEnvelopeFromAppError: (error: AppError, exitCode: number) => JsonErrorEnvelope;
+//# sourceMappingURL=json-envelope.d.ts.map

package/dist/src/unstable/cli-runtime/json-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-envelope.d.ts","sourceRoot":"","sources":["../../../../src/unstable/cli-runtime/json-envelope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,eAAO,MAAM,uBAAuB,mBAAoC,CAAC;AAEzE,eAAO,MAAM,uBAAuB;;;;;;;;EAYlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,uBAAuB,CAAC,IAAI,CAAC;AAEpE,eAAO,MAAM,qBAAqB,GAAI,MAAM;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,KAAG,iBAQF,CAAC;AAEH,eAAO,MAAM,iCAAiC,GAC5C,OAAO,QAAQ,EACf,UAAU,MAAM,KACf,iBAOC,CAAC"}

package/dist/src/unstable/cli-runtime/json-envelope.js

@@ -0,0 +1,34 @@
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+export const JsonSchemaVersion = 1;
+export const JsonSchemaVersionSchema = Schema.Literal(JsonSchemaVersion);
+export const JsonErrorEnvelopeSchema = Schema.Struct({
+    _version: JsonSchemaVersionSchema,
+    type: Schema.Literal("error"),
+    code: Schema.String,
+    message: Schema.String,
+    details: Schema.optional(Schema.Array(Schema.String)),
+    howToFix: Schema.optional(Schema.String),
+    exitCode: Schema.Number,
+}).annotate({
+    identifier: "JsonErrorEnvelope",
+    title: "JSON Error Envelope",
+    description: "Structured JSON error envelope for machine-readable CLI error output.",
+});
+export const makeJsonErrorEnvelope = (args) => ({
+    _version: JsonSchemaVersion,
+    type: "error",
+    code: args.code,
+    message: args.message,
+    ...(args.details !== undefined && args.details.length > 0 ? { details: [...args.details] } : {}),
+    ...(args.howToFix !== undefined ? { howToFix: args.howToFix } : {}),
+    exitCode: args.exitCode,
+});
+export const makeJsonErrorEnvelopeFromAppError = (error, exitCode) => makeJsonErrorEnvelope({
+    code: error.code,
+    message: error.what,
+    details: error.details,
+    ...(Option.isSome(error.howToFix) ? { howToFix: error.howToFix.value } : {}),
+    exitCode,
+});
+//# sourceMappingURL=json-envelope.js.map

package/dist/src/unstable/cli-runtime/json-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-envelope.js","sourceRoot":"","sources":["../../../../src/unstable/cli-runtime/json-envelope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAIxC,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAEnC,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEzE,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,MAAM,CAAC;IACnD,QAAQ,EAAE,uBAAuB;IACjC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC,MAAM;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM;IACtB,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACrD,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC,MAAM;CACxB,CAAC,CAAC,QAAQ,CAAC;IACV,UAAU,EAAE,mBAAmB;IAC/B,KAAK,EAAE,qBAAqB;IAC5B,WAAW,EAAE,uEAAuE;CACrF,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,IAMrC,EAAqB,EAAE,CAAC,CAAC;IACxB,QAAQ,EAAE,iBAAiB;IAC3B,IAAI,EAAE,OAAO;IACb,IAAI,EAAE,IAAI,CAAC,IAAI;IACf,OAAO,EAAE,IAAI,CAAC,OAAO;IACrB,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAChG,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACnE,QAAQ,EAAE,IAAI,CAAC,QAAQ;CACxB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAC/C,KAAe,EACf,QAAgB,EACG,EAAE,CACrB,qBAAqB,CAAC;IACpB,IAAI,EAAE,KAAK,CAAC,IAAI;IAChB,OAAO,EAAE,KAAK,CAAC,IAAI;IACnB,OAAO,EAAE,KAAK,CAAC,OAAO;IACtB,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5E,QAAQ;CACT,CAAC,CAAC"}

package/dist/src/unstable/cli-runtime/output-mode.d.ts

@@ -0,0 +1,32 @@
+import * as Schema from "effect/Schema";
+import { JsonSchemaVersion } from "./json-envelope.js";
+export type OutputFormat = "text" | "json";
+export declare const ProgressEventSchema: Schema.Struct<{
+    readonly _version: Schema.Literal<1>;
+    readonly type: Schema.Literal<"progress">;
+    readonly phase: Schema.String;
+    readonly percent: Schema.Number;
+    readonly message: Schema.String;
+}>;
+export type ProgressEvent = typeof ProgressEventSchema.Type;
+export declare const LogEventSchema: Schema.Struct<{
+    readonly _version: Schema.Literal<1>;
+    readonly type: Schema.Literal<"log">;
+    readonly level: Schema.Literals<readonly ["info", "warn", "error"]>;
+    readonly message: Schema.String;
+}>;
+export type LogEvent = typeof LogEventSchema.Type;
+export declare const ErrorEventSchema: Schema.Struct<{
+    readonly _version: Schema.Literal<1>;
+    readonly type: Schema.Literal<"error">;
+    readonly code: Schema.String;
+    readonly message: Schema.String;
+    readonly details: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly howToFix: Schema.optional<Schema.String>;
+    readonly exitCode: Schema.optional<Schema.Number>;
+}>;
+export type ErrorEvent = typeof ErrorEventSchema.Type;
+export type StreamEvent = ProgressEvent | LogEvent | ErrorEvent;
+export declare const emitEvent: (event: StreamEvent) => import("effect/Effect").Effect<void, never, never>;
+export { JsonSchemaVersion };
+//# sourceMappingURL=output-mode.d.ts.map

package/dist/src/unstable/cli-runtime/output-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-mode.d.ts","sourceRoot":"","sources":["../../../../src/unstable/cli-runtime/output-mode.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,EAAE,iBAAiB,EAA2B,MAAM,oBAAoB,CAAC;AAMhF,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAe3C,eAAO,MAAM,mBAAmB;;;;;;EAU9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,mBAAmB,CAAC,IAAI,CAAC;AAE5D,eAAO,MAAM,cAAc;;;;;EAazB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,cAAc,CAAC,IAAI,CAAC;AAElD,eAAO,MAAM,gBAAgB;;;;;;;;EAY3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAC;AAEtD,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,QAAQ,GAAG,UAAU,CAAC;AAMhE,eAAO,MAAM,SAAS,GAAI,OAAO,WAAW,uDAAyC,CAAC;AAEtF,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/src/unstable/cli-runtime/output-mode.js

@@ -0,0 +1,59 @@
+import * as Console from "effect/Console";
+import * as Schema from "effect/Schema";
+import { JsonSchemaVersion, JsonSchemaVersionSchema } from "./json-envelope.js";
+// ---------------------------------------------------------------------------
+// NDJSON event schemas — typed contract for machine-mode stderr events
+//
+// Machine mode emits a sequence of independently-parseable JSON lines (NDJSON)
+// on stderr. Each line has a "type" discriminator so consumers can route
+// events without buffering the full stream:
+//
+//   progress → drive progress bars (phase, percent, message)
+//   log      → informational messages at different severity levels
+//   error    → typed error with stable code for programmatic handling
+//   result   → final output (emitted last, wraps command-specific data)
+// ---------------------------------------------------------------------------
+export const ProgressEventSchema = Schema.Struct({
+    _version: JsonSchemaVersionSchema,
+    type: Schema.Literal("progress"),
+    phase: Schema.String,
+    percent: Schema.Number,
+    message: Schema.String,
+}).annotate({
+    identifier: "ProgressEvent",
+    title: "Progress Event",
+    description: "NDJSON progress event for driving progress bars in machine mode.",
+});
+export const LogEventSchema = Schema.Struct({
+    _version: JsonSchemaVersionSchema,
+    type: Schema.Literal("log"),
+    level: Schema.Literals(["info", "warn", "error"]).annotate({
+        identifier: "LogLevel",
+        title: "Log Level",
+        description: "Severity level for log events.",
+    }),
+    message: Schema.String,
+}).annotate({
+    identifier: "LogEvent",
+    title: "Log Event",
+    description: "NDJSON log event for informational messages at different severity levels.",
+});
+export const ErrorEventSchema = Schema.Struct({
+    _version: JsonSchemaVersionSchema,
+    type: Schema.Literal("error"),
+    code: Schema.String,
+    message: Schema.String,
+    details: Schema.optional(Schema.Array(Schema.String)),
+    howToFix: Schema.optional(Schema.String),
+    exitCode: Schema.optional(Schema.Number),
+}).annotate({
+    identifier: "ErrorEvent",
+    title: "Error Event",
+    description: "NDJSON error event with a stable error code for programmatic handling.",
+});
+// ---------------------------------------------------------------------------
+// Event emitter — writes a single NDJSON line to stderr
+// ---------------------------------------------------------------------------
+export const emitEvent = (event) => Console.error(JSON.stringify(event));
+export { JsonSchemaVersion };
+//# sourceMappingURL=output-mode.js.map

package/dist/src/unstable/cli-runtime/output-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-mode.js","sourceRoot":"","sources":["../../../../src/unstable/cli-runtime/output-mode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAQhF,8EAA8E;AAC9E,uEAAuE;AACvE,EAAE;AACF,+EAA+E;AAC/E,yEAAyE;AACzE,4CAA4C;AAC5C,EAAE;AACF,6DAA6D;AAC7D,mEAAmE;AACnE,sEAAsE;AACtE,wEAAwE;AACxE,8EAA8E;AAE9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/C,QAAQ,EAAE,uBAAuB;IACjC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC,MAAM;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM;CACvB,CAAC,CAAC,QAAQ,CAAC;IACV,UAAU,EAAE,eAAe;IAC3B,KAAK,EAAE,gBAAgB;IACvB,WAAW,EAAE,kEAAkE;CAChF,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;IAC1C,QAAQ,EAAE,uBAAuB;IACjC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC,CAAC,QAAQ,CAAC;QAClE,UAAU,EAAE,UAAU;QACtB,KAAK,EAAE,WAAW;QAClB,WAAW,EAAE,gCAAgC;KAC9C,CAAC;IACF,OAAO,EAAE,MAAM,CAAC,MAAM;CACvB,CAAC,CAAC,QAAQ,CAAC;IACV,UAAU,EAAE,UAAU;IACtB,KAAK,EAAE,WAAW;IAClB,WAAW,EAAE,2EAA2E;CACzF,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC5C,QAAQ,EAAE,uBAAuB;IACjC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC,MAAM;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM;IACtB,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACrD,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;CACzC,CAAC,CAAC,QAAQ,CAAC;IACV,UAAU,EAAE,YAAY;IACxB,KAAK,EAAE,aAAa;IACpB,WAAW,EAAE,wEAAwE;CACtF,CAAC,CAAC;AAKH,8EAA8E;AAC9E,wDAAwD;AACxD,8EAA8E;AAE9E,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAkB,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;AAEtF,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/src/unstable/cli-runtime/resolve-format.d.ts

@@ -0,0 +1,15 @@
+import * as Option from "effect/Option";
+import type { OutputFormat } from "./output-mode.js";
+/**
+ * Resolve output format from raw argv BEFORE Effect runs.
+ *
+ * If CLI parsing itself fails (e.g. unknown flag), Effect never executes, so
+ * raw argv scanning is the only reliable way to preserve explicit --json.
+ */
+export declare const resolveFormatFromArgv: (args: ReadonlyArray<string>) => OutputFormat;
+/**
+ * Resolve output format from the global flag.
+ * Text remains the default unless --json was explicitly requested.
+ */
+export declare const resolveFormat: (explicitJson: Option.Option<boolean>) => OutputFormat;
+//# sourceMappingURL=resolve-format.d.ts.map

package/dist/src/unstable/cli-runtime/resolve-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-format.d.ts","sourceRoot":"","sources":["../../../../src/unstable/cli-runtime/resolve-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAKrD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,MAAM,aAAa,CAAC,MAAM,CAAC,KAAG,YAEnE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,cAAc,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KAAG,YACN,CAAC"}

package/dist/src/unstable/cli-runtime/resolve-format.js

@@ -0,0 +1,17 @@
+import * as Option from "effect/Option";
+const hasExplicitJsonFlag = (args) => args.includes("--json") || args.includes("-j");
+/**
+ * Resolve output format from raw argv BEFORE Effect runs.
+ *
+ * If CLI parsing itself fails (e.g. unknown flag), Effect never executes, so
+ * raw argv scanning is the only reliable way to preserve explicit --json.
+ */
+export const resolveFormatFromArgv = (args) => {
+    return hasExplicitJsonFlag(args) ? "json" : "text";
+};
+/**
+ * Resolve output format from the global flag.
+ * Text remains the default unless --json was explicitly requested.
+ */
+export const resolveFormat = (explicitJson) => Option.getOrElse(explicitJson, () => false) ? "json" : "text";
+//# sourceMappingURL=resolve-format.js.map

package/dist/src/unstable/cli-runtime/resolve-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-format.js","sourceRoot":"","sources":["../../../../src/unstable/cli-runtime/resolve-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC,MAAM,mBAAmB,GAAG,CAAC,IAA2B,EAAW,EAAE,CACnE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,IAA2B,EAAgB,EAAE;IACjF,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;AACrD,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,YAAoC,EAAgB,EAAE,CAClF,MAAM,CAAC,SAAS,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC"}

package/dist/src/unstable/cli-runtime/run-cli-main.d.ts

@@ -0,0 +1,14 @@
+import * as Effect from "effect/Effect";
+import type { VerbosityLevel } from "../cli-flags/verbosity.js";
+export interface CliMainContext {
+    readonly verbosityLevel: VerbosityLevel;
+}
+/**
+ * Resolve CLI context from argv before Effect runs.
+ * These values are passed into `makeFoundationLayer` by callers.
+ */
+export declare const resolveCliContext: (args: ReadonlyArray<string>) => CliMainContext;
+export declare const runCliMain: (execute: (args: ReadonlyArray<string>) => Effect.Effect<void, unknown, never>, options?: {
+    readonly args?: ReadonlyArray<string> | undefined;
+}) => Promise<void>;
+//# sourceMappingURL=run-cli-main.d.ts.map

package/dist/src/unstable/cli-runtime/run-cli-main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-cli-main.d.ts","sourceRoot":"","sources":["../../../../src/unstable/cli-runtime/run-cli-main.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAMxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;CACzC;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,aAAa,CAAC,MAAM,CAAC,KAAG,cAE9D,CAAC;AAGH,eAAO,MAAM,UAAU,GACrB,SAAS,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,EAC7E,UAAU;IACR,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;CACnD,KACA,OAAO,CAAC,IAAI,CASd,CAAC"}

package/dist/src/unstable/cli-runtime/run-cli-main.js

@@ -0,0 +1,24 @@
+import * as Effect from "effect/Effect";
+import { handleError } from "./handle-error.js";
+import { withGracefulShutdown } from "./graceful-shutdown.js";
+import { resolveFormatFromArgv } from "./resolve-format.js";
+import { resolveVerbosityFromArgv } from "../cli-flags/resolve-verbosity.js";
+/**
+ * Resolve CLI context from argv before Effect runs.
+ * These values are passed into `makeFoundationLayer` by callers.
+ */
+export const resolveCliContext = (args) => ({
+    verbosityLevel: resolveVerbosityFromArgv(args),
+});
+// Raw async/await: bootstraps the CLI before the Effect runtime is configured.
+export const runCliMain = async (execute, options) => {
+    const args = options?.args ?? process.argv.slice(2);
+    const format = resolveFormatFromArgv(args);
+    try {
+        await Effect.runPromise(withGracefulShutdown(execute(args)));
+    }
+    catch (error) {
+        handleError(error, format);
+    }
+};
+//# sourceMappingURL=run-cli-main.js.map

package/dist/src/unstable/cli-runtime/run-cli-main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-cli-main.js","sourceRoot":"","sources":["../../../../src/unstable/cli-runtime/run-cli-main.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AAO7E;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,IAA2B,EAAkB,EAAE,CAAC,CAAC;IACjF,cAAc,EAAE,wBAAwB,CAAC,IAAI,CAAC;CAC/C,CAAC,CAAC;AAEH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,EAC7B,OAA6E,EAC7E,OAEC,EACc,EAAE;IACjB,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAE3C,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,UAAU,CAAC,oBAAoB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC7B,CAAC;AACH,CAAC,CAAC"}

package/dist/src/unstable/cli-runtime/runtime-envelope.d.ts

@@ -0,0 +1,44 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type { OutputFormat } from "./output-mode.js";
+import type { AppError } from "../app-error/index.js";
+import type { PromptCancelled } from "../cli-prompt/prompt-cancelled.js";
+import { type CliTelemetryConfigService } from "./telemetry-layer.js";
+import { type CliRenderer } from "../cli-renderer/index.js";
+import { Verbosity, type VerbosityLevel } from "../cli-flags/index.js";
+export type ExpectedCliError = AppError | PromptCancelled;
+export type CliRuntimeFoundation = CliRenderer | Verbosity;
+/**
+ * Build the foundation layer: CliRenderer + Verbosity.
+ *
+ * The returned layer requires the global verbosity flag settings in its
+ * context when no explicit verbosity level is supplied.
+ */
+export declare const makeFoundationLayer: (format: OutputFormat, options?: {
+    readonly envVerbose?: boolean | undefined;
+    readonly envDebug?: boolean | undefined;
+    readonly verbosityLevel?: VerbosityLevel | undefined;
+}) => Layer.Layer<Verbosity | CliRenderer, never, "effect/unstable/cli/GlobalFlag/axm-quiet" | "effect/unstable/cli/GlobalFlag/axm-verbose" | "effect/unstable/cli/GlobalFlag/axm-debug">;
+/**
+ * Resolve the output format from the global flag + options.
+ */
+export declare const resolveCliFormat: Effect.Effect<OutputFormat, never, "effect/unstable/cli/GlobalFlag/axm-json">;
+/**
+ * Wrap a pre-provided program in CLI error handling + telemetry.
+ *
+ * The program should already have all its service dependencies satisfied
+ * except for TelemetryClient (provided via telemetryLayer internally)
+ * and HttpClient (required by the telemetry layer).
+ * Callers compose their own layers before passing the program here.
+ */
+export declare const withCliErrorHandling: <A, R>(program: Effect.Effect<A, ExpectedCliError, R>, options: {
+    readonly command?: string | undefined;
+    readonly format: OutputFormat;
+    readonly telemetryConfig: CliTelemetryConfigService;
+}) => Effect.Effect<A, never, import("effect/unstable/http/HttpClient").HttpClient | "effect/unstable/cli/GlobalFlag/axm-non-interactive" | "effect/unstable/cli/GlobalFlag/axm-json" | "effect/unstable/cli/GlobalFlag/axm-quiet" | "effect/unstable/cli/GlobalFlag/axm-verbose" | "effect/unstable/cli/GlobalFlag/axm-debug" | Exclude<R, import("../telemetry/client.ts").TelemetryClient | import("./telemetry.js").CommandSemanticProperties>>;
+export interface WithCliRuntimeOptions {
+    readonly command?: string | undefined;
+    readonly telemetryConfig: CliTelemetryConfigService;
+}
+export declare const withCliRuntime: <A, R>(program: Effect.Effect<A, ExpectedCliError, R>, options: WithCliRuntimeOptions) => Effect.Effect<A, never, import("effect/unstable/http/HttpClient").HttpClient | "effect/unstable/cli/GlobalFlag/axm-non-interactive" | "effect/unstable/cli/GlobalFlag/axm-json" | "effect/unstable/cli/GlobalFlag/axm-quiet" | "effect/unstable/cli/GlobalFlag/axm-verbose" | "effect/unstable/cli/GlobalFlag/axm-debug" | Exclude<Exclude<Exclude<R, Verbosity | CliRenderer>, import("effect/Scope").Scope>, import("../telemetry/client.ts").TelemetryClient | import("./telemetry.js").CommandSemanticProperties>>;
+//# sourceMappingURL=runtime-envelope.d.ts.map

package/dist/src/unstable/cli-runtime/runtime-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-envelope.d.ts","sourceRoot":"","sources":["../../../../src/unstable/cli-runtime/runtime-envelope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAItC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAGzE,OAAO,EAAyB,KAAK,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAY7F,OAAO,EAAwC,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAClG,OAAO,EAAsB,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAO3F,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,eAAe,CAAC;AAC1D,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAAG,SAAS,CAAC;AAwC3D;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,YAAY,EACpB,UAAU;IACR,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CACtD,wLA+BF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,+EAG3B,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,EAAE,CAAC,EACvC,SAAS,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAC,EAC9C,SAAS;IACP,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,eAAe,EAAE,yBAAyB,CAAC;CACrD,kbA0FF,CAAC;AAMF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,eAAe,EAAE,yBAAyB,CAAC;CACrD;AAED,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,EACjC,SAAS,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAC,EAC9C,SAAS,qBAAqB,2fAY5B,CAAC"}

package/dist/src/unstable/cli-runtime/runtime-envelope.js

@@ -0,0 +1,158 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { jsonFlag, debugFlag, verboseFlag, quietFlag } from "../cli-flags/index.js";
+import { renderAppError } from "../app-error/index.js";
+import { effectCliExit, isEffectCliExit } from "./effect-cli-exit.js";
+import { resolveFormat } from "./resolve-format.js";
+import { makeCliTelemetryLayer } from "./telemetry-layer.js";
+import { readGlobalFlagProperties, reportCliDefect, reportCliError, trackCliCommand, trackCliCommandCompleted, getCommandSemanticProperties, CommandSemanticPropertiesLive, } from "./telemetry.js";
+import { CommandArgv, serializeArgv } from "./command-argv.js";
+import { InteractiveRenderer, MachineRenderer } from "../cli-renderer/index.js";
+import { makeVerbosityLayer, Verbosity } from "../cli-flags/index.js";
+import { makeJsonErrorEnvelopeFromAppError } from "./json-envelope.js";
+const writeStderr = (message) => {
+    process.stderr.write(message.endsWith("\n") ? message : `${message}\n`);
+};
+const defaultExitCodeForExpectedError = (error) => error._tag === "PromptCancelled" ? 0 : 1;
+const writeExpectedCliError = (error, format) => Effect.gen(function* () {
+    if (error._tag === "PromptCancelled") {
+        return;
+    }
+    // Try Verbosity service first; fall back to raw flags for backward compatibility
+    const verbosityOption = yield* Effect.serviceOption(Verbosity);
+    const { verbose, debug } = Option.match(verbosityOption, {
+        onNone: () => ({ verbose: false, debug: false }),
+        onSome: (v) => ({
+            verbose: v.isAtLeast("verbose"),
+            debug: v.isAtLeast("debug"),
+        }),
+    });
+    if (format === "text") {
+        writeStderr(renderAppError(error, { verbose, debug }));
+        return;
+    }
+    process.stdout.write(JSON.stringify(makeJsonErrorEnvelopeFromAppError(error, defaultExitCodeForExpectedError(error)), null, 2) + "\n");
+    writeStderr(`\u2717 ${error.what}`);
+});
+// ---------------------------------------------------------------------------
+// Building blocks — composable pieces callers assemble directly
+// ---------------------------------------------------------------------------
+/**
+ * Build the foundation layer: CliRenderer + Verbosity.
+ *
+ * The returned layer requires the global verbosity flag settings in its
+ * context when no explicit verbosity level is supplied.
+ */
+export const makeFoundationLayer = (format, options) => {
+    // Json mode uses machine-readable output.
+    const rendererLayer = format !== "text" ? MachineRenderer() : InteractiveRenderer();
+    // Verbosity: use explicit level if provided, otherwise derive from flags + env vars
+    const verbosityLayer = options?.verbosityLevel
+        ? makeVerbosityLayer(options.verbosityLevel)
+        : Layer.unwrap(Effect.gen(function* () {
+            const flagDebug = yield* debugFlag;
+            const flagVerbose = yield* verboseFlag;
+            const flagQuiet = yield* quietFlag;
+            const envDebug = options?.envDebug ?? false;
+            const envVerbose = options?.envVerbose ?? false;
+            const level = flagDebug || envDebug
+                ? "debug"
+                : flagVerbose || envVerbose
+                    ? "verbose"
+                    : flagQuiet
+                        ? "quiet"
+                        : "normal";
+            return makeVerbosityLayer(level);
+        }));
+    return Layer.mergeAll(rendererLayer, verbosityLayer);
+};
+/**
+ * Resolve the output format from the global flag + options.
+ */
+export const resolveCliFormat = Effect.gen(function* () {
+    const explicit = yield* jsonFlag;
+    return resolveFormat(explicit);
+});
+/**
+ * Wrap a pre-provided program in CLI error handling + telemetry.
+ *
+ * The program should already have all its service dependencies satisfied
+ * except for TelemetryClient (provided via telemetryLayer internally)
+ * and HttpClient (required by the telemetry layer).
+ * Callers compose their own layers before passing the program here.
+ */
+export const withCliErrorHandling = (program, options) => {
+    const command = options.command ?? "unknown";
+    const telemetryLayer = makeCliTelemetryLayer(command, options.telemetryConfig);
+    const enrichedProgram = Effect.gen(function* () {
+        // Read optional CommandArgv (won't fail if not provided)
+        const argvOption = yield* Effect.serviceOption(CommandArgv);
+        const argvProperties = Option.match(argvOption, {
+            onNone: () => ({}),
+            onSome: (argv) => serializeArgv(argv.value, argv.paramKinds),
+        });
+        // Read global flag properties for telemetry
+        const globalProperties = yield* readGlobalFlagProperties;
+        // Merge all properties for command_invoked
+        const allProperties = {
+            ...argvProperties,
+            ...globalProperties,
+        };
+        // Fire command_invoked
+        yield* trackCliCommand({ command, properties: allProperties });
+        // Execute program with timing
+        const startTime = Date.now();
+        return yield* program.pipe(Effect.tap(() => Effect.gen(function* () {
+            const semanticProperties = yield* getCommandSemanticProperties;
+            yield* trackCliCommandCompleted({
+                command,
+                result: "success",
+                durationMs: Date.now() - startTime,
+                semanticProperties,
+            });
+        })), Effect.catch((error) => {
+            const durationMs = Date.now() - startTime;
+            const exitCode = defaultExitCodeForExpectedError(error);
+            const result = error._tag === "PromptCancelled" ? "cancelled" : "error";
+            return writeExpectedCliError(error, options.format).pipe(Effect.andThen(reportCliError(error, command)), Effect.andThen(Effect.gen(function* () {
+                const semanticProperties = yield* getCommandSemanticProperties;
+                yield* trackCliCommandCompleted({
+                    command,
+                    result,
+                    durationMs,
+                    ...(error._tag === "AppError" && { errorCode: error.code }),
+                    semanticProperties,
+                });
+            })), Effect.andThen(Effect.die(effectCliExit(exitCode))));
+        }), Effect.catchCause((cause) => {
+            const durationMs = Date.now() - startTime;
+            const defect = Cause.squash(cause);
+            if (isEffectCliExit(defect)) {
+                return Effect.failCause(cause);
+            }
+            return reportCliDefect(cause, command).pipe(Effect.andThen(Effect.gen(function* () {
+                const semanticProperties = yield* getCommandSemanticProperties;
+                yield* trackCliCommandCompleted({
+                    command,
+                    result: "defect",
+                    durationMs,
+                    semanticProperties,
+                });
+            })), Effect.andThen(Effect.failCause(cause)));
+        }));
+    });
+    return enrichedProgram.pipe(Effect.provide(Layer.mergeAll(telemetryLayer, CommandSemanticPropertiesLive)));
+};
+export const withCliRuntime = (program, options) => Effect.gen(function* () {
+    const format = yield* resolveCliFormat;
+    const foundationLayer = makeFoundationLayer(format);
+    const provided = program.pipe(Effect.provide(foundationLayer), Effect.scoped);
+    return yield* withCliErrorHandling(provided, {
+        command: options.command,
+        format,
+        telemetryConfig: options.telemetryConfig,
+    });
+});
+//# sourceMappingURL=runtime-envelope.js.map