@mriekki/project-forge 0.0.0-stage → 2.0.0

package/assets/generated/deployment/docs/DEVELOPER_ENVIRONMENTS.md

@@ -0,0 +1,335 @@
+# Developer Environments
+
+Status: **CORE WORKSTATION/TARGET MECHANICS IMPLEMENTED; AUTOMATED HOST PACKAGE PREPARATION REMAINS INCREMENTAL**
+
+This document is the canonical developer-environment model for Project Forges. It describes the developer-facing progression from a generated repository to local development, optional Staging/Production capability, additional workstations, and additional remote boxes.
+
+The happy path intentionally hides Bootstrap/package/control-plane plumbing. Developers should see meaningful milestones and actionable setup, while the underlying repositories retain exact provenance and safety evidence.
+
+## Developer journey
+
+![Developer environment journey](images/developer-environment-journey.svg)
+
+The normal progression is:
+
+```text
+generated POC repository
+→ clone/open workspace
+→ /setup
+→ LOCAL READY
+→ optional remote onboarding
+→ STAGING READY
+→ optional Production onboarding
+→ PRODUCTION READY
+```
+
+Local readiness is a valid complete developer state. Staging and Production are progressive capabilities, not prerequisites for coding.
+
+## One setup front door
+
+The generated repository provides deterministic OS launchers:
+
+```text
+Windows  .\scripts\setup.ps1
+macOS    ./scripts/setup.sh
+```
+
+The normal conversational entry point is:
+
+```text
+/setup
+```
+
+`/setup` explains the current state/options and invokes the correct repository-local setup launcher. Direct script invocation remains the non-AI/automation fallback.
+
+The first local success target is `LOCAL WORKSPACE READY`. Remote access must not block it unless the POC explicitly requires a remote dependency for local development.
+
+## Progress and next action
+
+Use `/progress` to answer what is complete, what is blocked/deferred, who owns the next action, and local/Staging/Production capability state.
+
+Use `/next-step` for one recommended next action.
+
+Progress uses milestone states rather than percentages. Internal Bootstrap/package/generator phases are not developer milestones unless an internal failure becomes the actionable blocker.
+
+## Personal environment architecture
+
+![Personal environment architecture](images/personal-environment-architecture.svg)
+
+Each developer owns an independent portable profile. Two developers may describe the same physical target, but neither depends on the other's profile or workstation credentials.
+
+### Private personal Project Forge profile
+
+The standard personal repository is:
+
+```text
+<authenticated-github-user>/project-forge-profile
+```
+
+It must be private. The canonical portable file is:
+
+```text
+project-forge-profile.json
+```
+
+It contains only sanitized target definitions:
+
+- logical target name;
+- target OS profile;
+- stable DNS/mDNS hostname;
+- SSH user and port;
+- stable SSH host alias/identity name.
+
+It does **not** contain SSH private keys, passwords/passphrases, PATs/tokens, `known_hosts` contents, machine-specific credential paths, temporary IP overrides, local runtime/data, or readiness claims.
+
+Direct deterministic commands are available beneath `/setup`:
+
+```text
+project-forge-deploy environment profile status
+project-forge-deploy environment profile ensure
+project-forge-deploy environment profile sync --apply
+project-forge-deploy environment profile publish
+```
+
+`profile ensure` creates/initializes only the authenticated developer's exact private `project-forge-profile` repository and requires:
+
+```text
+[PERSONAL PROFILE WRITE]
+```
+
+An empty profile with `targets: []` is valid. A local-only developer never needs a remote target merely to have a portable workstation profile.
+
+`profile sync` fetches and validates the GitHub profile, updates the validated local cache, and with `--apply` creates only missing non-conflicting local target definitions. Existing differing local definitions are never overwritten.
+
+`profile publish` merges new non-conflicting local target definitions into the private profile and fails on conflicts rather than silently replacing remote definitions.
+
+### Workstation-local state
+
+Each workstation owns its own:
+
+- SSH private key/identity;
+- host trust;
+- credential-manager entries when explicitly chosen;
+- validated profile cache/last-known-good snapshot;
+- local Docker/runtime state;
+- repository-scoped developer-mode evidence.
+
+Private SSH keys are never synchronized between computers. A Mark Windows key, Mark Mac key, Kyle Mac key, and Daniel Windows key are distinct identities even when they can reach the same remote server.
+
+## Home Lab remote onboarding
+
+The implemented Home Lab path is password-assisted bootstrap followed by normal strict key-only operation.
+
+Preview:
+
+```text
+project-forge-deploy environment home-lab plan <target> \
+  --host-name <stable-hostname> \
+  --user <ssh-user>
+```
+
+Bootstrap:
+
+```text
+project-forge-deploy environment home-lab bootstrap <target> \
+  --host-name <stable-hostname> \
+  --user <ssh-user>
+```
+
+The password prompt is owned by local OpenSSH. The password is never pasted into chat, passed as a command argument, or persisted by Project Forge.
+
+The flow is:
+
+```text
+create/reuse target definition
+→ create/reuse this workstation's key
+→ first-use host pinning in target-specific trust file when needed
+→ local OpenSSH password prompt
+→ append public key idempotently to authorized_keys
+→ strict key-only verification
+→ TARGET ACCESS READY
+```
+
+The default Home Lab key is unencrypted for convenience. `--protect-key-with-passphrase` delegates a key passphrase prompt to `ssh-keygen`; protected keys must be available to the SSH agent for later non-interactive verification.
+
+A changed previously pinned host key remains a blocker and requires explicit trust rotation. Existing stricter console-verified trust is preserved during migration rather than weakened.
+
+## Docker and host preparation
+
+Docker is a workstation/target capability, not something every POC should reinstall.
+
+### Developer workstation
+
+The first POC on a computer may install/verify required local tools and Docker through the generated setup contract. Later POCs reuse the ready workstation.
+
+### Remote Ubuntu target
+
+Target access can now be established from the local workstation, but full automatic Ubuntu package preparation is still an incremental capability. The desired host progression remains:
+
+```text
+Ubuntu/sudo verification
+→ Docker Engine/Compose if missing
+→ required Project Forge host prerequisites
+→ Project Forge shared host platform
+→ platform doctor
+→ TARGET READY
+```
+
+The current platform doctor/install contract still requires host prerequisites to exist before shared-platform installation. Until a reviewed host-package bootstrap is added, `/setup remote` must report missing host packages as an actionable preparation gap rather than pretending they were installed.
+
+Healthy existing Docker/Project Forge installations are adopted/verified, not recreated. Ambiguous/incompatible existing state fails closed rather than being overwritten.
+
+## GitHub/GHCR credentials stay local
+
+A developer should not need to SSH to Staging/Production and enter a GitHub PAT.
+
+The implemented workstation-mediated artifact path is:
+
+```text
+local GitHub/GHCR authentication when needed
+→ acquire/build exact immutable image locally
+→ verify exact identity/digest
+→ stream Docker image over verified SSH
+→ remote docker load
+→ verify exact image remotely
+→ deploy/health-check using the preloaded image
+```
+
+Remote Home Lab boxes therefore do not need a developer's persistent GitHub PAT for the normal workstation-mediated deployment path.
+
+Application deployment selects this with:
+
+```text
+--image-source workstation
+```
+
+The legacy `--image-source remote-registry` path remains available during migration/for explicit target-side registry use.
+
+A credential needed to acquire a private image is entered only through the local Docker/GitHub credential boundary. Never paste it into chat or put it on a command line.
+
+If the exact immutable image is already cached locally, registry authentication is not required merely to transfer it to the remote target.
+
+## POC environment model
+
+![POC environment model](images/poc-environment-model.svg)
+
+The POC owns project-specific facts such as environment identities/roles, placement, target binding, application image, runtime/health contract, persistence, routes/exposure, and Production classification/authorization.
+
+The reusable workstation/target layer owns machine mechanics. A POC references targets; it does not own or duplicate a developer's private credentials.
+
+## New workstation
+
+A developer normally starts from any generated POC:
+
+```text
+clone repository
+→ open generated VS Code workspace
+→ /setup
+```
+
+`/setup` detects whether this is a fresh or already-prepared workstation and converges only missing safe capabilities.
+
+When GitHub is reachable, personal profile sync supplies portable target definitions. The new workstation still creates its own SSH identity/trust. Remote setup is optional and can be deferred until needed.
+
+## New remote box
+
+Adding a new remote target is a workstation-driven onboarding operation, not a POC implementation step:
+
+```text
+add/import portable target definition
+→ Home Lab or Strict workstation SSH onboarding
+→ verify/prepare Docker host prerequisites
+→ verify/install Project Forge shared platform
+→ TARGET READY
+```
+
+Once ready, multiple POCs can bind logical environments to that target without repeating host bootstrap.
+
+## Portable export/import fallback
+
+Normal portability is the developer's private `project-forge-profile`. A sanitized environment bundle is also implemented for explicit sharing/offline bootstrap:
+
+```text
+project-forge-deploy environment profile export --target <name> --output project-forge-environment-bundle.json
+project-forge-deploy environment profile preview-import project-forge-environment-bundle.json
+project-forge-deploy environment profile import project-forge-environment-bundle.json
+```
+
+Export/import is copy-by-value. Importing another developer's target definition creates an independent personal copy; later changes do not silently propagate across users.
+
+A portable bundle contains only non-secret definition fields. Import never transfers readiness, private keys, passwords, trust contents, credential paths, or IP overrides and never overwrites a conflicting existing target.
+
+## Last-known-good/offline behavior
+
+Validated profile state is cached under the user-scoped Project Forge home:
+
+```text
+~/.project-forge/profile/current/project-forge-profile.json
+~/.project-forge/profile/last-known-good/project-forge-profile.json
+~/.project-forge/profile/sync-state.json
+```
+
+A valid GitHub fetch updates both current and last-known-good snapshots. An invalid/unavailable remote profile never overwrites last-known-good state.
+
+When GitHub cannot be reached, profile sync can use the validated last-known-good profile so local work and previously established target definitions remain usable. Remote operations still require independent machine-specific access/trust verification.
+
+## Migration for existing developers
+
+Existing Mark/Kyle environments should migrate fully to this model rather than remain permanently dual-mode.
+
+The migration contract is:
+
+```text
+inventory existing workstation/targets
+→ ensure private personal project-forge-profile + validated cache
+→ adopt healthy existing Docker/SSH/trust where valid
+→ establish workstation-mediated artifact delivery
+→ prove Staging end-to-end
+→ verify Production access/readiness without deploying
+→ remove/archive superseded legacy configuration only after verification
+```
+
+Migration must not reinstall healthy Docker, rotate valid SSH identities merely for consistency, redeploy unrelated applications, reset data, or weaken stricter existing trust.
+
+Server-side GHCR credentials/PATs are removed only after proving that no remaining deployment path depends on them. Existing remote application containers/data remain intact while the access/deployment mechanism changes.
+
+After migration, the new profile/workstation model is authoritative. Legacy configuration may be retained temporarily only as explicitly inactive migration backup, not as a second active source of truth.
+
+## Progressive readiness examples
+
+All of these are valid states:
+
+```text
+Local READY
+Staging NOT CONFIGURED
+Production NOT CONFIGURED
+```
+
+```text
+Local READY
+Staging READY
+Production NOT AUTHORIZED
+```
+
+```text
+Local READY
+Staging READY
+Production READY (access/readiness only)
+```
+
+Production readiness never implies Production deployment authorization.
+
+## Developer-facing commands
+
+The intended small human surface is:
+
+```text
+/setup
+/progress
+/next-step
+/developer-env-mode status|local|remote
+/deployment-readiness <environment>
+/deploy <environment>
+```
+
+The first three are the normal guided experience. `project-forge-deploy environment ...` commands are deterministic implementation/fallback surfaces and can be invoked directly when desired.

package/assets/generated/deployment/docs/ENVIRONMENT_PROOF.md

@@ -0,0 +1,95 @@
+# Environment Proof Deployment
+
+A Project Forge environment proof verifies that one developer workstation can exercise the real remote deployment path for one exact named logical environment before the POC application exists or before its first real deployment.
+
+It is intentionally **not** the project application.
+
+## What it proves
+
+For a supported remote-target environment, the proof uses the same reusable mechanics as a normal workstation-mediated application deployment:
+
+```text
+this workstation
+→ verified target/profile access
+→ ready shared host platform
+→ pull small stable probe image locally
+→ resolve exact immutable RepoDigest
+→ transfer exact image over verified SSH
+→ deploy with the managed application runtime
+→ verify HTTP health
+→ tear down the reserved probe runtime
+→ verify cleanup evidence
+```
+
+The current default probe image tag is `nginx:alpine`. The tag is never treated as the deployed identity: Project Forge pulls it locally and resolves an exact `@sha256:` RepoDigest before image transfer or remote runtime mutation.
+
+The probe uses:
+
+- no project database;
+- no project persistent data;
+- no project application secrets;
+- a reserved per-repository probe app slug;
+- the exact selected logical environment name;
+- the existing per-app/per-environment deployment lock;
+- automatic cleanup through the existing scoped tear-down machinery.
+
+## Commands
+
+Read-only plan:
+
+```text
+project-forge-deploy environment proof plan <target> \
+  --owner-repo <owner/repo> \
+  --environment <name>
+```
+
+Run the proof after authorization:
+
+```text
+project-forge-deploy environment proof run <target> \
+  --owner-repo <owner/repo> \
+  --environment <name>
+```
+
+For a named environment whose project purpose is Production, preserve that classification even when its name is custom:
+
+```text
+project-forge-deploy environment proof run <target> \
+  --owner-repo <owner/repo> \
+  --environment prod-east \
+  --production
+```
+
+Use the exact installed CLI/help rather than copying examples blindly.
+
+## Authorization
+
+Normal non-Production proof:
+
+```text
+[ENVIRONMENT PROOF WRITE]
+```
+
+Production-class proof:
+
+```text
+[PRODUCTION ENVIRONMENT PROOF]
+```
+
+A successful proof never authorizes the later real application deployment. Production proof never authorizes a Production application deployment.
+
+## Cleanup
+
+The proof attempts cleanup even when deployment raises after mutation begins.
+
+Successful completion requires terminal cleanup evidence (`removed` or already `absent`) for the reserved probe runtime. If deployment succeeds but cleanup cannot be verified, the command fails rather than reporting a clean proof.
+
+The probe must not delete another POC, another application, another logical environment, or shared host platform state.
+
+## Relationship to `/setup` and `/deploy`
+
+`/setup` may run this proof after the developer selects a named remote environment to prepare on the current workstation.
+
+A later first real `/deploy <environment>` can reuse fresh proof evidence for target access/platform/transport mechanics and ask only unresolved application-specific questions such as persistence, health, route/exposure, and immutable application artifact policy.
+
+Project-defined environment names are not limited to Staging and Production. `demo`, `qa`, `prod-east`, or another safe configured slug use the same mechanics, while Production purpose/classification keeps the stronger authorization path.

package/assets/generated/deployment/docs/WORKSPACE_INSTANCES.md

@@ -0,0 +1,154 @@
+# Workspace Instances
+
+Status: **SUPPORTED MODEL — ONE PROJECT MAY HAVE MULTIPLE INDEPENDENT WORKSTATION CHECKOUTS**
+
+A **workspace instance** is one checkout of one Project Forge on one developer workstation. A project may have multiple workspace instances active at the same time, including different operating systems for the same developer.
+
+Examples:
+
+```text
+family-meal-planner-v3
+├─ Mark Windows workspace
+└─ Mark macOS workspace
+```
+
+Neither workstation is primary. One does not need to be online for the other to work.
+
+## Shared project state
+
+Git/GitHub is the normal shared source-code coordination boundary. The repository owns project facts such as:
+
+- source code and tests;
+- exact project technology/version choices;
+- Project Forge package/baseline state;
+- work-item and architecture documentation;
+- project-owned deployment topology and environment references.
+
+Independent workstreams should normally use independent short-lived branches. Different work items may be active from different workstations at the same time.
+
+Using the same branch from more than one workstation is allowed but requires ordinary Git coordination. A workspace must treat a remote branch that advanced elsewhere as new evidence and must not resolve divergence with force/reset/history rewriting automatically.
+
+## Portable personal state
+
+The authenticated developer's private `<login>/project-forge-profile` is portable, non-secret state shared across the developer's workstations.
+
+It may carry target definitions/preferences such as logical target, hostname, SSH user/port, OS profile, and stable host alias.
+
+It must not carry:
+
+- SSH private keys or passphrases;
+- passwords/PATs/tokens;
+- `known_hosts` contents;
+- machine-specific credential paths;
+- local databases or application runtime data;
+- Docker credential state;
+- workstation readiness claims.
+
+A new workstation may sync/apply this profile and then establish its own machine-specific identity/trust.
+
+## Machine-local workspace state
+
+Each workspace instance independently owns:
+
+- OS/tool installations;
+- VS Code/editor extensions;
+- local dependency caches;
+- local Docker/runtime state;
+- local development database/data;
+- SSH private key and host trust;
+- GitHub/Docker/registry credentials;
+- repository-scoped developer-mode/readiness evidence.
+
+Local mutable application data is not synchronized between workstations by Project Forge. Projects should reproduce schema/migrations/seed behavior rather than silently copying a workstation's development database to another computer.
+
+## Setup on another workstation
+
+The normal flow for an existing generated POC is:
+
+```text
+clone repository
+→ open generated VS Code workspace
+→ /setup
+```
+
+`/setup` detects the current OS automatically and chooses the generated launcher:
+
+```text
+Windows  .\scripts\setup.ps1
+macOS    ./scripts/setup.sh
+```
+
+When repository/project evidence exists but workstation-local readiness evidence does not, the developer-facing state is:
+
+```text
+EXISTING PROJECT — NEW WORKSTATION
+```
+
+Setup should reuse the project definition and portable personal profile, install/verify only missing safe machine capabilities, restore project dependencies, and converge local readiness. Remote access remains optional until needed.
+
+OS-specific project limitations remain real. For example, a Windows workspace may edit shared Swift source but cannot claim native iOS build readiness when the selected toolchain requires macOS/Xcode.
+
+## Concurrent source work
+
+Recommended shape:
+
+```text
+Windows → feature/work-item-a
+macOS   → feature/work-item-b
+```
+
+Both workspaces can build/test/run locally at the same time using independent local runtime/data.
+
+If both use the same branch, source coordination remains Git-based:
+
+```text
+local branch SHA
+vs
+remote branch SHA
+```
+
+Before history-sensitive work/delivery, fetch/inspect current remote evidence. If another workspace advanced the branch, reconcile explicitly. Never use `git stash` as cross-workstation transport and never force-push merely to make two clones agree.
+
+## Concurrent remote environment operations
+
+A shared Staging or Production application is different from independent local development. Multiple workstations may have access to the same logical remote environment, but only one mutating application operation for the same app/environment may proceed at a time.
+
+The Deployment Kit remote application runtime already acquires a non-blocking per-application/per-environment lock. If another deployment holds the lock, a concurrent deployment exits rather than racing the same runtime. Persistence operations use the same app/environment lock boundary.
+
+Conceptually:
+
+```text
+Windows  ─┐
+          ├─> same app / staging ─> one active mutation
+macOS    ─┘                       └> second mutation blocked
+```
+
+Readiness/access on each workstation remains machine-specific because credentials/trust are machine-local. Remote environment state itself is shared.
+
+## What Project Forge does not need
+
+Multi-workstation support does **not** require:
+
+- a central device registry;
+- one primary developer computer;
+- another workstation to be online;
+- shared private keys;
+- shared mutable local databases;
+- proprietary file synchronization outside Git;
+- automatic worktree transfer between computers.
+
+A friendly machine/workspace label may be shown locally when useful, but it is descriptive only and not a project authority.
+
+## Developer-facing commands
+
+The normal surface remains small:
+
+```text
+/setup
+/progress
+/next-step
+/start-work <ID>
+/deliver
+```
+
+`/setup` prepares **this** workspace instance. `/progress` reports **this** workspace instance plus shared project/environment evidence. Normal Git/work-item and delivery rules coordinate source changes across workstations.

package/assets/generated/deployment/docs/images/developer-environment-journey.svg

@@ -0,0 +1,56 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="520" viewBox="0 0 1200 520" role="img" aria-labelledby="title desc">
+  <title id="title">Project Forge developer environment journey</title>
+  <desc id="desc">Generated POC repository progresses through clone and setup to local ready, then optionally to staging ready and production ready.</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="10" flood-opacity="0.28"/>
+    </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="520" 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">Developer Environment Journey</text>
+  <text x="70" y="102" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="17" fill="#aebbd0">Start local. Add remote capability only when the project needs it.</text>
+
+  <g filter="url(#shadow)" font-family="Inter,Segoe UI,Arial,sans-serif">
+    <rect x="70" y="180" width="205" height="128" rx="18" fill="#1e2a40" stroke="#405274" stroke-width="2"/>
+    <text x="172" y="222" text-anchor="middle" font-size="15" font-weight="700" fill="#91a4c4">PROJECT</text>
+    <text x="172" y="254" text-anchor="middle" font-size="22" font-weight="700" fill="#ffffff">Generated POC</text>
+    <text x="172" y="282" text-anchor="middle" font-size="15" fill="#b8c5d8">clone + open workspace</text>
+
+    <rect x="360" y="180" width="205" height="128" rx="18" fill="#1f3440" stroke="#3b7584" stroke-width="2"/>
+    <text x="462" y="222" text-anchor="middle" font-size="15" font-weight="700" fill="#8bd2df">SETUP</text>
+    <text x="462" y="254" text-anchor="middle" font-size="24" font-weight="700" fill="#ffffff">/setup</text>
+    <text x="462" y="282" text-anchor="middle" font-size="15" fill="#b9dbe1">converge this computer</text>
+
+    <rect x="650" y="170" width="205" height="148" rx="18" fill="#173c35" stroke="#3a9d82" stroke-width="2"/>
+    <text x="752" y="216" text-anchor="middle" font-size="15" font-weight="700" fill="#79d9bc">LOCAL</text>
+    <text x="752" y="250" text-anchor="middle" font-size="24" font-weight="700" fill="#ffffff">READY</text>
+    <text x="752" y="280" text-anchor="middle" font-size="15" fill="#b7ded3">build • test • run</text>
+    <text x="752" y="302" text-anchor="middle" font-size="13" fill="#89bcae">valid stopping point</text>
+
+    <rect x="940" y="126" width="190" height="112" rx="18" fill="#3d3219" stroke="#b58b2e" stroke-width="2"/>
+    <text x="1035" y="166" text-anchor="middle" font-size="15" font-weight="700" fill="#e5bf65">STAGING</text>
+    <text x="1035" y="198" text-anchor="middle" font-size="23" font-weight="700" fill="#ffffff">READY</text>
+    <text x="1035" y="220" text-anchor="middle" font-size="13" fill="#ddc98e">optional remote capability</text>
+
+    <rect x="940" y="292" width="190" height="112" rx="18" fill="#3b2228" stroke="#b55a6f" stroke-width="2"/>
+    <text x="1035" y="332" text-anchor="middle" font-size="15" font-weight="700" fill="#ed8ca2">PRODUCTION</text>
+    <text x="1035" y="364" text-anchor="middle" font-size="23" font-weight="700" fill="#ffffff">READY</text>
+    <text x="1035" y="386" text-anchor="middle" font-size="13" fill="#ddb2bc">deployment still explicit</text>
+  </g>
+
+  <g stroke="#8ea0bd" stroke-width="3" fill="none" marker-end="url(#arrow)">
+    <path d="M275 244 H350"/>
+    <path d="M565 244 H640"/>
+    <path d="M855 226 C900 226 900 182 930 182"/>
+    <path d="M855 270 C900 270 900 348 930 348"/>
+  </g>
+
+  <text x="885" y="454" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="14" fill="#8ea0bd">Remote capabilities are additive; they do not invalidate local readiness.</text>
+</svg>