@okfit/cli 0.9.0 → 0.10.0

package/errors.js

@@ -1,10 +1,12 @@
 import { InitBundleDirError } from "./internal/initWizard.js";
 import { DocumentStdinIsTerminalError } from "./internal/stdin.js";
-import { Cancelled, ConfigIssueRenderer, NotInteractive } from "@effected/cli";
+import { ConfigIssueRenderer } from "@effected/cli";
 import { ConfigMalformedError, ConfigPathNotFoundError, DocumentPathError, InitOverwriteError, NotAPublicationError, PublicationNotFoundError, QueryConceptNotFoundError, QuerySelectionError, QueryUnknownVocabularyError, SyncPublicationConflictError, SyncStagedLogError, VerifyConceptNotFoundError, VerifySelectionError, VerifyUnsupportedFrontmatterError } from "@okfit/engine";
 
 //#region src/errors.ts
 const hasTag = (error, tag) => typeof error === "object" && error !== null && "_tag" in error && error._tag === tag;
+/** Where a defect's report sends the reader. */
+const ISSUE_URL = "https://github.com/spencerbeggs/okfit/issues";
 /** `path` relative to `cwd` when it is under it, else the absolute path unchanged (K-51). */
 const relativeToCwd = (path, cwd) => {
 	if (path === cwd) return ".";
@@ -18,14 +20,10 @@ const relativeToCwd = (path, cwd) => {
 *
 * Rules, in order:
 *
-* 1. A `ShowHelp` (any `_tag === "ShowHelp"`) renders as `[]` — the empty
-*    array. `Command.runWith` has already rendered the help document and any
-*    parse errors before re-failing, so a second rendering here would print
-*    "Help requested" after the help text. In practice this branch is
-*    defensive only: `@effected/cli`'s `CliRuntime.main`/`reportFailures`
-*    already handles a `ShowHelp` before `render` is ever called
-*    (`main.ts`'s own doc comment), so `renderFailure` never actually sees
-*    one on the path this package uses.
+* 1. A cancelled or non-interactive run (`details.isCancelled`,
+*    `details.isNotInteractive`: a cancelled fallback prompt is a defect in the
+*    cause, but not a bug) renders as the kit's own `defaultLines`, unprefixed.
+*    `ShowHelp` never reaches `render`: `CliRuntime.main` handles it first.
 * 2. `ConfigPathNotFoundError` renders as its own `error: <message>` line;
 *    `InitOverwriteError` renders as the K-51 header, one two-space-indented
 *    relativised path per conflict, and the literal `Nothing was written.`.
@@ -56,18 +54,23 @@ const relativeToCwd = (path, cwd) => {
 * 5d. `QueryUnknownVocabularyError`, `QueryConceptNotFoundError` and
 *    `QuerySelectionError` (`okfit query`) each render as one
 *    `error: <message>` line.
-* 6. Everything else — core's `BundleRootNotFoundError`/`BundleReadError`/
+* 6. A defect (`details.isDefect`: a `die`, a thrown exception, a bug) that no
+*    rule above claimed renders as `error: ` plus the kit's report for the
+*    run without its status marker, then `Please report at <issues URL>`.
+* 7. Every other typed failure — core's `BundleRootNotFoundError`/`BundleReadError`/
 *    `BundleDepthExceededError`, config-file's other errors, `XdgEnvError`
 *    (the K-13 `HOME`-unset case) — renders as the single line
 *    `error: ${String(error)}`. Each of those
 *    classes' own `message` already names the offending path, which is all
 *    K-46 asserts.
 *
+* `details` is the kit's `FailureDetails`: `isDefect` tells a typed failure
+* from a defect exactly, so no rule here guesses from an error's shape.
+*
 * @public
 */
-const renderFailure = (error) => {
-	if (hasTag(error, "ShowHelp")) return [];
-	if (error instanceof Cancelled || error instanceof NotInteractive) return [error.message];
+const renderFailure = (error, details) => {
+	if (details.isCancelled || details.isNotInteractive) return details.defaultLines;
 	if (error instanceof ConfigPathNotFoundError) return [`error: ${error.message}`];
 	if (error instanceof ConfigMalformedError) return [`error: ${error.message}`];
 	if (error instanceof InitOverwriteError) return [
@@ -92,6 +95,14 @@ const renderFailure = (error) => {
 		const validationError = error;
 		return [`error: ${String(validationError)}`, ...ConfigIssueRenderer.render(validationError).map((line) => `  ${line}`)];
 	}
+	if (details.isDefect) {
+		const [first = String(error), ...rest] = details.lines({ status: false });
+		return [
+			`error: ${first}`,
+			...rest,
+			`Please report at ${ISSUE_URL}`
+		];
+	}
 	return [`error: ${String(error)}`];
 };
 

package/index.d.ts

@@ -1,5 +1,5 @@
 import { Command } from "effect/cli";
-import "@effected/cli";
+import { FailureDetails } from "@effected/cli";
 import { Runtime, Schema } from "effect";
 import { ContextEnvelope, RenderedDiagnostic } from "@okfit/engine";
 //#region src/commands/root.d.ts
@@ -47,14 +47,10 @@ export declare const rootCommand: Command.Command<"okfit", {
  *
  * Rules, in order:
  *
- * 1. A `ShowHelp` (any `_tag === "ShowHelp"`) renders as `[]` — the empty
- *    array. `Command.runWith` has already rendered the help document and any
- *    parse errors before re-failing, so a second rendering here would print
- *    "Help requested" after the help text. In practice this branch is
- *    defensive only: `@effected/cli`'s `CliRuntime.main`/`reportFailures`
- *    already handles a `ShowHelp` before `render` is ever called
- *    (`main.ts`'s own doc comment), so `renderFailure` never actually sees
- *    one on the path this package uses.
+ * 1. A cancelled or non-interactive run (`details.isCancelled`,
+ *    `details.isNotInteractive`: a cancelled fallback prompt is a defect in the
+ *    cause, but not a bug) renders as the kit's own `defaultLines`, unprefixed.
+ *    `ShowHelp` never reaches `render`: `CliRuntime.main` handles it first.
  * 2. `ConfigPathNotFoundError` renders as its own `error: <message>` line;
  *    `InitOverwriteError` renders as the K-51 header, one two-space-indented
  *    relativised path per conflict, and the literal `Nothing was written.`.
@@ -85,16 +81,22 @@ export declare const rootCommand: Command.Command<"okfit", {
  * 5d. `QueryUnknownVocabularyError`, `QueryConceptNotFoundError` and
  *    `QuerySelectionError` (`okfit query`) each render as one
  *    `error: <message>` line.
- * 6. Everything else — core's `BundleRootNotFoundError`/`BundleReadError`/
+ * 6. A defect (`details.isDefect`: a `die`, a thrown exception, a bug) that no
+ *    rule above claimed renders as `error: ` plus the kit's report for the
+ *    run without its status marker, then `Please report at <issues URL>`.
+ * 7. Every other typed failure — core's `BundleRootNotFoundError`/`BundleReadError`/
  *    `BundleDepthExceededError`, config-file's other errors, `XdgEnvError`
  *    (the K-13 `HOME`-unset case) — renders as the single line
  *    `error: ${String(error)}`. Each of those
  *    classes' own `message` already names the offending path, which is all
  *    K-46 asserts.
  *
+ * `details` is the kit's `FailureDetails`: `isDefect` tells a typed failure
+ * from a defect exactly, so no rule here guesses from an error's shape.
+ *
  * @public
  */
-export declare const renderFailure: (error: unknown) => ReadonlyArray<string>;
+export declare const renderFailure: (error: unknown, details: FailureDetails) => ReadonlyArray<string>;
 //#endregion
 //#region src/internal/initWizard.d.ts
 declare const InitBundleDirError_base: Schema.Class<InitBundleDirError, Schema.TaggedStruct<"InitBundleDirError", {

package/internal/initWizard.js

@@ -63,7 +63,8 @@ const checkBundleDir = (value) => {
 /**
 * The `okfit init` wizard: profile, bundle directory, config location, in
 * that order. A setting is prompted for only when its flag was not given and
-* the run is interactive; otherwise its flag value or default is used
+* the run is interactive (the profile also needs more than one registered: a
+* lone profile is used without a screen); otherwise its flag value or default is used
 * (`CliUi.prompt`'s `otherwise`, so a non-interactive run never loads Ink).
 *
 * A bad `--bundle` flag fails with {@link InitBundleDirError} before any
@@ -86,14 +87,15 @@ const initWizard = (given, defaults) => Effect.gen(function* () {
 		});
 		flagBundle = checked.dir;
 	}
+	const profileNames = PROFILE_NAMES;
 	return {
-		profile: Option.isSome(given.profile) ? given.profile.value : yield* CliUi.prompt(Select.screen({
+		profile: Option.isSome(given.profile) ? given.profile.value : profileNames.length === 1 ? defaults.profile : yield* CliUi.prompt(Select.screen({
 			message: "Profile to scaffold with",
-			choices: PROFILE_NAMES.map((name) => ({
+			choices: profileNames.map((name) => ({
 				label: name,
 				value: name
 			})),
-			initial: Math.max(0, PROFILE_NAMES.indexOf(defaults.profile))
+			initial: Math.max(0, profileNames.indexOf(defaults.profile))
 		}), { otherwise: defaults.profile }),
 		bundle: flagBundle ?? (yield* CliUi.prompt(TextInput.screen({
 			message: "Bundle directory (relative to the project root)",

package/internal/versionFormatter.js

@@ -1,7 +1,5 @@
-import { CliColor } from "@effected/cli";
-import { CurrentDistribution, distributionSuffix } from "@effected/engine";
+import { distributionSuffix } from "@effected/engine";
 import { ENGINE_VERSION } from "@okfit/engine";
-import { Effect, Layer } from "effect";
 import { CONFIG_SCHEMA_VERSION, OKF_SPEC_VERSION } from "@okfit/core";
 
 //#region src/internal/versionFormatter.ts
@@ -9,28 +7,19 @@ import { CONFIG_SCHEMA_VERSION, OKF_SPEC_VERSION } from "@okfit/core";
 * `okfit --version`'s full text (okfit #137):
 * `<name> <version>[ via <distName> <distVersion>] (engine <ENGINE_VERSION>, okf <OKF_SPEC_VERSION>, config-schema <CONFIG_SCHEMA_VERSION>)`.
 * `GlobalFlag.Version`'s built-in `run` calls `formatter.formatVersion(command.name,
-* version)` (`command.name` is always `"okfit"`, `version` is `CLI_VERSION` --
-* `cli/GlobalFlag.ts:189-199`), so those two arguments alone are
-* exactly `okfit <CLI_VERSION>`; this appends the engine, okf, and
-* distribution parts.
+* version)` (`command.name` is always `"okfit"`, `version` is `CLI_VERSION`), so
+* those two arguments alone are exactly `okfit <CLI_VERSION>`; this appends the
+* distribution, engine and okf parts.
 *
-* Built on `@effected/cli`'s `CliColor.formatterLayer` (the kit's one
-* colour-decision point, read through the ambient `ConfigProvider`, never
-* `process` directly) and `@effected/engine`'s `distributionSuffix` for the
-* `via <name> <version>` segment -- the shape `effect-v4-cli`'s
-* `recipes.md#version-formatter` teaches. Only `formatVersion` is
-* overridden; every other `Formatter` method (help, error rendering) is
-* `CliColor.formatterLayer`'s own default, so help/error output stays
-* consistent with the rest of the program's colour decision.
-*
-* `Layer.unwrap` around `Effect.map(CurrentDistribution, ...)` reads the
-* distribution once, from the ambient `CurrentDistribution` reference
-* `main.ts` provides, rather than threading it in as a constructor argument
-* the way the hand-rolled formatter used to.
+* Passed to `CliRuntime.main` as `env.formatter`: `helpOnUsageError: "stderr"`
+* only reroutes help written through a formatter `main` installed, so a layer
+* inside the program would not do. Every method left out keeps the kit's
+* coloured default. `distribution` is the value `main` was given, known before
+* the program runs, so it is read directly rather than from the context.
 *
 * @internal
 */
-const versionFormatterLayer = Layer.unwrap(Effect.map(CurrentDistribution, (distribution) => CliColor.formatterLayer({ formatVersion: (name, version) => `${name} ${version}${distributionSuffix(distribution)} (engine ${ENGINE_VERSION}, okf ${OKF_SPEC_VERSION}, config-schema ${CONFIG_SCHEMA_VERSION})` })));
+const versionFormatter = (distribution) => ({ formatVersion: (name, version) => `${name} ${version}${distributionSuffix(distribution)} (engine ${ENGINE_VERSION}, okf ${OKF_SPEC_VERSION}, config-schema ${CONFIG_SCHEMA_VERSION})` });
 
 //#endregion
-export { versionFormatterLayer };
+export { versionFormatter };

package/main.js

@@ -1,7 +1,7 @@
 import { CLI_VERSION } from "./version.js";
 import { rootCommand } from "./commands/root.js";
 import { renderFailure } from "./errors.js";
-import { versionFormatterLayer } from "./internal/versionFormatter.js";
+import { versionFormatter } from "./internal/versionFormatter.js";
 import { CliAudience, CliRuntime } from "@effected/cli";
 import { CurrentDistribution } from "@effected/engine";
 import { Now, OkfitPlatform } from "@okfit/engine";
@@ -46,12 +46,17 @@ const main = (options = {}) => {
 	const program = Effect.gen(function* () {
 		const now = yield* nowEffect;
 		return yield* CliAudience.run(rootCommand, { version: CLI_VERSION }).pipe(Effect.provideService(Now, now));
-	}).pipe(Effect.provide(versionFormatterLayer), Effect.provideService(CurrentDistribution, distribution));
+	}).pipe(Effect.provideService(CurrentDistribution, distribution));
 	NodeRuntime.runMain(CliRuntime.main(program, {
 		platform: OkfitPlatform,
 		exitCode: 3,
 		render: renderFailure,
-		env: { audienceEnvVar: "OKFIT_AUDIENCE" }
+		helpOnUsageError: "stderr",
+		env: {
+			audienceEnvVar: "OKFIT_AUDIENCE",
+			stderrIsTerminal: Effect.sync(() => process.stderr.isTTY === true),
+			formatter: versionFormatter(distribution)
+		}
 	}));
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/cli",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"private": false,
 	"description": "The okfit command line: validate, lint, index, and inspect Open Knowledge Format (OKF) bundles.",
 	"keywords": [
@@ -42,23 +42,23 @@
 		"okfit": "bin/okfit.js"
 	},
 	"dependencies": {
-		"@effect/platform-node": "^4.0.0",
-		"@effected/cli": "^0.11.0",
-		"@effected/config-file": "^0.14.0",
-		"@effected/engine": "^0.3.0",
+		"@effect/platform-node": "^4.0.1",
+		"@effected/cli": "^0.13.0",
+		"@effected/config-file": "^0.14.2",
+		"@effected/engine": "^0.4.0",
 		"@effected/env": "^0.1.0",
 		"@effected/git": "^0.20.0",
 		"@effected/glob": "^0.10.0",
-		"@effected/jsonc": "^0.15.0",
-		"@effected/markdown": "^0.15.0",
-		"@effected/schemastore": "^0.20.0",
-		"@effected/toml": "^0.11.0",
+		"@effected/jsonc": "^0.15.1",
+		"@effected/markdown": "^0.15.1",
+		"@effected/schemastore": "^0.21.1",
+		"@effected/toml": "^0.11.1",
 		"@effected/walker": "^0.15.0",
-		"@effected/yaml": "^0.19.0",
-		"@okfit/core": "0.9.0",
-		"@okfit/engine": "0.12.0",
+		"@effected/yaml": "^0.19.1",
+		"@okfit/core": "0.9.1",
+		"@okfit/engine": "0.13.0",
 		"@okfit/profiles": "0.9.0",
-		"effect": "^4.0.0",
+		"effect": "^4.0.1",
 		"ink": "^7.1.1",
 		"react": "^19.2.0"
 	},

package/version.js

@@ -11,7 +11,7 @@
 *
 * @public
 */
-const CLI_VERSION = "0.9.0";
+const CLI_VERSION = "0.10.0";
 
 //#endregion
 export { CLI_VERSION };