feat: integrate apcore-toolkit as a required dependency to standardize CSV/JSONL output and remove branding from CLI help and documentation.

Author: tercel

CHANGELOG.md

@@ -5,13 +5,31 @@ All notable changes to apcore-cli (Python SDK) will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-
-## [Unreleased]
+## [0.9.0] - 2026-05-11
 
 ### Added
 
 - **`tests/conformance/test_snake_case_kwargs.py`** — runs the cross-language Algorithm C-SNAKE fixture (`apcore-cli/conformance/fixtures/snake-case-kwargs/cases.json`) against `build_module_command` via `click.testing.CliRunner`. Five cases verify that schema property names with underscores (`has_solution`, `sort_by`, `sort_order`) survive the round trip from CLI parse to the input dict received by `executor.call`. No source change required — click natively maps `--has-solution` to `has_solution`; the Python SDK is the parity reference for the parallel TypeScript fix. Surfaced as part of the cross-SDK regression coverage gap audit.
 
+### Fixed
+
+- **CSV `--format csv` Python-repr bug** — `csv.DictWriter` was called with `{k: str(v) for k, v in row.items()}` which emitted Python repr `{'k': 'v'}` (single quotes) for nested dict/list values. The output was not valid JSON and any downstream JSON parser would fail. Now delegates to `apcore_toolkit.format_csv(rows)` which emits canonical compact JSON. `src/apcore_cli/output.py:149, 378`.
+- **CSV heterogeneous-keys data loss** — header is now the union of keys across all rows (was first-row only via `list(rows[0].keys())`).
+- **CSV line terminator** — now `\r\n` per RFC 4180.
+- **JSONL canonical form** — now compact (no spaces between separators), matching the cross-SDK contract. Tests updated.
+
+### Changed
+
+- **User-visible help/man/completion text no longer leaks the `apcore` framework name** to end users of downstream CLIs built on apcore-cli. Affected strings: `init` group description (`Scaffold new apcore modules` → `Scaffold new modules`, `init_cmd.py:45`), `--extensions-dir` option help (`Path to apcore extensions directory.` → `Path to extensions directory.`, `factory.py:460`), zsh/fish completion descriptions for `exec` (`Execute an apcore module` → `Execute a module`, `shell.py:130, 211`), and man-page `ENVIRONMENT` section text (`shell.py:299, 314, 319, 458`) — drops `apcore` from the descriptive copy (`Path to the apcore extensions directory` → `Path to the extensions directory`, `Global apcore logging verbosity` → `Global logging verbosity`, `API key for authenticating with the apcore registry` → `API key for authenticating with the registry`). Logger names, source comments, module docstrings, and environment-variable identifiers (`APCORE_*`) are unchanged — only descriptive copy that appears in `--help`, shell completion, and `man` output. Cross-SDK parity with TypeScript 0.8.2 and Rust 0.8.1.
+
+### Changed (breaking dependency semantics)
+
+- **`apcore-toolkit` promoted from optional extra to REQUIRED runtime dependency** (`>=0.7.0`). The previous `pip install 'apcore-cli[toolkit]'` extras pattern is retained as a no-op for backward compat with install scripts, but the toolkit is now always installed alongside apcore-cli. All `--format` operations route through the toolkit's reference implementation for csv/jsonl/markdown/skill.
+
+### Why
+
+See ADR-09 in `apcore-cli/docs/tech-design.md` for the byte-equivalent toolkit-delegated tier rationale.
+
 
 ## [0.8.0] - 2026-05-08
 

README.md

@@ -48,10 +48,10 @@ Terminal adapter for apcore. Execute AI-Perceivable modules from the command lin
 pip install apcore-cli
 ```
 
-Requires Python 3.11+ and `apcore >= 0.21.0`. The optional `toolkit` extra requires `apcore-toolkit >= 0.6`:
+Requires Python 3.11+, `apcore >= 0.21.0`, and `apcore-toolkit >= 0.7.0` (now a **required** runtime dependency as of v0.9.0 — previously optional; see the [tech-design ADR-09](https://github.com/aiperceivable/apcore-cli/blob/main/docs/tech-design.md) for the byte-equivalent toolkit-delegated tier rationale). The `[toolkit]` extras group is retained as a no-op for backward compat:
 
 ```bash
-pip install "apcore-cli[toolkit]"
+pip install "apcore-cli[toolkit]"   # equivalent to plain `pip install apcore-cli`
 ```
 
 ## Quick Start
@@ -323,7 +323,7 @@ When executing a module (e.g. `apcore-cli math add`), these built-in options are
 | `--input -` | Read JSON input from STDIN |
 | `--yes` / `-y` | Bypass approval prompts |
 | `--large-input` | Allow STDIN input larger than 10MB |
-| `--format` | Output format: `{json, table, csv, yaml, jsonl}` |
+| `--format` | Output format: `{json, table, csv, yaml, jsonl, markdown, skill}`. **v0.9.0:** `csv` and `jsonl` are byte-identical across SDKs (delegated to `apcore-toolkit.format_csv` / `format_jsonl`); fixes the prior `str(v)` Python-repr bug for nested values. |
 | `--sandbox` | Run module in subprocess sandbox *(not yet implemented)* |
 | `--dry-run` | Run preflight checks without executing (FE-11, v0.6.0) |
 | `--trace` | Emit execution pipeline trace (v0.6.0) |

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "apcore-cli"
-version = "0.8.0"
+version = "0.9.0"
 description = "Terminal adapter for apcore — execute AI-Perceivable modules from the command line"
 readme = "README.md"
 license = "Apache-2.0"
@@ -27,6 +27,7 @@ classifiers = [
 ]
 dependencies = [
     "apcore>=0.21.0",
+    "apcore-toolkit>=0.7.0",
     "click>=8.1",
     "jsonschema>=4.20",
     "rich>=13.0",
@@ -45,9 +46,10 @@ dev = [
     "ruff>=0.1",
     "pre-commit>=3.5",
 ]
-toolkit = [
-    "apcore-toolkit>=0.6",
-]
+# `toolkit` is kept as a no-op extras group for backward compat with downstream
+# `apcore-cli[toolkit]` install commands; apcore-toolkit is now a required
+# runtime dependency (see ADR-09).
+toolkit = []
 
 [project.scripts]
 apcore-cli = "apcore_cli.__main__:main"

src/apcore_cli/factory.py

@@ -457,7 +457,7 @@ def cli(
                 click.Option(
                     ["--extensions-dir", "extensions_dir_opt"],
                     default=None,
-                    help="Path to apcore extensions directory.",
+                    help="Path to extensions directory.",
                 ),
                 click.Option(
                     ["--commands-dir", "commands_dir_opt"],

src/apcore_cli/init_cmd.py

@@ -42,7 +42,7 @@ def register_init_command(cli: click.Group) -> None:
 
     @cli.group("init")
     def init_group():
-        """Scaffold new apcore modules."""
+        """Scaffold new modules."""
         pass
 
     @init_group.command("module")

src/apcore_cli/output.py

@@ -8,6 +8,7 @@
 from typing import TYPE_CHECKING, Any
 
 import click
+from apcore_toolkit import format_csv, format_jsonl
 from rich.console import Console
 from rich.panel import Panel
 from rich.syntax import Syntax
@@ -28,6 +29,24 @@
 )
 
 
+def _to_rows_for_tabular(value: Any) -> list[dict] | None:
+    """Coerce an exec result into the row-shape expected by the toolkit's
+    tabular formatters (csv / jsonl). Returns ``None`` for shapes that don't
+    map to tabular (scalars, empty lists, lists of non-dicts).
+    """
+    if value is None:
+        return None
+    if isinstance(value, list):
+        if not value:
+            return None
+        if not all(isinstance(item, dict) for item in value):
+            return None
+        return value
+    if isinstance(value, dict):
+        return [value]
+    return None
+
+
 def _descriptor_to_scanned(module_def: Any) -> Any:
     """Adapt a registry `ModuleDescriptor` to the toolkit's `ScannedModule`.
 
@@ -147,26 +166,19 @@ def format_module_list(
         if format == "json":
             click.echo(json.dumps(rows, indent=2))
         elif format == "csv":
-            import csv
-            import io
-
+            # Delegate to apcore-toolkit for byte-equivalent cross-SDK output.
+            # Fixes the prior `str(v)` Python-repr bug for nested values.
             if rows:
-                buf = io.StringIO()
-                writer = csv.DictWriter(buf, fieldnames=list(rows[0].keys()))
-                writer.writeheader()
-                for row in rows:
-                    writer.writerow({k: str(v) for k, v in row.items()})
-                click.echo(buf.getvalue().rstrip())
+                click.echo(format_csv(rows).rstrip())
         elif format == "yaml":
             try:
                 import yaml
 
                 click.echo(yaml.dump(rows, default_flow_style=False, allow_unicode=True).rstrip())
             except ImportError:
                 click.echo(json.dumps(rows, indent=2))
-        elif format == "jsonl":
-            for row in rows:
-                click.echo(json.dumps(row))
+        elif format == "jsonl" and rows:
+            click.echo(format_jsonl(rows).rstrip())
 
 
 def _annotations_to_dict(annotations: Any) -> dict | None:
@@ -376,22 +388,9 @@ def format_exec_result(result: Any, format: str | None = None, fields: str | Non
     effective = resolve_format(format)
 
     if effective == "csv":
-        import csv
-        import io
-
-        if isinstance(result, dict):
-            buf = io.StringIO()
-            writer = csv.DictWriter(buf, fieldnames=list(result.keys()))
-            writer.writeheader()
-            writer.writerow({k: str(v) for k, v in result.items()})
-            click.echo(buf.getvalue().rstrip())
-        elif isinstance(result, list) and result and isinstance(result[0], dict):
-            buf = io.StringIO()
-            writer = csv.DictWriter(buf, fieldnames=list(result[0].keys()))
-            writer.writeheader()
-            for row in result:
-                writer.writerow({k: str(v) for k, v in row.items()})
-            click.echo(buf.getvalue().rstrip())
+        rows = _to_rows_for_tabular(result)
+        if rows is not None:
+            click.echo(format_csv(rows).rstrip())
         else:
             click.echo(json.dumps(result, default=str))
     elif effective == "yaml":
@@ -402,9 +401,9 @@ def format_exec_result(result: Any, format: str | None = None, fields: str | Non
         except ImportError:
             click.echo(json.dumps(result, indent=2, default=str))
     elif effective == "jsonl":
-        if isinstance(result, list):
-            for item in result:
-                click.echo(json.dumps(item, default=str))
+        rows = _to_rows_for_tabular(result)
+        if rows is not None:
+            click.echo(format_jsonl(rows).rstrip())
         else:
             click.echo(json.dumps(result, default=str))
     elif effective == "table" and isinstance(result, dict):

src/apcore_cli/shell.py

@@ -127,7 +127,7 @@ def _generate_zsh_completion(prog_name: str) -> str:
         f"{fn}() {{\n"
         "    local -a commands groups_and_top\n"
         "    commands=(\n"
-        "        'exec:Execute an apcore module'\n"
+        "        'exec:Execute a module'\n"
         "        'list:List available modules'\n"
         "        'describe:Show module metadata and schema'\n"
         "        'completion:Generate shell completion script'\n"
@@ -208,7 +208,7 @@ def _generate_fish_completion(prog_name: str) -> str:
         f"{group_cmds_fish_fn}"
         f"\n"
         f'complete -c {quoted} -n "__fish_use_subcommand"'
-        ' -a exec -d "Execute an apcore module"\n'
+        ' -a exec -d "Execute a module"\n'
         f'complete -c {quoted} -n "__fish_use_subcommand"'
         ' -a list -d "List available modules"\n'
         f'complete -c {quoted} -n "__fish_use_subcommand"'
@@ -296,7 +296,7 @@ def _generate_man_page(command_name: str, command: click.Command | None, prog_na
     sections.append(".SH ENVIRONMENT")
     sections.append(".TP")
     sections.append("\\fBAPCORE_EXTENSIONS_ROOT\\fR")
-    sections.append("Path to the apcore extensions directory. Overrides the default \\fI./extensions\\fR.")
+    sections.append("Path to the extensions directory. Overrides the default \\fI./extensions\\fR.")
     sections.append(".TP")
     sections.append("\\fBAPCORE_CLI_AUTO_APPROVE\\fR")
     sections.append(
@@ -311,12 +311,12 @@ def _generate_man_page(command_name: str, command: click.Command | None, prog_na
     sections.append(".TP")
     sections.append("\\fBAPCORE_LOGGING_LEVEL\\fR")
     sections.append(
-        "Global apcore logging verbosity. One of: DEBUG, INFO, WARNING, ERROR. "
+        "Global logging verbosity. One of: DEBUG, INFO, WARNING, ERROR. "
         "Used as fallback when \\fBAPCORE_CLI_LOGGING_LEVEL\\fR is not set. Default: WARNING."
     )
     sections.append(".TP")
     sections.append("\\fBAPCORE_AUTH_API_KEY\\fR")
-    sections.append("API key for authenticating with the apcore registry.")
+    sections.append("API key for authenticating with the registry.")
 
     sections.append(".SH EXIT CODES")
     exit_codes = [
@@ -455,7 +455,7 @@ def build_program_man_page(
     s.append(".SH ENVIRONMENT")
     s.append(".TP")
     s.append("\\fBAPCORE_EXTENSIONS_ROOT\\fR")
-    s.append("Path to the apcore extensions directory.")
+    s.append("Path to the extensions directory.")
     s.append(".TP")
     s.append("\\fBAPCORE_CLI_AUTO_APPROVE\\fR")
     s.append("Set to \\fB1\\fR to bypass approval prompts.")

tests/conformance/test_snake_case_kwargs.py

@@ -27,16 +27,8 @@
 from apcore_cli.cli import build_module_command
 
 _DEFAULT_SPEC_REPO = Path(__file__).resolve().parents[3] / "apcore-cli"
-SPEC_REPO_ROOT = Path(
-    os.environ.get("APCORE_CLI_SPEC_REPO", str(_DEFAULT_SPEC_REPO))
-)
-FIXTURE_PATH = (
-    SPEC_REPO_ROOT
-    / "conformance"
-    / "fixtures"
-    / "snake-case-kwargs"
-    / "cases.json"
-)
+SPEC_REPO_ROOT = Path(os.environ.get("APCORE_CLI_SPEC_REPO", str(_DEFAULT_SPEC_REPO)))
+FIXTURE_PATH = SPEC_REPO_ROOT / "conformance" / "fixtures" / "snake-case-kwargs" / "cases.json"
 
 
 def _load_fixture() -> dict[str, Any]:
@@ -64,9 +56,7 @@ def _make_module_def(module_id: str, input_schema: dict[str, Any]) -> Any:
     ids=[c["id"] for c in _FIXTURE["test_cases"]],
 )
 def test_snake_case_kwargs_flow(case: dict[str, Any]) -> None:
-    module_def = _make_module_def(
-        _FIXTURE["module_id"], _FIXTURE["input_schema"]
-    )
+    module_def = _make_module_def(_FIXTURE["module_id"], _FIXTURE["input_schema"])
     captured: dict[str, Any] = {}
 
     def _capture_call(module_id: str, input_data: dict[str, Any]) -> Any:
@@ -82,17 +72,11 @@ def _capture_call(module_id: str, input_data: dict[str, Any]) -> Any:
     runner = CliRunner()
     args = ["--format", "json", "-y", *case["args"]]
     result = runner.invoke(cmd, args, catch_exceptions=False)
-    assert result.exit_code == 0, (
-        f"args={case['args']} exit_code={result.exit_code} "
-        f"stdout={result.output!r}"
-    )
+    assert result.exit_code == 0, f"args={case['args']} exit_code={result.exit_code} " f"stdout={result.output!r}"
 
     actual = captured.get("input", {})
     for key, expected in case["expected_input"].items():
-        assert key in actual, (
-            f"missing key '{key}' in input; full input={actual!r}"
-        )
+        assert key in actual, f"missing key '{key}' in input; full input={actual!r}"
         assert actual[key] == expected, (
-            f"input['{key}'] = {actual[key]!r}, expected {expected!r}; "
-            f"full input={actual!r}"
+            f"input['{key}'] = {actual[key]!r}, expected {expected!r}; " f"full input={actual!r}"
         )

tests/test_output_format_exec.py

@@ -49,6 +49,33 @@ def test_csv_non_dict_falls_back_to_json(self, capsys):
         # non-dict/list → JSON dump of the scalar string
         assert out == '"hello"'
 
+    # --- Regression: nested-object CSV (apcore-cli-python str() repr bug) ---
+    def test_csv_nested_object_serializes_as_json(self, capsys):
+        """Before toolkit-delegate, str() emitted Python repr `{'k': 'v'}`
+        with single quotes — invalid JSON. Toolkit emits canonical JSON."""
+        format_exec_result(
+            {"schema": {"type": "object", "properties": {"a": {"type": "integer"}}}},
+            format="csv",
+        )
+        out = capsys.readouterr().out
+        # Must contain canonical JSON (double-quoted), not Python repr.
+        assert "'type'" not in out, "must not emit Python repr"
+        assert '"type":"object"' in out.replace('""', '"') or '""type""' in out
+
+    # --- Regression: heterogeneous-keys data loss ---
+    def test_csv_heterogeneous_keys_included(self, capsys):
+        """Before toolkit-delegate, csv.DictWriter was given only first-row
+        keys, dropping later-row fields silently. Toolkit emits union of keys."""
+        format_exec_result(
+            [{"sn": 1, "title": "A"}, {"sn": 2, "title": "B", "description": "later-only"}],
+            format="csv",
+        )
+        out = capsys.readouterr().out
+        lines = [line for line in out.splitlines() if line.strip()]
+        assert lines[0] == "sn,title,description"
+        assert lines[1] == "1,A,"
+        assert lines[2] == "2,B,later-only"
+
     def test_yaml_format(self, capsys):
         format_exec_result({"a": 1, "b": [1, 2]}, format="yaml")
         out = capsys.readouterr().out
@@ -58,12 +85,13 @@ def test_yaml_format(self, capsys):
     def test_jsonl_list(self, capsys):
         format_exec_result([{"i": 1}, {"i": 2}], format="jsonl")
         out = capsys.readouterr().out
-        assert '{"i": 1}' in out
-        assert '{"i": 2}' in out
+        # Toolkit-canonical compact JSON: no whitespace between separators.
+        assert '{"i":1}' in out
+        assert '{"i":2}' in out
 
     def test_jsonl_non_list(self, capsys):
         format_exec_result({"i": 1}, format="jsonl")
-        assert capsys.readouterr().out.strip() == '{"i": 1}'
+        assert capsys.readouterr().out.strip() == '{"i":1}'
 
     def test_table_dict_uses_rich(self, capsys):
         # Force table format even though stdout isn't a TTY — the function

tests/test_shell.py

@@ -29,7 +29,7 @@ def list_cmd(tag):
     @cli.command("exec")
     @click.argument("module_id", required=False)
     def exec_cmd(module_id):
-        """Execute an apcore module."""
+        """Execute a module."""
         pass
 
     register_shell_commands(cli, prog_name=prog_name)