@msn-control/liftoff 0.7.0 → 0.8.0

package/docs/troubleshooting.md

@@ -7,6 +7,8 @@ Check the canonical release:
 ```bash
 npm view @msn-control/liftoff@latest version --registry=https://registry.npmjs.org
 liftoff --version
+liftoff upgrade --check
+liftoff upgrade
 ```
 
 Versions before 0.3.0 are unsupported.
@@ -16,6 +18,40 @@ mirror owner to synchronize or approve the release. Liftoff does not modify
 `.npmrc`. A successful installation of an older mirrored package does not make
 that version supported.
 
+Versions that predate `liftoff upgrade` require one manual global installation:
+
+```bash
+npm install -g @msn-control/liftoff@latest --registry=https://registry.npmjs.org
+```
+
+## CLI upgrade is blocked by installation origin
+
+Automatic replacement supports only the canonical package at npm's effective
+global package root. A local dependency, `npx` cache copy, linked checkout, or
+another package-manager installation is intentionally refused. Use the manual
+global npm command shown by Liftoff; do not try to make upgrade replace a
+different installation.
+
+## CLI upgrade is blocked by a stale managed registry
+
+Canonical npm defines the exact stable target, but Liftoff installs through the
+configured registry. Ask the mirror owner to synchronize or approve that exact
+version, then rerun `liftoff upgrade --check`. Liftoff does not edit `.npmrc` or
+bypass the managed registry.
+
+## npm cannot write the global prefix
+
+Liftoff does not run `sudo`, request administrator credentials, or retry with
+elevation. Resolve Node/npm global-prefix ownership through the approved
+workstation process, then rerun the command.
+
+## CLI replacement verification fails
+
+Liftoff reports `failed` even when npm exited zero unless installed metadata and
+`liftoff --version` both match the exact target. Run the exact-version global npm
+repair command printed in the result. Liftoff does not claim an automatic
+rollback after npm may have partially changed global state.
+
 ## An installed tool is still reported missing
 
 Installers that change `PATH` may require a new terminal. Open one, rerun:
@@ -81,6 +117,48 @@ hand-edited unsafe path.
 Commit or copy local work before overwriting. Transaction rollback protects a
 failed update, but Liftoff keeps no backup after success.
 
+For a new governance policy or launcher conflict, review that exact local file
+before considering `liftoff update --force`; do not delete it or activate remote
+governance merely to make update pass. The schema-v5 manifest records
+`handoff-partial` and no ownership entry for each preserved unrecorded conflict.
+Run `liftoff update --check` to inspect the remaining paths. Once each path is
+absent or matches the current artifact, plain update promotes the handoff to
+`handoff-generated`. Setting `governanceProfile` to `none` turns previously
+managed handoff files into preserved orphans rather than deleting them; an
+unrecorded conflicting file remains user-owned and is not reported as an
+orphan.
+
+## Governance handoff exists but nothing is enforced
+
+That is the expected initial state. The manifest records `handoff-generated`,
+not active enforcement. Commit and push the repository, run the selected-agent
+launcher, review its read-only Phase 0 report, and explicitly approve the plan
+before the agent creates a governance change.
+
+Missing licenses, a private Staging runner, alert routes, parallel deployment,
+or sufficient canary traffic must be reported as blockers or inapplicable
+controls. Do not replace them with duplicate scanners or placeholder success.
+
+Do not run an older Liftoff release to reverse a completed baseline migration.
+Restore the affected generated files and `liftoff.manifest.json` through version
+control, then reinstall from the restored locks.
+
+## A frozen Python install cannot reach the package index
+
+Keep the committed `pyproject.toml` and `uv.lock` unchanged and retry the
+generated `uv sync --frozen` command when registry connectivity is restored.
+Do not regenerate the lock as a connectivity workaround.
+
+Python Dockerfiles also accept a credential-free PEP 503 mirror while retaining
+the lock's exact versions and hashes:
+
+```bash
+docker build --build-arg UV_DEFAULT_INDEX=https://packages.example.test/simple/ .
+```
+
+Do not place credentials in build arguments. Configure authenticated registries
+through an approved secret-aware build mechanism.
+
 ## Power Apps dependencies or CLI are missing
 
 From the project root:

package/docs/workloads.md

@@ -7,12 +7,12 @@ prerequisites, generated artifacts, and maintenance checks that apply to it.
 
 | Workload | Primary choices | Required runtime | Liftoff-generated platform areas |
 | --- | --- | --- | --- |
-| GenAI application | Pattern, Azure region, environments, optional frontend | Python 3.12 and Node.js 20.19+ | API, orchestration, data, messaging, Docker, Azure OpenTofu |
-| API application | Python, Node.js, or Go API stack; Azure region; environments; optional frontend | Selected API runtime and Node.js 20.19+ | API, data, Docker, Azure OpenTofu |
-| Power Apps code app | Spec workflow, agents, optional Code Apps plugin | Node.js 22.12+ | Official React/Vite starter and project-local Power Apps tooling |
+| GenAI application | Pattern, Azure region, environments, optional frontend | Python 3.14, `uv` 0.12.7+, and Node.js 24.20+ | API, orchestration, data, messaging, Docker, Azure OpenTofu |
+| API application | Python 3.14, Node.js 24, or Go 1.27 API stack; Azure region; environments; optional frontend | Selected API runtime and Node.js 24.20+ | API, data, Docker, Azure OpenTofu |
+| Power Apps code app | Spec workflow, agents, optional Code Apps plugin | Node.js 24.20+ | Official React/Vite starter and project-local Power Apps tooling |
 
 All three workloads continue into the common OpenSpec or Spec Kit and coding
-agent flow.
+agent flow and the default local repository-governance handoff.
 
 ## GenAI application
 
@@ -29,11 +29,14 @@ The selected pattern fixes the API stack to Python, FastAPI, and PydanticAI.
 ### Generated output
 
 - FastAPI backend and Scalar/OpenAPI integration.
+- A committed `uv.lock` consumed through `uv sync --frozen`.
 - PydanticAI orchestration, prompts, and model configuration boundaries.
 - PostgreSQL and pattern-specific Redis or Azure Service Bus boundaries.
 - Offline-testable tracing and integration adapters.
 - Docker Compose and Azure OpenTofu.
 - Optional Vue frontend and pattern-specific Azure Functions workers.
+- Versioned repository-governance policy, workload context, guide, and
+  selected-agent launcher unless `none` is selected.
 
 ### Deferred actions
 
@@ -55,9 +58,12 @@ infrastructure before applying it.
 ### Generated output
 
 - Stack-native API, OpenAPI, tests, and database migrations.
+- Ecosystem-native locked metadata: `uv.lock`, `package-lock.json`, or
+  `go.mod` plus `go.sum`.
 - PostgreSQL, Redis, Azurite, and Mailpit local services where applicable.
 - Docker Compose and Azure OpenTofu.
 - Optional Vue frontend.
+- Versioned local repository-governance handoff unless explicitly disabled.
 
 ### Deferred actions
 
@@ -87,9 +93,12 @@ environment, API frontend, Docker, or OpenTofu selection.
 - React, Vite, TypeScript, Tailwind, and the Power Apps SDK and Vite plugin.
 - Locked root `package.json` and `package-lock.json`.
 - Project-local `power-apps` CLI supplied by the generated dependency graph.
-- `liftoff.config.json`, schema-v4 `liftoff.manifest.json`, starter provenance,
+- `liftoff.config.json`, schema-v5 `liftoff.manifest.json`, starter provenance,
   and third-party attribution.
 - Official OpenSpec or Spec Kit output and every selected agent marker.
+- The common local governance policy and selected-agent launcher, with backend,
+  container, OpenTofu, custom deployment, and API DAST controls marked
+  inapplicable.
 
 Liftoff does not create an API backend, `docker-compose.yml`,
 `infrastructure/`, API environments, or an environment-bound

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msn-control/liftoff",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Interactive CLI for governed GenAI, API, and Power Apps code app projects.",
   "type": "module",
   "license": "GPL-3.0-only",
@@ -32,7 +32,9 @@
   "files": [
     "dist",
     "assets/locks",
+    "assets/governance",
     "assets/power-apps-code-app",
+    "assets/supported-stack.json",
     "docs",
     "README.md",
     "LICENSE"
@@ -45,25 +47,31 @@
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",
     "audit:template-dependencies": "node scripts/audit-template-dependencies.mjs",
+    "refresh:supported-stack": "node scripts/refresh-supported-stack-baseline.mjs --write",
+    "check:supported-stack": "node scripts/refresh-supported-stack-baseline.mjs",
+    "check:supported-stack-freshness": "node scripts/check-supported-stack-freshness.mjs",
+    "canonicalize:python-locks": "node scripts/canonicalize-uv-lock.mjs assets/locks/python-standard/uv.lock assets/locks/python-genai/uv.lock",
     "refresh:power-apps-starter": "node scripts/refresh-power-apps-starter.mjs",
     "smoke:package": "npm run build && node scripts/package-smoke-test.mjs",
     "verify:standard-node-templates": "npm run build && node scripts/verify-standard-node-templates.mjs",
+    "verify:generated-containers": "npm run build && node scripts/verify-generated-containers.mjs",
     "verify:power-apps-starter": "npm run build && node scripts/verify-power-apps-starter.mjs",
     "verify:release-identity": "npm run build && node scripts/verify-release-identity.mjs",
     "verify:published": "npm run build && node scripts/verify-published-package.mjs",
-    "check": "npm run build && npm test"
+    "check": "npm run check:supported-stack && npm run build && npm test"
   },
   "engines": {
-    "node": ">=20.19"
+    "node": ">=24.20"
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6",
-    "@types/node": "^20.14.10",
+    "@types/node": "^24.6.0",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.9"
+    "vite": "8.2.2",
+    "vitest": "4.1.11"
   },
   "dependencies": {
-    "@inquirer/prompts": "^7.10.1",
+    "@inquirer/prompts": "^8.6.0",
     "cross-spawn": "^7.0.6",
     "picocolors": "^1.1.1"
   }