@vitest-agent/cli 3.1.6 → 3.2.0

package/commands/agent.js

@@ -14,34 +14,6 @@ import { exitCodeForTag, injectEnv } from "@vitest-agent/sdk/dispatch";
 import { resolveSidecarBinaryPath } from "@vitest-agent/sidecar";
 
 //#region src/commands/agent.ts
-/**
-* `agent` subcommand namespace.
-*
-* Commands intended for agents and hook scripts — humans typically do
-* not invoke these directly. The group composes the hook-driven
-* utilities (triage, wrapup, record) with the sidecar invocations
-* called by plugins/claude-code/hooks/*.sh scripts (register-agent, end-agent,
-* inject-env).
-*
-* The sidecar subcommands return plain text on stdout that the bash
-* hooks parse, and structured error info on stderr in the shape
-* `<exit_code> <error_tag>: <message>`.
-*
-* Exit codes follow the contract documented in the agent-agnostic
-* taxonomy plan:
-*   0 = success
-*   1 = registration conflict
-*   2 = sidecar timeout
-*   3 = database error
-*   4 = project identity not resolvable
-*   5 = other unexpected defect
-*
-* `check-test-path` is not part of that family and does not share the
-* taxonomy: it exits 1, with nothing on stdout, to mean "no verdict was
-* rendered — fail open."
-*
-* @packageDocumentation
-*/
 const writeStdout = (line) => Effect.sync(() => {
 	process.stdout.write(`${line}\n`);
 });

package/commands/db.js

@@ -8,11 +8,6 @@ import { layer } from "@effect/sql-sqlite-node/SqliteClient";
 import { SqlClient } from "effect/unstable/sql/SqlClient";
 
 //#region src/commands/db.ts
-/**
-* CLI db command -- manage the vitest-agent database.
-*
-* @packageDocumentation
-*/
 const pathCommand = Command.make("path", {}, () => Effect.gen(function* () {
 	const dbPath = yield* resolveDataPath(process.env.VITEST_AGENT_PROJECT_DIR ?? process.cwd());
 	yield* Effect.sync(() => process.stdout.write(`${dbPath}\n`));

package/commands/doctor.js

@@ -4,11 +4,6 @@ import { Effect, Option } from "effect";
 import { Command, Flag } from "effect/unstable/cli";
 
 //#region src/commands/doctor.ts
-/**
-* CLI doctor command -- diagnose database health.
-*
-* @packageDocumentation
-*/
 const formatOption = Flag.withDefault(Flag.Literals("format", ["markdown", "json"]), "markdown");
 const writeOutput = (results, format) => Effect.sync(() => {
 	if (format === "json") process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);

package/commands/triage.js

@@ -3,15 +3,6 @@ import { Effect } from "effect";
 import { Command, Flag } from "effect/unstable/cli";
 
 //#region src/commands/triage.ts
-/**
-* CLI triage command -- emits the W3 orientation triage brief.
-*
-* Calls the shared formatTriageEffect generator, which the MCP
-* triage_brief tool also uses. The plugin's SessionStart hook runs
-* this and pipes the result into Claude Code's additionalContext.
-*
-* @packageDocumentation
-*/
 const formatOption = Flag.withDefault(Flag.Literals("format", [
 	"markdown",
 	"json",

package/commands/wrapup.js

@@ -3,16 +3,6 @@ import { Effect } from "effect";
 import { Command, Flag } from "effect/unstable/cli";
 
 //#region src/commands/wrapup.ts
-/**
-* CLI wrapup command -- emits the W5 wrap-up prompt for a session.
-*
-* Drives the four interpretive hooks (Stop / SessionEnd / PreCompact /
-* UserPromptSubmit). Hooks invoke the bin with --kind set; humans on
-* the terminal can also run it on demand with --chat-id (host chat UUID)
-* or --row-id (internal integer FK, mostly for debugging).
-*
-* @packageDocumentation
-*/
 const rowIdOption = Flag.optional(Flag.Int("row-id"));
 const chatIdOption = Flag.optional(Flag.String("chat-id"));
 const kindOption = Flag.withDefault(Flag.Literals("kind", [

package/lib/version-formatter.js

@@ -0,0 +1,23 @@
+import { CliColor } from "@effected/cli";
+import { CurrentDistribution, distributionSuffix } from "@effected/engine";
+import { Effect, Layer } from "effect";
+
+//#region src/lib/version-formatter.ts
+/**
+* The program's one `CliOutput.Formatter` layer: `CliColor.formatterLayer`
+* (the kit's single colour decision — stdout is a TTY and `NO_COLOR` is
+* unset or empty) with only `formatVersion` overridden, so `--version`
+* prints `vitest-agent <cli version>` plus ` via <name> <version>` when a
+* carrier (`@vitest-agent/plugin`'s bin shim) threaded its identity down.
+* Help and parse-error rendering stay `CliColor`'s own.
+*
+* `Layer.unwrap` reads `CurrentDistribution` once, at layer build time, from
+* the ambient context `main.ts` provides — so `main.ts` must provide
+* `CurrentDistribution` OUTSIDE the layer, not inside it.
+*
+* @internal
+*/
+const versionFormatterLayer = Layer.unwrap(Effect.map(CurrentDistribution, (distribution) => CliColor.formatterLayer({ formatVersion: (name, version) => `${name} ${version}${distributionSuffix(distribution)}` })));
+
+//#endregion
+export { versionFormatterLayer };

package/main.d.ts

@@ -1,22 +1,48 @@
+import { Distribution } from "@effected/engine";
 //#region src/main.d.ts
 /**
- * Assembled CLI program. Owns the process: resolves the data path, wires the
- * engine's platform layers, and runs the root command via
- * `NodeRuntime.runMain`.
+ * Options the carrier's bin shim passes to {@link main}.
  *
- * `bin.ts` is the published bin shim (`#!/usr/bin/env node` +
- * `main()`); this module is also published as the `./main` subpath so a
- * consumer can invoke the assembled program without going through the shim.
- *
- * @packageDocumentation
+ * @public
  */
+export interface MainOptions {
+  /**
+   * The meta-package the bin was launched through (for example
+   * `@vitest-agent/plugin`), appended to `--version` as
+   * ` via <name> <version>`. Omitted for a direct install of this package.
+   */
+  readonly distribution?: Distribution | undefined;
+}
 /**
  * Assembles and runs the CLI program, taking over the process. Not
  * re-exported from `index.ts` — a library consumer's import graph must not
  * pull in the process-owning module.
  *
+ * Output routing (hooks parse `agent *` stdout with jq, so stdout carries
+ * only what a command writes as its result):
+ *
+ * - Inside the platform, the engine's `LoggerLive` (installed by
+ *   `PlatformLive`) is the active logger: silent unless
+ *   `VITEST_REPORTER_LOG_LEVEL` is set, then NDJSON on stderr (plus
+ *   `VITEST_REPORTER_LOG_FILE`). Every `Effect.log*` a command or engine
+ *   service emits goes there.
+ * - Outside the platform, `CliRuntime.main`'s default `CliLogger` is
+ *   outermost and sends every level to stderr. It is what renders reported
+ *   failures (a layer-build failure, a typed command failure, a defect)
+ *   through `renderFailure`.
+ * - An explicit `--help` (or a bare group invocation) prints help on
+ *   stdout. A usage error (unknown flag, bad value, unknown subcommand)
+ *   prints help AND the parse errors on stderr (`helpOnUsageError: "stderr"`),
+ *   so stdout stays empty for a jq-piping hook. Both render via
+ *   the `CliOutput` formatter (`versionFormatterLayer`), which must come
+ *   through `platform` for the kit to reroute it.
+ *
+ * Exit codes are the kit's: `0` success (including bare `--help`), `64` a
+ * usage error (parse error, unknown subcommand), `1` any other reported
+ * failure. Commands that `process.exit` with their own code still do so.
+ *
  * @public
  */
-export declare const main: () => void;
+export declare const main: (options?: MainOptions) => void;
 //#endregion
 //# sourceMappingURL=main.d.ts.map

package/main.js

@@ -2,22 +2,26 @@ import { CURRENT_CLI_VERSION } from "./version.js";
 import { agentCommand } from "./commands/agent.js";
 import { dbCommand } from "./commands/db.js";
 import { doctorCommand } from "./commands/doctor.js";
+import { versionFormatterLayer } from "./lib/version-formatter.js";
 import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
 import * as NodeServices from "@effect/platform-node/NodeServices";
+import { CliRuntime } from "@effected/cli";
+import { CurrentDistribution } from "@effected/engine";
 import { PathResolutionLive, PlatformLive, resolveDataPath, resolveLogFile, resolveLogLevel, resolveProjectDir } from "@vitest-agent/engine";
 import { formatFatalError } from "@vitest-agent/sdk";
-import { Cause, Console, Effect } from "effect";
+import { Effect, Layer, Option } from "effect";
 import { Command } from "effect/unstable/cli";
 
 //#region src/main.ts
 /**
 * Assembled CLI program. Owns the process: resolves the data path, wires the
-* engine's platform layers, and runs the root command via
-* `NodeRuntime.runMain`.
+* engine's platform layers, and runs the root command through
+* `@effected/cli`'s `CliRuntime.main` under `NodeRuntime.runMain`.
 *
 * `bin.ts` is the published bin shim (`#!/usr/bin/env node` +
-* `main()`); this module is also published as the `./main` subpath so a
-* consumer can invoke the assembled program without going through the shim.
+* `main()`); this module is also published as the `./main` subpath so the
+* carrier (`@vitest-agent/plugin`) can ship the same program behind its own
+* bin, threading its identity in through {@link MainOptions.distribution}.
 *
 * @packageDocumentation
 */
@@ -27,13 +31,56 @@ const rootCommand = Command.make("vitest-agent").pipe(Command.withSubcommands([
 	agentCommand
 ]));
 /**
+* The one-line name of a typed failure: its `_tag` when it carries one (a
+* `PlatformError`, `SqlError`, `MigrationError`), else its `Error` name.
+*/
+const failureName = (error) => {
+	if (typeof error === "object" && error !== null && "_tag" in error && typeof error._tag === "string") return error._tag;
+	return error instanceof Error ? error.name : "Error";
+};
+/**
+* One rendering for every failure `CliRuntime.main` reports. The kit says
+* which kind it is (`details.isDefect`, exact: the cause carries no typed
+* failure): a typed failure from the error channel is one line, a defect
+* keeps the issue-report rendering `formatFatalError` gives it. `ShowHelp`
+* and runWith-rendered `UserError`s never reach here (the kit skips them).
+*/
+const renderFailure = (error, details) => {
+	if (details.isDefect) return `vitest-agent: ${formatFatalError(error)}`;
+	const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+	return `vitest-agent: ${failureName(error)}${message ? `: ${message}` : ""}`;
+};
+/**
 * Assembles and runs the CLI program, taking over the process. Not
 * re-exported from `index.ts` — a library consumer's import graph must not
 * pull in the process-owning module.
 *
+* Output routing (hooks parse `agent *` stdout with jq, so stdout carries
+* only what a command writes as its result):
+*
+* - Inside the platform, the engine's `LoggerLive` (installed by
+*   `PlatformLive`) is the active logger: silent unless
+*   `VITEST_REPORTER_LOG_LEVEL` is set, then NDJSON on stderr (plus
+*   `VITEST_REPORTER_LOG_FILE`). Every `Effect.log*` a command or engine
+*   service emits goes there.
+* - Outside the platform, `CliRuntime.main`'s default `CliLogger` is
+*   outermost and sends every level to stderr. It is what renders reported
+*   failures (a layer-build failure, a typed command failure, a defect)
+*   through `renderFailure`.
+* - An explicit `--help` (or a bare group invocation) prints help on
+*   stdout. A usage error (unknown flag, bad value, unknown subcommand)
+*   prints help AND the parse errors on stderr (`helpOnUsageError: "stderr"`),
+*   so stdout stays empty for a jq-piping hook. Both render via
+*   the `CliOutput` formatter (`versionFormatterLayer`), which must come
+*   through `platform` for the kit to reroute it.
+*
+* Exit codes are the kit's: `0` success (including bare `--help`), `64` a
+* usage error (parse error, unknown subcommand), `1` any other reported
+* failure. Commands that `process.exit` with their own code still do so.
+*
 * @public
 */
-const main = () => {
+const main = (options = {}) => {
 	const env = process.env;
 	const logLevel = resolveLogLevel(env);
 	const logFile = resolveLogFile(env);
@@ -41,16 +88,18 @@ const main = () => {
 		env,
 		cwd: process.cwd()
 	});
-	const cli = Command.run(rootCommand, { version: CURRENT_CLI_VERSION });
-	const program = resolveDataPath(projectDir).pipe(Effect.flatMap((dbPath) => cli.pipe(Effect.provide(PlatformLive({
+	const dataLayer = Layer.unwrap(Effect.map(resolveDataPath(projectDir), (dbPath) => PlatformLive({
 		dbPath,
 		env,
 		logLevel,
 		logFile
-	})))), Effect.provide(PathResolutionLive(projectDir)), Effect.provide(NodeServices.layer), Effect.catchCause((cause) => {
-		if (cause.reasons.filter(Cause.isDieReason).length > 0) return Console.error(`vitest-agent: ${formatFatalError(cause)}`).pipe(Effect.andThen(Effect.failCause(cause)));
-		return Effect.failCause(cause);
-	}));
+	})));
+	const platform = Layer.mergeAll(dataLayer, versionFormatterLayer).pipe(Layer.provideMerge(PathResolutionLive(projectDir)), Layer.provideMerge(NodeServices.layer));
+	const program = CliRuntime.main(Command.run(rootCommand, { version: CURRENT_CLI_VERSION }), {
+		platform,
+		render: renderFailure,
+		helpOnUsageError: "stderr"
+	}).pipe(Effect.provideService(CurrentDistribution, Option.fromNullishOr(options.distribution)));
 	NodeRuntime.runMain(program);
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitest-agent/cli",
-	"version": "3.1.6",
+	"version": "3.2.0",
 	"private": false,
 	"description": "On-demand CLI for vitest-agent. Reads cached test data and reports status, overview, coverage, history, trends, and cache health.",
 	"keywords": [
@@ -45,8 +45,10 @@
 	"dependencies": {
 		"@effect/platform-node": "4.0.0-rc.117",
 		"@effect/sql-sqlite-node": "4.0.0-rc.117",
-		"@effected/workspaces": "^0.26.0",
-		"@vitest-agent/engine": "0.2.6",
+		"@effected/cli": "^0.9.0",
+		"@effected/engine": "^0.1.0",
+		"@effected/workspaces": "^0.27.0",
+		"@vitest-agent/engine": "0.2.7",
 		"@vitest-agent/sdk": "5.1.2",
 		"@vitest-agent/sidecar": "2.2.2",
 		"effect": "4.0.0-rc.117"

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.59.2"
+      "packageVersion": "7.59.1"
     }
   ]
 }

package/version.js

@@ -7,7 +7,7 @@
 *
 * @public
 */
-const CURRENT_CLI_VERSION = "3.1.6";
+const CURRENT_CLI_VERSION = "3.2.0";
 
 //#endregion
 export { CURRENT_CLI_VERSION };