specshift 1.0.0__tar.gz → 1.2.0__tar.gz

{specshift-1.0.0/specshift.egg-info → specshift-1.2.0}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: specshift
-Version: 1.0.0
-Summary: Detects, classifies, and optionally summarizes breaking changes in OpenAPI/Swagger contracts using AI
+Version: 1.2.0
+Summary: Detects, classifies, and optionally summarizes breaking changes in OpenAPI/Swagger, GraphQL, and Protobuf/gRPC contracts using AI
 Author: Lethe044
 License: MIT
 Project-URL: Homepage, https://github.com/Lethe044/specshift
 Project-URL: Repository, https://github.com/Lethe044/specshift
 Project-URL: Issues, https://github.com/Lethe044/specshift/issues
 Project-URL: Changelog, https://github.com/Lethe044/specshift/blob/main/CHANGELOG.md
-Keywords: openapi,swagger,api,breaking-changes,contract-testing,api-diff,devtools,cli,ci-cd
+Keywords: openapi,swagger,graphql,grpc,protobuf,api,breaking-changes,contract-testing,api-diff,devtools,cli,ci-cd,github-actions
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -93,11 +93,21 @@ requirement.
 
 - **Comprehensive structural diff**: deep comparison at the path, HTTP
   method, parameter, request body, response, and schema level.
+- **GraphQL support**: diff GraphQL SDL schemas with `specshift diff-graphql`,
+  covering types, fields, arguments, enum values, interfaces, unions, and
+  deprecations, no external GraphQL library required.
+- **Protobuf/gRPC support**: diff `.proto` files with `specshift diff-proto`,
+  using protobuf's own documented wire-compatibility rules (field numbers,
+  wire type categories, zigzag encoding) rather than generic JSON-shape
+  heuristics, so severity reflects what will actually break on the wire.
 - **Context-aware classification**: the same change is weighted
-  differently depending on whether it occurs in a request or a response.
+  differently depending on whether it occurs in a request or a response
+  (or, for GraphQL, an input type versus an object type).
 - **`$ref` resolution and `allOf` merging**: correctly follows the
   reference and composition patterns common in real-world specifications.
-- **Detects enum, format, nullable, and security scheme changes**.
+- **Detects enum, format, nullable, security scheme, content-type,
+  `additionalProperties`, `readOnly`/`writeOnly`, validation constraint,
+  default value, and `oneOf`/`anyOf` changes**.
 - **Works entirely for free**: no API key or paid service is required.
 - **Optional AI summary**: can generate a natural-language summary using
   Groq, the Gemini free tier, or any OpenAI-compatible endpoint. If no key
@@ -105,12 +115,18 @@ requirement.
   stops working.
 - **CI/CD integration**: the `specshift check` command compares the
   current specification against a branch and fails the build if a
-  breaking change is found.
+  breaking change is found. An official GitHub Action is also available
+  for one-line setup with automatic PR comments (see below).
 - **Live monitoring**: the `specshift watch` command periodically checks
   a remote API's specification and sends a Slack or Discord notification
   when it changes.
-- **Three output formats**: a colored console table, a Markdown report
-  (ideal for PR comments), and JSON (for integrating with other tools).
+- **Local web dashboard**: `specshift serve` opens a browser-based tool
+  for comparing specs interactively (drag in files or paste text), with
+  zero extra dependencies since it runs entirely on Python's standard
+  library and stays on localhost.
+- **Four output formats**: a colored console table, a Markdown report
+  (ideal for PR comments), JSON (for integrating with other tools), and a
+  standalone, filterable HTML report you can open in any browser.
 
 ## Installation
 
@@ -210,13 +226,50 @@ Useful options:
 
 | Option | Description |
 |---|---|
-| `--format console\|markdown\|json` | Output format (default: console) |
+| `--format console\|markdown\|json\|html` | Output format (default: console) |
 | `--output <file>` | Writes the output to a file |
 | `--ai` | Adds a natural-language summary |
 | `--ai-provider groq\|gemini\|openai_compatible` | Chooses the AI provider |
 | `--fail-on breaking\|warning\|none` | Determines at which level exit code 1 is returned |
 | `--quiet` | Only prints the summary line |
 
+### `specshift diff-graphql <old> <new>`
+
+Compares two GraphQL SDL schemas. `<old>` and `<new>` can be a file path,
+an http(s) URL, or raw SDL text. Supports the same `--format`, `--output`,
+`--ai`, and `--fail-on` options as `diff`.
+
+```bash
+specshift diff-graphql old_schema.graphql new_schema.graphql
+```
+
+### `specshift diff-proto <old> <new>`
+
+Compares two Protobuf/gRPC `.proto` schemas using protobuf's own
+wire-compatibility rules (field numbers, wire type categories) rather
+than generic JSON-shape heuristics. Supports the same `--format`,
+`--output`, `--ai`, and `--fail-on` options as `diff`.
+
+```bash
+specshift diff-proto old_service.proto new_service.proto
+```
+
+### `specshift serve`
+
+Starts a local, dependency-free web dashboard for comparing specs
+interactively. Opens a browser tab where you can drag in or paste two
+files (OpenAPI, GraphQL, or Protobuf, auto-detected), and view the same
+styled HTML report the CLI produces, with a short history of past
+comparisons in the current session.
+
+```bash
+specshift serve
+# or: specshift serve --port 9000 --no-browser
+```
+
+Everything runs in-process on your machine; nothing is uploaded anywhere,
+and the server binds to `127.0.0.1` by default.
+
 ### `specshift check`
 
 Designed for CI/CD. Compares the current specification file against a git
@@ -243,8 +296,48 @@ Creates a sample `.specshift.yml` file.
 
 ## Using it with GitHub Actions
 
-The workflow below checks your API contract against the `main` branch on
-every pull request and fails the build if a breaking change is found:
+### Option 1: the official SpecShift action (recommended)
+
+SpecShift ships its own composite GitHub Action that runs the contract
+check and automatically posts (and keeps updated) a Markdown report as a
+pull request comment:
+
+```yaml
+name: API Contract Check
+
+on:
+  pull_request:
+    paths:
+      - "openapi.yaml"
+
+permissions:
+  pull-requests: write
+
+jobs:
+  contract-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: Lethe044/SpecShift@v1
+        with:
+          spec-path: openapi.yaml
+          fail-on: breaking
+          # optional: ai-summary: 'true'
+```
+
+Available inputs: `spec-path`, `base-ref` (defaults to the PR base branch),
+`fail-on` (`breaking` | `warning` | `none`), `ai-summary` (`true`/`false`),
+`ai-provider`, `comment-on-pr` (`true`/`false`), `github-token`, and
+`specshift-version` to pin a specific release. Outputs: `has-breaking-changes`,
+`breaking-count`, `warning-count`, `info-count`, and `report-path`.
+
+### Option 2: calling the CLI directly
+
+If you'd rather not use the action (or want to combine it with other
+tooling), the CLI works just as well on its own:
 
 ```yaml
 name: API Contract Check
@@ -307,26 +400,39 @@ common scenarios:
 | Enum value removed | Breaking | Breaking |
 | Endpoint or method removed | Breaking | Breaking |
 
+The same table applies to GraphQL: `input` types behave like requests,
+`type`/`interface` fields behave like responses.
+
+Protobuf/gRPC follows a different model, based on the wire format rather
+than request/response direction: adding fields or rpc methods is always
+safe, changing a field's number is always breaking, and type changes are
+judged by wire type category (see the `diff-proto` section above).
+
 ## Comparison with other tools
 
 | | SpecShift | Raw JSON/YAML diff | oasdiff / openapi-diff style tools |
 |---|---|---|---|
 | Context-aware classification | Yes | No | Partially |
+| GraphQL support | Yes | No | Rarely |
+| Protobuf/gRPC support (wire-aware) | Yes | No | Rarely |
 | Natural-language summary | Yes (optional) | No | No |
+| Standalone HTML report | Yes | No | Rarely |
+| Local interactive dashboard | Yes | No | Rarely |
 | Free to use | Fully free | Free | Usually free |
-| CI integration | Built-in (`check`) | Manual | Varies |
+| CI integration | Built-in (`check` + official Action) | Manual | Varies |
 | Live URL monitoring | Built-in (`watch`) | No | Rarely |
 
 ## Roadmap
 
 This project is under active development. Some planned areas:
 
-- Support for gRPC/Protobuf contracts
-- GraphQL schema diffing
-- An official GitHub Action for posting automatic PR comments
-- A web-based result viewer
-- More semantic rules (path parameter pattern changes, content-type
-  changes, etc.)
+- Path parameter pattern (regex) and discriminator-level rule refinements
+- Deeper GraphQL support: directive-aware deprecation reasons, custom
+  scalar compatibility hints, and federation-aware schema composition
+- Protobuf `reserved` statement awareness, so a properly reserved field
+  number isn't flagged the same way as an unreserved removal
+- Optional shared/hosted history for the `serve` dashboard (currently
+  in-memory and per-session by design)
 
 Feel free to open an issue if you have a feature request.
 

{specshift-1.0.0 → specshift-1.2.0}/README.md

@@ -54,11 +54,21 @@ requirement.
 
 - **Comprehensive structural diff**: deep comparison at the path, HTTP
   method, parameter, request body, response, and schema level.
+- **GraphQL support**: diff GraphQL SDL schemas with `specshift diff-graphql`,
+  covering types, fields, arguments, enum values, interfaces, unions, and
+  deprecations, no external GraphQL library required.
+- **Protobuf/gRPC support**: diff `.proto` files with `specshift diff-proto`,
+  using protobuf's own documented wire-compatibility rules (field numbers,
+  wire type categories, zigzag encoding) rather than generic JSON-shape
+  heuristics, so severity reflects what will actually break on the wire.
 - **Context-aware classification**: the same change is weighted
-  differently depending on whether it occurs in a request or a response.
+  differently depending on whether it occurs in a request or a response
+  (or, for GraphQL, an input type versus an object type).
 - **`$ref` resolution and `allOf` merging**: correctly follows the
   reference and composition patterns common in real-world specifications.
-- **Detects enum, format, nullable, and security scheme changes**.
+- **Detects enum, format, nullable, security scheme, content-type,
+  `additionalProperties`, `readOnly`/`writeOnly`, validation constraint,
+  default value, and `oneOf`/`anyOf` changes**.
 - **Works entirely for free**: no API key or paid service is required.
 - **Optional AI summary**: can generate a natural-language summary using
   Groq, the Gemini free tier, or any OpenAI-compatible endpoint. If no key
@@ -66,12 +76,18 @@ requirement.
   stops working.
 - **CI/CD integration**: the `specshift check` command compares the
   current specification against a branch and fails the build if a
-  breaking change is found.
+  breaking change is found. An official GitHub Action is also available
+  for one-line setup with automatic PR comments (see below).
 - **Live monitoring**: the `specshift watch` command periodically checks
   a remote API's specification and sends a Slack or Discord notification
   when it changes.
-- **Three output formats**: a colored console table, a Markdown report
-  (ideal for PR comments), and JSON (for integrating with other tools).
+- **Local web dashboard**: `specshift serve` opens a browser-based tool
+  for comparing specs interactively (drag in files or paste text), with
+  zero extra dependencies since it runs entirely on Python's standard
+  library and stays on localhost.
+- **Four output formats**: a colored console table, a Markdown report
+  (ideal for PR comments), JSON (for integrating with other tools), and a
+  standalone, filterable HTML report you can open in any browser.
 
 ## Installation
 
@@ -171,13 +187,50 @@ Useful options:
 
 | Option | Description |
 |---|---|
-| `--format console\|markdown\|json` | Output format (default: console) |
+| `--format console\|markdown\|json\|html` | Output format (default: console) |
 | `--output <file>` | Writes the output to a file |
 | `--ai` | Adds a natural-language summary |
 | `--ai-provider groq\|gemini\|openai_compatible` | Chooses the AI provider |
 | `--fail-on breaking\|warning\|none` | Determines at which level exit code 1 is returned |
 | `--quiet` | Only prints the summary line |
 
+### `specshift diff-graphql <old> <new>`
+
+Compares two GraphQL SDL schemas. `<old>` and `<new>` can be a file path,
+an http(s) URL, or raw SDL text. Supports the same `--format`, `--output`,
+`--ai`, and `--fail-on` options as `diff`.
+
+```bash
+specshift diff-graphql old_schema.graphql new_schema.graphql
+```
+
+### `specshift diff-proto <old> <new>`
+
+Compares two Protobuf/gRPC `.proto` schemas using protobuf's own
+wire-compatibility rules (field numbers, wire type categories) rather
+than generic JSON-shape heuristics. Supports the same `--format`,
+`--output`, `--ai`, and `--fail-on` options as `diff`.
+
+```bash
+specshift diff-proto old_service.proto new_service.proto
+```
+
+### `specshift serve`
+
+Starts a local, dependency-free web dashboard for comparing specs
+interactively. Opens a browser tab where you can drag in or paste two
+files (OpenAPI, GraphQL, or Protobuf, auto-detected), and view the same
+styled HTML report the CLI produces, with a short history of past
+comparisons in the current session.
+
+```bash
+specshift serve
+# or: specshift serve --port 9000 --no-browser
+```
+
+Everything runs in-process on your machine; nothing is uploaded anywhere,
+and the server binds to `127.0.0.1` by default.
+
 ### `specshift check`
 
 Designed for CI/CD. Compares the current specification file against a git
@@ -204,8 +257,48 @@ Creates a sample `.specshift.yml` file.
 
 ## Using it with GitHub Actions
 
-The workflow below checks your API contract against the `main` branch on
-every pull request and fails the build if a breaking change is found:
+### Option 1: the official SpecShift action (recommended)
+
+SpecShift ships its own composite GitHub Action that runs the contract
+check and automatically posts (and keeps updated) a Markdown report as a
+pull request comment:
+
+```yaml
+name: API Contract Check
+
+on:
+  pull_request:
+    paths:
+      - "openapi.yaml"
+
+permissions:
+  pull-requests: write
+
+jobs:
+  contract-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: Lethe044/SpecShift@v1
+        with:
+          spec-path: openapi.yaml
+          fail-on: breaking
+          # optional: ai-summary: 'true'
+```
+
+Available inputs: `spec-path`, `base-ref` (defaults to the PR base branch),
+`fail-on` (`breaking` | `warning` | `none`), `ai-summary` (`true`/`false`),
+`ai-provider`, `comment-on-pr` (`true`/`false`), `github-token`, and
+`specshift-version` to pin a specific release. Outputs: `has-breaking-changes`,
+`breaking-count`, `warning-count`, `info-count`, and `report-path`.
+
+### Option 2: calling the CLI directly
+
+If you'd rather not use the action (or want to combine it with other
+tooling), the CLI works just as well on its own:
 
 ```yaml
 name: API Contract Check
@@ -268,26 +361,39 @@ common scenarios:
 | Enum value removed | Breaking | Breaking |
 | Endpoint or method removed | Breaking | Breaking |
 
+The same table applies to GraphQL: `input` types behave like requests,
+`type`/`interface` fields behave like responses.
+
+Protobuf/gRPC follows a different model, based on the wire format rather
+than request/response direction: adding fields or rpc methods is always
+safe, changing a field's number is always breaking, and type changes are
+judged by wire type category (see the `diff-proto` section above).
+
 ## Comparison with other tools
 
 | | SpecShift | Raw JSON/YAML diff | oasdiff / openapi-diff style tools |
 |---|---|---|---|
 | Context-aware classification | Yes | No | Partially |
+| GraphQL support | Yes | No | Rarely |
+| Protobuf/gRPC support (wire-aware) | Yes | No | Rarely |
 | Natural-language summary | Yes (optional) | No | No |
+| Standalone HTML report | Yes | No | Rarely |
+| Local interactive dashboard | Yes | No | Rarely |
 | Free to use | Fully free | Free | Usually free |
-| CI integration | Built-in (`check`) | Manual | Varies |
+| CI integration | Built-in (`check` + official Action) | Manual | Varies |
 | Live URL monitoring | Built-in (`watch`) | No | Rarely |
 
 ## Roadmap
 
 This project is under active development. Some planned areas:
 
-- Support for gRPC/Protobuf contracts
-- GraphQL schema diffing
-- An official GitHub Action for posting automatic PR comments
-- A web-based result viewer
-- More semantic rules (path parameter pattern changes, content-type
-  changes, etc.)
+- Path parameter pattern (regex) and discriminator-level rule refinements
+- Deeper GraphQL support: directive-aware deprecation reasons, custom
+  scalar compatibility hints, and federation-aware schema composition
+- Protobuf `reserved` statement awareness, so a properly reserved field
+  number isn't flagged the same way as an unreserved removal
+- Optional shared/hosted history for the `serve` dashboard (currently
+  in-memory and per-session by design)
 
 Feel free to open an issue if you have a feature request.
 

{specshift-1.0.0 → specshift-1.2.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specshift"
-version = "1.0.0"
-description = "Detects, classifies, and optionally summarizes breaking changes in OpenAPI/Swagger contracts using AI"
+version = "1.2.0"
+description = "Detects, classifies, and optionally summarizes breaking changes in OpenAPI/Swagger, GraphQL, and Protobuf/gRPC contracts using AI"
 readme = "README.md"
 requires-python = ">=3.9"
 license = { text = "MIT" }
@@ -13,6 +13,9 @@ authors = [{ name = "Lethe044" }]
 keywords = [
     "openapi",
     "swagger",
+    "graphql",
+    "grpc",
+    "protobuf",
     "api",
     "breaking-changes",
     "contract-testing",
@@ -20,6 +23,7 @@ keywords = [
     "devtools",
     "cli",
     "ci-cd",
+    "github-actions",
 ]
 classifiers = [
     "Development Status :: 5 - Production/Stable",

{specshift-1.0.0 → specshift-1.2.0}/specshift/__init__.py

@@ -4,14 +4,20 @@ summarizes changes in OpenAPI and Swagger contracts using AI.
 """
 
 from specshift.differ import diff_specs
+from specshift.graphql_differ import diff_graphql, load_sdl as load_graphql_sdl
 from specshift.models import Change, Severity, ChangeType, DiffResult
+from specshift.protobuf_differ import diff_protos, load_proto
 from specshift.spec_loader import load_spec
 
-__version__ = "1.0.0"
+__version__ = "1.2.0"
 
 __all__ = [
     "diff_specs",
+    "diff_graphql",
+    "diff_protos",
     "load_spec",
+    "load_graphql_sdl",
+    "load_proto",
     "Change",
     "Severity",
     "ChangeType",

{specshift-1.0.0 → specshift-1.2.0}/specshift/cli.py

@@ -15,9 +15,16 @@ from specshift.ai_summary import generate_summary
 from specshift.config import SpecShiftConfig, write_default_config
 from specshift.differ import diff_specs
 from specshift.git_utils import GitError, load_spec_from_git
+from specshift.graphql_differ import GraphQLLoadError, diff_graphql, load_sdl
 from specshift.models import DiffResult
 from specshift.notifier import NotifyError, notify_discord, notify_slack
-from specshift.reporter import print_console_report, render_json_report, render_markdown_report
+from specshift.protobuf_differ import ProtoLoadError, diff_protos, load_proto
+from specshift.reporter import (
+    print_console_report,
+    render_html_report,
+    render_json_report,
+    render_markdown_report,
+)
 from specshift.spec_loader import SpecLoadError, load_spec
 
 CACHE_DIR = Path(".specshift_cache")
@@ -26,17 +33,27 @@ CACHE_DIR = Path(".specshift_cache")
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="specshift",
-        description="Detects and classifies changes in OpenAPI/Swagger specifications.",
+        description="Detects and classifies changes in OpenAPI/Swagger, GraphQL, and Protobuf/gRPC contracts.",
     )
     parser.add_argument("--version", action="version", version=f"specshift {__version__}")
 
     subparsers = parser.add_subparsers(dest="command", required=True)
 
-    diff_parser = subparsers.add_parser("diff", help="Compare two specifications")
+    diff_parser = subparsers.add_parser("diff", help="Compare two OpenAPI/Swagger specifications")
     diff_parser.add_argument("old", help="Old specification: file path or URL")
     diff_parser.add_argument("new", help="New specification: file path or URL")
     _add_common_diff_args(diff_parser)
 
+    graphql_parser = subparsers.add_parser("diff-graphql", help="Compare two GraphQL SDL schemas")
+    graphql_parser.add_argument("old", help="Old GraphQL schema: file path or URL")
+    graphql_parser.add_argument("new", help="New GraphQL schema: file path or URL")
+    _add_common_diff_args(graphql_parser)
+
+    proto_parser = subparsers.add_parser("diff-proto", help="Compare two Protobuf/gRPC .proto schemas")
+    proto_parser.add_argument("old", help="Old .proto schema: file path or URL")
+    proto_parser.add_argument("new", help="New .proto schema: file path or URL")
+    _add_common_diff_args(proto_parser)
+
     check_parser = subparsers.add_parser(
         "check", help="For CI: compares the current specification against a git reference"
     )
@@ -60,12 +77,19 @@ def build_parser() -> argparse.ArgumentParser:
     init_parser.add_argument("--path", default=".specshift.yml", help="Path of the file to create")
     init_parser.add_argument("--force", action="store_true", help="Overwrite an existing file")
 
+    serve_parser = subparsers.add_parser(
+        "serve", help="Starts a local web dashboard for comparing specs interactively in the browser"
+    )
+    serve_parser.add_argument("--host", default="127.0.0.1", help="Host to bind to (default: 127.0.0.1)")
+    serve_parser.add_argument("--port", type=int, default=8787, help="Port to listen on (default: 8787)")
+    serve_parser.add_argument("--no-browser", action="store_true", help="Don't automatically open a browser tab")
+
     return parser
 
 
 def _add_common_diff_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
-        "--format", choices=["console", "markdown", "json"], default="console", help="Output format"
+        "--format", choices=["console", "markdown", "json", "html"], default="console", help="Output format"
     )
     parser.add_argument("--output", help="Write the output to a file (stdout if omitted)")
     parser.add_argument("--ai", action="store_true", help="Generate a natural-language AI summary")
@@ -89,13 +113,19 @@ def main(argv: Optional[list[str]] = None) -> int:
     try:
         if args.command == "diff":
             return _run_diff(args)
+        if args.command == "diff-graphql":
+            return _run_diff_graphql(args)
+        if args.command == "diff-proto":
+            return _run_diff_proto(args)
         if args.command == "check":
             return _run_check(args)
         if args.command == "watch":
             return _run_watch(args)
         if args.command == "init":
             return _run_init(args)
-    except (SpecLoadError, GitError) as exc:
+        if args.command == "serve":
+            return _run_serve(args)
+    except (SpecLoadError, GitError, GraphQLLoadError, ProtoLoadError) as exc:
         print(f"Error: {exc}", file=sys.stderr)
         return 2
     except KeyboardInterrupt:
@@ -113,6 +143,20 @@ def _run_diff(args: argparse.Namespace) -> int:
     return _emit_result(result, args)
 
 
+def _run_diff_graphql(args: argparse.Namespace) -> int:
+    old_sdl = load_sdl(args.old)
+    new_sdl = load_sdl(args.new)
+    result = diff_graphql(old_sdl, new_sdl)
+    return _emit_result(result, args)
+
+
+def _run_diff_proto(args: argparse.Namespace) -> int:
+    old_proto = load_proto(args.old)
+    new_proto = load_proto(args.new)
+    result = diff_protos(old_proto, new_proto)
+    return _emit_result(result, args)
+
+
 def _run_check(args: argparse.Namespace) -> int:
     config = SpecShiftConfig.load(args.config)
     spec_path = args.spec or config.spec_path
@@ -151,6 +195,8 @@ def _emit_result(result: DiffResult, args: argparse.Namespace) -> int:
         output_text = render_json_report(result, ai_summary=ai_summary)
     elif args.format == "markdown":
         output_text = render_markdown_report(result, ai_summary=ai_summary)
+    elif args.format == "html":
+        output_text = render_html_report(result, ai_summary=ai_summary)
     else:
         output_text = None  # console format is printed directly
 
@@ -166,9 +212,12 @@ def _emit_result(result: DiffResult, args: argparse.Namespace) -> int:
             if ai_summary:
                 print(f"\nAI Summary:\n{ai_summary}")
     else:
-        if args.output:
-            Path(args.output).write_text(output_text, encoding="utf-8")
-            print(f"Report written to: {args.output}")
+        output_path = args.output
+        if args.format == "html" and not output_path:
+            output_path = "specshift-report.html"
+        if output_path:
+            Path(output_path).write_text(output_text, encoding="utf-8")
+            print(f"Report written to: {output_path}")
         else:
             print(output_text)
 
@@ -194,6 +243,13 @@ def _run_init(args: argparse.Namespace) -> int:
     return 0
 
 
+def _run_serve(args: argparse.Namespace) -> int:
+    from specshift.webapp import run_server
+
+    run_server(host=args.host, port=args.port, open_browser=not args.no_browser)
+    return 0
+
+
 def _run_watch(args: argparse.Namespace) -> int:
     CACHE_DIR.mkdir(exist_ok=True)
     cache_key = hashlib.sha256(args.url.encode("utf-8")).hexdigest()[:16]