chore: align repo hygiene and docs (#2)

Author: iamh2o

.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+ push:
+ branches: ['*']
+ pull_request:
+ branches: [main]
+
+env:
+ PYTHON_VERSION: '3.11'
+
+jobs:
+ lint:
+ name: Code Quality (Ruff)
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: ${{ env.PYTHON_VERSION }}
+
+ - name: Install Ruff
+ run: pip install ruff
+
+ - name: Run Ruff check
+ run: ruff check dewey_service tests
+
+ - name: Run Ruff format check
+ run: ruff format --check dewey_service tests
+
+ security:
+ name: Security Scanning (Bandit)
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: ${{ env.PYTHON_VERSION }}
+
+ - name: Install Bandit
+ run: pip install "bandit[toml]"
+
+ - name: Run Bandit security scan
+ run: bandit -c pyproject.toml -r dewey_service
+
+ test:
+ name: Tests and Build
+ runs-on: ubuntu-latest
+ needs: [lint, security]
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: ${{ env.PYTHON_VERSION }}
+ cache: pip
+
+ - name: Install dependencies
+ run: |
+ python -m pip install --upgrade pip
+ pip install -e ".[dev]"
+
+ - name: Run tests
+ run: pytest
+
+ - name: Build package
+ run: python -m build

.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+repos:
+ - repo: https://github.com/astral-sh/ruff-pre-commit
+ rev: v0.15.1
+ hooks:
+ - id: ruff
+ args: [--fix, --exit-non-zero-on-fix]
+ - id: ruff-format
+
+ - repo: https://github.com/PyCQA/bandit
+ rev: 1.9.4
+ hooks:
+ - id: bandit
+ args: ["-c", "pyproject.toml"]
+ additional_dependencies: ["bandit[toml]"]
+
+ - repo: https://github.com/pre-commit/pre-commit-hooks
+ rev: v5.0.0
+ hooks:
+ - id: trailing-whitespace
+ - id: end-of-file-fixer
+ - id: check-yaml
+ - id: check-added-large-files
+ args: ["--maxkb=500"]
+ - id: check-merge-conflict
+ - id: detect-private-key

README.md

@@ -1,47 +1,43 @@
 # Dewey
 
-Dewey is the canonical artifact registry and artifact-resolution platform service for LSMC.
+Dewey is the canonical artifact registry and artifact-resolution service in this workspace.
 
-## Authority Scope
+It owns:
 
-Dewey is authoritative for:
+- artifact identity and metadata
+- artifact-set identity and membership
+- artifact resolution and storage metadata lookup
+- share-reference issuance
+- external object links to artifacts and artifact sets
 
-- `artifact` identity and metadata
-- `artifact_set` identity and membership
-- storage metadata and artifact resolution
-- `share_reference` issuance
-- registration/import of artifacts
-- external cross-system artifact links
+It does not own:
 
-Dewey does not own Atlas release visibility or attachment policy decisions.
+- customer release visibility decisions
+- Atlas storage policy authority
+- Bloom or Ursa execution state
 
-## Quick Start
+## Runtime Shape
 
-```bash
-cd /Users/jmajor/projects/lims3/dewey
-source dewey_activate
-python -m pip install -e .[dev]
-dewey db build --target local
-dewey server start --port 8913
-```
+Primary package: `dewey_service`
 
-TapDB local dev uses port `5439` via `config/tapdb-config-dewey.yaml`.
+Primary entrypoints:
 
-## Auth
+- app factory: `dewey_service.app:create_app`
+- CLI command: `dewey`
 
-- API: `Authorization: Bearer <token>` is required for all `/api/*` routes.
-- UI: Cognito Hosted UI session auth (`/auth/login` -> `/auth/callback`).
-- Mutating API routes require `Idempotency-Key`.
+The service exposes both API routes and a small Cognito-backed operator UI.
 
-## Canonical API Routes
+## API Surface
+
+Current routes:
 
-- `POST /api/v1/artifacts`
-- `POST /api/v1/artifacts/import`
 - `GET /api/v1/artifacts`
 - `GET /api/v1/artifacts/{artifact_euid}`
-- `POST /api/v1/artifact-sets`
+- `POST /api/v1/artifacts`
+- `POST /api/v1/artifacts/import`
 - `GET /api/v1/artifact-sets`
 - `GET /api/v1/artifact-sets/{artifact_set_euid}`
+- `POST /api/v1/artifact-sets`
 - `POST /api/v1/artifact-sets/{artifact_set_euid}/members`
 - `DELETE /api/v1/artifact-sets/{artifact_set_euid}/members/{artifact_euid}`
 - `POST /api/v1/resolve/artifact`
@@ -51,16 +47,45 @@ TapDB local dev uses port `5439` via `config/tapdb-config-dewey.yaml`.
 - `POST /api/v1/external-object-relations`
 - `GET /api/v1/{target_type}/{target_euid}/external-object-relations`
 
-## CLI Groups
+UI/auth routes:
+
+- `/login`
+- `/auth/login`
+- `/auth/callback`
+- `/ui`
+- `POST /logout`
+
+## Auth
+
+- API routes require `Authorization: Bearer <token>`
+- mutating API routes require `Idempotency-Key`
+- operator UI uses Cognito Hosted UI session auth
+
+## CLI Surface
+
+Primary groups:
+
+- `dewey server`: start the API/UI server
+- `dewey db`: build, seed, reset Dewey on top of TapDB
+- `dewey tapdb`: pass through TapDB commands in Dewey runtime context
+- `dewey cognito`: Cognito/daycog helper commands
+- `dewey test`, `dewey quality`, `dewey config`, `dewey env`
+
+## Quick Start
 
 ```bash
-dewey info
-dewey server start --help
-dewey db --help
-dewey tapdb --help
-dewey cognito --help
-dewey test --help
-dewey quality --help
-dewey config --help
-dewey env --help
+source dewey_activate
+pip install -e .[dev]
+dewey db build --target local
+dewey server start --port 8913 --no-ssl
 ```
+
+For production-like local HTTPS, place certs at `certs/localhost.pem` and `certs/localhost-key.pem` and omit `--no-ssl`.
+
+## Current Docs
+
+- [Docs index](docs/README.md)
+
+Historical cutover planning lives in `docs/` as background only.
+
+<!-- release-sweep: 2026-03-10 -->

dewey_service/app.py

@@ -205,7 +205,9 @@ async def logout(request: Request) -> RedirectResponse:
  return RedirectResponse(url=logout_url, status_code=status.HTTP_303_SEE_OTHER)
 
  @app.get("/ui", include_in_schema=False)
- async def ui_home(request: Request, profile: dict[str, Any] = Depends(require_ui_session)) -> HTMLResponse:
+ async def ui_home(
+ request: Request, profile: dict[str, Any] = Depends(require_ui_session)
+ ) -> HTMLResponse:
  artifacts = service.list_artifacts(limit=100)
  artifact_sets = service.list_artifact_sets(limit=100)
  return templates.TemplateResponse(

dewey_service/cli.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import os
+import shutil
 import subprocess
 import sys
 from pathlib import Path
@@ -65,7 +66,7 @@ def info() -> None:
 
 @server_app.command("start")
 def server_start(
- host: str = typer.Option("0.0.0.0", "--host", help="Host to bind"),
+ host: str = typer.Option("127.0.0.1", "--host", help="Host to bind"),
  port: int = typer.Option(8913, "--port", "-p", help="Port to bind"),
  reload: bool = typer.Option(False, "--reload/--no-reload", help="Enable autoreload"),
  ssl: bool = typer.Option(True, "--ssl/--no-ssl", help="Serve over HTTPS"),
@@ -96,7 +97,9 @@ def db_build(
  cluster: str = typer.Option("", "--cluster", help="Aurora cluster ID for aurora target"),
  profile: str = typer.Option(DEFAULT_AWS_PROFILE, "--profile", help="AWS profile"),
  region: str = typer.Option(DEFAULT_AWS_REGION, "--region", help="AWS region"),
- namespace: str = typer.Option(DEFAULT_TAPDB_DATABASE_NAME, "--namespace", help="TapDB namespace"),
+ namespace: str = typer.Option(
+ DEFAULT_TAPDB_DATABASE_NAME, "--namespace", help="TapDB namespace"
+ ),
 ) -> None:
  """Bootstrap TapDB runtime and apply Dewey overlay."""
  ensure_tapdb_version()
@@ -115,7 +118,15 @@ def db_build(
  if not cluster.strip():
  raise TapDBRuntimeError("--cluster is required for aurora target")
  result = run_tapdb_cli(
- ["bootstrap", "aurora", "--cluster", cluster.strip(), "--region", region, "--no-gui"],
+ [
+ "bootstrap",
+ "aurora",
+ "--cluster",
+ cluster.strip(),
+ "--region",
+ region,
+ "--no-gui",
+ ],
  target=target,
  client_id=DEFAULT_TAPDB_CLIENT_ID,
  profile=profile,
@@ -135,7 +146,9 @@ def db_build(
  console.print(f"[green]DATABASE_URL[/green] resolved: [dim]{db_url}[/dim]")
 
  # Overlay step: bootstrap Dewey templates through app service.
- subprocess.run([sys.executable, "-m", "dewey_service.db_seed"], cwd=PROJECT_ROOT, check=True)
+ subprocess.run(
+ [sys.executable, "-m", "dewey_service.db_seed"], cwd=PROJECT_ROOT, check=True
+ )
  console.print("[green]Dewey TapDB overlay complete[/green]")
  except (TapDBRuntimeError, subprocess.CalledProcessError) as exc:
  console.print(f"[red]DB build failed:[/red] {exc}")
@@ -146,7 +159,9 @@ def db_build(
 def db_seed() -> None:
  """Apply Dewey TapDB template overlay only."""
  try:
- subprocess.run([sys.executable, "-m", "dewey_service.db_seed"], cwd=PROJECT_ROOT, check=True)
+ subprocess.run(
+ [sys.executable, "-m", "dewey_service.db_seed"], cwd=PROJECT_ROOT, check=True
+ )
  except subprocess.CalledProcessError as exc:
  raise typer.Exit(exc.returncode) from exc
 
@@ -157,7 +172,9 @@ def db_reset(
  target: str = typer.Option("local", "--target", help="TapDB target: local|aurora"),
  profile: str = typer.Option(DEFAULT_AWS_PROFILE, "--profile", help="AWS profile"),
  region: str = typer.Option(DEFAULT_AWS_REGION, "--region", help="AWS region"),
- namespace: str = typer.Option(DEFAULT_TAPDB_DATABASE_NAME, "--namespace", help="TapDB namespace"),
+ namespace: str = typer.Option(
+ DEFAULT_TAPDB_DATABASE_NAME, "--namespace", help="TapDB namespace"
+ ),
 ) -> None:
  """Delete and rebuild TapDB target then apply Dewey overlay."""
  if not force and not typer.confirm("This will delete the current TapDB DB target. Continue?"):
@@ -188,7 +205,9 @@ def tapdb_run(
  target: str = typer.Option("local", "--target", help="TapDB target: local|aurora"),
  profile: str = typer.Option(DEFAULT_AWS_PROFILE, "--profile", help="AWS profile"),
  region: str = typer.Option(DEFAULT_AWS_REGION, "--region", help="AWS region"),
- namespace: str = typer.Option(DEFAULT_TAPDB_DATABASE_NAME, "--namespace", help="TapDB namespace"),
+ namespace: str = typer.Option(
+ DEFAULT_TAPDB_DATABASE_NAME, "--namespace", help="TapDB namespace"
+ ),
 ) -> None:
  """Run raw tapdb CLI arguments through Dewey runtime context."""
  if not ctx.args:
@@ -218,9 +237,13 @@ def tapdb_run(
 @cognito_app.command("status")
 def cognito_status() -> None:
  """Show daycog status for Dewey runtime."""
+ daycog_path = shutil.which("daycog")
+ if not daycog_path:
+ console.print("[red]daycog not found in PATH[/red]")
+ raise typer.Exit(1)
  try:
  proc = subprocess.run(
- ["daycog", "status"],
+ [daycog_path, "status"],
  capture_output=True,
  text=True,
  check=False,
@@ -242,7 +265,7 @@ def test_run(
  pytest_args: list[str] = typer.Argument(
  None,
  help="Optional pytest arguments, e.g. tests/test_app_boot.py -q",
- )
+ ),
 ) -> None:
  """Run Dewey tests."""
  args = list(pytest_args or ["-q"])
@@ -257,12 +280,16 @@ def test_run(
 @quality_app.command("lint")
 def quality_lint() -> None:
  """Run Ruff lint checks."""
- proc = subprocess.run([sys.executable, "-m", "ruff", "check", "."], cwd=PROJECT_ROOT, check=False)
+ proc = subprocess.run(
+ [sys.executable, "-m", "ruff", "check", "."], cwd=PROJECT_ROOT, check=False
+ )
  raise typer.Exit(proc.returncode)
 
 
 @quality_app.command("format")
-def quality_format(check: bool = typer.Option(True, "--check/--fix", help="Check or apply formatting")) -> None:
+def quality_format(
+ check: bool = typer.Option(True, "--check/--fix", help="Check or apply formatting"),
+) -> None:
  """Run Ruff formatter."""
  cmd = [sys.executable, "-m", "ruff", "format", "."]
  if check:
@@ -274,7 +301,9 @@ def quality_format(check: bool = typer.Option(True, "--check/--fix", help="Check
 @quality_app.command("check")
 def quality_check() -> None:
  """Run lint then tests."""
- lint = subprocess.run([sys.executable, "-m", "ruff", "check", "."], cwd=PROJECT_ROOT, check=False)
+ lint = subprocess.run(
+ [sys.executable, "-m", "ruff", "check", "."], cwd=PROJECT_ROOT, check=False
+ )
  if lint.returncode != 0:
  raise typer.Exit(lint.returncode)
  tests = subprocess.run([sys.executable, "-m", "pytest", "-q"], cwd=PROJECT_ROOT, check=False)
@@ -285,8 +314,12 @@ def quality_check() -> None:
 def config_path() -> None:
  """Print resolved Dewey config paths."""
  settings = get_settings()
- console.print(f"DEWEY config path: [cyan]{os.environ.get('XDG_CONFIG_HOME', '~/.config')}/dewey/config.yaml[/cyan]")
- console.print(f"TAPDB config path: [cyan]{settings.tapdb_config_path or os.environ.get('TAPDB_CONFIG_PATH', '')}[/cyan]")
+ console.print(
+ f"DEWEY config path: [cyan]{os.environ.get('XDG_CONFIG_HOME', '~/.config')}/dewey/config.yaml[/cyan]"
+ )
+ console.print(
+ f"TAPDB config path: [cyan]{settings.tapdb_config_path or os.environ.get('TAPDB_CONFIG_PATH', '')}[/cyan]"
+ )
 
 
 @config_app.command("show")