Skip to content

symfonic.diagnostics.cli

cli

Typer command implementation for symfonic doctor (v7.16, item 5).

Separated from :mod:symfonic.agent.cli.main so the CLI module can stay small and so the command surface can be unit-tested in isolation via a CliRunner against a focused sub-app.

Behaviour:

  • Optional PROJECT_PATH positional argument -- when present, the command prepends it to sys.path and tries to import the scaffold convention from app.setup.agent import build_agent. When absent, a default :class:SymfonicAgent is constructed with a :class:MockModelProvider so the env-var checks (embedding, postgres) and the agent-config checks still run.
  • --strict promotes WARN findings to exit code 2 (mypy-style).
  • --no-network forces network-sensitive checks to skip; the default honours CI=true.
  • --json emits a single JSON document on stdout and suppresses the human-readable progress lines on stderr.

doctor 

doctor(project_path: Annotated[Path | None, Argument(help='Adopter project root containing ``app/setup/agent.py``. When omitted, a default in-memory agent is constructed -- env-var checks still run.')] = None, strict: Annotated[bool, Option('--strict', help='Promote WARN findings to exit code 2.')] = False, no_network: Annotated[bool | None, Option('--no-network/--network', help='Skip network-sensitive checks (POSTGRES_DSN probe). Default honours CI=true in the environment.')] = None, json_output: Annotated[bool, Option('--json', help='Emit a single JSON document on stdout instead of the human-readable report.  Suppresses all stderr progress.')] = False, offline: Annotated[bool, Option('--offline', help='Run the migration inspection instead of the live audit: no agent is constructed, nothing in PROJECT_PATH is imported, and no socket is opened.')] = False, config: Annotated[Path | None, Option('--config', help='JSON or TOML file holding the raw adopter configuration to inspect (--offline only).')] = None, env_file: Annotated[Path | None, Option('--env-file', help='KEY=value file holding the environment the inspected deployment runs with. Without it the platform-security checks are recorded as not inspected rather than answered from this machine (--offline only).')] = None, migration_report: Annotated[Path | None, Option('--migration-report', help='Write the Markdown migration inspection report to this path (--offline only).')] = None, package_version: Annotated[str | None, Option('--package-version', help='symfonic-core version of the inspected deployment (--offline only).')] = None) -> None

Audit the current symfonic configuration for the v7.16 silent-fail traps.

Source code in src/symfonic/diagnostics/cli.py 
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
def doctor(
    project_path: Annotated[
        Path | None,
        typer.Argument(
            help="Adopter project root containing ``app/setup/agent.py``. "
            "When omitted, a default in-memory agent is constructed -- "
            "env-var checks still run.",
        ),
    ] = None,
    strict: Annotated[
        bool,
        typer.Option(
            "--strict",
            help="Promote WARN findings to exit code 2.",
        ),
    ] = False,
    no_network: Annotated[
        bool | None,
        typer.Option(
            "--no-network/--network",
            help=(
                "Skip network-sensitive checks (POSTGRES_DSN probe). "
                "Default honours CI=true in the environment."
            ),
        ),
    ] = None,
    json_output: Annotated[
        bool,
        typer.Option(
            "--json",
            help=(
                "Emit a single JSON document on stdout instead of the "
                "human-readable report.  Suppresses all stderr progress."
            ),
        ),
    ] = False,
    offline: Annotated[
        bool,
        typer.Option(
            "--offline",
            help=(
                "Run the migration inspection instead of the live audit: no "
                "agent is constructed, nothing in PROJECT_PATH is imported, and "
                "no socket is opened."
            ),
        ),
    ] = False,
    config: Annotated[
        Path | None,
        typer.Option(
            "--config",
            help=(
                "JSON or TOML file holding the raw adopter configuration to "
                "inspect (--offline only)."
            ),
        ),
    ] = None,
    env_file: Annotated[
        Path | None,
        typer.Option(
            "--env-file",
            help=(
                "KEY=value file holding the environment the inspected deployment "
                "runs with. Without it the platform-security checks are recorded "
                "as not inspected rather than answered from this machine "
                "(--offline only)."
            ),
        ),
    ] = None,
    migration_report: Annotated[
        Path | None,
        typer.Option(
            "--migration-report",
            help=(
                "Write the Markdown migration inspection report to this path "
                "(--offline only)."
            ),
        ),
    ] = None,
    package_version: Annotated[
        str | None,
        typer.Option(
            "--package-version",
            help=(
                "symfonic-core version of the inspected deployment "
                "(--offline only)."
            ),
        ),
    ] = None,
) -> None:
    """Audit the current symfonic configuration for the v7.16 silent-fail traps."""
    _reject_offline_only_options(
        offline,
        config=config,
        env_file=env_file,
        migration_report=migration_report,
        package_version=package_version,
    )
    if offline:
        _run_offline_mode(
            project_path,
            config=config,
            env_file=env_file,
            migration_report=migration_report,
            package_version=package_version,
            strict=strict,
            json_output=json_output,
        )
        return

    agent = _load_agent(project_path, suppress_stderr=json_output)
    effective_no_network = resolve_no_network(explicit_flag=no_network)
    report = audit_hms_sync(agent, no_network=effective_no_network)

    if json_output:
        typer.echo(json.dumps(report.to_json_dict(strict=strict), indent=2))
    else:
        _render_human(report)

    raise SystemExit(report.exit_code(strict=strict))