@effected/cli 0.21.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/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

@@ -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
    */
@@ -3209,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}.
@@ -3238,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}.
@@ -3292,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
@@ -3307,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;
   /**
@@ -3437,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.21.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.1"
+		"@effected/github-commands": "^0.6.2"
 	},
 	"peerDependencies": {
-		"@effected/config-file": "^0.19.0",
+		"@effected/config-file": "^0.19.1",
 		"@effected/env": "^0.5.0",
 		"@effected/glob": "^0.14.0",
 		"@effected/walker": "^0.19.0",

package/ui/UiKey.js

@@ -7,6 +7,11 @@ const CONTROL = /[\u0000-\u001f\u007f]/;
 /**
 * 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
 */
 const UiKey = {

package/ui.d.ts

@@ -621,6 +621,11 @@ export type UiKey = {
 /**
  * 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
  */
 export declare const UiKey: {