@mriekki/project-forge 0.0.0-stage → 2.0.0

package/assets/generated/deployment/docs/images/personal-environment-architecture.svg

@@ -0,0 +1,54 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="700" viewBox="0 0 1200 700" role="img" aria-labelledby="title desc">
+  <title id="title">Personal Project Forge environment architecture</title>
+  <desc id="desc">A developer has a private portable profile, separate workstation-local keys and trust on each computer, and remote targets reached over SSH without storing developer GitHub credentials on the target.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0b1220"/>
+      <stop offset="1" stop-color="#172033"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="8" stdDeviation="9" flood-opacity="0.3"/>
+    </filter>
+    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto">
+      <path d="M0,0 L10,5 L0,10 Z" fill="#8ea0bd"/>
+    </marker>
+  </defs>
+  <rect width="1200" height="700" rx="24" fill="url(#bg)"/>
+  <text x="70" y="70" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="30" font-weight="700" fill="#f7f9fc">Personal Environment Architecture</text>
+  <text x="70" y="102" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="17" fill="#aebbd0">Portable definitions sync. Private machine identity stays on each computer.</text>
+
+  <g filter="url(#shadow)" font-family="Inter,Segoe UI,Arial,sans-serif">
+    <rect x="365" y="135" width="470" height="130" rx="20" fill="#25294a" stroke="#7277c9" stroke-width="2"/>
+    <text x="600" y="176" text-anchor="middle" font-size="15" font-weight="700" fill="#aaaef1">PRIVATE PERSONAL PROFILE</text>
+    <text x="600" y="208" text-anchor="middle" font-size="23" font-weight="700" fill="#ffffff">Portable target definitions</text>
+    <text x="600" y="238" text-anchor="middle" font-size="15" fill="#c6c8ea">host • user • port • stable alias • safe preferences</text>
+
+    <rect x="110" y="340" width="390" height="190" rx="20" fill="#1c3342" stroke="#3b7f9b" stroke-width="2"/>
+    <text x="305" y="381" text-anchor="middle" font-size="15" font-weight="700" fill="#8ed2eb">WORKSTATION A</text>
+    <text x="305" y="415" text-anchor="middle" font-size="24" font-weight="700" fill="#ffffff">Windows / Mac</text>
+    <text x="305" y="452" text-anchor="middle" font-size="15" fill="#bddce8">own SSH private key + trust</text>
+    <text x="305" y="478" text-anchor="middle" font-size="15" fill="#bddce8">Docker + local runtime/data</text>
+    <text x="305" y="504" text-anchor="middle" font-size="15" fill="#bddce8">local credential prompts/cache</text>
+
+    <rect x="700" y="340" width="390" height="190" rx="20" fill="#1c3342" stroke="#3b7f9b" stroke-width="2"/>
+    <text x="895" y="381" text-anchor="middle" font-size="15" font-weight="700" fill="#8ed2eb">WORKSTATION B</text>
+    <text x="895" y="415" text-anchor="middle" font-size="24" font-weight="700" fill="#ffffff">second computer</text>
+    <text x="895" y="452" text-anchor="middle" font-size="15" fill="#bddce8">different SSH private key + trust</text>
+    <text x="895" y="478" text-anchor="middle" font-size="15" fill="#bddce8">Docker + local runtime/data</text>
+    <text x="895" y="504" text-anchor="middle" font-size="15" fill="#bddce8">same portable definitions</text>
+
+    <rect x="365" y="585" width="470" height="82" rx="18" fill="#213825" stroke="#4a9a58" stroke-width="2"/>
+    <text x="600" y="620" text-anchor="middle" font-size="15" font-weight="700" fill="#8fda9d">REMOTE TARGETS</text>
+    <text x="600" y="648" text-anchor="middle" font-size="18" fill="#ffffff">Docker runtime + Project Forge platform • no developer PAT required</text>
+  </g>
+
+  <g stroke="#8ea0bd" stroke-width="3" fill="none" marker-end="url(#arrow)">
+    <path d="M505 265 C460 300 390 310 330 332"/>
+    <path d="M695 265 C740 300 810 310 870 332"/>
+    <path d="M305 530 C350 570 430 588 505 600"/>
+    <path d="M895 530 C850 570 770 588 695 600"/>
+  </g>
+
+  <text x="84" y="578" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="14" fill="#8ea0bd">Verified SSH</text>
+  <text x="1018" y="578" text-anchor="end" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="14" fill="#8ea0bd">Verified SSH</text>
+</svg>

package/assets/generated/deployment/docs/images/poc-environment-model.svg

@@ -0,0 +1,61 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="720" viewBox="0 0 1200 720" role="img" aria-labelledby="title desc">
+  <title id="title">Project Forge environment model</title>
+  <desc id="desc">A POC uses local workstation runtime and optional remote logical staging and production environments bound to reusable remote targets and shared host platform infrastructure.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0b1220"/>
+      <stop offset="1" stop-color="#172033"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="8" stdDeviation="9" flood-opacity="0.3"/>
+    </filter>
+    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto">
+      <path d="M0,0 L10,5 L0,10 Z" fill="#8ea0bd"/>
+    </marker>
+  </defs>
+  <rect width="1200" height="720" rx="24" fill="url(#bg)"/>
+  <text x="70" y="70" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="30" font-weight="700" fill="#f7f9fc">POC Environment Model</text>
+  <text x="70" y="102" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="17" fill="#aebbd0">The POC owns application/environment facts; reusable workstation and target layers own machine mechanics.</text>
+
+  <g filter="url(#shadow)" font-family="Inter,Segoe UI,Arial,sans-serif">
+    <rect x="390" y="135" width="420" height="106" rx="20" fill="#25294a" stroke="#7277c9" stroke-width="2"/>
+    <text x="600" y="176" text-anchor="middle" font-size="15" font-weight="700" fill="#aaaef1">GENERATED POC</text>
+    <text x="600" y="209" text-anchor="middle" font-size="21" font-weight="700" fill="#ffffff">Environment bindings + app runtime facts</text>
+
+    <rect x="95" y="330" width="300" height="190" rx="20" fill="#173c35" stroke="#3a9d82" stroke-width="2"/>
+    <text x="245" y="370" text-anchor="middle" font-size="15" font-weight="700" fill="#79d9bc">LOCAL</text>
+    <text x="245" y="405" text-anchor="middle" font-size="23" font-weight="700" fill="#ffffff">Developer workstation</text>
+    <text x="245" y="442" text-anchor="middle" font-size="15" fill="#b7ded3">Docker app container</text>
+    <text x="245" y="468" text-anchor="middle" font-size="15" fill="#b7ded3">local SQLite / app data</text>
+    <text x="245" y="494" text-anchor="middle" font-size="15" fill="#b7ded3">loopback exposure</text>
+
+    <rect x="450" y="310" width="650" height="300" rx="22" fill="#20293a" stroke="#50627d" stroke-width="2"/>
+    <text x="775" y="350" text-anchor="middle" font-size="15" font-weight="700" fill="#9baac2">REMOTE TARGET LAYER</text>
+
+    <rect x="500" y="385" width="245" height="150" rx="18" fill="#3d3219" stroke="#b58b2e" stroke-width="2"/>
+    <text x="622" y="423" text-anchor="middle" font-size="15" font-weight="700" fill="#e5bf65">STAGING</text>
+    <text x="622" y="455" text-anchor="middle" font-size="21" font-weight="700" fill="#ffffff">Docker app</text>
+    <text x="622" y="484" text-anchor="middle" font-size="14" fill="#ddc98e">own runtime + data</text>
+    <text x="622" y="509" text-anchor="middle" font-size="14" fill="#ddc98e">logical target binding</text>
+
+    <rect x="805" y="385" width="245" height="150" rx="18" fill="#3b2228" stroke="#b55a6f" stroke-width="2"/>
+    <text x="928" y="423" text-anchor="middle" font-size="15" font-weight="700" fill="#ed8ca2">PRODUCTION</text>
+    <text x="928" y="455" text-anchor="middle" font-size="21" font-weight="700" fill="#ffffff">Docker app</text>
+    <text x="928" y="484" text-anchor="middle" font-size="14" fill="#ddb2bc">own runtime + data</text>
+    <text x="928" y="509" text-anchor="middle" font-size="14" fill="#ddb2bc">separate authorization</text>
+
+    <rect x="545" y="558" width="460" height="80" rx="16" fill="#273246" stroke="#5b6d89" stroke-width="2"/>
+    <text x="775" y="590" text-anchor="middle" font-size="15" font-weight="700" fill="#a9b6cc">REUSABLE SHARED HOST PLATFORM</text>
+    <text x="775" y="616" text-anchor="middle" font-size="14" fill="#c3ccda">Docker engine • Caddy • shared network • target access mechanics</text>
+  </g>
+
+  <g stroke="#8ea0bd" stroke-width="3" fill="none" marker-end="url(#arrow)">
+    <path d="M500 241 C420 275 330 292 275 320"/>
+    <path d="M600 241 C620 285 620 320 622 375"/>
+    <path d="M700 241 C850 280 915 315 928 375"/>
+    <path d="M622 535 V548"/>
+    <path d="M928 535 V548"/>
+  </g>
+
+  <text x="70" y="668" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="14" fill="#8ea0bd">Staging and Production may bind to separate targets or share a physical host; logical identity and Production gates remain distinct.</text>
+</svg>

package/assets/generated/deployment/src/project_forge_deployment/__init__.py

@@ -0,0 +1,3 @@
+"""Project Forge Deployment Kit."""
+
+__version__ = "0.1.0.dev0"

package/assets/generated/deployment/src/project_forge_deployment/__main__.py

@@ -0,0 +1,3 @@
+from .entrypoint import main
+
+raise SystemExit(main())

package/assets/generated/deployment/src/project_forge_deployment/app_cli.py

@@ -0,0 +1,163 @@
+"""CLI for generic immutable application runtime deployment."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from .app_runtime import (
+    APP_DEPLOY_WRITE_PHRASE,
+    PRODUCTION_APP_DEPLOY_WRITE_PHRASE,
+    app_inventory,
+    apply_app_deploy,
+    deploy_write_phrase,
+    normalize_app_spec,
+    plan_app_deploy,
+)
+from .app_runtime_workstation import apply_app_deploy_from_workstation
+from .errors import DeploymentKitError
+from .sqlite_adapter import assert_app_spec_matches_persistence
+
+
+def _print(value: Any, *, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(value, indent=2, sort_keys=True))
+        return
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if isinstance(item, (dict, list)):
+                print(f"{key}: {json.dumps(item, sort_keys=True)}")
+            else:
+                print(f"{key}: {item}")
+        return
+    print(value)
+
+
+def _parse_env(items: list[str]) -> list[tuple[str, str]]:
+    result: list[tuple[str, str]] = []
+    for item in items:
+        if "=" not in item:
+            raise DeploymentKitError("--env entries must use NAME=value form.")
+        key, value = item.split("=", 1)
+        result.append((key, value))
+    return result
+
+
+def _confirm(args: argparse.Namespace, phrase: str, action: str) -> None:
+    if args.yes:
+        return
+    entered = input(f"Type {phrase} to {action}: ").strip()
+    if entered != phrase:
+        raise DeploymentKitError(f"{action.capitalize()} was not authorized.")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="project-forge-deploy app")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    inventory = sub.add_parser(
+        "inventory",
+        help="Read Kit-managed application runtime ownership/readiness without writes",
+    )
+    inventory.add_argument("name")
+    inventory.add_argument("--json", action="store_true")
+
+    deploy = sub.add_parser(
+        "deploy",
+        help="Deploy one immutable application runtime without modifying routes",
+    )
+    deploy.add_argument("name")
+    deploy.add_argument("--owner-repo", required=True)
+    deploy.add_argument("--environment", required=True)
+    deploy.add_argument(
+        "--production",
+        action="store_true",
+        help="Classify this named environment as Production even when its name is not literally 'production'",
+    )
+    deploy.add_argument("--app-slug", required=True)
+    deploy.add_argument("--container-name", required=True)
+    deploy.add_argument("--image", required=True)
+    deploy.add_argument("--runtime-port", type=int, required=True)
+    deploy.add_argument("--health-path", required=True)
+    deploy.add_argument("--run-as", required=True)
+    deploy.add_argument(
+        "--persistence-mode",
+        choices=("none", "directory"),
+        required=True,
+    )
+    deploy.add_argument("--data-container-path")
+    deploy.add_argument(
+        "--env",
+        action="append",
+        default=[],
+        help="Non-secret runtime environment value in NAME=value form; repeat as needed",
+    )
+    deploy.add_argument(
+        "--image-source",
+        choices=("remote-registry", "workstation"),
+        default="remote-registry",
+        help=(
+            "remote-registry preserves the existing target-side pull path; workstation streams an exact local image "
+            "over verified SSH so the target does not need registry credentials"
+        ),
+    )
+    deploy.add_argument("--json", action="store_true")
+    deploy.add_argument("--yes", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "inventory":
+            _print(app_inventory(args.name), as_json=args.json)
+            return 0
+
+        spec = normalize_app_spec(
+            owner_repo=args.owner_repo,
+            environment=args.environment,
+            app_slug=args.app_slug,
+            container_name=args.container_name,
+            image=args.image,
+            runtime_port=args.runtime_port,
+            health_path=args.health_path,
+            run_as=args.run_as,
+            persistence_mode=args.persistence_mode,
+            data_container_path=args.data_container_path,
+            environment_variables=_parse_env(args.env),
+        )
+        assert_app_spec_matches_persistence(args.name, spec)
+        plan = plan_app_deploy(args.name, spec)
+        plan_view = {key: value for key, value in plan.items() if key != "spec"}
+        plan_view["imageSource"] = args.image_source
+        production_classified = args.production or plan["environment"] == "production"
+        plan_view["productionClassified"] = production_classified
+        if args.image_source == "workstation":
+            plan_view["targetRegistryCredentialRequired"] = False
+        _print(plan_view, as_json=False)
+        phrase = PRODUCTION_APP_DEPLOY_WRITE_PHRASE if production_classified else deploy_write_phrase(plan)
+        _confirm(
+            args,
+            phrase,
+            f"deploy {plan['appSlug']} ({plan['environment']}) on target {args.name}",
+        )
+        result = (
+            apply_app_deploy_from_workstation(plan)
+            if args.image_source == "workstation"
+            else apply_app_deploy(plan)
+        )
+        _print(result, as_json=args.json)
+        return 0
+    except DeploymentKitError as error:
+        print(f"ERROR: {error}", file=sys.stderr)
+        return 2
+
+
+__all__ = [
+    "APP_DEPLOY_WRITE_PHRASE",
+    "PRODUCTION_APP_DEPLOY_WRITE_PHRASE",
+    "build_parser",
+    "main",
+]