@kjanat/dreamcli 1.0.0 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +63 -6
- package/LICENSE +1 -1
- package/README.md +296 -164
- package/dist/core/cli/dispatch.d.mts +85 -0
- package/dist/core/cli/dispatch.mjs +1 -0
- package/dist/core/cli/index.d.mts +418 -0
- package/dist/core/cli/index.mjs +1 -0
- package/dist/core/cli/planner.d.mts +143 -0
- package/dist/core/cli/planner.mjs +1 -0
- package/dist/core/cli/plugin.d.mts +94 -0
- package/dist/core/cli/plugin.mjs +1 -0
- package/dist/core/cli/propagate.d.mts +39 -0
- package/dist/core/cli/propagate.mjs +1 -0
- package/dist/core/cli/root-help.d.mts +28 -0
- package/dist/core/cli/root-help.mjs +7 -0
- package/dist/core/cli/root-surface.d.mts +42 -0
- package/dist/core/cli/root-surface.mjs +1 -0
- package/dist/core/cli/runtime-preflight.d.mts +149 -0
- package/dist/core/cli/runtime-preflight.mjs +1 -0
- package/dist/core/completion/index.d.mts +46 -0
- package/dist/core/completion/index.mjs +1 -0
- package/dist/core/completion/shells/bash.d.mts +24 -0
- package/dist/core/completion/shells/bash.mjs +3 -0
- package/dist/core/completion/shells/fish.d.mts +20 -0
- package/dist/core/completion/shells/fish.mjs +2 -0
- package/dist/core/completion/shells/powershell.d.mts +14 -0
- package/dist/core/completion/shells/powershell.mjs +2 -0
- package/dist/core/completion/shells/shared.d.mts +139 -0
- package/dist/core/completion/shells/shared.mjs +1 -0
- package/dist/core/completion/shells/zsh.d.mts +24 -0
- package/dist/core/completion/shells/zsh.mjs +2 -0
- package/dist/core/config/index.d.mts +161 -0
- package/dist/core/config/index.mjs +1 -0
- package/dist/core/config/package-json.d.mts +68 -0
- package/dist/core/config/package-json.mjs +1 -0
- package/dist/core/errors/index.d.mts +126 -0
- package/dist/core/errors/index.mjs +1 -0
- package/dist/core/execution/index.d.mts +49 -0
- package/dist/core/execution/index.mjs +1 -0
- package/dist/core/help/index.d.mts +49 -0
- package/dist/core/help/index.mjs +8 -0
- package/dist/core/json-schema/index.d.mts +109 -0
- package/dist/core/json-schema/index.mjs +55 -0
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +185 -0
- package/dist/core/json-schema/meta-descriptions.generated.mjs +28 -0
- package/dist/core/output/activity.d.mts +194 -0
- package/dist/core/output/activity.mjs +1 -0
- package/dist/core/output/contracts.d.mts +88 -0
- package/dist/core/output/contracts.mjs +1 -0
- package/dist/core/output/display-value.d.mts +19 -0
- package/dist/core/output/display-value.mjs +1 -0
- package/dist/core/output/index.d.mts +280 -0
- package/dist/core/output/index.mjs +2 -0
- package/dist/core/output/renderers.d.mts +46 -0
- package/dist/core/output/renderers.mjs +1 -0
- package/dist/core/output/writer.d.mts +40 -0
- package/dist/core/output/writer.mjs +1 -0
- package/dist/core/parse/index.d.mts +79 -0
- package/dist/core/parse/index.mjs +1 -0
- package/dist/core/prompt/index.d.mts +205 -0
- package/dist/core/prompt/index.mjs +6 -0
- package/dist/core/resolve/args.d.mts +8 -0
- package/dist/core/resolve/args.mjs +1 -0
- package/dist/core/resolve/coerce.d.mts +22 -0
- package/dist/core/resolve/coerce.mjs +1 -0
- package/dist/core/resolve/config.d.mts +10 -0
- package/dist/core/resolve/config.mjs +1 -0
- package/dist/core/resolve/contracts.d.mts +112 -0
- package/dist/core/resolve/errors.d.mts +11 -0
- package/dist/core/resolve/errors.mjs +2 -0
- package/dist/core/resolve/flags.d.mts +10 -0
- package/dist/core/resolve/flags.mjs +1 -0
- package/dist/core/resolve/index.d.mts +42 -0
- package/dist/core/resolve/index.mjs +1 -0
- package/dist/core/resolve/property.d.mts +47 -0
- package/dist/core/resolve/property.mjs +1 -0
- package/dist/core/schema/activity.d.mts +169 -0
- package/dist/core/schema/arg.d.mts +559 -0
- package/dist/core/schema/arg.mjs +1 -0
- package/dist/core/schema/command.d.mts +960 -0
- package/dist/core/schema/command.mjs +1 -0
- package/dist/core/schema/flag.d.mts +491 -0
- package/dist/core/schema/flag.mjs +1 -0
- package/dist/core/schema/index.d.mts +8 -0
- package/dist/core/schema/middleware.d.mts +122 -0
- package/dist/core/schema/middleware.mjs +1 -0
- package/dist/core/schema/prompt.d.mts +117 -0
- package/dist/core/schema/run.d.mts +171 -0
- package/dist/core/schema-dsl/runtime.d.mts +144 -0
- package/dist/core/schema-dsl/runtime.mjs +2 -0
- package/dist/core/schema-dsl/to-json-schema.d.mts +30 -0
- package/dist/core/schema-dsl/to-json-schema.mjs +1 -0
- package/dist/core/testkit/index.d.mts +54 -0
- package/dist/core/testkit/index.mjs +1 -0
- package/dist/index.d.mts +28 -920
- package/dist/index.mjs +1 -10
- package/dist/runtime/adapter.d.mts +212 -0
- package/dist/{adapter-B37d9oia.mjs → runtime/adapter.mjs} +1 -1
- package/dist/runtime/auto.d.mts +26 -0
- package/dist/runtime/auto.mjs +1 -0
- package/dist/runtime/bun.d.mts +28 -0
- package/dist/runtime/bun.mjs +1 -0
- package/dist/runtime/deno.d.mts +76 -0
- package/dist/runtime/deno.mjs +2 -0
- package/dist/runtime/detect.d.mts +86 -0
- package/dist/runtime/detect.mjs +1 -0
- package/dist/runtime/index.d.mts +7 -0
- package/dist/runtime/node.d.mts +65 -0
- package/dist/runtime/node.mjs +2 -0
- package/dist/runtime/paths.d.mts +31 -0
- package/dist/runtime/paths.mjs +1 -0
- package/dist/runtime/support.d.mts +42 -0
- package/dist/runtime/support.mjs +1 -0
- package/dist/runtime.d.mts +6 -252
- package/dist/runtime.mjs +1 -1
- package/dist/testkit.d.mts +5 -24
- package/dist/testkit.mjs +1 -1
- package/dist/version.d.mts +16 -0
- package/dist/version.mjs +1 -0
- package/dreamcli.schema.json +338 -0
- package/examples/basic.ts +2 -2
- package/examples/gh/package.json +7 -11
- package/examples/gh/src/commands/auth.ts +2 -2
- package/examples/gh/src/commands/issue.ts +4 -4
- package/examples/gh/src/commands/pr.ts +4 -4
- package/examples/gh/src/docs.ts +11 -0
- package/examples/gh/src/lib/auth.ts +1 -1
- package/examples/gh/src/main.test.ts +6 -5
- package/examples/gh/src/main.ts +8 -6
- package/examples/interactive.ts +3 -3
- package/examples/json-mode.ts +4 -6
- package/examples/middleware.ts +3 -3
- package/examples/multi-command.ts +3 -3
- package/examples/spinner-progress.ts +5 -5
- package/examples/testing.ts +8 -6
- package/package.json +70 -44
- package/src/core/cli/dispatch.ts +4 -0
- package/src/core/cli/index.ts +185 -632
- package/src/core/cli/planner.ts +413 -0
- package/src/core/cli/plugin.ts +7 -1
- package/src/core/cli/propagate.ts +1 -1
- package/src/core/cli/runtime-preflight.ts +409 -0
- package/src/core/completion/index.ts +15 -9
- package/src/core/completion/shells/bash.ts +6 -3
- package/src/core/completion/shells/fish.ts +245 -10
- package/src/core/completion/shells/powershell.ts +390 -9
- package/src/core/completion/shells/shared.ts +4 -4
- package/src/core/completion/shells/zsh.ts +12 -7
- package/src/core/config/index.ts +7 -4
- package/src/core/config/package-json.ts +6 -2
- package/src/core/errors/index.ts +23 -8
- package/src/core/execution/index.ts +270 -0
- package/src/core/help/index.ts +13 -15
- package/src/core/json-schema/index.ts +193 -7
- package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
- package/src/core/output/contracts.ts +194 -0
- package/src/core/output/index.ts +47 -82
- package/src/core/output/renderers.ts +125 -0
- package/src/core/parse/index.ts +39 -21
- package/src/core/prompt/index.ts +44 -27
- package/src/core/resolve/args.ts +144 -0
- package/src/core/resolve/coerce.ts +432 -0
- package/src/core/resolve/config.ts +26 -0
- package/src/core/resolve/contracts.ts +135 -0
- package/src/core/resolve/errors.ts +227 -0
- package/src/core/resolve/flags.ts +205 -0
- package/src/core/resolve/index.ts +41 -1264
- package/src/core/resolve/property.ts +99 -0
- package/src/core/schema/activity.ts +3 -0
- package/src/core/schema/arg.ts +26 -14
- package/src/core/schema/command.ts +265 -38
- package/src/core/schema/flag.ts +120 -15
- package/src/core/schema/index.ts +11 -2
- package/src/core/schema/middleware.ts +6 -6
- package/src/core/schema/prompt.ts +9 -1
- package/src/core/schema/run.ts +25 -17
- package/src/core/schema-dsl/index.ts +109 -0
- package/src/core/schema-dsl/parse.ts +262 -0
- package/src/core/schema-dsl/runtime.ts +609 -0
- package/src/core/schema-dsl/to-json-schema.ts +102 -0
- package/src/core/testkit/index.ts +55 -297
- package/src/index.ts +10 -4
- package/src/runtime/adapter.ts +13 -10
- package/src/runtime/auto.ts +3 -3
- package/src/runtime/bun.ts +4 -4
- package/src/runtime/deno.ts +43 -29
- package/src/runtime/detect.ts +4 -1
- package/src/runtime/index.ts +1 -1
- package/src/runtime/node.ts +43 -21
- package/src/runtime/paths.ts +9 -3
- package/src/runtime/support.ts +20 -4
- package/src/runtime.ts +1 -1
- package/src/testkit.ts +10 -8
- package/dist/adapter-CCSh5juX.cjs +0 -1
- package/dist/adapter-DIwO-q7K.d.mts +0 -3447
- package/dist/adapter-DQnxxLiE.d.cts +0 -3447
- package/dist/auto-5cjZaF9V.mjs +0 -3
- package/dist/auto-B0eSgoDw.cjs +0 -3
- package/dist/index.cjs +0 -10
- package/dist/index.d.cts +0 -920
- package/dist/runtime.cjs +0 -1
- package/dist/runtime.d.cts +0 -253
- package/dist/testkit-CEDYPvhF.mjs +0 -14
- package/dist/testkit-ClIKijxC.cjs +0 -14
- package/dist/testkit.cjs +0 -1
- package/dist/testkit.d.cts +0 -25
- package/examples/gh/tsconfig.json +0 -37
- package/examples/tsconfig.json +0 -17
- package/src/core/cli/AGENTS.md +0 -72
- package/src/core/completion/AGENTS.md +0 -72
- package/src/core/completion/completion-test-helpers.ts +0 -48
- package/src/core/output/AGENTS.md +0 -69
- package/src/core/resolve/AGENTS.md +0 -69
- package/src/core/schema/AGENTS.md +0 -61
- package/src/core/testkit/AGENTS.md +0 -55
- package/src/runtime/AGENTS.md +0 -74
- package/src/runtime/test-helpers.ts +0 -40
|
@@ -14,6 +14,7 @@
|
|
|
14
14
|
*/
|
|
15
15
|
|
|
16
16
|
import type { CLISchema } from '#internals/core/cli/index.ts';
|
|
17
|
+
import { getFlagAliasNames } from '#internals/core/schema/flag.ts';
|
|
17
18
|
import type {
|
|
18
19
|
ArgSchema,
|
|
19
20
|
CommandArgEntry,
|
|
@@ -23,6 +24,9 @@ import type {
|
|
|
23
24
|
PromptConfig,
|
|
24
25
|
SelectChoice,
|
|
25
26
|
} from '#internals/core/schema/index.ts';
|
|
27
|
+
import { parseSchema } from '#internals/core/schema-dsl/runtime.ts';
|
|
28
|
+
import { nodeToJsonSchema } from '#internals/core/schema-dsl/to-json-schema.ts';
|
|
29
|
+
import { definitionMetaSchemaDescriptions } from './meta-descriptions.generated.ts';
|
|
26
30
|
|
|
27
31
|
// --- Options
|
|
28
32
|
|
|
@@ -80,8 +84,14 @@ function resolveOptions(options: JsonSchemaOptions | undefined): ResolvedOptions
|
|
|
80
84
|
|
|
81
85
|
// --- Constants
|
|
82
86
|
|
|
83
|
-
/**
|
|
84
|
-
|
|
87
|
+
/**
|
|
88
|
+
* `$schema` URL for definition documents.
|
|
89
|
+
*
|
|
90
|
+
* Resolves via the actual file path on the CDN (`dreamcli.schema.json`).
|
|
91
|
+
* For offline or local-first workflows, use
|
|
92
|
+
* `./node_modules/@kjanat/dreamcli/dreamcli.schema.json`.
|
|
93
|
+
*/
|
|
94
|
+
const DEFINITION_SCHEMA_URL = 'https://cdn.jsdelivr.net/npm/@kjanat/dreamcli/dreamcli.schema.json';
|
|
85
95
|
|
|
86
96
|
/** Meta-schema URL for JSON Schema draft 2020-12 (input validation). */
|
|
87
97
|
const JSON_SCHEMA_DRAFT = 'https://json-schema.org/draft/2020-12/schema';
|
|
@@ -200,8 +210,9 @@ function serializeFlag(schema: FlagSchema, opts: ResolvedOptions): Record<string
|
|
|
200
210
|
if (schema.presence === 'defaulted' && isJsonSerializable(schema.defaultValue)) {
|
|
201
211
|
result.defaultValue = schema.defaultValue;
|
|
202
212
|
}
|
|
203
|
-
|
|
204
|
-
|
|
213
|
+
const visibleAliases = getFlagAliasNames(schema);
|
|
214
|
+
if (visibleAliases.length > 0) {
|
|
215
|
+
result.aliases = [...visibleAliases];
|
|
205
216
|
}
|
|
206
217
|
if (schema.envVar !== undefined) {
|
|
207
218
|
result.envVar = schema.envVar;
|
|
@@ -598,7 +609,7 @@ function flagToJsonSchemaType(schema: FlagSchema): Record<string, unknown> {
|
|
|
598
609
|
result.default = schema.defaultValue;
|
|
599
610
|
}
|
|
600
611
|
if (schema.deprecated !== undefined) {
|
|
601
|
-
result.deprecated =
|
|
612
|
+
result.deprecated = schema.deprecated;
|
|
602
613
|
}
|
|
603
614
|
|
|
604
615
|
return result;
|
|
@@ -619,7 +630,7 @@ function argToJsonSchemaType(schema: ArgSchema): Record<string, unknown> {
|
|
|
619
630
|
result.default = schema.defaultValue;
|
|
620
631
|
}
|
|
621
632
|
if (schema.deprecated !== undefined) {
|
|
622
|
-
result.deprecated =
|
|
633
|
+
result.deprecated = schema.deprecated;
|
|
623
634
|
}
|
|
624
635
|
|
|
625
636
|
return result;
|
|
@@ -699,7 +710,182 @@ function isPlainJsonObject(value: object): value is Record<string, unknown> {
|
|
|
699
710
|
return proto === Object.prototype || proto === null;
|
|
700
711
|
}
|
|
701
712
|
|
|
713
|
+
// === Definition meta-schema — derived from schema DSL definitions
|
|
714
|
+
|
|
715
|
+
/** Convert a DSL string to a JSON Schema object definition. */
|
|
716
|
+
function def(source: string): Record<string, unknown> {
|
|
717
|
+
return nodeToJsonSchema(parseSchema(source));
|
|
718
|
+
}
|
|
719
|
+
|
|
720
|
+
interface DefinitionMetaSchemaDescriptionNode {
|
|
721
|
+
readonly description?: string;
|
|
722
|
+
readonly properties?: Readonly<Record<string, DefinitionMetaSchemaDescriptionNode>>;
|
|
723
|
+
}
|
|
724
|
+
|
|
725
|
+
function withDefinitionDescriptions(
|
|
726
|
+
schema: Record<string, unknown>,
|
|
727
|
+
descriptions: DefinitionMetaSchemaDescriptionNode,
|
|
728
|
+
): Record<string, unknown> {
|
|
729
|
+
const propertiesValue = schema.properties;
|
|
730
|
+
const describedProperties =
|
|
731
|
+
typeof propertiesValue === 'object' &&
|
|
732
|
+
propertiesValue !== null &&
|
|
733
|
+
isPlainJsonObject(propertiesValue) &&
|
|
734
|
+
descriptions.properties !== undefined
|
|
735
|
+
? Object.fromEntries(
|
|
736
|
+
Object.entries(propertiesValue).map(([name, propertySchema]) => {
|
|
737
|
+
const propertyDescriptions = descriptions.properties?.[name];
|
|
738
|
+
if (
|
|
739
|
+
propertyDescriptions === undefined ||
|
|
740
|
+
typeof propertySchema !== 'object' ||
|
|
741
|
+
propertySchema === null ||
|
|
742
|
+
!isPlainJsonObject(propertySchema)
|
|
743
|
+
) {
|
|
744
|
+
return [name, propertySchema];
|
|
745
|
+
}
|
|
746
|
+
|
|
747
|
+
return [name, withDefinitionDescriptions(propertySchema, propertyDescriptions)];
|
|
748
|
+
}),
|
|
749
|
+
)
|
|
750
|
+
: undefined;
|
|
751
|
+
|
|
752
|
+
return {
|
|
753
|
+
...schema,
|
|
754
|
+
...(descriptions.description !== undefined ? { description: descriptions.description } : {}),
|
|
755
|
+
...(describedProperties !== undefined ? { properties: describedProperties } : {}),
|
|
756
|
+
};
|
|
757
|
+
}
|
|
758
|
+
|
|
759
|
+
function withDefinitionMetaSchemaDescriptions(
|
|
760
|
+
schema: Record<string, unknown>,
|
|
761
|
+
descriptions: {
|
|
762
|
+
readonly root: DefinitionMetaSchemaDescriptionNode;
|
|
763
|
+
readonly defs: Readonly<Record<string, DefinitionMetaSchemaDescriptionNode>>;
|
|
764
|
+
},
|
|
765
|
+
): Record<string, unknown> {
|
|
766
|
+
const describedRoot = withDefinitionDescriptions(schema, descriptions.root);
|
|
767
|
+
const defsValue = describedRoot.$defs;
|
|
768
|
+
if (typeof defsValue !== 'object' || defsValue === null || !isPlainJsonObject(defsValue)) {
|
|
769
|
+
return describedRoot;
|
|
770
|
+
}
|
|
771
|
+
|
|
772
|
+
return {
|
|
773
|
+
...describedRoot,
|
|
774
|
+
$defs: Object.fromEntries(
|
|
775
|
+
Object.entries(defsValue).map(([name, defSchema]) => {
|
|
776
|
+
const defDescriptions = descriptions.defs[name];
|
|
777
|
+
if (
|
|
778
|
+
defDescriptions === undefined ||
|
|
779
|
+
typeof defSchema !== 'object' ||
|
|
780
|
+
defSchema === null ||
|
|
781
|
+
!isPlainJsonObject(defSchema)
|
|
782
|
+
) {
|
|
783
|
+
return [name, defSchema];
|
|
784
|
+
}
|
|
785
|
+
|
|
786
|
+
return [name, withDefinitionDescriptions(defSchema, defDescriptions)];
|
|
787
|
+
}),
|
|
788
|
+
),
|
|
789
|
+
};
|
|
790
|
+
}
|
|
791
|
+
|
|
792
|
+
/**
|
|
793
|
+
* JSON Schema (draft 2020-12) that validates the output of {@link generateSchema}.
|
|
794
|
+
*
|
|
795
|
+
* Each `$defs` entry is defined once as a schema DSL string — the DSL
|
|
796
|
+
* parser produces a runtime AST, and {@link nodeToJsonSchema} converts
|
|
797
|
+
* that AST to a JSON Schema fragment. No probe fixtures, no override
|
|
798
|
+
* maps, no manually maintained type definitions.
|
|
799
|
+
*
|
|
800
|
+
* Hosted at {@link DEFINITION_SCHEMA_URL} for `$schema` resolution. Also
|
|
801
|
+
* exported so tooling can validate definition documents without a network
|
|
802
|
+
* round-trip.
|
|
803
|
+
*
|
|
804
|
+
* @example
|
|
805
|
+
* ```ts
|
|
806
|
+
* import Ajv from 'ajv/dist/2020';
|
|
807
|
+
* import { definitionMetaSchema, generateSchema } from '@kjanat/dreamcli';
|
|
808
|
+
*
|
|
809
|
+
* const ajv = new Ajv();
|
|
810
|
+
* const validate = ajv.compile(definitionMetaSchema);
|
|
811
|
+
* const valid = validate(generateSchema(myCli.schema));
|
|
812
|
+
* ```
|
|
813
|
+
*/
|
|
814
|
+
const definitionMetaSchema: Record<string, unknown> = withDefinitionMetaSchemaDescriptions(
|
|
815
|
+
{
|
|
816
|
+
$schema: JSON_SCHEMA_DRAFT,
|
|
817
|
+
$id: DEFINITION_SCHEMA_URL,
|
|
818
|
+
title: '@kjanat/dreamcli definition schema',
|
|
819
|
+
description:
|
|
820
|
+
'Describes the structure of a CLI built with dreamcli — commands, flags, args, types, constraints, env bindings, and prompts.',
|
|
821
|
+
...def(`{
|
|
822
|
+
$schema: '${DEFINITION_SCHEMA_URL}';
|
|
823
|
+
name: string;
|
|
824
|
+
version?: string;
|
|
825
|
+
description?: string;
|
|
826
|
+
defaultCommand?: string;
|
|
827
|
+
commands: @command[]
|
|
828
|
+
}`),
|
|
829
|
+
$defs: {
|
|
830
|
+
command: def(`{
|
|
831
|
+
name: string;
|
|
832
|
+
description?: string;
|
|
833
|
+
aliases?: string[];
|
|
834
|
+
hidden?: true;
|
|
835
|
+
examples?: @example[];
|
|
836
|
+
flags: Record<string, @flag>;
|
|
837
|
+
args: @arg[];
|
|
838
|
+
commands: @command[]
|
|
839
|
+
}`),
|
|
840
|
+
flag: def(`{
|
|
841
|
+
kind: 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'custom';
|
|
842
|
+
presence: 'optional' | 'required' | 'defaulted';
|
|
843
|
+
defaultValue?: unknown;
|
|
844
|
+
aliases?: string[];
|
|
845
|
+
envVar?: string;
|
|
846
|
+
configPath?: string;
|
|
847
|
+
description?: string;
|
|
848
|
+
enumValues?: string[];
|
|
849
|
+
elementSchema?: @flag;
|
|
850
|
+
prompt?: @prompt;
|
|
851
|
+
deprecated?: string | true;
|
|
852
|
+
propagate?: true
|
|
853
|
+
}`),
|
|
854
|
+
arg: def(`{
|
|
855
|
+
name: string;
|
|
856
|
+
kind: 'string' | 'number' | 'enum' | 'custom';
|
|
857
|
+
presence: 'required' | 'optional' | 'defaulted';
|
|
858
|
+
variadic?: true;
|
|
859
|
+
stdinMode?: true;
|
|
860
|
+
defaultValue?: unknown;
|
|
861
|
+
description?: string;
|
|
862
|
+
envVar?: string;
|
|
863
|
+
enumValues?: string[];
|
|
864
|
+
deprecated?: string | true
|
|
865
|
+
}`),
|
|
866
|
+
prompt: def(`{
|
|
867
|
+
kind: 'confirm' | 'input' | 'select' | 'multiselect';
|
|
868
|
+
message: string;
|
|
869
|
+
placeholder?: string;
|
|
870
|
+
choices?: @choice[];
|
|
871
|
+
min?: integer;
|
|
872
|
+
max?: integer
|
|
873
|
+
}`),
|
|
874
|
+
choice: def(`{
|
|
875
|
+
value: string;
|
|
876
|
+
label?: string;
|
|
877
|
+
description?: string
|
|
878
|
+
}`),
|
|
879
|
+
example: def(`{
|
|
880
|
+
command: string;
|
|
881
|
+
description?: string
|
|
882
|
+
}`),
|
|
883
|
+
},
|
|
884
|
+
},
|
|
885
|
+
definitionMetaSchemaDescriptions,
|
|
886
|
+
);
|
|
887
|
+
|
|
702
888
|
// === Exports
|
|
703
889
|
|
|
704
890
|
export type { JsonSchemaOptions };
|
|
705
|
-
export { generateInputSchema, generateSchema };
|
|
891
|
+
export { definitionMetaSchema, generateInputSchema, generateSchema };
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Generated definition meta-schema descriptions from normalized TypeDoc output.
|
|
3
|
+
*
|
|
4
|
+
* @module
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
const definitionMetaSchemaDescriptions = {
|
|
8
|
+
root: {
|
|
9
|
+
description:
|
|
10
|
+
'Runtime descriptor for the CLI program.\n\nStores the program name, version, description, and registered commands.\\\nBuilt incrementally by CLIBuilder.',
|
|
11
|
+
properties: {
|
|
12
|
+
name: {
|
|
13
|
+
description: 'Program name (used in help text, usage lines, and completion scripts).',
|
|
14
|
+
},
|
|
15
|
+
version: {
|
|
16
|
+
description: 'Program version (shown by `--version`).',
|
|
17
|
+
},
|
|
18
|
+
description: {
|
|
19
|
+
description: 'Program description (shown in root help).',
|
|
20
|
+
},
|
|
21
|
+
defaultCommand: {
|
|
22
|
+
description:
|
|
23
|
+
'Default command dispatched when no subcommand matches.\n\nWhen set, the CLI root behaves like a hybrid command group: subcommands\ndispatch by name as usual, but empty argv or flags-only argv falls\nthrough to this command instead of showing root help.\n\nSet via the .default() builder method.',
|
|
24
|
+
},
|
|
25
|
+
commands: {
|
|
26
|
+
description: 'Registered commands (type-erased for heterogeneous storage).',
|
|
27
|
+
},
|
|
28
|
+
},
|
|
29
|
+
},
|
|
30
|
+
defs: {
|
|
31
|
+
command: {
|
|
32
|
+
description:
|
|
33
|
+
"Runtime descriptor produced by CommandBuilder.\n\nConsumers (parser, help generator, CLI dispatcher) read this to\nunderstand the command's shape — flags, args, aliases, subcommands,\nmiddleware, and interactive resolver.",
|
|
34
|
+
properties: {
|
|
35
|
+
name: {
|
|
36
|
+
description: "The command name (used for dispatch, e.g. `'deploy'`).",
|
|
37
|
+
},
|
|
38
|
+
description: {
|
|
39
|
+
description: 'Human-readable description for help text.',
|
|
40
|
+
},
|
|
41
|
+
aliases: {
|
|
42
|
+
description: 'Alternative names for this command.',
|
|
43
|
+
},
|
|
44
|
+
hidden: {
|
|
45
|
+
description: 'Whether this command is hidden from help listings.',
|
|
46
|
+
},
|
|
47
|
+
examples: {
|
|
48
|
+
description: 'Usage examples for help text.',
|
|
49
|
+
},
|
|
50
|
+
flags: {
|
|
51
|
+
description: 'Named flag schemas, keyed by flag name.',
|
|
52
|
+
},
|
|
53
|
+
args: {
|
|
54
|
+
description: 'Ordered positional arg entries (name + schema).',
|
|
55
|
+
},
|
|
56
|
+
commands: {
|
|
57
|
+
description:
|
|
58
|
+
'Nested subcommand schemas (for help rendering and completion).\n\nPure data — no execution closures. Populated by `.command()` on\n`CommandBuilder`. Empty for leaf commands.',
|
|
59
|
+
},
|
|
60
|
+
},
|
|
61
|
+
},
|
|
62
|
+
flag: {
|
|
63
|
+
description:
|
|
64
|
+
"The runtime descriptor stored inside every FlagBuilder. Consumers (parser,\nhelp generator, resolution chain) read this to understand the flag's shape\nwithout touching generics.",
|
|
65
|
+
properties: {
|
|
66
|
+
kind: {
|
|
67
|
+
description: 'What kind of value this flag accepts.',
|
|
68
|
+
},
|
|
69
|
+
presence: {
|
|
70
|
+
description:
|
|
71
|
+
"Presence describes whether a flag value is guaranteed to exist when the\naction handler runs:\n\n- `'optional'` — not required; unresolved value follows the kind-specific\n optional fallback (`undefined` for most flags, `[]` for arrays)\n- `'required'` — must be supplied; error if missing\n- `'defaulted'` — always present (falls back to default value)",
|
|
72
|
+
},
|
|
73
|
+
defaultValue: {
|
|
74
|
+
description: 'Runtime default value (if any).',
|
|
75
|
+
},
|
|
76
|
+
aliases: {
|
|
77
|
+
description: "Short/long aliases (e.g. `[{ name: 'f', hidden: false }]` for `--force`).",
|
|
78
|
+
},
|
|
79
|
+
envVar: {
|
|
80
|
+
description: 'Environment variable name for v0.2+ resolution.',
|
|
81
|
+
},
|
|
82
|
+
configPath: {
|
|
83
|
+
description: "Dotted config path for v0.2+ resolution (e.g. `'deploy.region'`).",
|
|
84
|
+
},
|
|
85
|
+
description: {
|
|
86
|
+
description: 'Human-readable description for help text.',
|
|
87
|
+
},
|
|
88
|
+
enumValues: {
|
|
89
|
+
description: "Allowed literal values when `kind === 'enum'`.",
|
|
90
|
+
},
|
|
91
|
+
elementSchema: {
|
|
92
|
+
description: "Element schema when `kind === 'array'`.",
|
|
93
|
+
},
|
|
94
|
+
prompt: {
|
|
95
|
+
description: 'Interactive prompt configuration for v0.3+ resolution.',
|
|
96
|
+
},
|
|
97
|
+
deprecated: {
|
|
98
|
+
description:
|
|
99
|
+
'Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated flag is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`.',
|
|
100
|
+
},
|
|
101
|
+
propagate: {
|
|
102
|
+
description:
|
|
103
|
+
'Whether this flag propagates to subcommands in nested command trees.\n\nWhen `true`, the flag is automatically available to all descendant\ncommands. A child command that defines a flag with the same name\nshadows the propagated parent flag.',
|
|
104
|
+
},
|
|
105
|
+
},
|
|
106
|
+
},
|
|
107
|
+
arg: {
|
|
108
|
+
description:
|
|
109
|
+
"The runtime descriptor stored inside every ArgBuilder. Consumers (parser,\nhelp generator) read this to understand the arg's shape without touching\ngenerics.",
|
|
110
|
+
properties: {
|
|
111
|
+
name: {
|
|
112
|
+
description:
|
|
113
|
+
'A named positional argument entry in the command schema.\n\nPairs a user-facing arg name with its ArgSchema descriptor.\nThe array ordering in CommandSchema.args determines CLI position.',
|
|
114
|
+
},
|
|
115
|
+
kind: {
|
|
116
|
+
description: 'What kind of value this arg accepts.',
|
|
117
|
+
},
|
|
118
|
+
presence: {
|
|
119
|
+
description:
|
|
120
|
+
"Presence describes whether a positional arg is guaranteed to exist when the\naction handler runs:\n\n- `'required'` — must be supplied; error if missing (default)\n- `'optional'` — may be `undefined` if not supplied\n- `'defaulted'` — always present (falls back to default value)",
|
|
121
|
+
},
|
|
122
|
+
variadic: {
|
|
123
|
+
description: 'Whether this arg consumes all remaining positionals.',
|
|
124
|
+
},
|
|
125
|
+
stdinMode: {
|
|
126
|
+
description: 'Whether this arg may read from stdin during resolution.',
|
|
127
|
+
},
|
|
128
|
+
defaultValue: {
|
|
129
|
+
description: 'Runtime default value (if any).',
|
|
130
|
+
},
|
|
131
|
+
description: {
|
|
132
|
+
description: 'Human-readable description for help text.',
|
|
133
|
+
},
|
|
134
|
+
envVar: {
|
|
135
|
+
description:
|
|
136
|
+
"Environment variable name for env resolution.\n\nWhen set and the CLI value is absent, the resolver reads this env var\nand coerces the string to the arg's declared kind.",
|
|
137
|
+
},
|
|
138
|
+
enumValues: {
|
|
139
|
+
description: "Allowed literal values when `kind === 'enum'`.",
|
|
140
|
+
},
|
|
141
|
+
deprecated: {
|
|
142
|
+
description:
|
|
143
|
+
'Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated arg is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`.',
|
|
144
|
+
},
|
|
145
|
+
},
|
|
146
|
+
},
|
|
147
|
+
prompt: {
|
|
148
|
+
description:
|
|
149
|
+
"Discriminated union of all prompt configurations.\n\nUse the `kind` field to narrow:\n```ts\nif (config.kind === 'select') {\n config.choices // readonly SelectChoice[] | undefined\n}\n```",
|
|
150
|
+
properties: {
|
|
151
|
+
kind: {
|
|
152
|
+
description:
|
|
153
|
+
"The kind of interactive prompt to present.\n\n- `'confirm'` — yes/no boolean question\n- `'input'` — free-text string input\n- `'select'` — single selection from a list\n- `'multiselect'` — multiple selections from a list",
|
|
154
|
+
},
|
|
155
|
+
message: {
|
|
156
|
+
description: 'The question displayed to the user.',
|
|
157
|
+
},
|
|
158
|
+
placeholder: {
|
|
159
|
+
description: 'Placeholder text shown before user types (informational only).',
|
|
160
|
+
},
|
|
161
|
+
choices: {
|
|
162
|
+
description:
|
|
163
|
+
'Available choices. When omitted for `enum` flags, the enum values\nfrom the flag schema are used automatically.',
|
|
164
|
+
},
|
|
165
|
+
min: {
|
|
166
|
+
description: 'Minimum number of selections required.',
|
|
167
|
+
},
|
|
168
|
+
max: {
|
|
169
|
+
description: 'Maximum number of selections allowed.',
|
|
170
|
+
},
|
|
171
|
+
},
|
|
172
|
+
},
|
|
173
|
+
choice: {
|
|
174
|
+
description:
|
|
175
|
+
'A selectable option for SelectPromptConfig and MultiselectPromptConfig prompts.',
|
|
176
|
+
properties: {
|
|
177
|
+
value: {
|
|
178
|
+
description: 'The value returned when this choice is selected.',
|
|
179
|
+
},
|
|
180
|
+
label: {
|
|
181
|
+
description: 'Display label shown to the user.',
|
|
182
|
+
},
|
|
183
|
+
description: {
|
|
184
|
+
description: 'Optional description shown alongside the choice.',
|
|
185
|
+
},
|
|
186
|
+
},
|
|
187
|
+
},
|
|
188
|
+
example: {
|
|
189
|
+
description: 'A single usage example shown in help text.',
|
|
190
|
+
properties: {
|
|
191
|
+
command: {
|
|
192
|
+
description: "The command invocation (e.g. `'deploy production --force'`).",
|
|
193
|
+
},
|
|
194
|
+
description: {
|
|
195
|
+
description: 'Optional description of what this example does.',
|
|
196
|
+
},
|
|
197
|
+
},
|
|
198
|
+
},
|
|
199
|
+
},
|
|
200
|
+
} as const;
|
|
201
|
+
|
|
202
|
+
export { definitionMetaSchemaDescriptions };
|
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Internal output policy contract for mode selection and cleanup semantics.
|
|
3
|
+
*
|
|
4
|
+
* Captures the stable seam between semantic output decisions and the concrete
|
|
5
|
+
* rendering layer before the output module is split more aggressively.
|
|
6
|
+
*
|
|
7
|
+
* @module dreamcli/core/output/contracts
|
|
8
|
+
* @internal
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import type { Fallback, TableOptions } from '#internals/core/schema/activity.ts';
|
|
12
|
+
|
|
13
|
+
/** Ordered output verbosity levels owned by the output policy layer. */
|
|
14
|
+
const OUTPUT_VERBOSITY_LEVELS = ['normal', 'quiet'] as const;
|
|
15
|
+
|
|
16
|
+
/** Stable output text streams. */
|
|
17
|
+
const OUTPUT_STREAMS = ['stdout', 'stderr'] as const;
|
|
18
|
+
|
|
19
|
+
/** Stable activity rendering modes. */
|
|
20
|
+
const ACTIVITY_RENDER_MODES = ['noop', 'static', 'tty', 'capture'] as const;
|
|
21
|
+
|
|
22
|
+
/** Stable activity cleanup actions. */
|
|
23
|
+
const ACTIVITY_CLEANUP_KINDS = ['none', 'stop', 'done'] as const;
|
|
24
|
+
|
|
25
|
+
/** Stable text verbosity labels. */
|
|
26
|
+
type Verbosity = (typeof OUTPUT_VERBOSITY_LEVELS)[number];
|
|
27
|
+
|
|
28
|
+
/** Stable output stream labels. */
|
|
29
|
+
type OutputStream = (typeof OUTPUT_STREAMS)[number];
|
|
30
|
+
|
|
31
|
+
/** Stable activity-render labels. */
|
|
32
|
+
type ActivityRenderMode = (typeof ACTIVITY_RENDER_MODES)[number];
|
|
33
|
+
|
|
34
|
+
/** Stable cleanup labels for tracked activity handles. */
|
|
35
|
+
type ActivityCleanupKind = (typeof ACTIVITY_CLEANUP_KINDS)[number];
|
|
36
|
+
|
|
37
|
+
/** Semantic output facts chosen before concrete rendering begins. */
|
|
38
|
+
interface OutputPolicy {
|
|
39
|
+
/** Whether `--json` was requested, routing structured data to stdout. */
|
|
40
|
+
readonly jsonMode: boolean;
|
|
41
|
+
/** Whether the output stream is connected to an interactive terminal. */
|
|
42
|
+
readonly isTTY: boolean;
|
|
43
|
+
/** Active verbosity level controlling which message categories emit. */
|
|
44
|
+
readonly verbosity: Verbosity;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** Inputs for building an {@linkcode OutputPolicy} snapshot. */
|
|
48
|
+
interface ResolveOutputPolicyOptions {
|
|
49
|
+
/** Whether `--json` was requested on the command line. */
|
|
50
|
+
readonly jsonMode: boolean;
|
|
51
|
+
/** Whether the output stream is connected to an interactive terminal. */
|
|
52
|
+
readonly isTTY: boolean;
|
|
53
|
+
/** Verbosity level to apply for this channel instance. */
|
|
54
|
+
readonly verbosity: Verbosity;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** Concrete activity policy chosen for spinner/progress creation. */
|
|
58
|
+
interface ActivityPolicy {
|
|
59
|
+
/** Render strategy for the activity indicator (never `'capture'` here). */
|
|
60
|
+
readonly mode: Exclude<ActivityRenderMode, 'capture'>;
|
|
61
|
+
/** Activity output always targets stderr to avoid polluting structured stdout. */
|
|
62
|
+
readonly stream: 'stderr';
|
|
63
|
+
/** Cleanup action the output layer must run when the handle is discarded. */
|
|
64
|
+
readonly cleanup: ActivityCleanupKind;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** Stable output-policy facts the re-foundation workstream is freezing. */
|
|
68
|
+
interface OutputContract {
|
|
69
|
+
/** In JSON mode, stdout carries only machine-readable structured output. */
|
|
70
|
+
readonly jsonReservesStdoutForStructuredData: true;
|
|
71
|
+
/** Quiet verbosity suppresses `info()` messages entirely. */
|
|
72
|
+
readonly quietSuppressesInfo: true;
|
|
73
|
+
/** Spinner/progress writes go to stderr so stdout stays parseable. */
|
|
74
|
+
readonly activityUsesStderrOutsideCapture: true;
|
|
75
|
+
/** Animated TTY spinners require both a real terminal and non-JSON mode. */
|
|
76
|
+
readonly ttyActivityRequiresTTYAndNonJson: true;
|
|
77
|
+
/** Spinner handles clean up via `stop()` to clear the animation line. */
|
|
78
|
+
readonly spinnerCleanupUsesStop: true;
|
|
79
|
+
/** Progress handles clean up via `done()` to render the final state. */
|
|
80
|
+
readonly progressCleanupUsesDone: true;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/** Runtime-accessible copy of the frozen output-policy invariants. */
|
|
84
|
+
const outputContract = {
|
|
85
|
+
jsonReservesStdoutForStructuredData: true,
|
|
86
|
+
quietSuppressesInfo: true,
|
|
87
|
+
activityUsesStderrOutsideCapture: true,
|
|
88
|
+
ttyActivityRequiresTTYAndNonJson: true,
|
|
89
|
+
spinnerCleanupUsesStop: true,
|
|
90
|
+
progressCleanupUsesDone: true,
|
|
91
|
+
} satisfies OutputContract;
|
|
92
|
+
|
|
93
|
+
/** Build the stable output-policy snapshot for one channel instance. */
|
|
94
|
+
function resolveOutputPolicy(options: ResolveOutputPolicyOptions): OutputPolicy {
|
|
95
|
+
return {
|
|
96
|
+
jsonMode: options.jsonMode,
|
|
97
|
+
isTTY: options.isTTY,
|
|
98
|
+
verbosity: options.verbosity,
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** Resolve the default text stream for non-JSON structured output. */
|
|
103
|
+
function resolveTextStream(policy: OutputPolicy): OutputStream {
|
|
104
|
+
return policy.jsonMode ? 'stderr' : 'stdout';
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/** Whether `info()` messages should be emitted under the current policy. */
|
|
108
|
+
function shouldEmitInfo(policy: OutputPolicy): boolean {
|
|
109
|
+
return policy.verbosity !== 'quiet';
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/** Resolve the concrete table format under the current policy. */
|
|
113
|
+
function resolveTableFormat(policy: OutputPolicy, options?: TableOptions): 'text' | 'json' {
|
|
114
|
+
switch (options?.format) {
|
|
115
|
+
case 'json':
|
|
116
|
+
return 'json';
|
|
117
|
+
case 'text':
|
|
118
|
+
return 'text';
|
|
119
|
+
case 'auto':
|
|
120
|
+
case undefined:
|
|
121
|
+
return policy.jsonMode ? 'json' : 'text';
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/** Resolve the text-table stream after table-format selection. */
|
|
126
|
+
function resolveTableTextStream(policy: OutputPolicy, options?: TableOptions): OutputStream {
|
|
127
|
+
if (options?.format === 'text' && 'stream' in options && options.stream !== undefined) {
|
|
128
|
+
return options.stream;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
return resolveTextStream(policy);
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/** Resolve the non-capture activity mode shared by spinner and progress. */
|
|
135
|
+
function resolveActivityRenderMode(
|
|
136
|
+
policy: OutputPolicy,
|
|
137
|
+
fallback: Fallback,
|
|
138
|
+
): ActivityPolicy['mode'] {
|
|
139
|
+
if (policy.jsonMode) {
|
|
140
|
+
return 'noop';
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
if (policy.isTTY) {
|
|
144
|
+
return 'tty';
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
return fallback === 'static' ? 'static' : 'noop';
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/** Resolve spinner activity policy including cleanup ownership. */
|
|
151
|
+
function resolveSpinnerPolicy(policy: OutputPolicy, fallback: Fallback): ActivityPolicy {
|
|
152
|
+
const mode = resolveActivityRenderMode(policy, fallback);
|
|
153
|
+
return {
|
|
154
|
+
mode,
|
|
155
|
+
stream: 'stderr',
|
|
156
|
+
cleanup: mode === 'noop' ? 'none' : 'stop',
|
|
157
|
+
};
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/** Resolve progress activity policy including cleanup ownership. */
|
|
161
|
+
function resolveProgressPolicy(policy: OutputPolicy, fallback: Fallback): ActivityPolicy {
|
|
162
|
+
const mode = resolveActivityRenderMode(policy, fallback);
|
|
163
|
+
return {
|
|
164
|
+
mode,
|
|
165
|
+
stream: 'stderr',
|
|
166
|
+
cleanup: mode === 'noop' ? 'none' : 'done',
|
|
167
|
+
};
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
export type {
|
|
171
|
+
ActivityCleanupKind,
|
|
172
|
+
ActivityPolicy,
|
|
173
|
+
ActivityRenderMode,
|
|
174
|
+
OutputContract,
|
|
175
|
+
OutputPolicy,
|
|
176
|
+
OutputStream,
|
|
177
|
+
ResolveOutputPolicyOptions,
|
|
178
|
+
Verbosity,
|
|
179
|
+
};
|
|
180
|
+
export {
|
|
181
|
+
ACTIVITY_CLEANUP_KINDS,
|
|
182
|
+
ACTIVITY_RENDER_MODES,
|
|
183
|
+
OUTPUT_STREAMS,
|
|
184
|
+
OUTPUT_VERBOSITY_LEVELS,
|
|
185
|
+
outputContract,
|
|
186
|
+
resolveActivityRenderMode,
|
|
187
|
+
resolveOutputPolicy,
|
|
188
|
+
resolveProgressPolicy,
|
|
189
|
+
resolveSpinnerPolicy,
|
|
190
|
+
resolveTableFormat,
|
|
191
|
+
resolveTableTextStream,
|
|
192
|
+
resolveTextStream,
|
|
193
|
+
shouldEmitInfo,
|
|
194
|
+
};
|