@msn-control/liftoff 0.4.0 → 0.5.0

package/docs/spec-workflows-and-agents.md

@@ -0,0 +1,92 @@
+# Spec workflows and agents
+
+Spec-driven governance and coding-agent integration are common to every
+Liftoff workload.
+
+## Choose a spec workflow
+
+### OpenSpec
+
+OpenSpec organizes proposed behavior changes as reviewable artifacts before
+implementation. Liftoff runs the pinned official OpenSpec initializer in
+temporary staging and passes every selected coding agent in stable order.
+
+Generated projects contain `openspec/` plus the selected agent integration
+markers.
+
+### Spec Kit
+
+Spec Kit provides a specification, planning, and implementation workflow.
+Liftoff initializes the selected default coding agent first, adds every
+secondary integration, and records the default separately from the full agent
+set.
+
+Generated projects contain `.specify/`, `specs/`, and the selected agent
+integration markers.
+
+Liftoff does not hand-write framework-owned core or integration output. It
+executes the tested official initializer, confines its writes to allowed roots,
+and validates the declared markers before merging.
+
+## Select coding agents
+
+Liftoff supports:
+
+- GitHub Copilot.
+- Claude Code.
+- Both agents together.
+
+On a real TTY, use the arrow keys to move, Space to mark or unmark an agent,
+and Enter to confirm. At least one agent is required.
+
+When standard input is redirected, the deterministic fallback accepts a
+comma-separated value such as:
+
+```text
+copilot,claude
+```
+
+Noninteractive commands use:
+
+```bash
+--agents copilot,claude
+```
+
+Spec Kit additionally requires `--default-agent copilot` or
+`--default-agent claude` when both are selected. OpenSpec does not record a
+default agent.
+
+## Readiness and ownership
+
+The selected framework CLI and every selected agent are blocking workstation
+requirements. Liftoff may detect Copilot through its CLI or supported VS Code
+extensions. Claude Code is checked through version and health probes.
+
+Framework files remain owned by the official initializer. Liftoff validates
+them but excludes framework-owned output from durable artifact hashes so a
+framework can manage its own lifecycle.
+
+## Optional Code Apps plugin
+
+Power Apps projects can request Microsoft's
+`code-apps-preview@power-platform-skills` plugin. The integration is optional,
+Preview, and independent for each selected agent.
+
+Liftoff runs only allowlisted read-only plugin-list probes. A missing or
+unobservable plugin produces advisory guidance and never makes initialization
+or doctor fail by itself.
+
+Install the targeted plugin manually inside the selected agent:
+
+```text
+/plugin marketplace add microsoft/power-platform-skills
+/plugin install code-apps-preview@power-platform-skills
+```
+
+Liftoff does not run Microsoft's broad marketplace installer and does not
+invoke `/create-code-app`. The plugin's connector and deployment skills remain
+available for post-creation work.
+
+Changing the valid plugin preference in `liftoff.config.json` is reconciled by
+`liftoff update`; it updates generated guidance and manifest intent without
+creating API or infrastructure artifacts.

package/docs/troubleshooting.md

@@ -0,0 +1,133 @@
+# Troubleshooting
+
+## The installed version is older than canonical npm
+
+Check the canonical release:
+
+```bash
+npm view @msn-control/liftoff@latest version --registry=https://registry.npmjs.org
+liftoff --version
+```
+
+Versions before 0.3.0 are unsupported.
+
+If a managed registry exposes an older version, stop onboarding and ask the
+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.
+
+## An installed tool is still reported missing
+
+Installers that change `PATH` may require a new terminal. Open one, rerun:
+
+```bash
+liftoff doctor
+```
+
+Do not assume installer exit code 0 proves readiness; the requirement probe
+must pass.
+
+## Initialization wants to create a child folder
+
+In-place initialization occurs only when the current directory exactly matches
+the Git worktree root:
+
+```bash
+git rev-parse --show-toplevel
+pwd
+```
+
+Change to that root and rerun `liftoff init`. See
+[existing repositories](existing-repositories.md).
+
+## Initialization reports replacement conflicts
+
+Review the complete replacement list. Approve interactively or rerun with
+`--force` only when every listed regular file may be replaced.
+
+`--force` cannot bypass directories, symlinks, unsafe ancestors, an existing
+manifest, or a non-empty migration target. Move or rename the structural
+conflict and retry.
+
+## A handled write failed
+
+Liftoff reports whether rollback completed. Correct the filesystem problem and
+retry. If rollback was incomplete, stop and inspect every reported path before
+running another write command.
+
+## Validation reports a malformed or unsafe manifest
+
+Manifest paths must be portable path-part arrays confined to the project.
+Traversal, absolute, drive-qualified, UNC, embedded-separator, empty, and
+symlink-escaping paths are rejected before artifact access.
+
+Restore `liftoff.manifest.json` from version control or regenerate the project
+with the matching Liftoff version. Do not weaken path validation or retain a
+hand-edited unsafe path.
+
+## Update reports conflicts or orphans
+
+`liftoff update` does not write. Review the report:
+
+- Apply safe changes with `liftoff update --apply`.
+- Developer conflicts remain untouched unless you explicitly use
+  `liftoff update --apply --force`.
+- Orphans are never deleted automatically.
+
+Commit local work before applying when possible.
+
+## Power Apps dependencies or CLI are missing
+
+From the project root:
+
+```bash
+npm ci
+npx --no-install power-apps --version
+npm run dev
+```
+
+The CLI is project-local. Do not replace the locked install with an unrelated
+global package.
+
+## The Code Apps plugin is missing or not observable
+
+Plugin state is advisory. In each selected agent session, use:
+
+```text
+/plugin marketplace add microsoft/power-platform-skills
+/plugin install code-apps-preview@power-platform-skills
+```
+
+Then rerun `liftoff doctor`. Do not run `/create-code-app` in a Liftoff project.
+Liftoff does not run Microsoft's broad plugin installer.
+
+## Terminal output is hard to read or being captured
+
+Rich output requires a wide TTY. Redirected output automatically uses
+deterministic plain text. To disable color while retaining layout:
+
+```bash
+NO_COLOR=1 liftoff doctor
+```
+
+Use `--json` with validate, doctor, or update for machine consumption.
+
+## `liftoff create` is rejected
+
+Use:
+
+```bash
+liftoff init
+```
+
+The old command has no compatibility alias.
+
+## Get command syntax
+
+```bash
+liftoff help
+liftoff init --help
+liftoff update --help
+```
+
+Unknown or incompatible inputs fail instead of falling back to another action.

package/docs/workloads.md

@@ -0,0 +1,128 @@
+# Workloads
+
+Liftoff asks for one workload first, then routes only the questions,
+prerequisites, generated artifacts, and maintenance checks that apply to it.
+
+## At a glance
+
+| 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 |
+
+All three workloads continue into the common OpenSpec or Spec Kit and coding
+agent flow.
+
+## GenAI application
+
+### Questions
+
+- Project name.
+- GenAI pattern such as prompt, chatbot, RAG, agent, multi-agent, or workflow.
+- Azure region and generated environments.
+- Whether to generate a frontend.
+- Spec workflow and coding agents.
+
+The selected pattern fixes the API stack to Python, FastAPI, and PydanticAI.
+
+### Generated output
+
+- FastAPI backend and Scalar/OpenAPI integration.
+- 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.
+
+### Deferred actions
+
+Liftoff does not insert model credentials, sign in to cloud services, or deploy
+resources. Configure `.env`, authenticate separately, and review generated
+infrastructure before applying it.
+
+## API application
+
+### Questions
+
+- Project name.
+- API stack: Python/FastAPI, Node.js/Fastify with TypeScript, or Go/Huma v2
+  with Chi.
+- Azure region and generated environments.
+- Whether to generate a frontend.
+- Spec workflow and coding agents.
+
+### Generated output
+
+- Stack-native API, OpenAPI, tests, and database migrations.
+- PostgreSQL, Redis, Azurite, and Mailpit local services where applicable.
+- Docker Compose and Azure OpenTofu.
+- Optional Vue frontend.
+
+### Deferred actions
+
+Service secrets, cloud authentication, external integrations, and deployment
+remain explicit developer or delivery-pipeline actions.
+
+## Power Apps code app
+
+Power Apps uses an immutable, packaged snapshot of Microsoft's official
+[`PowerAppsCodeApps/templates/starter`](https://github.com/microsoft/PowerAppsCodeApps/tree/main/templates/starter).
+Initialization and update do not fetch the mutable upstream branch.
+
+### Questions
+
+- Project name.
+- OpenSpec or Spec Kit.
+- GitHub Copilot, Claude Code, or both.
+- Spec Kit default agent when both are selected.
+- Whether to request the optional Microsoft Code Apps agent plugin
+  (Preview).
+
+Power Apps does not ask for an API stack, GenAI pattern, cloud, region, API
+environment, API frontend, Docker, or OpenTofu selection.
+
+### Generated output
+
+- 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,
+  and third-party attribution.
+- Official OpenSpec or Spec Kit output and every selected agent marker.
+
+Liftoff does not create an API backend, `docker-compose.yml`,
+`infrastructure/`, API environments, or an environment-bound
+`power.config.json` for this workload.
+
+### Deferred actions
+
+After initialization:
+
+```bash
+npm ci
+npm run dev
+npx --no-install power-apps --version
+```
+
+Environment binding, connector creation, authentication, and deployment remain
+outside initialization. Follow Microsoft's current Code Apps documentation
+before running `power-apps init` or `power-apps push`.
+
+If the optional Code Apps plugin was requested, install only the targeted
+plugin from an agent session:
+
+```text
+/plugin marketplace add microsoft/power-platform-skills
+/plugin install code-apps-preview@power-platform-skills
+```
+
+Do not run `/create-code-app` inside the generated project; Liftoff already
+created the application.
+
+## Change workload later
+
+`liftoff update` reconciles supported desired-state changes within the recorded
+workload. It does not convert among GenAI, API, and Power Apps or change an API
+stack, GenAI pattern, or user-supplied starter identity. Initialize a fresh
+project or use a supported migration flow instead.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@msn-control/liftoff",
-  "version": "0.4.0",
-  "description": "Mission Control Liftoff CLI for scaffolding governed GenAI and standard API applications.",
+  "version": "0.5.0",
+  "description": "Interactive CLI for governed GenAI, API, and Power Apps code app projects.",
   "type": "module",
   "license": "GPL-3.0-only",
   "homepage": "https://github.com/voyager163/liftoff#readme",
@@ -21,6 +21,7 @@
     "fastify",
     "golang",
     "pydanticai",
+    "power-apps",
     "opentofu",
     "openspec",
     "mission-control"
@@ -31,6 +32,8 @@
   "files": [
     "dist",
     "assets/locks",
+    "assets/power-apps-code-app",
+    "docs",
     "README.md",
     "LICENSE"
   ],
@@ -41,7 +44,9 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",
+    "refresh:power-apps-starter": "node scripts/refresh-power-apps-starter.mjs",
     "smoke:package": "npm run build && node scripts/package-smoke-test.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"
@@ -56,6 +61,7 @@
     "vitest": "^4.1.9"
   },
   "dependencies": {
+    "@inquirer/prompts": "^7.10.1",
     "cross-spawn": "^7.0.6",
     "picocolors": "^1.1.1"
   }