scriber-core 1.0.0__py3-none-any.whl

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.
@@ -0,0 +1,28 @@
1
+ # src/scriber_core/__init__.py
2
+ """
3
+ scriber_core
4
+
5
+ Single top-level import namespace for the Scriber Labs & Eigenscribe workspace
6
+ baseline. The design-token / gradient frontend and the CLI suite are bundled as
7
+ subpackages (``scriber_core.frontend`` and ``scriber_core.cli``) under one package
8
+ root, so the distribution no longer installs generic top-level ``frontend`` /
9
+ ``cli`` packages that could collide with other projects.
10
+
11
+ Author: Eigenscribe & Scriber Labs
12
+ Date: November 20, 2026
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ from typing import Final
18
+
19
+ from . import frontend
20
+ from . import cli
21
+
22
+ __version__: Final[str] = "1.0.0"
23
+
24
+ __all__: list[str] = [
25
+ "__version__",
26
+ "frontend",
27
+ "cli",
28
+ ]
@@ -0,0 +1,164 @@
1
+ """
2
+ Scriber Core CLI Package.
3
+
4
+ Provides terminal color table formatters, block swatch generators, and palette inspection tools.
5
+ Follows the gold standard module structure: what exists, what you're allowed to call,
6
+ how it works, and proof it works.
7
+
8
+ Author: Eigenscribe & Scriber Labs
9
+ Date: November 19, 2026
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ from typing import Final
15
+
16
+ from scriber_core.frontend.colors import COLOR_PALETTE, RGB, hex_to_rgb
17
+
18
+ from . import branding, command_catalog, colors_table, main, messaging, smoke_tests, vt_mode
19
+ from .branding import (
20
+ BORDER_FRAME_COLOR,
21
+ CLI_VERSION,
22
+ CMD_NAME_COLOR,
23
+ DESC_TEXT_COLOR,
24
+ EIGENSCRIBE_BLOCK_TEXT,
25
+ HEADER_CATEGORY_COLOR,
26
+ PRIMARY_GRADIENT,
27
+ SECONDARY_GRADIENT,
28
+ SECTION_BULLET_COLOR,
29
+ SYNTAX_FLAG_COLOR,
30
+ ansi_color,
31
+ print_brand_header,
32
+ render_brand_header,
33
+ run_smoke_test as run_branding_smoke_test,
34
+ )
35
+ from .command_catalog import (
36
+ BADGE_COLORS,
37
+ CommandDescriptor,
38
+ REGISTERED_COMMANDS,
39
+ print_commands_list,
40
+ render_commands_list,
41
+ run_smoke_test as run_catalog_smoke_test,
42
+ )
43
+ from .colors_table import (
44
+ BOX_STYLES,
45
+ DEFAULT_BLOCK_CHAR,
46
+ DEFAULT_BLOCK_WIDTH,
47
+ DEFAULT_BORDER_STYLE,
48
+ ColorEntry,
49
+ SortKey,
50
+ TableStyle,
51
+ build_color_entries,
52
+ cli,
53
+ format_color_swatch,
54
+ format_colored_name,
55
+ print_colors_table,
56
+ render_colors_table,
57
+ run_smoke_test as run_colors_table_smoke_test,
58
+ )
59
+ from .main import (
60
+ cli as main_cli,
61
+ cli_group,
62
+ )
63
+ from .messaging import (
64
+ EIGENSCRIBE_PALETTE,
65
+ STYLE_MAP,
66
+ ansi_256,
67
+ cli_banner,
68
+ cli_echo,
69
+ cli_error,
70
+ cli_highlight,
71
+ cli_info,
72
+ cli_message,
73
+ cli_rule,
74
+ cli_success,
75
+ cli_warning,
76
+ render_banner,
77
+ render_echo,
78
+ render_message,
79
+ render_rule,
80
+ supports_256_color,
81
+ run_smoke_test as run_messaging_smoke_test,
82
+ )
83
+ from .smoke_tests import run_smoke_test as run_cli_smoke_test
84
+ from .vt_mode import enable_vt_mode, run_smoke_test as run_vt_mode_smoke_test
85
+
86
+ __version__: Final[str] = CLI_VERSION
87
+
88
+ __all__: list[str] = [
89
+ "__version__",
90
+ # Submodules
91
+ "branding",
92
+ "command_catalog",
93
+ "colors_table",
94
+ "main",
95
+ "messaging",
96
+ "smoke_tests",
97
+ "vt_mode",
98
+ # Re-exported Palette Data
99
+ "COLOR_PALETTE",
100
+ "RGB",
101
+ "hex_to_rgb",
102
+ # Functions
103
+ "cli",
104
+ "cli_group",
105
+ "main_cli",
106
+ "print_colors_table",
107
+ "render_colors_table",
108
+ "build_color_entries",
109
+ "format_color_swatch",
110
+ "format_colored_name",
111
+ "print_brand_header",
112
+ "render_brand_header",
113
+ "print_commands_list",
114
+ "render_commands_list",
115
+ "ansi_color",
116
+ "enable_vt_mode",
117
+ # Messaging Functions
118
+ "cli_message",
119
+ "cli_echo",
120
+ "cli_rule",
121
+ "cli_banner",
122
+ "cli_info",
123
+ "cli_success",
124
+ "cli_warning",
125
+ "cli_error",
126
+ "cli_highlight",
127
+ "render_message",
128
+ "render_echo",
129
+ "render_rule",
130
+ "render_banner",
131
+ "ansi_256",
132
+ "supports_256_color",
133
+ # Smoke test functions (module-level)
134
+ "run_cli_smoke_test",
135
+ "run_messaging_smoke_test",
136
+ "run_branding_smoke_test",
137
+ "run_catalog_smoke_test",
138
+ "run_colors_table_smoke_test",
139
+ "run_vt_mode_smoke_test",
140
+ # Types & Models
141
+ "ColorEntry",
142
+ "CommandDescriptor",
143
+ "SortKey",
144
+ "TableStyle",
145
+ # Constants
146
+ "BOX_STYLES",
147
+ "DEFAULT_BLOCK_CHAR",
148
+ "DEFAULT_BLOCK_WIDTH",
149
+ "DEFAULT_BORDER_STYLE",
150
+ "CLI_VERSION",
151
+ "PRIMARY_GRADIENT",
152
+ "SECONDARY_GRADIENT",
153
+ "EIGENSCRIBE_BLOCK_TEXT",
154
+ "REGISTERED_COMMANDS",
155
+ "HEADER_CATEGORY_COLOR",
156
+ "CMD_NAME_COLOR",
157
+ "SYNTAX_FLAG_COLOR",
158
+ "DESC_TEXT_COLOR",
159
+ "BORDER_FRAME_COLOR",
160
+ "SECTION_BULLET_COLOR",
161
+ "BADGE_COLORS",
162
+ "EIGENSCRIBE_PALETTE",
163
+ "STYLE_MAP",
164
+ ]
@@ -0,0 +1,17 @@
1
+ """
2
+ __main__.py
3
+
4
+ Package execution launcher for `python -m scriber_core.cli`.
5
+ Follows the gold standard entry point pattern.
6
+
7
+ Author: Eigenscribe & Scriber Labs
8
+ Date: November 19, 2026
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from scriber_core.cli.main import main
14
+
15
+
16
+ if __name__ == "__main__":
17
+ main()
@@ -0,0 +1,314 @@
1
+ """
2
+ branding.py
3
+
4
+ Branding and header rendering for the Eigenscribe CLI.
5
+ Contains the ASCII art logo, gradient helpers for block text, semantic color
6
+ token constants, and functions to render the branded header with gradient
7
+ styling.
8
+
9
+ The conceptual story follows the Eigenscribe architectural standard:
10
+ What exists -> What you're allowed to call -> How it works -> Proof it works.
11
+
12
+ Author: Eigenscribe & Scriber Labs
13
+ Date: November 19, 2026
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ from typing import Final, Sequence
19
+
20
+ import click
21
+
22
+ from scriber_core.frontend.colors import COLOR_PALETTE, RGB, hex_to_rgb
23
+ from scriber_core.frontend.gradients import GRADIENT_PRESETS, multi_gradient
24
+
25
+
26
+ __all__: list[str] = [
27
+ # Constants
28
+ "CLI_VERSION",
29
+ "PRIMARY_GRADIENT",
30
+ "SECONDARY_GRADIENT",
31
+ "EIGENSCRIBE_BLOCK_TEXT",
32
+ "HEADER_CATEGORY_COLOR",
33
+ "CMD_NAME_COLOR",
34
+ "SYNTAX_FLAG_COLOR",
35
+ "DESC_TEXT_COLOR",
36
+ "BORDER_FRAME_COLOR",
37
+ "SECTION_BULLET_COLOR",
38
+ # Functions
39
+ "ansi_color",
40
+ "interpolate_gradient_color",
41
+ "vertical_gradient_block_text",
42
+ "render_brand_header",
43
+ "print_brand_header",
44
+ "run_smoke_test",
45
+ ]
46
+
47
+
48
+ # -----------------------------------------------------------------------------------------------------------
49
+ # 🎭 Typing helpers / constants (define once, use Final)
50
+ # -----------------------------------------------------------------------------------------------------------
51
+
52
+ CLI_VERSION: Final[str] = "1.0.0"
53
+
54
+ PRIMARY_GRADIENT: Final[tuple[str, ...]] = GRADIENT_PRESETS["eigenscribe"]
55
+ SECONDARY_GRADIENT: Final[tuple[str, ...]] = ("#00a6ff", "#7952f5", "#a855f7", "#ff28a2")
56
+
57
+ # ASCII art rendering "EIGENSCRIBE" (figlet standard font)
58
+ EIGENSCRIBE_BLOCK_TEXT: Final[str] = r"""
59
+ _____ ___ ____ _____ _ _ ____ ____ ____ ___ ____ _____
60
+ | ____|_ _/ ___| ____| \ | / ___| / ___| _ \|_ _| __ )| ____|
61
+ | _| | | | _| _| | \| \___ \| | | |_) || || _ \| _|
62
+ | |___ | | |_| | |___| |\ |___) | |___| _ < | || |_) | |___
63
+ |_____|___\____|_____|_| \_|____/ \____|_| \_\___|____/|_____|
64
+ """
65
+
66
+ # Semantic Color Token Mapping from COLOR_PALETTE
67
+ HEADER_CATEGORY_COLOR: Final[str] = COLOR_PALETTE["node-2"] # #00e8ff - High contrast primary focus
68
+ CMD_NAME_COLOR: Final[str] = COLOR_PALETTE["success_emerald"] # #10b981 - Command names in help output
69
+ SYNTAX_FLAG_COLOR: Final[str] = COLOR_PALETTE["pale_lilac"] # #d8b4fe - Syntax and options
70
+ DESC_TEXT_COLOR: Final[str] = COLOR_PALETTE["ice_blue"] # #b8f6ff - Readable description body
71
+ BORDER_FRAME_COLOR: Final[str] = COLOR_PALETTE["periwinkle_blue"] # #5280ff - Structural frame borders
72
+ SECTION_BULLET_COLOR: Final[str] = COLOR_PALETTE["sky_cyan"] # #4cc9f0 - Bullet markers
73
+
74
+
75
+ # -----------------------------------------------------------------------------------------------------------
76
+ # 2️⃣ Public API (functions users are meant to call)
77
+ # -----------------------------------------------------------------------------------------------------------
78
+
79
+
80
+ def ansi_color(hex_code: str, text: str, *, bold: bool = False) -> str:
81
+ """Format a text string with ANSI 24-bit TrueColor foreground escape sequences.
82
+
83
+ Parameters
84
+ ----------
85
+ hex_code : str
86
+ Hexadecimal color string (e.g. '#00e8ff').
87
+ text : str
88
+ Text string to style.
89
+ bold : bool, default=False
90
+ Whether to apply bold font weight.
91
+
92
+ Returns
93
+ -------
94
+ str
95
+ Text string wrapped in TrueColor ANSI sequences.
96
+ """
97
+ r, g, b = hex_to_rgb(hex_code)
98
+ weight = "1;" if bold else ""
99
+ return f"\033[{weight}38;2;{r};{g};{b}m{text}\033[0m"
100
+
101
+
102
+ def interpolate_gradient_color(colors: Sequence[str], position: float) -> str:
103
+ """Interpolate a hex color from a gradient at a given position [0.0, 1.0].
104
+
105
+ Parameters
106
+ ----------
107
+ colors : Sequence[str]
108
+ Hex color stops for the gradient (at least two).
109
+ position : float
110
+ Normalized position in [0.0, 1.0].
111
+
112
+ Returns
113
+ -------
114
+ str
115
+ Interpolated hex color string.
116
+ """
117
+ if len(colors) < 2:
118
+ return colors[0] if colors else "#000000"
119
+
120
+ if position <= 0.0:
121
+ return colors[0]
122
+ if position >= 1.0:
123
+ return colors[-1]
124
+
125
+ # Find the two surrounding color stops
126
+ segment_length = 1.0 / (len(colors) - 1)
127
+ segment = int(position / segment_length)
128
+ segment = min(segment, len(colors) - 2)
129
+
130
+ t = (position - segment * segment_length) / segment_length
131
+ t = max(0.0, min(1.0, t))
132
+
133
+ r1, g1, b1 = hex_to_rgb(colors[segment])
134
+ r2, g2, b2 = hex_to_rgb(colors[segment + 1])
135
+
136
+ r = round(r1 + t * (r2 - r1))
137
+ g = round(g1 + t * (g2 - g1))
138
+ b = round(b1 + t * (b2 - b1))
139
+
140
+ return f"#{r:02x}{g:02x}{b:02x}"
141
+
142
+
143
+ def vertical_gradient_block_text(
144
+ block_text: str,
145
+ colors: Sequence[str],
146
+ *,
147
+ bold: bool = True,
148
+ ) -> str:
149
+ """Apply a top-to-bottom gradient to multi-line block text (ASCII art).
150
+
151
+ Each non-empty row receives a single interpolated color from the gradient,
152
+ based on its vertical position among all non-empty rows.
153
+
154
+ Parameters
155
+ ----------
156
+ block_text : str
157
+ Multi-line block text (e.g. ASCII art).
158
+ colors : Sequence[str]
159
+ Hex color stops for the gradient.
160
+ bold : bool, default=True
161
+ Whether to apply bold ANSI formatting.
162
+
163
+ Returns
164
+ -------
165
+ str
166
+ ANSI TrueColor-escaped block text with per-row gradient colors.
167
+ """
168
+ rows = block_text.strip("\n").split("\n")
169
+ non_empty_rows = [r for r in rows if r.strip()]
170
+ total = len(non_empty_rows)
171
+
172
+ weight = "1;" if bold else ""
173
+ styled_rows: list[str] = []
174
+ non_empty_index = 0
175
+
176
+ for row in rows:
177
+ if row.strip():
178
+ position = non_empty_index / (total - 1) if total > 1 else 0.0
179
+ color = interpolate_gradient_color(colors, position)
180
+ r, g, b = hex_to_rgb(color)
181
+ styled_rows.append(f"\033[{weight}38;2;{r};{g};{b}m{row}\033[0m")
182
+ non_empty_index += 1
183
+ else:
184
+ styled_rows.append(row)
185
+
186
+ return "\n".join(styled_rows)
187
+
188
+
189
+ def render_brand_header(
190
+ *,
191
+ title: str = "🔱 SCRIBER CORE — DETERMINISTIC WORKSPACE & PALETTE SUITE",
192
+ description: str = "Deterministic workspace baseline, styling tokens, and visualization rules for scientific and development agents.",
193
+ width: int = 88,
194
+ ) -> str:
195
+ """Render the signature 'EIGENSCRIBE' block text, gradient title, and description.
196
+
197
+ Parameters
198
+ ----------
199
+ title : str, default="🔱 SCRIBER CORE — DETERMINISTIC WORKSPACE & PALETTE SUITE"
200
+ Main branded title string.
201
+ description : str, default="..."
202
+ Branded subtitle / description string.
203
+ width : int, default=88
204
+ Total horizontal display width.
205
+
206
+ Returns
207
+ -------
208
+ str
209
+ Formatted ANSI TrueColor header block string.
210
+ """
211
+ lines: list[str] = []
212
+
213
+ # 1. Block text reading "EIGENSCRIBE" with top-to-bottom eigenscribe gradient
214
+ block_logo = vertical_gradient_block_text(EIGENSCRIBE_BLOCK_TEXT, colors=PRIMARY_GRADIENT, bold=True)
215
+ lines.append(block_logo)
216
+ lines.append("")
217
+
218
+ # 2. Branded title with PRIMARY_GRADIENT
219
+ styled_title = multi_gradient(f" {title}", colors=PRIMARY_GRADIENT, bold=True)
220
+ lines.append(styled_title)
221
+
222
+ # 3. Branded description with SECONDARY_GRADIENT
223
+ styled_desc = multi_gradient(f" {description}", colors=SECONDARY_GRADIENT, bold=False)
224
+ lines.append(styled_desc)
225
+ lines.append("")
226
+
227
+ # 4. Horizontal rule divider
228
+ divider = "═" * width
229
+ lines.append(ansi_color(BORDER_FRAME_COLOR, f" {divider}", bold=True))
230
+
231
+ return "\n".join(lines)
232
+
233
+
234
+ def print_brand_header(
235
+ *,
236
+ title: str = "🔱 SCRIBER CORE — DETERMINISTIC WORKSPACE & PALETTE SUITE",
237
+ description: str = "Deterministic workspace baseline, styling tokens, and visualization rules for scientific and development agents.",
238
+ width: int = 88,
239
+ color: bool = True,
240
+ ) -> None:
241
+ """Print the signature brand header directly to standard output.
242
+
243
+ Parameters
244
+ ----------
245
+ title : str, optional
246
+ Branded title string.
247
+ description : str, optional
248
+ Branded description string.
249
+ width : int, default=88
250
+ Rule divider width.
251
+ color : bool, default=True
252
+ Whether to preserve ANSI TrueColor escape sequences.
253
+ """
254
+ click.echo(render_brand_header(title=title, description=description, width=width), color=color)
255
+
256
+
257
+ # -----------------------------------------------------------------------------------------------------------
258
+ # 4️⃣ 💨 Smoke tests / example usage (proof it works)
259
+ # -----------------------------------------------------------------------------------------------------------
260
+
261
+
262
+ def run_smoke_test() -> bool:
263
+ """Validate branding constants and header rendering.
264
+
265
+ Returns
266
+ -------
267
+ bool
268
+ True if all branding checks pass.
269
+ """
270
+ print("💨 Running src/scriber_core/cli/branding.py smoke tests...")
271
+
272
+ # Verify constants
273
+ assert CLI_VERSION == "1.0.0"
274
+ assert len(PRIMARY_GRADIENT) == 4
275
+ assert len(SECONDARY_GRADIENT) == 4
276
+ assert len(EIGENSCRIBE_BLOCK_TEXT.strip()) > 0
277
+
278
+ # Verify color tokens reference valid palette keys
279
+ for color_key in (
280
+ HEADER_CATEGORY_COLOR,
281
+ CMD_NAME_COLOR,
282
+ SYNTAX_FLAG_COLOR,
283
+ DESC_TEXT_COLOR,
284
+ BORDER_FRAME_COLOR,
285
+ SECTION_BULLET_COLOR,
286
+ ):
287
+ assert color_key in COLOR_PALETTE.values(), f"Color token {color_key!r} not in COLOR_PALETTE"
288
+
289
+ # Verify ansi_color produces valid ANSI codes
290
+ test_str = ansi_color("#00e8ff", "test_cyan", bold=True)
291
+ assert "\033[1;38;2;0;232;255mtest_cyan\033[0m" == test_str
292
+
293
+ # Verify header rendering
294
+ header_output = render_brand_header()
295
+ assert "\033[38;2;" in header_output or "\033[1;38;2;" in header_output
296
+
297
+ print("✅ src/scriber_core/cli/branding.py smoke tests passed successfully.\n")
298
+ return True
299
+
300
+
301
+ # -----------------------------------------------------------------------------------------------------------
302
+ # 🔥 Entry point
303
+ # -----------------------------------------------------------------------------------------------------------
304
+
305
+
306
+ def main() -> None:
307
+ """Orchestrate branding smoke test output."""
308
+ success = run_smoke_test()
309
+ if not success:
310
+ raise ValueError("Branding validation failed during smoke test checks.")
311
+
312
+
313
+ if __name__ == "__main__":
314
+ main()