dossierdock 0.1.0__tar.gz

dossierdock-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shashank Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dossierdock-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: dossierdock
+Version: 0.1.0
+Summary: Release-readiness evidence and CI workflow generation for containerized AI services.
+Author: Shashank Singh
+License: MIT License
+        
+        Copyright (c) 2026 Shashank Singh
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/shasanksingh/dossierdock
+Project-URL: Issues, https://github.com/shasanksingh/dossierdock/issues
+Keywords: ai,containers,deployment,docker,ci-cd,mlops,release-evidence,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# DossierDock
+
+`dossierdock` is a provider-neutral **release-evidence CLI for containerized AI services**. It does more than produce a build command: it checks the service contract, image hardening signals, health-route evidence, and local-secret exposure, then writes a portable release dossier for a pull request, CI artifact, or operational handover.
+
+The first release deliberately does **not** own cloud credentials or send a deployment anywhere. That makes it a safe foundation for teams that want a clear, reviewable path from an AI service to a container build and CI pipeline. Remote targets (SSH, AWS, and other providers) can be added as opt-in adapters rather than built into every command.
+
+## Why it is different
+
+Most deployment tools build or deploy an image. DossierDock focuses on answering: **“What evidence says this AI service is ready to release?”**
+
+It produces a small, provider-neutral `release-dossier.json` containing only safe metadata: the service contract, health endpoint, manifest hash, blockers, review items, and checks performed. No API key, connection string, or secret value is collected or written to the dossier.
+
+This makes the tool useful before choosing AWS, Docker, Kubernetes, a VM, or another delivery target.
+
+## What it does today
+
+- Creates a portable `dossierdock.toml` manifest.
+- Checks the Dockerfile, health endpoint, AI-service metadata, and deployment metadata before CI runs.
+- Reviews root-container execution, missing Docker health checks, and common credential files that are not ignored.
+- Looks for evidence that the declared HTTP health route exists in application source.
+- Writes a portable release dossier suitable for CI artifacts and release reviews.
+- Prints a deterministic build and release plan as text or JSON.
+- Writes a GitHub Actions workflow that tests the project and builds an immutable container image.
+- Uses only the Python standard library at runtime.
+
+## Quick start
+
+```bash
+python -m pip install -e .
+dossierdock init --path .
+dossierdock doctor
+dossierdock plan
+dossierdock dossier
+dossierdock workflow github --output .github/workflows/dossierdock.yml
+```
+
+Add a health endpoint to your API, then build it locally:
+
+```bash
+docker build -t my-ai-service:dev .
+docker run --rm -p 8000:8000 my-ai-service:dev
+```
+
+## Manifest
+
+```toml
+[app]
+name = "my-ai-service"
+dockerfile = "Dockerfile"
+context = "."
+image = "my-ai-service"
+healthcheck = "/health"
+port = 8000
+
+[deployment]
+target = "local"
+environment = "development"
+
+[ai]
+service_kind = "ai-api"
+model_provider = "external"
+telemetry = "open-telemetry"
+```
+
+The manifest contains no credentials. Keep provider credentials in the CI platform's secret store and add a target adapter only when you are ready to deploy.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `dossierdock init` | Create a starter manifest. |
+| `dossierdock doctor` | Report release-readiness issues and checks. |
+| `dossierdock plan` | Show the container build and health-check plan. |
+| `dossierdock dossier` | Write reviewable, secret-free release evidence as JSON. |
+| `dossierdock workflow github` | Create a GitHub Actions CI workflow. |
+
+## Release dossier
+
+```bash
+dossierdock dossier --output .dossierdock/release-dossier.json
+```
+
+The dossier records the application, declared AI-service contract, health URL, SHA-256 fingerprint of the manifest, blockers, and review items. Generated GitHub Actions workflows upload it as a build artifact so the release evidence stays with the exact CI run that built the image.
+
+## Project layout
+
+```text
+src/dossierdock/     CLI, config loader, checks, workflow templates
+tests/               Standard-library unit tests
+examples/            A deployable manifest example
+docs/                Architecture and contributor notes
+```
+
+## Roadmap
+
+1. Docker build and local smoke-test adapters.
+2. OpenTelemetry-compatible deployment annotations and release events.
+3. SSH release adapter with rollback and health verification.
+4. Separate AWS deployment adapter and learning guide.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). This project is released under the [MIT License](LICENSE).

dossierdock-0.1.0/README.md

@@ -0,0 +1,103 @@
+# DossierDock
+
+`dossierdock` is a provider-neutral **release-evidence CLI for containerized AI services**. It does more than produce a build command: it checks the service contract, image hardening signals, health-route evidence, and local-secret exposure, then writes a portable release dossier for a pull request, CI artifact, or operational handover.
+
+The first release deliberately does **not** own cloud credentials or send a deployment anywhere. That makes it a safe foundation for teams that want a clear, reviewable path from an AI service to a container build and CI pipeline. Remote targets (SSH, AWS, and other providers) can be added as opt-in adapters rather than built into every command.
+
+## Why it is different
+
+Most deployment tools build or deploy an image. DossierDock focuses on answering: **“What evidence says this AI service is ready to release?”**
+
+It produces a small, provider-neutral `release-dossier.json` containing only safe metadata: the service contract, health endpoint, manifest hash, blockers, review items, and checks performed. No API key, connection string, or secret value is collected or written to the dossier.
+
+This makes the tool useful before choosing AWS, Docker, Kubernetes, a VM, or another delivery target.
+
+## What it does today
+
+- Creates a portable `dossierdock.toml` manifest.
+- Checks the Dockerfile, health endpoint, AI-service metadata, and deployment metadata before CI runs.
+- Reviews root-container execution, missing Docker health checks, and common credential files that are not ignored.
+- Looks for evidence that the declared HTTP health route exists in application source.
+- Writes a portable release dossier suitable for CI artifacts and release reviews.
+- Prints a deterministic build and release plan as text or JSON.
+- Writes a GitHub Actions workflow that tests the project and builds an immutable container image.
+- Uses only the Python standard library at runtime.
+
+## Quick start
+
+```bash
+python -m pip install -e .
+dossierdock init --path .
+dossierdock doctor
+dossierdock plan
+dossierdock dossier
+dossierdock workflow github --output .github/workflows/dossierdock.yml
+```
+
+Add a health endpoint to your API, then build it locally:
+
+```bash
+docker build -t my-ai-service:dev .
+docker run --rm -p 8000:8000 my-ai-service:dev
+```
+
+## Manifest
+
+```toml
+[app]
+name = "my-ai-service"
+dockerfile = "Dockerfile"
+context = "."
+image = "my-ai-service"
+healthcheck = "/health"
+port = 8000
+
+[deployment]
+target = "local"
+environment = "development"
+
+[ai]
+service_kind = "ai-api"
+model_provider = "external"
+telemetry = "open-telemetry"
+```
+
+The manifest contains no credentials. Keep provider credentials in the CI platform's secret store and add a target adapter only when you are ready to deploy.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `dossierdock init` | Create a starter manifest. |
+| `dossierdock doctor` | Report release-readiness issues and checks. |
+| `dossierdock plan` | Show the container build and health-check plan. |
+| `dossierdock dossier` | Write reviewable, secret-free release evidence as JSON. |
+| `dossierdock workflow github` | Create a GitHub Actions CI workflow. |
+
+## Release dossier
+
+```bash
+dossierdock dossier --output .dossierdock/release-dossier.json
+```
+
+The dossier records the application, declared AI-service contract, health URL, SHA-256 fingerprint of the manifest, blockers, and review items. Generated GitHub Actions workflows upload it as a build artifact so the release evidence stays with the exact CI run that built the image.
+
+## Project layout
+
+```text
+src/dossierdock/     CLI, config loader, checks, workflow templates
+tests/               Standard-library unit tests
+examples/            A deployable manifest example
+docs/                Architecture and contributor notes
+```
+
+## Roadmap
+
+1. Docker build and local smoke-test adapters.
+2. OpenTelemetry-compatible deployment annotations and release events.
+3. SSH release adapter with rollback and health verification.
+4. Separate AWS deployment adapter and learning guide.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). This project is released under the [MIT License](LICENSE).

dossierdock-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dossierdock"
+version = "0.1.0"
+description = "Release-readiness evidence and CI workflow generation for containerized AI services."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Shashank Singh" },
+]
+keywords = ["ai", "containers", "deployment", "docker", "ci-cd", "mlops", "release-evidence", "security"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Build Tools",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["build>=1.2", "twine>=5.1"]
+
+[project.scripts]
+dossierdock = "dossierdock.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/shasanksingh/dossierdock"
+Issues = "https://github.com/shasanksingh/dossierdock/issues"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

dossierdock-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dossierdock-0.1.0/src/dossierdock/__init__.py

@@ -0,0 +1,5 @@
+"""DossierDock: release-readiness evidence for AI services."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

dossierdock-0.1.0/src/dossierdock/__main__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from dossierdock.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dossierdock-0.1.0/src/dossierdock/cli.py

@@ -0,0 +1,153 @@
+"""Command-line interface for DossierDock."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+from typing import Sequence
+
+from dossierdock import __version__
+from dossierdock.config import DEFAULT_CONFIG
+from dossierdock.doctor import run_doctor
+from dossierdock.evidence import build_dossier
+from dossierdock.workflow import GITHUB_ACTIONS_WORKFLOW
+
+
+def _write(path: Path, content: str, force: bool) -> None:
+    if path.exists() and not force:
+        raise FileExistsError(f"Refusing to overwrite {path}. Use --force to replace it.")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def _print_report(report, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(report.as_dict(), indent=2))
+        return
+    for check in report.checks:
+        print(f"[{check.status.upper():7}] {check.name}: {check.message}")
+    print("\nDossierDock is ready." if report.healthy else "\nDossierDock found issues to resolve.")
+
+
+def _command_init(args: argparse.Namespace) -> int:
+    root = Path(args.path).expanduser().resolve()
+    destination = root / "dossierdock.toml"
+    try:
+        _write(destination, DEFAULT_CONFIG, args.force)
+    except FileExistsError as error:
+        print(error, file=sys.stderr)
+        return 2
+    print(f"Created {destination}")
+    return 0
+
+
+def _command_doctor(args: argparse.Namespace) -> int:
+    report = run_doctor(args.config)
+    _print_report(report, args.json)
+    return 0 if report.healthy else 1
+
+
+def _command_plan(args: argparse.Namespace) -> int:
+    report = run_doctor(args.config)
+    if not report.config:
+        _print_report(report, args.json)
+        return 1
+    config = report.config
+    plan = {
+        "application": config.name,
+        "environment": config.environment,
+        "target": config.target,
+        "build": {
+            "context": str(config.context_path),
+            "dockerfile": str(config.dockerfile_path),
+            "image": config.image,
+        },
+        "healthcheck": f"http://localhost:{config.port}{config.healthcheck}",
+        "ready": report.healthy,
+    }
+    if args.json:
+        print(json.dumps(plan, indent=2))
+    else:
+        print(f"Application: {plan['application']} ({plan['environment']})")
+        print(f"Target:      {plan['target']}")
+        print(f"Build:       docker build -f {config.dockerfile} -t {config.image} {config.context}")
+        print(f"Health:      {plan['healthcheck']}")
+        print(f"Ready:       {'yes' if report.healthy else 'no — run dossierdock doctor'}")
+    return 0 if report.healthy else 1
+
+
+def _command_dossier(args: argparse.Namespace) -> int:
+    report = run_doctor(args.config)
+    dossier = build_dossier(report)
+    serialized = json.dumps(dossier, indent=2) + "\n"
+    if args.output == "-":
+        print(serialized, end="")
+    else:
+        destination = Path(args.output).expanduser().resolve()
+        try:
+            _write(destination, serialized, args.force)
+        except FileExistsError as error:
+            print(error, file=sys.stderr)
+            return 2
+        print(f"Created release dossier: {destination}")
+    return 0 if report.healthy else 1
+
+
+def _command_workflow_github(args: argparse.Namespace) -> int:
+    destination = Path(args.output).expanduser().resolve()
+    try:
+        _write(destination, GITHUB_ACTIONS_WORKFLOW, args.force)
+    except FileExistsError as error:
+        print(error, file=sys.stderr)
+        return 2
+    print(f"Created GitHub Actions workflow: {destination}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="dossierdock",
+        description="Release-readiness evidence and CI workflow generation for containerized AI services.",
+    )
+    parser.add_argument("--version", action="version", version=f"dossierdock {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_parser = subparsers.add_parser("init", help="Create a starter dossierdock.toml manifest.")
+    init_parser.add_argument("--path", default=".", help="Directory that will receive dossierdock.toml.")
+    init_parser.add_argument("--force", action="store_true", help="Replace an existing manifest.")
+    init_parser.set_defaults(handler=_command_init)
+
+    for name, handler, help_text in (
+        ("doctor", _command_doctor, "Check local container-delivery inputs."),
+        ("plan", _command_plan, "Show the generated build and health-check plan."),
+    ):
+        command = subparsers.add_parser(name, help=help_text)
+        command.add_argument("--config", help="Path to dossierdock.toml (defaults to the current directory).")
+        command.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
+        command.set_defaults(handler=handler)
+
+    dossier = subparsers.add_parser("dossier", help="Create a portable AI service release-evidence dossier.")
+    dossier.add_argument("--config", help="Path to dossierdock.toml (defaults to the current directory).")
+    dossier.add_argument(
+        "--output",
+        default=".dossierdock/release-dossier.json",
+        help="Dossier destination, or '-' to print JSON to stdout.",
+    )
+    dossier.add_argument("--force", action="store_true", help="Replace an existing dossier.")
+    dossier.set_defaults(handler=_command_dossier)
+
+    workflow = subparsers.add_parser("workflow", help="Generate CI workflow files.")
+    workflow_subparsers = workflow.add_subparsers(dest="workflow_command", required=True)
+    github = workflow_subparsers.add_parser("github", help="Write a GitHub Actions CI workflow.")
+    github.add_argument("--output", default=".github/workflows/dossierdock.yml", help="Workflow destination.")
+    github.add_argument("--force", action="store_true", help="Replace an existing workflow.")
+    github.set_defaults(handler=_command_workflow_github)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    arguments = parser.parse_args(argv)
+    return arguments.handler(arguments)

dossierdock-0.1.0/src/dossierdock/config.py

@@ -0,0 +1,125 @@
+"""Manifest loading and validation for DossierDock."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+import re
+import tomllib
+from typing import Any
+
+
+class ConfigError(ValueError):
+    """Raised when a DossierDock manifest is missing or invalid."""
+
+
+@dataclass(frozen=True, slots=True)
+class AppConfig:
+    name: str
+    dockerfile: str
+    context: str
+    image: str
+    healthcheck: str
+    port: int
+    target: str
+    environment: str
+    service_kind: str
+    model_provider: str
+    telemetry: str
+    config_path: Path
+
+    @property
+    def project_root(self) -> Path:
+        return self.config_path.parent
+
+    @property
+    def dockerfile_path(self) -> Path:
+        return self.project_root / self.dockerfile
+
+    @property
+    def context_path(self) -> Path:
+        return self.project_root / self.context
+
+    def public_dict(self) -> dict[str, Any]:
+        """Return serialisable non-secret configuration for command output."""
+        data = asdict(self)
+        data["config_path"] = str(self.config_path)
+        return data
+
+
+DEFAULT_CONFIG = """# DossierDock release-evidence manifest\n# Keep credentials in your CI secret store, never in this file.\n\n[app]\nname = \"my-ai-service\"\ndockerfile = \"Dockerfile\"\ncontext = \".\"\nimage = \"my-ai-service\"\nhealthcheck = \"/health\"\nport = 8000\n\n[deployment]\ntarget = \"local\"\nenvironment = \"development\"\n\n[ai]\n# Metadata only: never put API keys or connection strings here.\nservice_kind = \"ai-api\"\nmodel_provider = \"external\"\ntelemetry = \"open-telemetry\"\n"""
+
+
+def default_config_path() -> Path:
+    return Path.cwd() / "dossierdock.toml"
+
+
+def _table(document: dict[str, Any], key: str) -> dict[str, Any]:
+    value = document.get(key)
+    if not isinstance(value, dict):
+        raise ConfigError(f"Missing [{key}] section.")
+    return value
+
+
+def _optional_table(document: dict[str, Any], key: str) -> dict[str, Any]:
+    value = document.get(key, {})
+    if not isinstance(value, dict):
+        raise ConfigError(f"[{key}] must be a table.")
+    return value
+
+
+def _text(table: dict[str, Any], key: str, default: str | None = None) -> str:
+    value = table.get(key, default)
+    if not isinstance(value, str) or not value.strip():
+        raise ConfigError(f"'{key}' must be a non-empty string.")
+    return value.strip()
+
+
+def _port(table: dict[str, Any]) -> int:
+    value = table.get("port", 8000)
+    if isinstance(value, bool) or not isinstance(value, int) or not 1 <= value <= 65535:
+        raise ConfigError("'port' must be an integer between 1 and 65535.")
+    return value
+
+
+def _safe_name(value: str) -> str:
+    if not re.fullmatch(r"[a-z0-9][a-z0-9._-]*", value):
+        raise ConfigError("'name' may contain lowercase letters, digits, dots, underscores, and hyphens only.")
+    return value
+
+
+def load_config(path: str | Path | None = None) -> AppConfig:
+    """Load and validate a DossierDock TOML manifest."""
+    config_path = Path(path) if path else default_config_path()
+    config_path = config_path.expanduser().resolve()
+    if not config_path.is_file():
+        raise ConfigError(f"Manifest not found: {config_path}")
+
+    try:
+        with config_path.open("rb") as handle:
+            document = tomllib.load(handle)
+    except tomllib.TOMLDecodeError as error:
+        raise ConfigError(f"Invalid TOML in {config_path.name}: {error}") from error
+
+    app = _table(document, "app")
+    deployment = _table(document, "deployment")
+    ai = _optional_table(document, "ai")
+    name = _safe_name(_text(app, "name"))
+    healthcheck = _text(app, "healthcheck", "/health")
+    if not healthcheck.startswith("/"):
+        raise ConfigError("'healthcheck' must start with '/'.")
+
+    return AppConfig(
+        name=name,
+        dockerfile=_text(app, "dockerfile", "Dockerfile"),
+        context=_text(app, "context", "."),
+        image=_text(app, "image", name),
+        healthcheck=healthcheck,
+        port=_port(app),
+        target=_text(deployment, "target", "local"),
+        environment=_text(deployment, "environment", "development"),
+        service_kind=_text(ai, "service_kind", "ai-api"),
+        model_provider=_text(ai, "model_provider", "unspecified"),
+        telemetry=_text(ai, "telemetry", "unspecified"),
+        config_path=config_path,
+    )

dossierdock-0.1.0/src/dossierdock/doctor.py

@@ -0,0 +1,149 @@
+"""Preflight checks for container build inputs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+from pathlib import Path
+import re
+
+from dossierdock.config import AppConfig, ConfigError, load_config
+
+
+@dataclass(frozen=True, slots=True)
+class Check:
+    name: str
+    status: str
+    message: str
+
+    def as_dict(self) -> dict[str, str]:
+        return asdict(self)
+
+
+@dataclass(frozen=True, slots=True)
+class DoctorReport:
+    checks: tuple[Check, ...]
+    config: AppConfig | None = None
+
+    @property
+    def healthy(self) -> bool:
+        return all(check.status != "error" for check in self.checks)
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "healthy": self.healthy,
+            "checks": [check.as_dict() for check in self.checks],
+            "config": self.config.public_dict() if self.config else None,
+        }
+
+
+def _check_file(path: Path, name: str, required: bool) -> Check:
+    if path.is_file():
+        return Check(name, "ok", f"Found {path.name}.")
+    level = "error" if required else "warning"
+    tip = "Create it before building the image." if required else "Recommended to reduce build context size."
+    return Check(name, level, f"{path.name} was not found. {tip}")
+
+
+def _docker_contract_checks(config: AppConfig) -> list[Check]:
+    """Check image hardening signals without executing Docker or the application."""
+    if not config.dockerfile_path.is_file():
+        return []
+    dockerfile = config.dockerfile_path.read_text(encoding="utf-8", errors="ignore")
+    checks: list[Check] = []
+    if re.search(r"^\s*USER\s+", dockerfile, flags=re.MULTILINE):
+        checks.append(Check("container_user", "ok", "Dockerfile declares a runtime user."))
+    else:
+        checks.append(Check("container_user", "warning", "Dockerfile has no USER instruction; review root execution."))
+    if re.search(r"^\s*HEALTHCHECK\s+", dockerfile, flags=re.MULTILINE):
+        checks.append(Check("container_healthcheck", "ok", "Dockerfile declares a container health check."))
+    else:
+        checks.append(
+            Check(
+                "container_healthcheck",
+                "warning",
+                "No Docker HEALTHCHECK found; DossierDock will retain the external HTTP health contract.",
+            )
+        )
+    return checks
+
+
+def _health_route_check(config: AppConfig) -> Check:
+    """Look for the declared route in typical API source files without parsing frameworks."""
+    source_suffixes = {".py", ".js", ".ts", ".tsx", ".go", ".java"}
+    ignored = {".git", ".venv", "venv", "node_modules", "build", "dist", "__pycache__"}
+    marker = config.healthcheck.lower()
+    for candidate in config.project_root.rglob("*"):
+        if any(part in ignored for part in candidate.parts) or candidate.suffix.lower() not in source_suffixes:
+            continue
+        if candidate.is_file() and marker in candidate.read_text(encoding="utf-8", errors="ignore").lower():
+            return Check("health_route", "ok", f"Found '{config.healthcheck}' in {candidate.relative_to(config.project_root)}.")
+    return Check(
+        "health_route",
+        "warning",
+        f"Could not locate '{config.healthcheck}' in source files; verify the route during a smoke test.",
+    )
+
+
+def _secret_exposure_check(config: AppConfig) -> Check:
+    """Flag local environment files that are not protected by .gitignore.
+
+    The check never prints values. It only reports the filenames that need review.
+    """
+    sensitive_names = (".env", ".env.local", ".env.production", "credentials.json", "service-account.json")
+    found = [name for name in sensitive_names if (config.project_root / name).is_file()]
+    if not found:
+        return Check("secret_exposure", "ok", "No common local credential files found in the project root.")
+
+    ignore_file = config.project_root / ".gitignore"
+    ignored_patterns = ignore_file.read_text(encoding="utf-8", errors="ignore") if ignore_file.is_file() else ""
+    unprotected = [name for name in found if name not in ignored_patterns and not (name.startswith(".env") and ".env" in ignored_patterns)]
+    if unprotected:
+        return Check("secret_exposure", "error", f"Sensitive local files are not ignored: {', '.join(unprotected)}.")
+    return Check("secret_exposure", "warning", f"Local credential files are ignored but should not be copied into images: {', '.join(found)}.")
+
+
+def run_doctor(path: str | Path | None = None) -> DoctorReport:
+    """Run only local, non-invasive preflight checks."""
+    try:
+        config = load_config(path)
+    except ConfigError as error:
+        return DoctorReport((Check("manifest", "error", str(error)),))
+
+    checks: list[Check] = [Check("manifest", "ok", f"Loaded {config.config_path.name}.")]
+    checks.append(_check_file(config.dockerfile_path, "dockerfile", required=True))
+
+    if config.context_path.is_dir():
+        checks.append(Check("context", "ok", f"Build context: {config.context_path}"))
+    else:
+        checks.append(Check("context", "error", f"Build context not found: {config.context_path}"))
+
+    checks.append(_check_file(config.project_root / ".dockerignore", "dockerignore", required=False))
+    checks.extend(_docker_contract_checks(config))
+    checks.append(
+        Check(
+            "healthcheck",
+            "ok",
+            f"Application should answer on http://localhost:{config.port}{config.healthcheck}.",
+        )
+    )
+    checks.append(_health_route_check(config))
+    checks.append(_secret_exposure_check(config))
+    checks.append(
+        Check(
+            "ai_contract",
+            "ok",
+            f"AI service contract: {config.service_kind}; provider metadata: {config.model_provider}; telemetry: {config.telemetry}.",
+        )
+    )
+
+    if config.target == "local":
+        checks.append(Check("target", "ok", "Local target selected; no remote credentials are required."))
+    else:
+        checks.append(
+            Check(
+                "target",
+                "warning",
+                f"Target '{config.target}' is declared but no remote adapter is installed in this release.",
+            )
+        )
+    return DoctorReport(tuple(checks), config)

dossierdock-0.1.0/src/dossierdock/evidence.py

@@ -0,0 +1,50 @@
+"""Portable release-evidence generation for AI services."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import hashlib
+from typing import Any
+
+from dossierdock.doctor import DoctorReport
+
+
+DOSSIER_SCHEMA_VERSION = "1.0"
+
+
+def build_dossier(report: DoctorReport) -> dict[str, Any]:
+    """Build a shareable deployment dossier without reading or exposing secrets."""
+    if report.config is None:
+        return {
+            "schema_version": DOSSIER_SCHEMA_VERSION,
+            "generated_at": datetime.now(timezone.utc).isoformat(),
+            "release_readiness": "blocked",
+            "blockers": [check.as_dict() for check in report.checks if check.status == "error"],
+            "review_items": [check.as_dict() for check in report.checks if check.status == "warning"],
+        }
+
+    config = report.config
+    digest = hashlib.sha256(config.config_path.read_bytes()).hexdigest()
+    blockers = [check.as_dict() for check in report.checks if check.status == "error"]
+    review_items = [check.as_dict() for check in report.checks if check.status == "warning"]
+    return {
+        "schema_version": DOSSIER_SCHEMA_VERSION,
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "release_readiness": "ready" if not blockers and not review_items else "review" if not blockers else "blocked",
+        "application": {
+            "name": config.name,
+            "image": config.image,
+            "environment": config.environment,
+            "target": config.target,
+            "healthcheck": f"http://localhost:{config.port}{config.healthcheck}",
+        },
+        "ai_service_contract": {
+            "service_kind": config.service_kind,
+            "model_provider": config.model_provider,
+            "telemetry": config.telemetry,
+        },
+        "manifest_sha256": digest,
+        "blockers": blockers,
+        "review_items": review_items,
+        "checks": [check.as_dict() for check in report.checks],
+    }

dossierdock-0.1.0/src/dossierdock/workflow.py

@@ -0,0 +1,43 @@
+"""Versioned templates for generated CI workflows."""
+
+from __future__ import annotations
+
+
+GITHUB_ACTIONS_WORKFLOW = """name: DossierDock CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: \"3.11\"
+      - name: Install project and DossierDock
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install dossierdock
+          if [ -f requirements.txt ]; then python -m pip install -r requirements.txt; fi
+      - name: Run project tests
+        run: |
+          if [ -d tests ]; then python -m unittest discover -s tests -v; fi
+      - name: Validate container delivery inputs
+        run: dossierdock doctor
+      - name: Create release-evidence dossier
+        run: dossierdock dossier --force
+      - name: Preserve release evidence
+        uses: actions/upload-artifact@v4
+        with:
+          name: dossierdock-release-dossier
+          path: .dossierdock/release-dossier.json
+      - name: Build immutable container image
+        run: docker build --tag ${{ github.repository }}:${{ github.sha }} .
+"""

dossierdock-0.1.0/src/dossierdock.egg-info/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: dossierdock
+Version: 0.1.0
+Summary: Release-readiness evidence and CI workflow generation for containerized AI services.
+Author: Shashank Singh
+License: MIT License
+        
+        Copyright (c) 2026 Shashank Singh
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/shasanksingh/dossierdock
+Project-URL: Issues, https://github.com/shasanksingh/dossierdock/issues
+Keywords: ai,containers,deployment,docker,ci-cd,mlops,release-evidence,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# DossierDock
+
+`dossierdock` is a provider-neutral **release-evidence CLI for containerized AI services**. It does more than produce a build command: it checks the service contract, image hardening signals, health-route evidence, and local-secret exposure, then writes a portable release dossier for a pull request, CI artifact, or operational handover.
+
+The first release deliberately does **not** own cloud credentials or send a deployment anywhere. That makes it a safe foundation for teams that want a clear, reviewable path from an AI service to a container build and CI pipeline. Remote targets (SSH, AWS, and other providers) can be added as opt-in adapters rather than built into every command.
+
+## Why it is different
+
+Most deployment tools build or deploy an image. DossierDock focuses on answering: **“What evidence says this AI service is ready to release?”**
+
+It produces a small, provider-neutral `release-dossier.json` containing only safe metadata: the service contract, health endpoint, manifest hash, blockers, review items, and checks performed. No API key, connection string, or secret value is collected or written to the dossier.
+
+This makes the tool useful before choosing AWS, Docker, Kubernetes, a VM, or another delivery target.
+
+## What it does today
+
+- Creates a portable `dossierdock.toml` manifest.
+- Checks the Dockerfile, health endpoint, AI-service metadata, and deployment metadata before CI runs.
+- Reviews root-container execution, missing Docker health checks, and common credential files that are not ignored.
+- Looks for evidence that the declared HTTP health route exists in application source.
+- Writes a portable release dossier suitable for CI artifacts and release reviews.
+- Prints a deterministic build and release plan as text or JSON.
+- Writes a GitHub Actions workflow that tests the project and builds an immutable container image.
+- Uses only the Python standard library at runtime.
+
+## Quick start
+
+```bash
+python -m pip install -e .
+dossierdock init --path .
+dossierdock doctor
+dossierdock plan
+dossierdock dossier
+dossierdock workflow github --output .github/workflows/dossierdock.yml
+```
+
+Add a health endpoint to your API, then build it locally:
+
+```bash
+docker build -t my-ai-service:dev .
+docker run --rm -p 8000:8000 my-ai-service:dev
+```
+
+## Manifest
+
+```toml
+[app]
+name = "my-ai-service"
+dockerfile = "Dockerfile"
+context = "."
+image = "my-ai-service"
+healthcheck = "/health"
+port = 8000
+
+[deployment]
+target = "local"
+environment = "development"
+
+[ai]
+service_kind = "ai-api"
+model_provider = "external"
+telemetry = "open-telemetry"
+```
+
+The manifest contains no credentials. Keep provider credentials in the CI platform's secret store and add a target adapter only when you are ready to deploy.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `dossierdock init` | Create a starter manifest. |
+| `dossierdock doctor` | Report release-readiness issues and checks. |
+| `dossierdock plan` | Show the container build and health-check plan. |
+| `dossierdock dossier` | Write reviewable, secret-free release evidence as JSON. |
+| `dossierdock workflow github` | Create a GitHub Actions CI workflow. |
+
+## Release dossier
+
+```bash
+dossierdock dossier --output .dossierdock/release-dossier.json
+```
+
+The dossier records the application, declared AI-service contract, health URL, SHA-256 fingerprint of the manifest, blockers, and review items. Generated GitHub Actions workflows upload it as a build artifact so the release evidence stays with the exact CI run that built the image.
+
+## Project layout
+
+```text
+src/dossierdock/     CLI, config loader, checks, workflow templates
+tests/               Standard-library unit tests
+examples/            A deployable manifest example
+docs/                Architecture and contributor notes
+```
+
+## Roadmap
+
+1. Docker build and local smoke-test adapters.
+2. OpenTelemetry-compatible deployment annotations and release events.
+3. SSH release adapter with rollback and health verification.
+4. Separate AWS deployment adapter and learning guide.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). This project is released under the [MIT License](LICENSE).

dossierdock-0.1.0/src/dossierdock.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+src/dossierdock/__init__.py
+src/dossierdock/__main__.py
+src/dossierdock/cli.py
+src/dossierdock/config.py
+src/dossierdock/doctor.py
+src/dossierdock/evidence.py
+src/dossierdock/workflow.py
+src/dossierdock.egg-info/PKG-INFO
+src/dossierdock.egg-info/SOURCES.txt
+src/dossierdock.egg-info/dependency_links.txt
+src/dossierdock.egg-info/entry_points.txt
+src/dossierdock.egg-info/requires.txt
+src/dossierdock.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_config.py

dossierdock-0.1.0/src/dossierdock.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dossierdock-0.1.0/src/dossierdock.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dossierdock = dossierdock.cli:main

dossierdock-0.1.0/src/dossierdock.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+build>=1.2
+twine>=5.1

dossierdock-0.1.0/src/dossierdock.egg-info/top_level.txt

@@ -0,0 +1 @@
+dossierdock

dossierdock-0.1.0/tests/test_cli.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from contextlib import redirect_stderr, redirect_stdout
+from io import StringIO
+import json
+from pathlib import Path
+import tempfile
+import unittest
+
+from dossierdock.cli import main
+from dossierdock.doctor import run_doctor
+
+
+class CliTests(unittest.TestCase):
+    def _call(self, arguments: list[str]) -> tuple[int, str, str]:
+        output, errors = StringIO(), StringIO()
+        with redirect_stdout(output), redirect_stderr(errors):
+            code = main(arguments)
+        return code, output.getvalue(), errors.getvalue()
+
+    def test_init_creates_manifest_without_overwriting(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            code, output, _ = self._call(["init", "--path", str(root)])
+            self.assertEqual(code, 0)
+            self.assertIn("Created", output)
+            self.assertTrue((root / "dossierdock.toml").is_file())
+
+            code, _, errors = self._call(["init", "--path", str(root)])
+            self.assertEqual(code, 2)
+            self.assertIn("Refusing to overwrite", errors)
+
+    def test_doctor_and_plan_accept_valid_container_inputs(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            self._call(["init", "--path", str(root)])
+            (root / "Dockerfile").write_text("FROM python:3.11-slim\n", encoding="utf-8")
+            report = run_doctor(root / "dossierdock.toml")
+            self.assertTrue(report.healthy)
+
+            code, output, _ = self._call(["plan", "--config", str(root / "dossierdock.toml")])
+            self.assertEqual(code, 0)
+            self.assertIn("docker build", output)
+            self.assertIn("http://localhost:8000/health", output)
+
+    def test_workflow_generation_is_explicit_and_repeat_safe(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            destination = Path(temporary) / ".github" / "workflows" / "dossierdock.yml"
+            code, _, _ = self._call(["workflow", "github", "--output", str(destination)])
+            self.assertEqual(code, 0)
+            content = destination.read_text(encoding="utf-8")
+            self.assertIn("docker build", content)
+            self.assertIn("dossierdock doctor", content)
+
+            code, _, errors = self._call(["workflow", "github", "--output", str(destination)])
+            self.assertEqual(code, 2)
+            self.assertIn("Refusing to overwrite", errors)
+
+    def test_dossier_captures_release_evidence_without_secret_values(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            self._call(["init", "--path", str(root)])
+            (root / "Dockerfile").write_text(
+                "FROM python:3.12-slim\nUSER 10001\nHEALTHCHECK CMD python -c \"print('ok')\"\n",
+                encoding="utf-8",
+            )
+            (root / ".dockerignore").write_text(".env\n", encoding="utf-8")
+            (root / "app.py").write_text('@app.get("/health")\ndef health(): pass\n', encoding="utf-8")
+            destination = root / "evidence.json"
+
+            code, output, _ = self._call(
+                ["dossier", "--config", str(root / "dossierdock.toml"), "--output", str(destination)]
+            )
+
+            self.assertEqual(code, 0)
+            self.assertIn("Created release dossier", output)
+            dossier = json.loads(destination.read_text(encoding="utf-8"))
+            self.assertEqual(dossier["release_readiness"], "ready")
+            self.assertEqual(dossier["ai_service_contract"]["service_kind"], "ai-api")
+            self.assertNotIn("do-not-copy-this", json.dumps(dossier))
+
+    def test_unignored_env_file_blocks_release(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            self._call(["init", "--path", str(root)])
+            (root / "Dockerfile").write_text("FROM python:3.12-slim\n", encoding="utf-8")
+            (root / ".env").write_text("SERVICE_TOKEN=do-not-copy-this\n", encoding="utf-8")
+            report = run_doctor(root / "dossierdock.toml")
+            self.assertFalse(report.healthy)
+            exposure = next(check for check in report.checks if check.name == "secret_exposure")
+            self.assertEqual(exposure.status, "error")
+            self.assertNotIn("do-not-copy-this", exposure.message)

dossierdock-0.1.0/tests/test_config.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from pathlib import Path
+import tempfile
+import unittest
+
+from dossierdock.config import ConfigError, load_config
+
+
+VALID_MANIFEST = """[app]
+name = "analytics-api"
+dockerfile = "Dockerfile"
+context = "."
+image = "analytics-api"
+healthcheck = "/health"
+port = 8000
+
+[deployment]
+target = "local"
+environment = "test"
+"""
+
+
+class ConfigTests(unittest.TestCase):
+    def _manifest(self, text: str) -> Path:
+        temporary = tempfile.TemporaryDirectory()
+        self.addCleanup(temporary.cleanup)
+        path = Path(temporary.name) / "dossierdock.toml"
+        path.write_text(text, encoding="utf-8")
+        return path
+
+    def test_loads_valid_manifest(self) -> None:
+        config = load_config(self._manifest(VALID_MANIFEST))
+        self.assertEqual(config.name, "analytics-api")
+        self.assertEqual(config.port, 8000)
+        self.assertEqual(config.healthcheck, "/health")
+
+    def test_rejects_healthcheck_without_leading_slash(self) -> None:
+        manifest = self._manifest(VALID_MANIFEST.replace('healthcheck = "/health"', 'healthcheck = "health"'))
+        with self.assertRaisesRegex(ConfigError, "must start"):
+            load_config(manifest)
+
+    def test_rejects_invalid_port(self) -> None:
+        manifest = self._manifest(VALID_MANIFEST.replace("port = 8000", "port = 0"))
+        with self.assertRaisesRegex(ConfigError, "between 1 and 65535"):
+            load_config(manifest)