@mriekki/lean 0.4.6 → 0.4.7

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/lean",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "defaultProfile": "greenfield-poc",
   "profiles": {
     "greenfield-poc": {
@@ -14,7 +14,7 @@
   "components": {
     "core": {
       "repository": "mriekki/lean-agentic-core",
-      "commit": "52905468c06fe39caa491a15a77e33cd400a60d9",
+      "commit": "c53620078d22ec8acb6fee99006045736a2d6491",
       "version": "1.13.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
@@ -23,7 +23,7 @@
     },
     "deployment": {
       "repository": "mriekki/lean-poc-deployment-kit",
-      "commit": "bfe07aac1809d4cf41428fba9fdbcfe6a5e85470",
+      "commit": "a4cdb4f43982692536b669a135a4c81057368fce",
       "distribution": "greenfield-poc",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/core/distribution.json

@@ -20,6 +20,7 @@
     {"source":"core/skills/core-sync/SKILL.md","destination":".github/skills/core-sync/SKILL.md"},
     {"source":"core/skills/upstream-fix/SKILL.md","destination":".github/skills/upstream-fix/SKILL.md"},
     {"source":"core/skills/wait-what/SKILL.md","destination":".github/skills/wait-what/SKILL.md"},
+    {"source":"core/skills/developer-env-mode/SKILL.md","destination":".github/skills/developer-env-mode/SKILL.md"},
     {"source":"core/skills/deployment-readiness/SKILL.md","destination":".github/skills/deployment-readiness/SKILL.md"},
     {"source":"core/skills/deploy/SKILL.md","destination":".github/skills/deploy/SKILL.md"},
     {"source":"core/skills/tear-down/SKILL.md","destination":".github/skills/tear-down/SKILL.md"},

package/assets/deployment/distribution.json

@@ -11,6 +11,8 @@
     {"source": "src/lean_poc_deployment/app_runtime_remote.py", "destination": "tools/lean-deployment/lean_poc_deployment/app_runtime_remote.py"},
     {"source": "src/lean_poc_deployment/local_cli.py", "destination": "tools/lean-deployment/lean_poc_deployment/local_cli.py"},
     {"source": "src/lean_poc_deployment/local_runtime.py", "destination": "tools/lean-deployment/lean_poc_deployment/local_runtime.py"},
+    {"source": "src/lean_poc_deployment/local_spec.py", "destination": "tools/lean-deployment/lean_poc_deployment/local_spec.py"},
+    {"source": "src/lean_poc_deployment/local_sqlite.py", "destination": "tools/lean-deployment/lean_poc_deployment/local_sqlite.py"},
     {"source": "src/lean_poc_deployment/box_platform.py", "destination": "tools/lean-deployment/lean_poc_deployment/box_platform.py"},
     {"source": "src/lean_poc_deployment/box_platform_assets.py", "destination": "tools/lean-deployment/lean_poc_deployment/box_platform_assets.py"},
     {"source": "src/lean_poc_deployment/box_platform_remote.py", "destination": "tools/lean-deployment/lean_poc_deployment/box_platform_remote.py"},

package/assets/generated/ASSEMBLY.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/lean",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "components": {
     "core": {
       "repository": "mriekki/lean-agentic-core",
-      "commit": "52905468c06fe39caa491a15a77e33cd400a60d9",
+      "commit": "c53620078d22ec8acb6fee99006045736a2d6491",
       "version": "1.13.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -99,6 +99,11 @@
           "destination": ".github/skills/wait-what/SKILL.md",
           "sha256": "9b5968158992681837071b60465682a887540b1fdab510861ed739ffa996fbdb"
         },
+        {
+          "source": "core/skills/developer-env-mode/SKILL.md",
+          "destination": ".github/skills/developer-env-mode/SKILL.md",
+          "sha256": "23a026a3c2e999855fe64006e76bffcbecf6348696266fd94452c605ef1d4c03"
+        },
         {
           "source": "core/skills/deployment-readiness/SKILL.md",
           "destination": ".github/skills/deployment-readiness/SKILL.md",
@@ -298,7 +303,7 @@
     },
     "deployment": {
       "repository": "mriekki/lean-poc-deployment-kit",
-      "commit": "bfe07aac1809d4cf41428fba9fdbcfe6a5e85470",
+      "commit": "a4cdb4f43982692536b669a135a4c81057368fce",
       "distribution": "greenfield-poc",
       "files": [
         {
@@ -334,13 +339,23 @@
         {
           "source": "src/lean_poc_deployment/local_cli.py",
           "destination": "tools/lean-deployment/lean_poc_deployment/local_cli.py",
-          "sha256": "9c658c0409da3c6297ad349035bccb263a587cd6d9b07a9796ccbb7cdb6676f9"
+          "sha256": "b183d937b21cef10c4766d588dccd03a729a373e587a82e7b80a9e2390797eb9"
         },
         {
           "source": "src/lean_poc_deployment/local_runtime.py",
           "destination": "tools/lean-deployment/lean_poc_deployment/local_runtime.py",
           "sha256": "82cf795733b59f4591515396be65317da4e515fde19874e3c5851bcff412d84d"
         },
+        {
+          "source": "src/lean_poc_deployment/local_spec.py",
+          "destination": "tools/lean-deployment/lean_poc_deployment/local_spec.py",
+          "sha256": "372b8c041edd9d3a1005861d85bb3a6bad38064b0be081a470460ad2dc62be4d"
+        },
+        {
+          "source": "src/lean_poc_deployment/local_sqlite.py",
+          "destination": "tools/lean-deployment/lean_poc_deployment/local_sqlite.py",
+          "sha256": "767c91f2af1f0df6f88b81a867826e4beaa1871865a97a9002a6b3fc53c781c9"
+        },
         {
           "source": "src/lean_poc_deployment/box_platform.py",
           "destination": "tools/lean-deployment/lean_poc_deployment/box_platform.py",

package/assets/generated/core/core/skills/developer-env-mode/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: developer-env-mode
+description: "Converge and verify the developer workstation for local-only or remote-enabled work. Mode changes become effective only after the selected readiness contract passes."
+argument-hint: "status|local|remote"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Developer Environment Mode
+
+`/developer-env-mode` manages the current workstation's operational development mode. It is not a deployment command and it does not weaken Staging or Production gates.
+
+Supported intents:
+
+```text
+/developer-env-mode status
+/developer-env-mode local
+/developer-env-mode remote
+```
+
+The governing invariant is:
+
+```text
+MODE != preference
+MODE = verified operational state
+```
+
+Never record a requested mode as ready until its readiness contract passes. If convergence fails, preserve the prior ready mode when one exists and report the blocker.
+
+## 1. Resolve repository and package provenance read-only
+
+From the repository root inspect, when present:
+
+- `POC_BOOTSTRAP.json`;
+- `LEAN_BASELINE.json` and component baselines;
+- `DEV_ENVIRONMENT.json`;
+- application setup/build/test commands and project-owned persistence configuration;
+- deployment topology and generated deployment tooling;
+- Git status so unrelated work is preserved.
+
+For package-managed consumers, verify managed files are coherent before relying on distributed Core or Deployment tooling. Route managed drift to `/lean-update` rather than overwriting it.
+
+Do not require a Bootstrap/Core/Deployment Kit source checkout for normal consumer use.
+
+## 2. Keep current mode state workstation-local
+
+Mode state is user/workstation state, not repository authority. Store it outside the repository under the user-scoped Lean directory, using a repository-scoped location such as:
+
+```text
+~/.lean-poc/workspaces/<owner>/<repo>/developer-environment.json
+```
+
+Do not commit this state. Do not store credentials, private keys, target trust stores, database contents, or secret values in it.
+
+Record enough non-secret evidence to distinguish requested mode from readiness, for example:
+
+- mode;
+- ready/not-ready;
+- verification timestamp;
+- source revision when available;
+- build/test state or fingerprint;
+- local database state when applicable;
+- local runtime health when applicable;
+- remote target/access readiness summary when applicable.
+
+A later `status` check must be allowed to report that the recorded mode is no longer ready when Docker stops, tools drift, the build becomes stale, the local database is missing/incompatible, or remote access disappears.
+
+## 3. `status` is read-only
+
+`/developer-env-mode status` performs no setup writes. Inspect current workstation evidence and live prerequisites, then report both the selected mode and current readiness.
+
+Prefer a compact result such as:
+
+```text
+DEVELOPER ENVIRONMENT
+
+Selected mode: LOCAL
+Readiness: NOT READY
+
+Docker ........ READY
+Build ......... STALE
+Tests ......... READY
+SQLite ........ READY
+Runtime ....... HEALTHY
+Remote access . UNAVAILABLE
+
+NEXT
+/developer-env-mode local
+```
+
+Do not silently repair state during `status`.
+
+## 4. `local` means converge a complete local development environment
+
+Selecting `local` authorizes bounded, non-destructive workstation setup needed to make the current repository usable locally. It does not authorize destructive database reset, deletion of unrelated Docker state, remote publication, remote deployment, or Production writes.
+
+Converge in this order.
+
+### A. Workstation prerequisites
+
+Verify the current OS is supported by repository configuration. Use repository setup/doctor tooling when present to verify required tools and versions.
+
+For Docker-based local execution require a working Docker CLI/engine. Prefer repository-distributed Deployment Kit commands when `DEPLOYMENT_BASELINE.json` proves they are installed.
+
+### B. Dependencies and restore
+
+Run repository-defined dependency restore/setup commands when missing or stale. Preserve pinned versions and project conventions. Do not substitute arbitrary global tooling when the repository defines a supported path.
+
+### C. Local persistence
+
+If the application uses SQLite for local development:
+
+1. resolve the project-owned database filename/container path and migration/initialization contract from repository configuration/docs/code;
+2. prefer the installed Deployment Kit local SQLite ensure/status primitive when available for workstation-owned persistent storage;
+3. when the database is absent, create the owned local SQLite file/directory non-destructively;
+4. run the repository-provided migration/schema initialization needed to make that database usable;
+5. verify the resulting database can be opened and that the application-required schema/migration state is current when the repository provides such a check.
+
+If an existing SQLite database is corrupt, incompatible, or has unexpected ownership/schema state, **STOP**. Never delete, replace, reset, or migrate destructively merely to make mode convergence pass. Present the exact recovery/reset decision separately.
+
+Do not assume every project uses SQLite. Other persistence requires an explicit repository-owned local setup contract.
+
+### D. Build and tests
+
+Run the repository's required local build and test commands. A missing or stale build is a normal convergence condition; rebuild it.
+
+If build or required tests fail, report `LOCAL MODE NOT READY` and do not mark the mode ready.
+
+When the project policy says application validation is local-only, GitHub publication/PR activity does not replace this local build/test evidence.
+
+### E. Local immutable Docker artifact
+
+When the local runtime is Docker-based, build the application image locally using repository-owned commands. Resolve an immutable local image identity.
+
+The standard Deployment Kit workstation adapter may accept either:
+
+- an exact registry digest (`name@sha256:...`), or
+- a local Docker image ID (`sha256:<64 hex>`) for workstation-only execution.
+
+Never use a mutable tag as the final deployed identity. A local image ID is valid only for workstation placement and is not remote-release evidence.
+
+### F. Workstation runtime
+
+Converge the local application runtime through the repository-distributed workstation adapter when available:
+
+```text
+placement: workstation
+isolation: container
+exposure: loopback
+```
+
+Keep exposure loopback-only. Mount the project-owned local SQLite persistence directory when required. Verify the declared health endpoint and any required local smoke check.
+
+Do not resolve SSH targets, publish images, create public routes, or deploy Staging/Production while entering local mode.
+
+### G. Commit local mode only after readiness passes
+
+Only after prerequisites, persistence, build, tests, runtime, and health requirements pass, write the workstation-local mode state as ready.
+
+A successful summary should distinguish local evidence from remote evidence:
+
+```text
+LOCAL DEVELOPER ENVIRONMENT READY
+
+Build ........ READY
+Tests ........ READY
+Docker ....... READY
+SQLite ....... READY / NOT APPLICABLE
+Application .. HEALTHY
+Remote deploy. DISABLED BY MODE
+```
+
+## 5. `remote` means verify remote-enabled capability, not deploy
+
+Selecting `remote` authorizes bounded, non-destructive checks/setup needed to prove that the current workstation can work with the repository's configured remote non-Production environment(s). It does **not** publish an artifact or deploy an application.
+
+Verify as applicable:
+
+- normal local developer prerequisites still needed to build/test the project;
+- repository deployment topology contains a non-deferred remote environment;
+- exact target/provider binding exists when required;
+- workstation-to-target trust/access is valid;
+- target OS/runtime/platform readiness is valid;
+- persistence/readiness prerequisites can be inspected safely;
+- GitHub/registry access needed for a later release/publish step is available;
+- repository release/deployment tooling and baselines are coherent.
+
+For the standard remote-SSH path preserve strict host identity. Unknown or changed host identity is a stop condition. Never fall back to another environment or host.
+
+Do not require a Production target merely to enter remote mode. Do not weaken Production authorization because remote mode is ready.
+
+Only after the selected remote readiness checks pass, record `remote` as ready.
+
+Then report the next explicit operation, typically:
+
+```text
+/deployment-readiness <environment>
+```
+
+A later `/deploy <environment>` remains separately gated.
+
+## 6. Fail closed on destructive or ambiguous repair
+
+Automatic convergence may safely create missing local directories, dependency caches, build outputs, a new owned SQLite file, migrations that the project defines as normal forward initialization, and a new owned local application container.
+
+Stop for a separate explicit decision before:
+
+- deleting/resetting an existing database;
+- destructive migration or rollback;
+- replacing unexplained persistent data;
+- deleting unrelated containers/images/volumes;
+- publishing an artifact remotely;
+- rebinding a target;
+- weakening host verification;
+- deploying Staging or Production;
+- changing public/LAN exposure.
+
+## 7. Relationship to other Lean commands
+
+`/developer-env-mode` prepares a workstation and establishes current operational readiness.
+
+It does not replace:
+
+- `/lean-update` for managed Lean package changes;
+- project setup/doctor tooling;
+- `/start-work` for implementation authorization;
+- `/deployment-readiness` for environment-specific pre-deploy evidence;
+- `/deploy` for deployment authorization/execution;
+- `/tear-down` for destructive cleanup.
+
+Mode switching never implies merge, release publication, Staging deployment, or Production deployment.

package/assets/generated/deployment/src/lean_poc_deployment/local_cli.py

@@ -12,9 +12,13 @@ from .local_runtime import (
     apply_local_deploy,
     local_deploy_write_phrase,
     local_inventory,
-    normalize_local_spec,
     plan_local_deploy,
 )
+from .local_spec import normalize_workstation_spec
+from .local_sqlite import ensure_local_sqlite, local_sqlite_status
+
+
+LOCAL_SQLITE_ENSURE_WRITE_PHRASE = "[LOCAL SQLITE ENSURE]"
 
 
 def _print(value: Any, *, as_json: bool) -> None:
@@ -45,6 +49,14 @@ def _confirm(args: argparse.Namespace, phrase: str, action: str) -> None:
         raise DeploymentKitError(f"{action.capitalize()} was not authorized.")
 
 
+def _add_sqlite_identity(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--owner-repo", required=True)
+    parser.add_argument("--environment", required=True)
+    parser.add_argument("--app-slug", required=True)
+    parser.add_argument("--database-file", required=True)
+    parser.add_argument("--json", action="store_true")
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="lean-poc-deploy local")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -55,6 +67,19 @@ def build_parser() -> argparse.ArgumentParser:
     )
     inventory.add_argument("--json", action="store_true")
 
+    sqlite_status = sub.add_parser(
+        "sqlite-status",
+        help="Inspect one Lean-owned workstation SQLite database without writes",
+    )
+    _add_sqlite_identity(sqlite_status)
+
+    sqlite_ensure = sub.add_parser(
+        "sqlite-ensure",
+        help="Create a missing Lean-owned workstation SQLite database non-destructively",
+    )
+    _add_sqlite_identity(sqlite_ensure)
+    sqlite_ensure.add_argument("--yes", action="store_true")
+
     deploy = sub.add_parser(
         "deploy",
         help="Deploy one immutable application container bound only to loopback",
@@ -83,7 +108,50 @@ def main(argv: list[str] | None = None) -> int:
             _print(local_inventory(), as_json=args.json)
             return 0
 
-        spec = normalize_local_spec(
+        if args.command == "sqlite-status":
+            _print(
+                local_sqlite_status(
+                    owner_repo=args.owner_repo,
+                    environment=args.environment,
+                    app_slug=args.app_slug,
+                    database_file=args.database_file,
+                ),
+                as_json=args.json,
+            )
+            return 0
+
+        if args.command == "sqlite-ensure":
+            status = local_sqlite_status(
+                owner_repo=args.owner_repo,
+                environment=args.environment,
+                app_slug=args.app_slug,
+                database_file=args.database_file,
+            )
+            if status["state"] == "ready":
+                _print(status, as_json=args.json)
+                return 0
+            if status["state"] == "unmanaged-existing":
+                raise DeploymentKitError(
+                    "Refusing automatic adoption of an existing unmanaged local SQLite database."
+                )
+            _print(status, as_json=False)
+            _confirm(
+                args,
+                LOCAL_SQLITE_ENSURE_WRITE_PHRASE,
+                f"create local SQLite storage for {args.app_slug} ({args.environment})",
+            )
+            _print(
+                ensure_local_sqlite(
+                    owner_repo=args.owner_repo,
+                    environment=args.environment,
+                    app_slug=args.app_slug,
+                    database_file=args.database_file,
+                ),
+                as_json=args.json,
+            )
+            return 0
+
+        spec = normalize_workstation_spec(
             owner_repo=args.owner_repo,
             environment=args.environment,
             app_slug=args.app_slug,

package/assets/generated/deployment/src/lean_poc_deployment/local_spec.py

@@ -0,0 +1,82 @@
+"""Workstation-only application spec normalization."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from typing import Any, Iterable
+
+from .app_runtime import normalize_app_spec
+from .errors import DeploymentKitError
+
+
+_LOCAL_IMAGE_ID_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
+def _host_port(value: int) -> int:
+    if type(value) is not int or not 1 <= value <= 65535:
+        raise DeploymentKitError("hostPort must be an integer from 1 through 65535.")
+    return value
+
+
+def _base_image(image: str) -> tuple[str, bool]:
+    if isinstance(image, str) and _LOCAL_IMAGE_ID_RE.fullmatch(image):
+        return f"local-workstation/immutable@{image}", True
+    return image, False
+
+
+def normalize_workstation_spec(
+    *,
+    owner_repo: str,
+    environment: str,
+    app_slug: str,
+    container_name: str,
+    image: str,
+    runtime_port: int,
+    host_port: int,
+    health_path: str,
+    run_as: str,
+    persistence_mode: str,
+    data_container_path: str | None,
+    environment_variables: dict[str, str] | Iterable[tuple[str, str]],
+) -> dict[str, Any]:
+    """Normalize a loopback-only workstation spec.
+
+    Remote deployment keeps the registry-digest-only contract. Workstation execution
+    additionally accepts an immutable local Docker image ID (sha256:<64 hex>) so a
+    developer can build/test/run without publishing to a registry first.
+    """
+
+    normalized_image, local_image_id = _base_image(image)
+    base = normalize_app_spec(
+        owner_repo=owner_repo,
+        environment=environment,
+        app_slug=app_slug,
+        container_name=container_name,
+        image=normalized_image,
+        runtime_port=runtime_port,
+        health_path=health_path,
+        run_as=run_as,
+        persistence_mode=persistence_mode,
+        data_container_path=data_container_path,
+        environment_variables=environment_variables,
+    )
+    base.pop("specSha256", None)
+    if local_image_id:
+        base["image"] = image
+    base.update(
+        {
+            "schemaVersion": 1,
+            "placement": "workstation",
+            "isolation": "container",
+            "exposure": "loopback",
+            "hostAddress": "127.0.0.1",
+            "hostPort": _host_port(host_port),
+            "imageSource": "local-image-id" if local_image_id else "registry-digest",
+        }
+    )
+    base["specSha256"] = hashlib.sha256(
+        json.dumps(base, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+    return base

package/assets/generated/deployment/src/lean_poc_deployment/local_sqlite.py

@@ -0,0 +1,205 @@
+"""Non-destructive workstation SQLite lifecycle helpers."""
+
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from .errors import DeploymentKitError
+from .profiles import config_root
+
+
+_SLUG_RE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
+_REPO_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
+_DB_FILE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+_METADATA_FILE = "sqlite-local.json"
+
+
+def _slug(value: str, field: str) -> str:
+    if not isinstance(value, str) or _SLUG_RE.fullmatch(value) is None:
+        raise DeploymentKitError(f"{field} must use lowercase letters, digits, and internal hyphens.")
+    return value
+
+
+def _owner_repo(value: str) -> str:
+    if not isinstance(value, str) or _REPO_RE.fullmatch(value) is None:
+        raise DeploymentKitError("ownerRepo must use GitHub owner/repository form without URL syntax.")
+    return value
+
+
+def _database_file(value: str) -> str:
+    if not isinstance(value, str) or _DB_FILE_RE.fullmatch(value) is None or value in {".", ".."}:
+        raise DeploymentKitError("databaseFile must be a safe file name without path separators.")
+    return value
+
+
+def _state_root(app_slug: str, environment: str) -> Path:
+    return config_root() / "local-apps" / app_slug / environment
+
+
+def _data_dir(app_slug: str, environment: str) -> Path:
+    return _state_root(app_slug, environment) / "data"
+
+
+def _metadata_path(app_slug: str, environment: str) -> Path:
+    return _state_root(app_slug, environment) / _METADATA_FILE
+
+
+def _database_path(app_slug: str, environment: str, database_file: str) -> Path:
+    return _data_dir(app_slug, environment) / database_file
+
+
+def _load_metadata(app_slug: str, environment: str) -> dict[str, Any] | None:
+    path = _metadata_path(app_slug, environment)
+    if not path.is_file():
+        return None
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise DeploymentKitError(f"Cannot read local SQLite metadata {path}: {error}") from error
+    if not isinstance(value, dict) or value.get("schemaVersion") != 1:
+        raise DeploymentKitError(f"Unsupported local SQLite metadata: {path}")
+    return value
+
+
+def _write_metadata(path: Path, value: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(".tmp")
+    temporary.write_text(json.dumps(value, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    temporary.replace(path)
+
+
+def _quick_check(path: Path) -> str:
+    try:
+        with sqlite3.connect(path) as connection:
+            row = connection.execute("PRAGMA quick_check").fetchone()
+    except sqlite3.DatabaseError as error:
+        raise DeploymentKitError(f"Local SQLite database is not valid: {path}: {error}") from error
+    result = str(row[0]) if row else "missing-result"
+    if result.lower() != "ok":
+        raise DeploymentKitError(f"Local SQLite quick_check failed for {path}: {result}")
+    return result
+
+
+def local_sqlite_status(
+    *, owner_repo: str, environment: str, app_slug: str, database_file: str
+) -> dict[str, Any]:
+    owner_repo = _owner_repo(owner_repo)
+    environment = _slug(environment, "environment")
+    app_slug = _slug(app_slug, "appSlug")
+    database_file = _database_file(database_file)
+    metadata = _load_metadata(app_slug, environment)
+    path = _database_path(app_slug, environment, database_file)
+
+    if metadata is not None:
+        expected = {
+            "ownerRepo": owner_repo,
+            "environment": environment,
+            "appSlug": app_slug,
+            "databaseFile": database_file,
+        }
+        for key, value in expected.items():
+            if metadata.get(key) != value:
+                raise DeploymentKitError(
+                    f"Local SQLite metadata ownership mismatch for {app_slug}/{environment}: {key}."
+                )
+
+    if path.exists() and metadata is None:
+        return {
+            "schemaVersion": 1,
+            "ownerRepo": owner_repo,
+            "environment": environment,
+            "appSlug": app_slug,
+            "databaseFile": database_file,
+            "databasePath": str(path),
+            "state": "unmanaged-existing",
+            "managed": False,
+            "present": True,
+            "valid": False,
+            "mutated": False,
+        }
+
+    if not path.exists():
+        return {
+            "schemaVersion": 1,
+            "ownerRepo": owner_repo,
+            "environment": environment,
+            "appSlug": app_slug,
+            "databaseFile": database_file,
+            "databasePath": str(path),
+            "state": "missing",
+            "managed": metadata is not None,
+            "present": False,
+            "valid": False,
+            "mutated": False,
+        }
+
+    _quick_check(path)
+    return {
+        "schemaVersion": 1,
+        "ownerRepo": owner_repo,
+        "environment": environment,
+        "appSlug": app_slug,
+        "databaseFile": database_file,
+        "databasePath": str(path),
+        "state": "ready",
+        "managed": True,
+        "present": True,
+        "valid": True,
+        "bytes": path.stat().st_size,
+        "mutated": False,
+    }
+
+
+def ensure_local_sqlite(
+    *, owner_repo: str, environment: str, app_slug: str, database_file: str
+) -> dict[str, Any]:
+    owner_repo = _owner_repo(owner_repo)
+    environment = _slug(environment, "environment")
+    app_slug = _slug(app_slug, "appSlug")
+    database_file = _database_file(database_file)
+
+    status = local_sqlite_status(
+        owner_repo=owner_repo,
+        environment=environment,
+        app_slug=app_slug,
+        database_file=database_file,
+    )
+    if status["state"] == "unmanaged-existing":
+        raise DeploymentKitError(
+            "Refusing to adopt an existing unmanaged local SQLite database automatically. "
+            "Review its ownership/data before using or moving it."
+        )
+    if status["state"] == "ready":
+        return status
+
+    path = _database_path(app_slug, environment, database_file)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with sqlite3.connect(path) as connection:
+            connection.execute("PRAGMA user_version")
+            connection.commit()
+    except sqlite3.DatabaseError as error:
+        raise DeploymentKitError(f"Unable to create local SQLite database {path}: {error}") from error
+
+    metadata = {
+        "schemaVersion": 1,
+        "ownerRepo": owner_repo,
+        "environment": environment,
+        "appSlug": app_slug,
+        "databaseFile": database_file,
+    }
+    _write_metadata(_metadata_path(app_slug, environment), metadata)
+    _quick_check(path)
+    result = local_sqlite_status(
+        owner_repo=owner_repo,
+        environment=environment,
+        app_slug=app_slug,
+        database_file=database_file,
+    )
+    result["mutated"] = True
+    result["created"] = True
+    return result

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mriekki/lean",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Public consumer distribution and updater for Lean engineering assets.",
   "type": "module",
   "bin": {