@effected/cli 0.20.0 → 0.22.0

package/Doc.js

@@ -523,6 +523,11 @@ var Doc = class {
 	* GitHub's log format only when it says GitHub Actions, and plain text otherwise, including when it is
 	* absent. An explicit `format` is honoured whatever the audience.
 	*
+	* The context is built here, at print time, so it carries the fiber's count of open Actions log groups
+	* (`RenderContext.groupDepth`): printed inside an `ActionLogger.group` from `@effected/github-actions`, a
+	* document's top-level collapsible renders as plain text rather than as a second `::group::`, which would end
+	* the open one at the runner.
+	*
 	* @param doc - the document
 	* @param options - the stream and the format
 	*/

package/Fmt.js

@@ -1,4 +1,5 @@
 import { displayWidth, graphemes, stripAnsi } from "./internal/displayWidth.js";
+import { Duration, Option } from "effect";
 
 // src/Fmt.ts
 const CONTROL = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
@@ -76,18 +77,27 @@ var Fmt = class {
 		return useEllipsis ? `${out}${ellipsis}` : out;
 	};
 	/**
-	* A duration in milliseconds as short human text: `250ms`, `1.2s`, `2s`, `1m 3s`, `2m`, `1h 2m`, `2h`.
+	* A duration as short human text: `250ms`, `1.2s`, `2s`, `1m 3s`, `2m`, `1h 2m`, `2h`.
 	*
 	* @remarks
 	* Under a second it is whole milliseconds; under a minute, seconds to one decimal with a trailing `.0`
 	* dropped; under an hour, minutes and whole seconds, with the seconds dropped when zero; from an hour, hours and
 	* whole minutes, the seconds dropped. A value that rounds up to the next unit (`999.6` to a second, `59999` to a
 	* minute, `3599999` to an hour) is written in that unit, so `1000ms`, `60s` and `60m` never appear. There is no
-	* days unit. A negative or non-finite input is `0ms`.
+	* days unit. The format is bespoke: core's `Duration.format` renders differently.
 	*
-	* @param ms - the duration in milliseconds
+	* The input is anything `Duration.Input` admits. A plain number is milliseconds and is used as given, never
+	* converted through a `Duration`, which rounds a fractional millisecond to whole nanoseconds and would move a value
+	* such as `999.4999999` across the rounding boundary. A `bigint` is nanoseconds, as in core. A negative, infinite
+	* or invalid input (a string `Duration.Input` cannot parse) is `0ms`: a formatter in a render path never throws.
+	*
+	* @param input - the duration; a number is milliseconds
 	*/
-	static duration = (ms) => {
+	static duration = (input) => {
+		const ms = typeof input === "number" ? input : Option.match(Duration.fromInput(input), {
+			onNone: () => 0,
+			onSome: Duration.toMillis
+		});
 		const value = Number.isFinite(ms) ? Math.max(0, ms) : 0;
 		const whole = Math.round(value);
 		if (whole < 1e3) return `${whole}ms`;

package/Render.js

@@ -8,11 +8,16 @@ import { renderAnsi } from "./internal/renderAnsi.js";
 import { renderPlain } from "./internal/renderPlain.js";
 import { renderGithubLog } from "./internal/renderGithubLog.js";
 import { renderMarkdown } from "./internal/renderMarkdown.js";
-import { Effect } from "effect";
+import { Context, Effect } from "effect";
 import { Audience, TerminalEnv } from "@effected/env";
-import { CommandNeutralizer } from "@effected/github-commands";
+import { CommandNeutralizer, WorkflowCommand } from "@effected/github-commands";
 
 // src/Render.ts
+/**
+* The fiber-local count of open Actions log groups, by the kit-wide key, so a group `@effected/github-actions`'
+* `ActionLogger.group` opened is visible here without an edge between the two packages.
+*/
+const GroupDepth = Context.Reference(WorkflowCommand.groupDepthKey, { defaultValue: () => 0 });
 /** A renderer's text, with workflow commands neutralized when the context says the runner is reading it. */
 const guarded = (text, ctx) => ctx.neutralizeWorkflowCommands === true ? CommandNeutralizer.text(text) : text;
 /**
@@ -53,7 +58,10 @@ var Render = class {
 	*   required), for every audience, since the runner reads whatever is written there;
 	* - `width` is the option, else `TerminalEnv.width()` for a human whose stream is a terminal, and **unbounded**
 	*   (`Infinity`) for a human whose stream is not one (`tool | grep`, `tool > out.txt`), an agent or a CI, so nothing
-	*   a reader needs is truncated or wrapped for a terminal that is not there: a pipe has no width to honour.
+	*   a reader needs is truncated or wrapped for a terminal that is not there: a pipe has no width to honour;
+	* - `groupDepth` is the fiber's count of open Actions log groups (the fiber-local keyed by
+	*   `WorkflowCommand.groupDepthKey`, which `ActionLogger.group` provides), set when it is above `0`, so a
+	*   document printed inside a group opens no second one; see {@link RenderContext.groupDepth}.
 	*
 	* @param stream - the stream the output is for
 	* @param options - an explicit width and a path display function
@@ -64,8 +72,11 @@ var Render = class {
 		const theme = (yield* CliTheme).forStream(stream);
 		const seen = CliTheme.forAudience(theme, kind);
 		const links = yield* CliLinks;
+		const underActions = yield* underGithubActions;
+		const groupDepth = yield* GroupDepth;
 		return {
-			...(yield* underGithubActions) ? { neutralizeWorkflowCommands: true } : {},
+			...underActions ? { neutralizeWorkflowCommands: true } : {},
+			...groupDepth > 0 ? { groupDepth } : {},
 			width: options?.width ?? (kind === "human" && terminal[stream].isTerminal ? terminal.width() : Number.POSITIVE_INFINITY),
 			audience: kind,
 			color: seen.color,
@@ -88,7 +99,8 @@ var Render = class {
 	* with no escape of any kind. A colour level paints with the default token styles. An `agent` is colourless and
 	* unlinked whatever `color` and `links` say, as in {@link Render.context}.
 	*
-	* @param options - the audience, and the colour, glyphs, width, path display, links, neutralizing and link base
+	* @param options - the audience, and the colour, glyphs, width, path display, links, neutralizing, link base and
+	*   open group depth
 	*/
 	static contextOf = (options) => {
 		const agent = options.audience === "agent";
@@ -107,7 +119,8 @@ var Render = class {
 			}),
 			displayPath: options.displayPath ?? ((absolute) => absolute),
 			...options.neutralizeWorkflowCommands ?? options.audience === "ci" ? { neutralizeWorkflowCommands: true } : options.neutralizeWorkflowCommands === false ? { neutralizeWorkflowCommands: false } : {},
-			...options.linkBase === void 0 ? {} : { linkBase: options.linkBase }
+			...options.linkBase === void 0 ? {} : { linkBase: options.linkBase },
+			...options.groupDepth === void 0 ? {} : { groupDepth: options.groupDepth }
 		};
 	};
 	/**
@@ -237,6 +250,15 @@ var Render = class {
 	* top-level section. GitHub does not nest groups, so a collapsible inside a group, or inside a list or callout
 	* (where it would not start a line), keeps plain's rendering: its title on a line and its body indented.
 	*
+	* A group already open around the output counts the same way. When the context's `groupDepth` is above `0`
+	* ({@link RenderContext.groupDepth}, which `Render.context` reads from the fiber-local `ActionLogger.group` in
+	* `@effected/github-actions` provides, by the key `WorkflowCommand.groupDepthKey`), a top-level collapsible keeps
+	* plain's rendering too, so a document printed inside an `ActionLogger.group` does not open a second group, which
+	* would end the first at the runner. The depth is the context's, read when the context was built. What no depth
+	* can fix is two fibers writing groups at once: the runner has one log stream, so concurrent sibling groups, this
+	* renderer's or `ActionLogger`'s, interleave in it. Render and print a document from the fiber that owns the
+	* stream, not from a fiber racing another group.
+	*
 	* The runner has two command parsers, and a line is a command if either accepts it: after its leading whitespace it
 	* starts with `::`, or `##[` occurs ANYWHERE in it (a bare `##` is not one). A document's text must not be able to
 	* do that (`::add-mask::`, `::error::`, `##[error]`), so such a `::` line gets a braille pattern blank (U+2800) in

package/index.d.ts

@@ -1,4 +1,4 @@
-import { Array as Array$1, Cause, Context, Effect, FileSystem, Layer, LogLevel, Logger, MutableRef, Option, Path, Runtime, Schema, Stdio, Terminal } from "effect";
+import { Array as Array$1, Cause, Context, Duration, Effect, FileSystem, Layer, LogLevel, Logger, MutableRef, Option, Path, Runtime, Schema, Stdio, Terminal } from "effect";
 import { Audience, AudienceKind, ColorLevel, CurrentRuntimeEnv, RuntimeEnv, TerminalEnv } from "@effected/env";
 import { CliError, CliOutput, Command, Flag, Param, Prompt } from "effect/cli";
 import { ConfigValidationError } from "@effected/config-file";
@@ -1412,6 +1412,11 @@ export declare class Doc {
    * GitHub's log format only when it says GitHub Actions, and plain text otherwise, including when it is
    * absent. An explicit `format` is honoured whatever the audience.
    *
+   * The context is built here, at print time, so it carries the fiber's count of open Actions log groups
+   * (`RenderContext.groupDepth`): printed inside an `ActionLogger.group` from `@effected/github-actions`, a
+   * document's top-level collapsible renders as plain text rather than as a second `::group::`, which would end
+   * the open one at the runner.
+   *
    * @param doc - the document
    * @param options - the stream and the format
    */
@@ -3025,18 +3030,23 @@ export declare class Fmt {
    */
   static readonly truncate: (text: string, width: number, options?: TruncateOptions) => string;
   /**
-   * A duration in milliseconds as short human text: `250ms`, `1.2s`, `2s`, `1m 3s`, `2m`, `1h 2m`, `2h`.
+   * A duration as short human text: `250ms`, `1.2s`, `2s`, `1m 3s`, `2m`, `1h 2m`, `2h`.
    *
    * @remarks
    * Under a second it is whole milliseconds; under a minute, seconds to one decimal with a trailing `.0`
    * dropped; under an hour, minutes and whole seconds, with the seconds dropped when zero; from an hour, hours and
    * whole minutes, the seconds dropped. A value that rounds up to the next unit (`999.6` to a second, `59999` to a
    * minute, `3599999` to an hour) is written in that unit, so `1000ms`, `60s` and `60m` never appear. There is no
-   * days unit. A negative or non-finite input is `0ms`.
+   * days unit. The format is bespoke: core's `Duration.format` renders differently.
+   *
+   * The input is anything `Duration.Input` admits. A plain number is milliseconds and is used as given, never
+   * converted through a `Duration`, which rounds a fractional millisecond to whole nanoseconds and would move a value
+   * such as `999.4999999` across the rounding boundary. A `bigint` is nanoseconds, as in core. A negative, infinite
+   * or invalid input (a string `Duration.Input` cannot parse) is `0ms`: a formatter in a render path never throws.
    *
-   * @param ms - the duration in milliseconds
+   * @param input - the duration; a number is milliseconds
    */
-  static readonly duration: (ms: number) => string;
+  static readonly duration: (input: Duration.Input) => string;
   /**
    * A ratio from 0 to 1 as a percentage, or a number already from 0 to 100 with `scale: 100`: `83.3%`, `50%`,
    * `100%`.
@@ -3204,6 +3214,20 @@ interface RenderContext {
    * cannot open. The other renderers do not read it.
    */
   readonly linkBase?: string | undefined;
+  /**
+   * How many GitHub Actions log groups are open around the output. Unset or `0`, none is: `Render.githubLog` then
+   * writes a top-level collapsible as a `::group::`. Above `0` it writes the collapsible as plain does, its title on
+   * a line and its body indented, because the runner does not nest groups and a second `::group::` would end the open
+   * one. The other renderers do not read it.
+   *
+   * @remarks
+   * `Render.context` reads it from the fiber-local keyed by `WorkflowCommand.groupDepthKey`
+   * (`@effected/github-commands`), the count `ActionLogger.group` in `@effected/github-actions` provides around a
+   * group's body, so a context built inside a group knows it. It is read when the context is built, not when a
+   * document is rendered: a context built outside a group and used inside one still says none is open, so build it
+   * where the document is printed, as `Doc.print` does.
+   */
+  readonly groupDepth?: number | undefined;
 }
 /**
  * Options for {@link Render.contextOf}.
@@ -3233,6 +3257,8 @@ interface RenderContextOfOptions {
   readonly neutralizeWorkflowCommands?: boolean | undefined;
   /** See {@link RenderContext.linkBase}; unset by default. */
   readonly linkBase?: string | undefined;
+  /** See {@link RenderContext.groupDepth}; unset (no group open) by default. */
+  readonly groupDepth?: number | undefined;
 }
 /**
  * Options for {@link Render.context}.
@@ -3287,7 +3313,10 @@ export declare class Render {
    *   required), for every audience, since the runner reads whatever is written there;
    * - `width` is the option, else `TerminalEnv.width()` for a human whose stream is a terminal, and **unbounded**
    *   (`Infinity`) for a human whose stream is not one (`tool | grep`, `tool > out.txt`), an agent or a CI, so nothing
-   *   a reader needs is truncated or wrapped for a terminal that is not there: a pipe has no width to honour.
+   *   a reader needs is truncated or wrapped for a terminal that is not there: a pipe has no width to honour;
+   * - `groupDepth` is the fiber's count of open Actions log groups (the fiber-local keyed by
+   *   `WorkflowCommand.groupDepthKey`, which `ActionLogger.group` provides), set when it is above `0`, so a
+   *   document printed inside a group opens no second one; see {@link RenderContext.groupDepth}.
    *
    * @param stream - the stream the output is for
    * @param options - an explicit width and a path display function
@@ -3302,7 +3331,8 @@ export declare class Render {
    * with no escape of any kind. A colour level paints with the default token styles. An `agent` is colourless and
    * unlinked whatever `color` and `links` say, as in {@link Render.context}.
    *
-   * @param options - the audience, and the colour, glyphs, width, path display, links, neutralizing and link base
+   * @param options - the audience, and the colour, glyphs, width, path display, links, neutralizing, link base and
+   *   open group depth
    */
   static readonly contextOf: (options: RenderContextOfOptions) => RenderContext;
   /**
@@ -3432,6 +3462,15 @@ export declare class Render {
    * top-level section. GitHub does not nest groups, so a collapsible inside a group, or inside a list or callout
    * (where it would not start a line), keeps plain's rendering: its title on a line and its body indented.
    *
+   * A group already open around the output counts the same way. When the context's `groupDepth` is above `0`
+   * ({@link RenderContext.groupDepth}, which `Render.context` reads from the fiber-local `ActionLogger.group` in
+   * `@effected/github-actions` provides, by the key `WorkflowCommand.groupDepthKey`), a top-level collapsible keeps
+   * plain's rendering too, so a document printed inside an `ActionLogger.group` does not open a second group, which
+   * would end the first at the runner. The depth is the context's, read when the context was built. What no depth
+   * can fix is two fibers writing groups at once: the runner has one log stream, so concurrent sibling groups, this
+   * renderer's or `ActionLogger`'s, interleave in it. Render and print a document from the fiber that owns the
+   * stream, not from a fiber racing another group.
+   *
    * The runner has two command parsers, and a line is a command if either accepts it: after its leading whitespace it
    * starts with `::`, or `##[` occurs ANYWHERE in it (a bare `##` is not one). A document's text must not be able to
    * do that (`::add-mask::`, `::error::`, `##[error]`), so such a `::` line gets a braille pattern blank (U+2800) in

package/internal/renderGithubLog.js

@@ -32,6 +32,7 @@ const blockLines = (block, ctx) => {
 	switch (block._tag) {
 		case "Annotation": return [annotationLine(block)];
 		case "Collapsible": {
+			if ((ctx.groupDepth ?? 0) > 0) return plainLines([block], ctx);
 			const title = commandData(plainInline(block.title, ctx).map((span) => span.text).join(""));
 			return [
 				WorkflowCommand.group(title),
@@ -48,7 +49,8 @@ const blockLines = (block, ctx) => {
 	}
 };
 /**
-* Render a document for a GitHub Actions log: plain text, with a top-level collapsible as a group.
+* Render a document for a GitHub Actions log: plain text, with a top-level collapsible as a group when no group is
+* open around the output (`ctx.groupDepth`).
 *
 * @internal
 */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/cli",
-	"version": "0.20.0",
+	"version": "0.22.0",
 	"private": false,
 	"description": "The presentation boundary of an effect/cli program: audience-aware output, a document IR and renderers, editor links, failure reports and logging, plus opt-in Ink screens, widgets and a live view",
 	"keywords": [
@@ -57,10 +57,10 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/github-commands": "^0.6.0"
+		"@effected/github-commands": "^0.6.2"
 	},
 	"peerDependencies": {
-		"@effected/config-file": "^0.18.0",
+		"@effected/config-file": "^0.19.1",
 		"@effected/env": "^0.5.0",
 		"@effected/glob": "^0.14.0",
 		"@effected/walker": "^0.19.0",

package/ui/CliUi.js

@@ -306,7 +306,7 @@ var CliUi = class CliUi {
 	* so core renders its own message and `CliRuntime.main` exits `64`. Name the parameter with `flag` (the name
 	* without dashes) or `argument` so that error can be built.
 	*
-	* The options are {@link @effected/cli!CliPromptFallbackOptions}, the same as `CliPrompt.fallback`'s, and `clear`
+	* The options are `CliPromptFallbackOptions` (from `@effected/cli`), the same as `CliPrompt.fallback`'s, and `clear`
 	* as for {@link CliUi.run}.
 	*
 	* It runs during parsing, whose environment is core's alone, so it reads `CliTheme` if one is there: with

package/ui/UiKey.js

@@ -5,7 +5,12 @@ const named = (name) => ({
 });
 const CONTROL = /[\u0000-\u001f\u007f]/;
 /**
-* Normalising Ink's input into {@link UiKey}s.
+* Normalising Ink's input into {@link (UiKey:type)}s.
+*
+* @remarks
+* A typed `const` rather than the house static-class form by force, not by
+* choice: a class cannot share its name with the {@link (UiKey:type)} union
+* (TS2300, duplicate identifier), and that union is the key model itself.
 *
 * @public
 */

package/ui.d.ts

@@ -484,7 +484,7 @@ export declare class CliUi {
    * so core renders its own message and `CliRuntime.main` exits `64`. Name the parameter with `flag` (the name
    * without dashes) or `argument` so that error can be built.
    *
-   * The options are {@link @effected/cli!CliPromptFallbackOptions}, the same as `CliPrompt.fallback`'s, and `clear`
+   * The options are `CliPromptFallbackOptions` (from `@effected/cli`), the same as `CliPrompt.fallback`'s, and `clear`
    * as for {@link CliUi.run}.
    *
    * It runs during parsing, whose environment is core's alone, so it reads `CliTheme` if one is there: with
@@ -619,7 +619,12 @@ export type UiKey = {
   readonly char: string;
 };
 /**
- * Normalising Ink's input into {@link UiKey}s.
+ * Normalising Ink's input into {@link (UiKey:type)}s.
+ *
+ * @remarks
+ * A typed `const` rather than the house static-class form by force, not by
+ * choice: a class cannot share its name with the {@link (UiKey:type)} union
+ * (TS2300, duplicate identifier), and that union is the key model itself.
  *
  * @public
  */
@@ -1517,8 +1522,8 @@ interface TextInputScreenOptions {
    * does the scrollback; erase the frame as well with `clear: true` on the run when even the mask's length should not
    * stay behind.
    *
-   * The message `validate` returns is drawn as it is, unmasked: a message that echoes the value (`"ghp_abc is a
-   * token"`) draws the secret in the frame. Say what is wrong without quoting the value.
+   * The message `validate` returns is drawn as it is, unmasked: a message that echoes the value
+   * (`"ghp_abc is a token"`) draws the secret in the frame. Say what is wrong without quoting the value.
    */
   readonly mask?: string | true | ((value: string) => boolean);
 }
@@ -1665,7 +1670,7 @@ declare const UiStreams_base: Context.Reference<UiStreamsShape>;
  */
 export declare class UiStreams extends UiStreams_base {}
 /**
- * The styling props of an Ink `Text` that a {@link @effected/cli!Style} maps to.
+ * The styling props of an Ink `Text` that a `Style` (from `@effected/cli`) maps to.
  *
  * @public
  */