@msn-control/liftoff 0.4.0 → 0.5.0

package/docs/configuration-and-manifests.md

@@ -0,0 +1,102 @@
+# Configuration and manifests
+
+Generated projects have two Liftoff root files with different ownership.
+
+## `liftoff.config.json`: developer-owned desired state
+
+Liftoff writes configuration once during initialization and does not
+machine-rewrite it afterward.
+
+Supported edits are reconciled by `liftoff update`:
+
+- API workloads can add or remove environments and enable applicable generated
+  areas such as the frontend.
+- Power Apps can change the optional Code Apps plugin preference.
+
+Workload kind, API stack, GenAI pattern, spec workflow, selected agents, and a
+user-supplied Power Apps starter source change are not ordinary updates.
+
+A Power Apps configuration contains only applicable fields:
+
+```json
+{
+  "projectName": "sales-hub",
+  "projectType": "power-apps-code-app",
+  "specWorkflow": "openspec",
+  "agents": ["github-copilot"],
+  "codeAppsPlugin": false
+}
+```
+
+API, cloud, region, frontend, and environment fields are rejected for this
+workload rather than silently ignored.
+
+## `liftoff.manifest.json`: CLI-owned compatibility record
+
+New projects use manifest schema v4. Its common project identity includes the
+name, spec workflow, selected agents, and applicable Spec Kit default. A
+discriminated `project.workload` object contains only fields valid for one
+workload:
+
+- `genai`: API stack, pattern, cloud, region, frontend, and environments.
+- `standard`: API stack, cloud, region, frontend, and environments.
+- `power-apps-code-app`: immutable starter repository, template path, commit,
+  and Code Apps plugin preference.
+
+The manifest also records:
+
+- Generating Liftoff version.
+- Official framework adapter, state, and tested contract version when known.
+- Durable artifact logical names.
+- OS-neutral path-part arrays.
+- `sha256:` content hashes.
+
+Power Apps source identity uses explicit repository, path, and 40-character
+commit fields. It is not inferred from mutable URLs or generated file paths.
+
+Treat the manifest as CLI-owned. Restore it from version control or regenerate
+with the matching Liftoff version when validation reports malformed identity,
+paths, or hashes.
+
+## Compatibility
+
+Readers support schemas v2, v3, and v4:
+
+- V2 normalizes the legacy flat API identity and records framework state as
+  uncertain without inventing agents.
+- V3 normalizes flat GenAI or API identity plus framework and agent metadata.
+- V4 represents the discriminated workload model, including Power Apps.
+
+A read-only `liftoff update` leaves an old manifest byte-for-byte unchanged. A
+successful apply writes v4 only after the file transaction succeeds. Skipped
+conflicts retain their recorded hashes.
+
+## Artifact ownership
+
+Durable Liftoff artifacts carry logical names and hashes. That lets validate,
+doctor, and update distinguish:
+
+- Current template bytes.
+- An untouched file with a template upgrade.
+- A developer edit that conflicts with a template change.
+- A named artifact moved by the template.
+- Missing, new, and orphaned artifacts.
+
+Framework-owned OpenSpec and Spec Kit files are validated separately and are
+not claimed in durable hashes. One-time seed files are also excluded so they
+can follow their own lifecycle.
+
+## Contract conventions
+
+- Writers use `artifactVersion` 4; readers support v2, v3, and v4.
+- Artifact logical names and catalog identifiers are append-only.
+- Rendering is deterministic and does not depend on timestamps, host versions,
+  or network state.
+- `.liftoff/` is reserved for future CLI-managed state.
+- Machine-readable paths are path-part arrays, never platform-joined strings.
+- Exit codes are 0 for success or clean, 1 for failure, and 2 for detected
+  drift in check mode.
+- JSON outputs carry a numeric top-level `schemaVersion`.
+
+See [safety and consent](safety-and-consent.md) for reconciliation and rollback
+behavior.

package/docs/existing-repositories.md

@@ -0,0 +1,87 @@
+# Existing repositories
+
+Liftoff chooses its target from the current directory and Git worktree
+discovery before it stages any output.
+
+## Exact Git root: initialize in place
+
+When the current directory is exactly the root reported by
+`git rev-parse --show-toplevel`, `liftoff init` uses that directory as the
+target:
+
+```bash
+cd existing-repository
+liftoff init
+```
+
+With no project name, Liftoff derives project identity from the repository
+directory. Supplying a name changes the generated project identity but still
+does not create a child folder:
+
+```bash
+liftoff init customer-portal
+```
+
+## Other locations: create a named child
+
+In a non-Git directory, or in a directory below but not equal to a Git root, a
+project name produces a child:
+
+```text
+workspace/
+`-- customer-portal/
+    |-- liftoff.config.json
+    `-- liftoff.manifest.json
+```
+
+This distinction prevents an invocation deep inside an existing repository
+from unexpectedly treating that subdirectory as the repository root.
+
+## Non-empty targets
+
+Liftoff never blindly replaces a target tree. It:
+
+1. Renders Liftoff-owned files in temporary staging.
+2. Runs the official OpenSpec or Spec Kit initializer in staging.
+3. Rejects unexpected roots, nested Git metadata, and unsafe paths.
+4. Compares every destination before writing.
+5. Lists different regular files as one replacement set.
+6. Requires explicit overwrite permission before replacing that set.
+7. Applies the authorized merge transactionally and rolls back handled
+   failures.
+
+Unrelated existing files are preserved. Structural collisions, symlinks,
+unsafe ancestors, and an existing `liftoff.manifest.json` are blockers that
+`--force` cannot bypass.
+
+See [safety and consent](safety-and-consent.md) for the complete permission
+model.
+
+## Existing Liftoff project
+
+If the target already contains `liftoff.manifest.json`, do not run init again.
+Use:
+
+```bash
+liftoff validate
+liftoff update
+liftoff update --apply
+```
+
+Update is a read-only drift check unless `--apply` is present.
+
+## Existing non-Liftoff application
+
+Use migration when you want a fresh governed scaffold and a filtered source
+copy:
+
+```bash
+liftoff migrate ../legacy-app --region eastus --agents copilot,claude --yes
+```
+
+Migration requires a new or empty sibling target, runs the same readiness and
+framework pipeline, and leaves the source byte-for-byte unchanged. `--force`
+does not permit a non-empty migration target.
+
+Arbitrary existing Power Apps application migration is not currently
+supported.

package/docs/getting-started.md

@@ -0,0 +1,114 @@
+# Getting started
+
+Liftoff is an interactive project initializer for governed GenAI applications,
+standard APIs, and Power Apps code apps.
+
+## 1. Install the CLI
+
+Liftoff requires Node.js 20.19 or newer. Power Apps code app projects require
+Node.js 22.12 or newer for their generated framework.
+
+The canonical release registry is `https://registry.npmjs.org`:
+
+```bash
+npm view @msn-control/liftoff@latest version --registry=https://registry.npmjs.org
+npm install -g @msn-control/liftoff@latest --registry=https://registry.npmjs.org
+liftoff --version
+```
+
+Versions before 0.3.0 are unsupported and must not be used for new projects.
+If your organization requires a managed npm registry, query
+`@msn-control/liftoff@latest` through that registry and compare the version with
+canonical npm. Stop if the mirror is older or rejects the explicit current
+version; ask the mirror owner to synchronize or approve the release. Liftoff
+does not modify `.npmrc` or bypass registry policy.
+
+See [prerequisites](prerequisites.md) for the complete plan-derived tool model.
+
+## 2. Start interactive initialization
+
+From the directory that should contain the project, run:
+
+```bash
+liftoff init
+```
+
+The guided flow asks for:
+
+1. Project identity and workload: GenAI, API, or Power Apps code app.
+2. Only the architecture choices applicable to that workload.
+3. OpenSpec or Spec Kit.
+4. One or both coding agents. On a real TTY, Space toggles agents and Enter
+   confirms the selection.
+5. A Spec Kit default agent when both agents are selected.
+6. The optional Preview Code Apps plugin preference for Power Apps projects.
+7. Plan confirmation, workstation readiness, and any separate install or
+   overwrite permissions that are needed.
+
+Liftoff renders into temporary staging, runs the official framework initializer
+there, validates the complete result, and only then merges it into the target.
+
+## 3. Understand the target
+
+At the exact root of an existing Git worktree, `liftoff init` initializes that
+root in place. A supplied project name changes project identity; it does not
+create a child folder.
+
+In a non-Git directory, or from a directory below but not equal to a Git root,
+a project name creates a named child directory.
+
+Read [existing repositories](existing-repositories.md) before initializing a
+non-empty target.
+
+## 4. Validate the result
+
+Run maintenance commands from the generated project root:
+
+```bash
+liftoff validate
+liftoff doctor
+```
+
+`validate` checks durable generated artifacts and framework markers. `doctor`
+adds read-only workstation, runtime, authentication, dependency, and
+workload-specific diagnostics.
+
+Next steps depend on the selected workload:
+
+- GenAI and API projects: copy `.env.example` to `.env`, install the generated
+  stack dependencies, then use `liftoff dev` and `liftoff infra` to print local
+  development and infrastructure commands.
+- Power Apps projects: run `npm ci`, then `npm run dev`. Environment binding,
+  connector addition, and `power-apps push` are deliberately deferred.
+
+See [workloads](workloads.md) for exact generated outputs and deferred actions.
+
+## Noninteractive automation
+
+Use `liftoff plan` to resolve choices and preview requirements without writing
+files or running installers:
+
+```bash
+liftoff plan --type power-apps-code-app --spec openspec --agents copilot
+```
+
+Automation can pass the same options to `liftoff init`. Use `--yes` for project
+defaults and confirmation only. It does not authorize file replacement,
+machine-level tools, or project dependency installation. Those permissions
+remain independent.
+
+See the [CLI reference](cli-reference.md) and
+[safety and consent](safety-and-consent.md) before automating initialization.
+
+## Existing application migration
+
+`liftoff migrate <source>` scans a non-Liftoff application, creates a fresh
+sibling scaffold, and stages a filtered source copy for guided migration. The
+source remains byte-for-byte unchanged.
+
+```bash
+liftoff migrate ../legacy-app --region eastus --agents copilot,claude --yes
+```
+
+Power Apps migration from an arbitrary existing application is not part of the
+current workload contract.

package/docs/prerequisites.md

@@ -0,0 +1,99 @@
+# Prerequisites
+
+Liftoff derives workstation and project requirements from the complete resolved
+plan. A Power Apps project is not asked to install API or infrastructure tools,
+and a Go API is not asked to install Python.
+
+## Baseline
+
+- Liftoff CLI: Node.js 20.19 or newer.
+- Power Apps code app: Node.js 22.12 or newer.
+- Selected framework: the Liftoff-tested OpenSpec or Spec Kit contract.
+- Selected agents: GitHub Copilot, Claude Code, or both.
+
+API workloads additionally require their selected Python, Node.js, or Go
+runtime. GenAI uses Python 3.12 and the Python/FastAPI/PydanticAI stack.
+
+## Blocking and advisory checks
+
+Blocking checks must be ready before initialization can safely complete:
+
+- Required runtime and minimum version.
+- Selected spec framework CLI.
+- Every selected coding agent.
+
+Advisory checks describe useful but deferrable capabilities:
+
+- Docker CLI and daemon health for API workloads.
+- OpenTofu for generated Azure infrastructure.
+- Azure CLI and observable authentication health.
+- Optional Code Apps plugin state for Power Apps.
+
+Authentication checks are read-only. Liftoff never stores credentials or signs
+in to a cloud or agent on your behalf.
+
+## Preview requirements without writes
+
+`liftoff plan` shows both generated artifacts and workstation requirements
+without writing files or running installers:
+
+```bash
+liftoff plan --type power-apps-code-app --spec openspec --agents copilot,claude
+```
+
+## Tool installation consent
+
+Liftoff prints allowlisted commands before running them. Machine-level
+installation requires `--install-tools` or separate interactive approval.
+
+- macOS recipes use Homebrew, npm, or `uv`.
+- Windows recipes use WinGet, npm, or `uv`.
+- Linux system packages are never installed with automatic elevation. Liftoff
+  prints distribution-appropriate official guidance; npm and `uv` framework
+  recipes remain separately consented.
+
+An install that changes `PATH` is re-probed when possible and may require a new
+terminal. Do not treat installer success as readiness until the corresponding
+probe passes.
+
+## Project dependency consent
+
+Project-local dependency setup is separate from workstation tools and requires
+`--install-dependencies` or interactive approval after a successful project
+merge.
+
+For Power Apps, Liftoff runs only the root locked install:
+
+```bash
+npm ci
+```
+
+The generated `package.json` and `package-lock.json` are validated before
+installation and protected from installer mutation. If dependency setup is
+skipped or fails, Liftoff prints the exact resume command rather than claiming
+the project is ready.
+
+GenAI and API projects use their generated stack-native locked dependency
+commands.
+
+## Power Apps local CLI
+
+The Power Apps CLI is supplied by the generated project dependency graph.
+Liftoff checks it without downloading another package:
+
+```bash
+npx --no-install power-apps --version
+```
+
+If `node_modules` is absent, run `npm ci` first. Environment binding and cloud
+authentication remain separate later actions.
+
+## Agent detection
+
+Copilot can be detected through its CLI or supported VS Code extensions.
+Claude Code is checked with its version and doctor commands. When both are
+selected, both must be ready.
+
+The optional Code Apps plugin uses independent, read-only probes for each
+selected agent. A missing executable, timeout, or unsupported plugin-list
+result is reported as not observable rather than silently treated as missing.

package/docs/project-structure.md

@@ -0,0 +1,119 @@
+# Generated project structure
+
+Generated paths are logical examples. Liftoff uses platform-correct filesystem
+handling on Windows, macOS, and Linux, and manifests store path-part arrays
+instead of joined strings.
+
+## GenAI and API projects
+
+```text
+project/
+|-- README.md
+|-- liftoff.config.json
+|-- liftoff.manifest.json
+|-- .env.example
+|-- Dockerfile
+|-- docker-compose.yml
+|-- backend/
+|-- database/
+|   |-- alembic.ini or stack-native migration config
+|   |-- migrations/
+|   `-- models/ or schema/
+|-- environments/
+|   |-- dev/
+|   |-- test/
+|   `-- prod/
+|-- infrastructure/
+|   `-- opentofu/
+|       `-- azure/
+|-- openspec/ or .specify/
+|-- frontend/                  # only when selected
+|-- functions/<worker-name>/  # only for worker-enabled GenAI patterns
+`-- migration/legacy/         # only after liftoff migrate
+```
+
+### Core areas
+
+- `backend` contains the selected API stack and Scalar/OpenAPI wiring. Python
+  uses `backend/apis`, Node.js uses `backend/src`, and Go uses
+  `backend/cmd/api` plus `backend/internal`.
+- `backend/orchestration` appears only in GenAI projects and contains
+  PydanticAI agents, prompts, model configuration, and integration boundaries.
+- `database` contains SQLAlchemy/Alembic for Python, Drizzle for Node.js, or
+  pgx/Goose for Go.
+- `environments/<env>` contains environment-specific backend settings and
+  Functions settings when a worker is generated.
+- `docker-compose.yml` starts the selected backend, PostgreSQL, Redis,
+  Azurite, and Mailpit. GenAI projects use pgvector where needed and include an
+  optional Langfuse profile.
+- `infrastructure/opentofu/azure` contains modules, environment tfvars, local
+  state configuration, and a remote-state example.
+- `openspec` is created for OpenSpec. `.specify` and `specs` are created for
+  Spec Kit.
+
+### Conditional areas
+
+- `frontend` is generated only when selected. It uses Vue 3 and Tailwind with
+  a generic API starter or a GenAI experience matched to the pattern.
+- `functions/<worker-name>` appears for worker-enabled RAG, agent, multi-agent,
+  and workflow patterns.
+- `backend/workers` contains backend-adjacent or containerized worker code,
+  separate from Azure Functions runtime files.
+- `migration/legacy` contains the filtered source copy created by migration.
+
+## Power Apps code app
+
+```text
+project/
+|-- README.md
+|-- THIRD_PARTY_NOTICES.md
+|-- liftoff.config.json
+|-- liftoff.manifest.json
+|-- package.json
+|-- package-lock.json
+|-- index.html
+|-- vite.config.ts
+|-- eslint.config.js
+|-- tsconfig.json
+|-- public/
+|-- src/
+|   |-- App.tsx
+|   |-- main.tsx
+|   |-- router.tsx
+|   |-- components/
+|   |-- hooks/
+|   |-- pages/
+|   `-- providers/
+`-- openspec/ or .specify/
+```
+
+This root follows the pinned official Microsoft starter. It includes the
+Power Apps SDK, Vite plugin, and project-local CLI through locked npm
+dependencies.
+
+Liftoff intentionally does not generate `backend/`, `database/`,
+`docker-compose.yml`, `environments/`, `infrastructure/`, or
+`power.config.json` for this workload.
+
+## GenAI integration configuration
+
+Generated GenAI projects expose real configuration boundaries instead of
+success-shaped placeholders:
+
+- `PYDANTIC_AI_MODEL` selects the production model. An unconfigured production
+  invocation fails clearly.
+- Redis Streams uses `REDIS_URL` and `REDIS_STREAM_NAME`.
+- Azure Service Bus uses `SERVICE_BUS_QUEUE_NAME` and either
+  `SERVICE_BUS_CONNECTION_STRING` or
+  `SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE`; `AZURE_CLIENT_ID` selects a
+  user-assigned managed identity.
+- Langfuse requires both `LANGFUSE_PUBLIC_KEY` and
+  `LANGFUSE_SECRET_KEY`, with optional `LANGFUSE_HOST`. Without both keys,
+  tracing is explicitly disabled.
+- Frontends read `VITE_API_BASE_URL`, call the route selected by the pattern or
+  API stack, and expose loading, response, and failure states.
+- Backends allow the local frontend origin by default.
+  `CORS_ALLOWED_ORIGINS` configures additional origins.
+
+Generated backend, messaging, tracing, orchestration, and frontend tests do not
+require a live model, Redis, Service Bus, or Langfuse service.

package/docs/safety-and-consent.md

@@ -0,0 +1,98 @@
+# Safety and consent
+
+Liftoff separates project decisions, file replacement, workstation tools, and
+project dependencies. No one permission implies another.
+
+## Consent flags
+
+| Flag | Authorizes | Does not authorize |
+| --- | --- | --- |
+| `--yes` | Project defaults and plan confirmation | File replacement, machine installs, or project dependencies |
+| `--force` | Only listed and validated regular-file replacements | Manifest guards, symlinks, structural collisions, tools, dependencies, or non-empty migration targets |
+| `--install-tools` | Allowlisted workstation installation commands | Project decisions, overwrites, or project dependencies |
+| `--install-dependencies` | Locked project-local dependency commands after a successful merge | Machine tools, project decisions, or overwrites |
+
+Interactive sessions ask separately at the point each permission is needed.
+
+## Staged initialization
+
+Initialization does not write generated files directly into the destination.
+Liftoff:
+
+1. Resolves and validates a project plan.
+2. Renders Liftoff-owned artifacts into a temporary staging directory.
+3. Runs the official OpenSpec or Spec Kit initializer in staging.
+4. Rejects nested Git metadata, unexpected framework roots, symlinks, and
+   malformed output.
+5. Validates the full staged project.
+6. Computes one immutable destination preflight.
+7. Shows every different regular file that would be replaced.
+8. Applies only an authorized preflight.
+
+Unrelated destination files are preserved.
+
+## Overwrite boundaries
+
+A different regular file can be replaced only after explicit permission.
+Structural collisions are not overridable:
+
+- A generated file collides with a directory or another non-file entry.
+- An ancestor is not a directory.
+- A path is a symlink or escapes the project root through one.
+- The destination already contains `liftoff.manifest.json`.
+- A migration target is non-empty.
+
+`--force` cannot weaken these guards.
+
+## Atomic writes and rollback
+
+Individual project files use temporary-file replacement. Initialization keeps
+backups for replaced files and records created files and directories. A handled
+merge failure restores or removes those entries in reverse order.
+
+`liftoff update --apply` preflights all affected paths and applies generated
+file, move, delete, and manifest mutations as one rollback-capable
+transaction. Schema upgrades are committed only after the other mutations
+succeed. A corrected retry converges from the restored state.
+
+If automatic rollback itself cannot safely restore a path because another
+process changed it, Liftoff reports the incomplete rollback rather than
+overwriting unknown bytes.
+
+## Update ownership
+
+`liftoff update` is read-only by default:
+
+- Clean generated files remain unchanged.
+- New, missing, untouched-upgrade, and clean-move states can be applied.
+- Developer edits that also differ from the current template are conflicts.
+- Conflicts are skipped unless `--apply --force` is explicitly supplied.
+- Orphans are reported and left on disk for manual review.
+
+Power Apps reconciliation reads only the packaged immutable starter. It does
+not fetch the upstream repository. Workload kind and user-edited starter
+repository, template path, or commit changes are rejected before artifact
+access.
+
+## Framework and seed ownership
+
+OpenSpec and Spec Kit core/integration output is owned by their official
+initializers. Liftoff validates the selected contract and agent markers but
+does not claim framework-owned files in durable artifact hashes.
+
+One-time seed content is also omitted from durable hashes so it can follow its
+own lifecycle after generation.
+
+## Credentials and external actions
+
+Generated files contain configuration boundaries, not real credentials.
+Liftoff does not:
+
+- Modify `.npmrc` to bypass a managed registry.
+- Store cloud or agent credentials.
+- Perform cloud sign-in.
+- Apply OpenTofu.
+- Bind or push a Power Apps code app.
+- Run Microsoft's broad Code Apps marketplace installer.
+
+Those actions require their own review, authentication, and consent.