wizard-codegen 0.2.1__tar.gz → 0.3.0__tar.gz

wizard_codegen-0.2.1/README.md → wizard_codegen-0.3.0/PKG-INFO

@@ -1,3 +1,20 @@
+Metadata-Version: 2.4
+Name: wizard-codegen
+Version: 0.3.0
+Summary: A powerful, template-driven code generation tool for Protocol Buffers
+Requires-Python: >=3.10
+Requires-Dist: click==8.3.1
+Requires-Dist: jinja2==3.1.6
+Requires-Dist: prompt-toolkit>=3.0.52
+Requires-Dist: protobuf==6.33.5
+Requires-Dist: pydantic-core==2.41.5
+Requires-Dist: pydantic==2.12.5
+Requires-Dist: pyyaml==6.0.3
+Requires-Dist: rich==14.3.3
+Requires-Dist: textual>=8.1.1
+Requires-Dist: typer==0.21.1
+Description-Content-Type: text/markdown
+
 # 🧙 Wizard Codegen
 
 [![CircleCI](https://dl.circleci.com/status-badge/img/gh/ConsultingMD/wizard-codegen/tree/main.svg?style=svg&circle-token=CCIPRJ_6cYihJ2CPYtLrt8VjrCcSV_f02bbbce30f122a85da4e93588e8887e973128fd)](https://dl.circleci.com/status-badge/redirect/gh/ConsultingMD/wizard-codegen/tree/main)
@@ -46,6 +63,7 @@ handlers — this tool has you covered.
 | **Multi-Language Support** | Generate code for TypeScript, Swift, Kotlin, Go, and more                                                                |
 | **Jinja2 Templates**       | Full power of Jinja2 templating with custom filters                                                                      |
 | **Flexible Filtering**     | Target specific messages, enums, or services with `where` clauses                                                        |
+| **Runtime Name Filter**    | Generate only specific items from CLI: `wizard-codegen generate SampleProtoPage`                                         |
 | **Annotation Filtering**   | Filter messages by custom proto annotations/options (e.g., `has_option: "*.page"`)                                         |
 | **Git Proto Sources**      | Fetch proto definitions directly from Git repositories                                                                   |
 | **Multiple Write Modes**   | `overwrite`, `append`, or `write-once` file generation                                                                   |
@@ -55,6 +73,9 @@ handlers — this tool has you covered.
 | **Verbose Output**         | Debug with detailed proto and context inspection                                                                         |
 | **Nested Type Support**    | Full support for nested messages and enums                                                                               |
 | **Options Extraction**     | Access message, field, and enum options in templates                                                                     |
+| **Sample Data Loading**    | Auto-load `.samples.json` files co-located with protos into template context (`item.samples`, `item.default_sample`)     |
+| **Sample Validation**      | `validate` command checks `.samples.json` field names and types against proto schema recursively                         |
+| **Context Explorer**       | Interactive TUI and REPL for exploring the Jinja2 template context (`context-explorer` command)                          |
 
 ---
 
@@ -195,9 +216,18 @@ The CLI is built with [Typer](https://typer.tiangolo.com/) and provides rich, co
 #### `generate` — Generate code from protos
 
 ```bash
-# Basic generation
+# Basic generation (all items)
 wizard-codegen generate
 
+# Generate only specific items by name
+wizard-codegen generate SampleProtoPage
+
+# Generate multiple specific items
+wizard-codegen generate SampleProtoPage UserFormPage
+
+# Use glob patterns to match item names
+wizard-codegen generate "*Page"
+
 # With custom config file
 wizard-codegen --config path/to/codegen.yaml generate
 
@@ -207,10 +237,12 @@ wizard-codegen --dry-run generate
 # Verbose mode (detailed output)
 wizard-codegen --verbose generate
 
-# Combine flags
-wizard-codegen --verbose --dry-run --config custom.yaml generate
+# Combine flags and name filter
+wizard-codegen --verbose --dry-run generate SampleProtoPage
 ```
 
+The optional positional `NAMES` arguments filter which items are generated at runtime. This works alongside any `where` clauses in your config — the config filters are applied first, then the name filter narrows the results further. Glob patterns (`*Page`, `Sample*`) and regex patterns are supported. When no names are provided, all matching items are generated as usual.
+
 #### `list-protos` — List discovered proto files
 
 ```bash
@@ -486,6 +518,8 @@ When a template is rendered, it receives a rich context:
         "fields": [...],  # List of field objects
         "nested_messages": [...],  # Nested message definitions
         "nested_enums": [...],  # Nested enum definitions
+        "samples": [...],  # Loaded from co-located .samples.json (empty list if none)
+        "default_sample": {...},  # Resolved default sample (None if no samples)
     },
 
     # All files (for cross-referencing)
@@ -588,6 +622,157 @@ When a template is rendered, it receives a rich context:
 }
 ```
 
+### Sample Data (`.samples.json`)
+
+Proto files can have a co-located `.samples.json` file that provides example data. The file mirrors the proto filename:
+
+```
+service/wizard/pages/sample/v1/
+  sample.proto              # the page definition
+  sample.samples.json       # sample data
+```
+
+When found, the samples are loaded into the template context on the matching message item. Templates can access them via `item.samples` (always a list) and `item.default_sample` (the resolved default, or `None`).
+
+#### Single sample
+
+```json
+{
+  "context": {
+    "header": { "title": "Welcome" },
+    "primaryButtonText": "Continue"
+  },
+  "form": { "inputFieldValue": "" }
+}
+```
+
+#### Multiple samples
+
+Use an array. Name one `"default"` to mark it as the default; otherwise the first entry is used.
+
+```json
+[
+  { "name": "default", "context": { "header": { "title": "Welcome" } }, "form": {} },
+  { "name": "returning_user", "context": { "header": { "title": "Welcome back" } }, "form": {} }
+]
+```
+
+#### Using samples in templates
+
+```jinja
+{% if item.default_sample %}
+var defaultContext = {{ item.default_sample.context | tojson }};
+{% endif %}
+
+{% for sample in item.samples %}
+// Sample: {{ sample.name | default("unnamed") }}
+{% endfor %}
+```
+
+#### Validation
+
+The `wizard-codegen validate` command checks all found `.samples.json` files:
+
+- Invalid JSON is reported with parse details
+- Empty arrays are rejected
+- Every JSON key is checked against the message's proto field `json_name` values
+- Value types are checked (string, number, bool, object, array) against proto field types
+- Message-type fields are validated recursively, including externally referenced messages
+- Repeated fields must be arrays with correctly typed elements
+
+Samples are **optional** — the `generate` command works with or without them, and `validate` only checks files that exist (no warning for missing samples).
+
+#### Nested message propagation
+
+Samples are automatically propagated from a top-level message to its nested message types. For example, given a wizard page with nested `Context` and `Form` messages and a sample containing `{"context": {...}, "form": {...}}`, the `Context` message receives the `context` sub-object as its sample, and `Form` receives the `form` sub-object. The matching is based on the camelCase type name of the nested message. This means `item.samples` and `item.default_sample` are available in templates for both the parent and its nested message types.
+
+### Context Explorer
+
+The `context-explorer` command helps template authors discover what data is available in the Jinja2 template context. It supports two modes.
+
+#### Interactive TUI (default)
+
+The default mode launches a full-screen interactive terminal UI with an expandable/collapsible tree on the left and a detail inspector panel on the right:
+
+```bash
+# Launch TUI
+wizard-codegen context-explorer
+
+# Auto-expand to a specific path
+wizard-codegen context-explorer "message[.service.wizard.pages.sample.v1.SampleProtoPage]"
+```
+
+```
++-------------------------------+-------------------------------+
+| Context Explorer              |                               |
++-------------------------------+-------------------------------+
+| Context                       | Path: message[.pkg.Foo].name  |
+| v proto_root: "/path/..."     |                               |
+| v files (3 items)             | Type: Name                    |
+|   > [0] sample_page.proto     |                               |
+|   > [1] other.proto           | raw         SampleProtoPage   |
+| v message (5 keys)            | snake_case  sample_proto_page |
+|   v .pkg.SampleProtoPage      | kebab_case  sample-proto-page |
+|     > name: SampleProtoPage   | pascal_case SampleProtoPage   |
+|     > fields (3 items)        | camel_case  sampleProtoPage   |
+|     > nested_messages (2)     | macro_case  SAMPLEPROTOPAGE   |
+|     > options (1 keys)        | macro_snake SAMPLE_PROTO_PAGE |
+|   > .pkg.Other                | micro_case  sampleprotopage   |
+| > enum (2 keys)               |                               |
+| > service (1 keys)            |                               |
++-------------------------------+-------------------------------+
+| q Quit | space Toggle | arrows Navigate                      |
++-------------------------------+-------------------------------+
+```
+
+Nodes start collapsed and are lazily loaded on expand — keeping startup fast even for large contexts. Use arrow keys to navigate, space/enter to expand/collapse, `/` to focus the filter input, and `q` to quit.
+
+The filter input at the top lets you narrow down dict keys across all top-level sections (message, enum, service, types). Type a substring (e.g. `sample`) to hide keys that don't match, and press Escape to clear the filter. This is especially useful for hiding built-in google protobuf definitions.
+
+#### REPL mode
+
+Launch with `--repl` / `-r` for step-by-step text navigation with tab completion:
+
+```bash
+wizard-codegen context-explorer -r
+```
+
+```
+Context Explorer - type help for commands
+
+context:/> message
+  Key                                                    Type              Preview
+  .service.wizard.pages.sample.v1.SampleProtoPage        dict (8 keys)     name, full_name, fields, ...
+
+context:/message> [.service.wizard.pages.sample.v1.SampleProtoPage]
+  Key                Type              Preview
+  name               Name              SampleProtoPage
+  full_name          str               .service.wizard.pages.sample.v1.SampleProtoPage
+  fields             list (0 items)
+  nested_messages    list (2 items)
+  samples            list (2 items)
+  default_sample     dict (3 keys)     name, context, form
+
+context:/message[.service.wizard.pages.sample.v1.SampleProtoPage]> name
+  SampleProtoPage (raw=SampleProtoPage, snake=sample_proto_page, kebab=sample-proto-page,
+  pascal=SampleProtoPage, camel=sampleProtoPage, macro=SAMPLEPROTOPAGE,
+  macro_snake=SAMPLE_PROTO_PAGE, micro=sampleprotopage)
+```
+
+REPL commands:
+
+| Command        | Description                                                    |
+|----------------|----------------------------------------------------------------|
+| `<path>`       | Navigate to path (dot-separated, `[brackets]` for dict/list)  |
+| `keys`         | Show available keys at current level                           |
+| `..`           | Go up one level                                                |
+| `/`            | Go to root                                                     |
+| `tree [depth]` | Show tree from current position (optional depth limit)         |
+| `help`         | Show help                                                      |
+| `quit`         | Exit the explorer                                              |
+
+Path syntax uses dots for plain keys and brackets for keys containing dots or list indices: `message[.pkg.Foo].fields[0].name.snake_case`.
+
 ### Name Transformations
 
 Every name in the context is wrapped in a `Name` object that provides automatic case transformations:

wizard_codegen-0.2.1/PKG-INFO → wizard_codegen-0.3.0/README.md

@@ -1,18 +1,3 @@
-Metadata-Version: 2.4
-Name: wizard-codegen
-Version: 0.2.1
-Summary: A powerful, template-driven code generation tool for Protocol Buffers
-Requires-Python: >=3.10
-Requires-Dist: click==8.3.1
-Requires-Dist: jinja2==3.1.6
-Requires-Dist: protobuf==6.33.4
-Requires-Dist: pydantic-core==2.41.5
-Requires-Dist: pydantic==2.12.5
-Requires-Dist: pyyaml==6.0.3
-Requires-Dist: rich==14.3.2
-Requires-Dist: typer==0.21.1
-Description-Content-Type: text/markdown
-
 # 🧙 Wizard Codegen
 
 [![CircleCI](https://dl.circleci.com/status-badge/img/gh/ConsultingMD/wizard-codegen/tree/main.svg?style=svg&circle-token=CCIPRJ_6cYihJ2CPYtLrt8VjrCcSV_f02bbbce30f122a85da4e93588e8887e973128fd)](https://dl.circleci.com/status-badge/redirect/gh/ConsultingMD/wizard-codegen/tree/main)
@@ -61,6 +46,7 @@ handlers — this tool has you covered.
 | **Multi-Language Support** | Generate code for TypeScript, Swift, Kotlin, Go, and more                                                                |
 | **Jinja2 Templates**       | Full power of Jinja2 templating with custom filters                                                                      |
 | **Flexible Filtering**     | Target specific messages, enums, or services with `where` clauses                                                        |
+| **Runtime Name Filter**    | Generate only specific items from CLI: `wizard-codegen generate SampleProtoPage`                                         |
 | **Annotation Filtering**   | Filter messages by custom proto annotations/options (e.g., `has_option: "*.page"`)                                         |
 | **Git Proto Sources**      | Fetch proto definitions directly from Git repositories                                                                   |
 | **Multiple Write Modes**   | `overwrite`, `append`, or `write-once` file generation                                                                   |
@@ -70,6 +56,9 @@ handlers — this tool has you covered.
 | **Verbose Output**         | Debug with detailed proto and context inspection                                                                         |
 | **Nested Type Support**    | Full support for nested messages and enums                                                                               |
 | **Options Extraction**     | Access message, field, and enum options in templates                                                                     |
+| **Sample Data Loading**    | Auto-load `.samples.json` files co-located with protos into template context (`item.samples`, `item.default_sample`)     |
+| **Sample Validation**      | `validate` command checks `.samples.json` field names and types against proto schema recursively                         |
+| **Context Explorer**       | Interactive TUI and REPL for exploring the Jinja2 template context (`context-explorer` command)                          |
 
 ---
 
@@ -210,9 +199,18 @@ The CLI is built with [Typer](https://typer.tiangolo.com/) and provides rich, co
 #### `generate` — Generate code from protos
 
 ```bash
-# Basic generation
+# Basic generation (all items)
 wizard-codegen generate
 
+# Generate only specific items by name
+wizard-codegen generate SampleProtoPage
+
+# Generate multiple specific items
+wizard-codegen generate SampleProtoPage UserFormPage
+
+# Use glob patterns to match item names
+wizard-codegen generate "*Page"
+
 # With custom config file
 wizard-codegen --config path/to/codegen.yaml generate
 
@@ -222,10 +220,12 @@ wizard-codegen --dry-run generate
 # Verbose mode (detailed output)
 wizard-codegen --verbose generate
 
-# Combine flags
-wizard-codegen --verbose --dry-run --config custom.yaml generate
+# Combine flags and name filter
+wizard-codegen --verbose --dry-run generate SampleProtoPage
 ```
 
+The optional positional `NAMES` arguments filter which items are generated at runtime. This works alongside any `where` clauses in your config — the config filters are applied first, then the name filter narrows the results further. Glob patterns (`*Page`, `Sample*`) and regex patterns are supported. When no names are provided, all matching items are generated as usual.
+
 #### `list-protos` — List discovered proto files
 
 ```bash
@@ -501,6 +501,8 @@ When a template is rendered, it receives a rich context:
         "fields": [...],  # List of field objects
         "nested_messages": [...],  # Nested message definitions
         "nested_enums": [...],  # Nested enum definitions
+        "samples": [...],  # Loaded from co-located .samples.json (empty list if none)
+        "default_sample": {...},  # Resolved default sample (None if no samples)
     },
 
     # All files (for cross-referencing)
@@ -603,6 +605,157 @@ When a template is rendered, it receives a rich context:
 }
 ```
 
+### Sample Data (`.samples.json`)
+
+Proto files can have a co-located `.samples.json` file that provides example data. The file mirrors the proto filename:
+
+```
+service/wizard/pages/sample/v1/
+  sample.proto              # the page definition
+  sample.samples.json       # sample data
+```
+
+When found, the samples are loaded into the template context on the matching message item. Templates can access them via `item.samples` (always a list) and `item.default_sample` (the resolved default, or `None`).
+
+#### Single sample
+
+```json
+{
+  "context": {
+    "header": { "title": "Welcome" },
+    "primaryButtonText": "Continue"
+  },
+  "form": { "inputFieldValue": "" }
+}
+```
+
+#### Multiple samples
+
+Use an array. Name one `"default"` to mark it as the default; otherwise the first entry is used.
+
+```json
+[
+  { "name": "default", "context": { "header": { "title": "Welcome" } }, "form": {} },
+  { "name": "returning_user", "context": { "header": { "title": "Welcome back" } }, "form": {} }
+]
+```
+
+#### Using samples in templates
+
+```jinja
+{% if item.default_sample %}
+var defaultContext = {{ item.default_sample.context | tojson }};
+{% endif %}
+
+{% for sample in item.samples %}
+// Sample: {{ sample.name | default("unnamed") }}
+{% endfor %}
+```
+
+#### Validation
+
+The `wizard-codegen validate` command checks all found `.samples.json` files:
+
+- Invalid JSON is reported with parse details
+- Empty arrays are rejected
+- Every JSON key is checked against the message's proto field `json_name` values
+- Value types are checked (string, number, bool, object, array) against proto field types
+- Message-type fields are validated recursively, including externally referenced messages
+- Repeated fields must be arrays with correctly typed elements
+
+Samples are **optional** — the `generate` command works with or without them, and `validate` only checks files that exist (no warning for missing samples).
+
+#### Nested message propagation
+
+Samples are automatically propagated from a top-level message to its nested message types. For example, given a wizard page with nested `Context` and `Form` messages and a sample containing `{"context": {...}, "form": {...}}`, the `Context` message receives the `context` sub-object as its sample, and `Form` receives the `form` sub-object. The matching is based on the camelCase type name of the nested message. This means `item.samples` and `item.default_sample` are available in templates for both the parent and its nested message types.
+
+### Context Explorer
+
+The `context-explorer` command helps template authors discover what data is available in the Jinja2 template context. It supports two modes.
+
+#### Interactive TUI (default)
+
+The default mode launches a full-screen interactive terminal UI with an expandable/collapsible tree on the left and a detail inspector panel on the right:
+
+```bash
+# Launch TUI
+wizard-codegen context-explorer
+
+# Auto-expand to a specific path
+wizard-codegen context-explorer "message[.service.wizard.pages.sample.v1.SampleProtoPage]"
+```
+
+```
++-------------------------------+-------------------------------+
+| Context Explorer              |                               |
++-------------------------------+-------------------------------+
+| Context                       | Path: message[.pkg.Foo].name  |
+| v proto_root: "/path/..."     |                               |
+| v files (3 items)             | Type: Name                    |
+|   > [0] sample_page.proto     |                               |
+|   > [1] other.proto           | raw         SampleProtoPage   |
+| v message (5 keys)            | snake_case  sample_proto_page |
+|   v .pkg.SampleProtoPage      | kebab_case  sample-proto-page |
+|     > name: SampleProtoPage   | pascal_case SampleProtoPage   |
+|     > fields (3 items)        | camel_case  sampleProtoPage   |
+|     > nested_messages (2)     | macro_case  SAMPLEPROTOPAGE   |
+|     > options (1 keys)        | macro_snake SAMPLE_PROTO_PAGE |
+|   > .pkg.Other                | micro_case  sampleprotopage   |
+| > enum (2 keys)               |                               |
+| > service (1 keys)            |                               |
++-------------------------------+-------------------------------+
+| q Quit | space Toggle | arrows Navigate                      |
++-------------------------------+-------------------------------+
+```
+
+Nodes start collapsed and are lazily loaded on expand — keeping startup fast even for large contexts. Use arrow keys to navigate, space/enter to expand/collapse, `/` to focus the filter input, and `q` to quit.
+
+The filter input at the top lets you narrow down dict keys across all top-level sections (message, enum, service, types). Type a substring (e.g. `sample`) to hide keys that don't match, and press Escape to clear the filter. This is especially useful for hiding built-in google protobuf definitions.
+
+#### REPL mode
+
+Launch with `--repl` / `-r` for step-by-step text navigation with tab completion:
+
+```bash
+wizard-codegen context-explorer -r
+```
+
+```
+Context Explorer - type help for commands
+
+context:/> message
+  Key                                                    Type              Preview
+  .service.wizard.pages.sample.v1.SampleProtoPage        dict (8 keys)     name, full_name, fields, ...
+
+context:/message> [.service.wizard.pages.sample.v1.SampleProtoPage]
+  Key                Type              Preview
+  name               Name              SampleProtoPage
+  full_name          str               .service.wizard.pages.sample.v1.SampleProtoPage
+  fields             list (0 items)
+  nested_messages    list (2 items)
+  samples            list (2 items)
+  default_sample     dict (3 keys)     name, context, form
+
+context:/message[.service.wizard.pages.sample.v1.SampleProtoPage]> name
+  SampleProtoPage (raw=SampleProtoPage, snake=sample_proto_page, kebab=sample-proto-page,
+  pascal=SampleProtoPage, camel=sampleProtoPage, macro=SAMPLEPROTOPAGE,
+  macro_snake=SAMPLE_PROTO_PAGE, micro=sampleprotopage)
+```
+
+REPL commands:
+
+| Command        | Description                                                    |
+|----------------|----------------------------------------------------------------|
+| `<path>`       | Navigate to path (dot-separated, `[brackets]` for dict/list)  |
+| `keys`         | Show available keys at current level                           |
+| `..`           | Go up one level                                                |
+| `/`            | Go to root                                                     |
+| `tree [depth]` | Show tree from current position (optional depth limit)         |
+| `help`         | Show help                                                      |
+| `quit`         | Exit the explorer                                              |
+
+Path syntax uses dots for plain keys and brackets for keys containing dots or list indices: `message[.pkg.Foo].fields[0].name.snake_case`.
+
 ### Name Transformations
 
 Every name in the context is wrapped in a `Name` object that provides automatic case transformations:

wizard_codegen-0.3.0/cli/context_explorer/__init__.py

@@ -0,0 +1,5 @@
+from .tree import show_context_tree
+from .repl import run_repl
+from .tui import run_tui
+
+__all__ = ["show_context_tree", "run_repl", "run_tui"]

wizard_codegen-0.3.0/cli/context_explorer/path_resolver.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from typing import Any
+
+from utils.name import Name
+
+NAME_PROPERTIES = [
+    "raw", "snake_case", "kebab_case", "pascal_case",
+    "camel_case", "macro_case", "macro_snake_case", "micro_case",
+]
+
+
+class PathError(Exception):
+    pass
+
+
+def parse_path(path_str: str) -> list[str | int]:
+    """Tokenize a path like ``message[.pkg.Foo].fields[0]`` into segments.
+
+    Returns a list of string keys and integer indices.
+    """
+    segments: list[str | int] = []
+    s = path_str.strip()
+    if not s:
+        return segments
+
+    i = 0
+    while i < len(s):
+        if s[i] == "[":
+            try:
+                end = s.index("]", i + 1)
+            except ValueError:
+                raise PathError(f"unmatched '[' at position {i} in: {path_str}")
+            inner = s[i + 1 : end]
+            if not inner:
+                raise PathError(f"empty brackets at position {i} in: {path_str}")
+            try:
+                segments.append(int(inner))
+            except ValueError:
+                segments.append(inner)
+            i = end + 1
+            if i < len(s) and s[i] == ".":
+                i += 1
+        elif s[i] == ".":
+            i += 1
+        else:
+            end = i
+            while end < len(s) and s[end] not in ".[]":
+                end += 1
+            segments.append(s[i:end])
+            i = end
+            if i < len(s) and s[i] == ".":
+                i += 1
+
+    return segments
+
+
+def _step_into(data: Any, segment: str | int) -> Any:
+    if isinstance(segment, int):
+        if isinstance(data, list):
+            if 0 <= segment < len(data):
+                return data[segment]
+            raise PathError(f"index {segment} out of range (length {len(data)})")
+        raise PathError(f"cannot index into {type(data).__name__}")
+
+    if isinstance(data, dict):
+        if segment in data:
+            return data[segment]
+        available = ", ".join(list(data.keys())[:10])
+        if len(data) > 10:
+            available += ", ..."
+        raise PathError(f"key '{segment}' not found. Available: {available}")
+
+    if isinstance(data, Name):
+        if segment in NAME_PROPERTIES:
+            return getattr(data, segment)
+        raise PathError(
+            f"Name has no property '{segment}'. "
+            f"Available: {', '.join(NAME_PROPERTIES)}"
+        )
+
+    if isinstance(data, list):
+        raise PathError(f"use bracket index [N] for lists (length {len(data)})")
+
+    raise PathError(f"cannot navigate into {type(data).__name__}")
+
+
+def resolve_segments(data: Any, segments: list[str | int]) -> Any:
+    """Navigate into *data* following pre-parsed *segments*."""
+    current = data
+    for seg in segments:
+        current = _step_into(current, seg)
+    return current
+
+
+def resolve_path(data: Any, path_str: str) -> Any:
+    """Navigate into *data* using a dot/bracket path string."""
+    return resolve_segments(data, parse_path(path_str))
+
+
+def get_keys(data: Any) -> list[str]:
+    """Return navigable keys/indices for *data*.
+
+    List indices are returned as plain digit strings (``"0"``, ``"1"``).
+    Callers that need bracket notation for display should wrap them.
+    """
+    if isinstance(data, dict):
+        return list(str(k) for k in data.keys())
+    if isinstance(data, list):
+        return [str(i) for i in range(len(data))]
+    if isinstance(data, Name):
+        return list(NAME_PROPERTIES)
+    return []
+
+
+def needs_brackets(key: str) -> bool:
+    """True when *key* must be wrapped in ``[...]`` because it contains dots."""
+    return "." in key or key.startswith(".")