newstack 0.1.0__tar.gz → 0.3.0__tar.gz

newstack-0.3.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-11-02
+
+### Added
+
+- **`newstack adopt <dir>`** — retrofit a stack's infrastructure onto a project that already
+  has code. Additive by construction: an existing file is never opened for writing, and any
+  change that would need a merge inside a file is reported as a manual step instead.
+  - Auto-detects the stack from the project's own markers (`go.mod`, `Cargo.toml`,
+    `manage.py`, `pyproject.toml`/`package.json` contents, a bare `index.html`); ambiguous
+    matches print candidates and exit 2; `--stack` overrides.
+  - Copies infrastructure only — workflows, `.gitignore`, lint/type config — never a
+    README, LICENSE, `pyproject.toml`, `package.json`, `go.mod` or source file.
+  - `--dry-run` reports without writing; re-running is a no-op; `--json` for scripting.
+  - `--with-tests` (experimental) also copies the stack's starter tests.
+- Manifest keys `detect`, `detect_fallback`, `adopt` and `adopt_tests`, validated by the
+  registry and by tests that require every adoptable path to exist and to be infrastructure.
+
+### Changed
+
+- `newstack new` and `adopt` share one step formatter, so an unknown `{placeholder}` in a
+  manifest's `next_steps` prints literally instead of raising `KeyError`.
+
+## [0.2.0] - 2026-11-02
+
+### Added
+
+- Four new stacks, all verified the same way as the original six:
+  - `go-cli` — stdlib `flag` parsing, table tests, vet/test/build gates.
+  - `rust-cli` — std-only parsing, lib+bin split, fmt/clippy/test/release gates.
+  - `django` — Django 6.1, config/core split, SQLite, pytest-django, and a
+    migration-drift step that fails when a model changes without a migration.
+  - `svelte-kit-ts` — SvelteKit 3 with Svelte 5 runes, Vitest, static adapter build.
+- CI runs one job per stack (ten in total), with Go and Rust toolchains installed only
+  for the jobs that need them.
+- Docs drift tests: the README table and the CI matrix must both list every registered
+  stack, and the README may not hardcode a stack count.
+
+### Changed
+
+- Install instructions now point at PyPI (`uvx newstack`, `uv tool install newstack`).
+
+## [0.1.0] - 2026-11-02
+
+### Added
+
+- `newstack new <stack> <path>` — render a stack, initialise git, first commit.
+- `newstack new … --github [OWNER/REPO]` — create the GitHub repository and push.
+- `newstack list` — every stack with its toolchain requirements, `--json` supported.
+- `newstack check <stack…> | --all` — generate into a temp dir and run the stack's own
+  verification steps (`install`, `lint`, `test`, `build`), reported per step.
+- `newstack doctor` — which toolchains are installed, which stacks can be verified here.
+- Six stacks: `python-lib`, `python-cli`, `fastapi`, `react-vite-ts`, `node-express-ts`,
+  `static-site`.
+- Stack registry is extensible through the `NEWSTACK_STACKS` environment variable.
+- Zero runtime dependencies: standard library only.

{newstack-0.1.0 → newstack-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: newstack
-Version: 0.1.0
+Version: 0.3.0
 Summary: Scaffold a new project on any popular stack — every generated starter is proven green in CI.
 Project-URL: Homepage, https://github.com/DawnofGenX/newstack
 Project-URL: Repository, https://github.com/DawnofGenX/newstack
@@ -25,6 +25,7 @@ Description-Content-Type: text/markdown
 # newstack
 
 [![CI](https://github.com/DawnofGenX/newstack/actions/workflows/ci.yml/badge.svg)](https://github.com/DawnofGenX/newstack/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/newstack)](https://pypi.org/project/newstack/)
 ![python](https://img.shields.io/badge/python-3.10%2B-blue)
 ![dependencies](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
@@ -61,12 +62,10 @@ first day of work.
 
 ## Install
 
-Not on PyPI yet — install straight from the repository:
-
 ```bash
-uv tool install git+https://github.com/DawnofGenX/newstack
-# or, without installing:
-uvx --from git+https://github.com/DawnofGenX/newstack newstack list
+uvx newstack list          # run without installing
+uv tool install newstack   # or put it on your PATH
+pipx install newstack      # any of the usual runners works
 ```
 
 From a clone:
@@ -84,6 +83,7 @@ newstack new react-vite-ts ~/code/app
 newstack new fastapi ~/code/api -d "Billing service" --author "Your Name"
 newstack new python-lib ~/code/lib --dry-run     # preview, write nothing
 newstack new python-cli ~/code/tool --github     # create the repo and push it too
+newstack adopt ~/code/old-project --dry-run    # retrofit CI/lint onto existing code
 newstack check --all                # prove every stack on this machine
 newstack doctor                     # which toolchains do I have?
 ```
@@ -101,13 +101,46 @@ directory to CI-ready project.
 | `python-lib` | src layout, hatchling build, pytest, ruff, 4-version CI matrix | `uv` |
 | `python-cli` | console entry point on argparse, zero runtime deps, tested CLI | `uv` |
 | `fastapi` | typed JSON API, pydantic models, TestClient tests, Dockerfile | `uv` |
+| `django` | Django 6.1 app: config/core split, SQLite, pytest-django, migration drift check | `uv` |
 | `react-vite-ts` | React 19 + Vite + TS, Vitest + Testing Library, typecheck + build | `node`, `npm` |
 | `node-express-ts` | Express 5 API, typed handlers, supertest tests | `node`, `npm` |
-| `static-site` | HTML/CSS/JS page with a GitHub Pages deploy workflow | `node` |
+| `svelte-kit-ts` | SvelteKit + TS, Svelte 5 runes component, Vitest, static adapter build | `node`, `npm` |
+| `go-cli` | stdlib-only Go CLI: `flag` parsing, table tests, vet/test/build gates | `go` |
+| `rust-cli` | std-only Rust CLI: lib+bin split, fmt/clippy/test/release-build gates | `cargo` |
+| `static-site` | HTML/CSS/JS page, `node:test` suite, GitHub Pages deploy workflow | `node` |
 
 Each generated project ships its own `.github/workflows/` that is ready to run, plus a
 README, an MIT licence and a `.gitignore`.
 
+## Adopting an existing project
+
+Most projects do not start from a scaffold. `adopt` retrofits a stack's *infrastructure*
+onto a directory that already has code — and it is additive by construction: **an existing
+file is never opened for writing.**
+
+```console
+$ newstack adopt ~/sites/analytics-dashboard
+newstack 0.3.0  ·  adopt  →  /home/you/sites/analytics-dashboard
+
+  stack        static-site (auto-detected)
+  added        2 files
+      + .github/workflows/deploy-pages.yml
+      + .gitignore
+  tests        not copied — rerun with --with-tests if you want starter tests
+```
+
+- **Detection** reads the project's own markers (`go.mod`, `Cargo.toml`, `manage.py`, the
+  dependencies in `pyproject.toml` / `package.json`, a bare `index.html`). If two stacks
+  match, it prints the candidates and exits 2 rather than guessing; `--stack` overrides.
+- **Scope**: workflows, `.gitignore`, and per-stack lint/type config only. It will not copy
+  a README, a LICENSE, a `pyproject.toml`, or source files — those carry your project's
+  identity, not infrastructure.
+- **Merges are reported, not attempted.** If your `pyproject.toml` needs the stack's
+  `[tool.ruff]` block, adopt says so and leaves the file alone.
+- `--dry-run` prints the same report without writing. Re-running is a no-op.
+- `--with-tests` additionally copies the stack's *starter* tests — experimental, because
+  those tests import the sample module and usually need adapting to your code.
+
 ## The green guarantee
 
 A template is only as good as its last successful run, so `newstack` treats
@@ -115,12 +148,16 @@ verification as a first-class command:
 
 ```console
 $ newstack check --all
-  fastapi          PASS    1.0s  3 step(s)
-  node-express-ts  PASS    2.2s  3 step(s)
+  django           PASS    1.5s  5 step(s)
+  fastapi          PASS    1.4s  3 step(s)
+  go-cli           PASS    0.3s  3 step(s)
+  node-express-ts  PASS    6.1s  3 step(s)
   python-cli       PASS    0.5s  4 step(s)
-  python-lib       PASS    0.4s  3 step(s)
-  react-vite-ts    PASS    3.2s  4 step(s)
+  python-lib       PASS    0.5s  3 step(s)
+  react-vite-ts    PASS    5.5s  4 step(s)
+  rust-cli         PASS    0.5s  4 step(s)
   static-site      PASS    0.1s  3 step(s)
+  svelte-kit-ts    PASS    7.1s  4 step(s)
 ```
 
 (Real timings from a warm package cache — a cold run takes about a minute because
@@ -147,7 +184,10 @@ without maintaining one template per stack.
 
 ## Adding a stack
 
-A stack is a directory with a manifest and a template tree:
+A stack is a directory with a manifest and a template tree. The manifest carries four
+optional keys beyond the basics — `detect` (how a directory is recognised as this stack),
+`detect_fallback` (a generic stack that must lose to a specific match), and the `adopt` /
+`adopt_tests` allow-lists used by `newstack adopt`:
 
 ```text
 src/newstack/data/stacks/my-stack/
@@ -169,10 +209,16 @@ src/newstack/data/stacks/my-stack/
   "next_steps": ["cd {path}", "uv run pytest"],
   "verify": [
     {"name": "test", "cmd": "uv run pytest", "tools": ["uv"], "timeout": 600}
-  ]
+  ],
+  "detect": [{"file": "pyproject.toml", "contains": "my-framework"}],
+  "adopt": [".github/workflows/ci.yml", ".gitignore"],
+  "adopt_tests": ["tests/test_smoke.py"]
 }
 ```
 
+`adopt` entries must exist in the template and must never be an identity file
+(`README.md`, `LICENSE`, `pyproject.toml`, `package.json`, `go.mod`, `Cargo.toml`) — a
+test enforces both rules.<br>
 `{{!` escapes a literal `{{`, and `${{ ... }}` (GitHub Actions) is left untouched.
 Point `NEWSTACK_STACKS` at a directory of your own stacks to use private ones — same
 manifest format, no fork required.
@@ -189,7 +235,7 @@ manifest format, no fork required.
 ## Roadmap
 
 - `newstack update` — re-apply upstream template changes to an existing project.
-- More stacks: Go service, Rust CLI, Django, Vue, SvelteKit.
+- More stacks: Vue, Next.js, Flask.
 - `--license apache-2.0|bsd-3` and other variable choices beyond the current defaults.
 
 ## Licence

{newstack-0.1.0 → newstack-0.3.0}/README.md

@@ -1,6 +1,7 @@
 # newstack
 
 [![CI](https://github.com/DawnofGenX/newstack/actions/workflows/ci.yml/badge.svg)](https://github.com/DawnofGenX/newstack/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/newstack)](https://pypi.org/project/newstack/)
 ![python](https://img.shields.io/badge/python-3.10%2B-blue)
 ![dependencies](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
@@ -37,12 +38,10 @@ first day of work.
 
 ## Install
 
-Not on PyPI yet — install straight from the repository:
-
 ```bash
-uv tool install git+https://github.com/DawnofGenX/newstack
-# or, without installing:
-uvx --from git+https://github.com/DawnofGenX/newstack newstack list
+uvx newstack list          # run without installing
+uv tool install newstack   # or put it on your PATH
+pipx install newstack      # any of the usual runners works
 ```
 
 From a clone:
@@ -60,6 +59,7 @@ newstack new react-vite-ts ~/code/app
 newstack new fastapi ~/code/api -d "Billing service" --author "Your Name"
 newstack new python-lib ~/code/lib --dry-run     # preview, write nothing
 newstack new python-cli ~/code/tool --github     # create the repo and push it too
+newstack adopt ~/code/old-project --dry-run    # retrofit CI/lint onto existing code
 newstack check --all                # prove every stack on this machine
 newstack doctor                     # which toolchains do I have?
 ```
@@ -77,13 +77,46 @@ directory to CI-ready project.
 | `python-lib` | src layout, hatchling build, pytest, ruff, 4-version CI matrix | `uv` |
 | `python-cli` | console entry point on argparse, zero runtime deps, tested CLI | `uv` |
 | `fastapi` | typed JSON API, pydantic models, TestClient tests, Dockerfile | `uv` |
+| `django` | Django 6.1 app: config/core split, SQLite, pytest-django, migration drift check | `uv` |
 | `react-vite-ts` | React 19 + Vite + TS, Vitest + Testing Library, typecheck + build | `node`, `npm` |
 | `node-express-ts` | Express 5 API, typed handlers, supertest tests | `node`, `npm` |
-| `static-site` | HTML/CSS/JS page with a GitHub Pages deploy workflow | `node` |
+| `svelte-kit-ts` | SvelteKit + TS, Svelte 5 runes component, Vitest, static adapter build | `node`, `npm` |
+| `go-cli` | stdlib-only Go CLI: `flag` parsing, table tests, vet/test/build gates | `go` |
+| `rust-cli` | std-only Rust CLI: lib+bin split, fmt/clippy/test/release-build gates | `cargo` |
+| `static-site` | HTML/CSS/JS page, `node:test` suite, GitHub Pages deploy workflow | `node` |
 
 Each generated project ships its own `.github/workflows/` that is ready to run, plus a
 README, an MIT licence and a `.gitignore`.
 
+## Adopting an existing project
+
+Most projects do not start from a scaffold. `adopt` retrofits a stack's *infrastructure*
+onto a directory that already has code — and it is additive by construction: **an existing
+file is never opened for writing.**
+
+```console
+$ newstack adopt ~/sites/analytics-dashboard
+newstack 0.3.0  ·  adopt  →  /home/you/sites/analytics-dashboard
+
+  stack        static-site (auto-detected)
+  added        2 files
+      + .github/workflows/deploy-pages.yml
+      + .gitignore
+  tests        not copied — rerun with --with-tests if you want starter tests
+```
+
+- **Detection** reads the project's own markers (`go.mod`, `Cargo.toml`, `manage.py`, the
+  dependencies in `pyproject.toml` / `package.json`, a bare `index.html`). If two stacks
+  match, it prints the candidates and exits 2 rather than guessing; `--stack` overrides.
+- **Scope**: workflows, `.gitignore`, and per-stack lint/type config only. It will not copy
+  a README, a LICENSE, a `pyproject.toml`, or source files — those carry your project's
+  identity, not infrastructure.
+- **Merges are reported, not attempted.** If your `pyproject.toml` needs the stack's
+  `[tool.ruff]` block, adopt says so and leaves the file alone.
+- `--dry-run` prints the same report without writing. Re-running is a no-op.
+- `--with-tests` additionally copies the stack's *starter* tests — experimental, because
+  those tests import the sample module and usually need adapting to your code.
+
 ## The green guarantee
 
 A template is only as good as its last successful run, so `newstack` treats
@@ -91,12 +124,16 @@ verification as a first-class command:
 
 ```console
 $ newstack check --all
-  fastapi          PASS    1.0s  3 step(s)
-  node-express-ts  PASS    2.2s  3 step(s)
+  django           PASS    1.5s  5 step(s)
+  fastapi          PASS    1.4s  3 step(s)
+  go-cli           PASS    0.3s  3 step(s)
+  node-express-ts  PASS    6.1s  3 step(s)
   python-cli       PASS    0.5s  4 step(s)
-  python-lib       PASS    0.4s  3 step(s)
-  react-vite-ts    PASS    3.2s  4 step(s)
+  python-lib       PASS    0.5s  3 step(s)
+  react-vite-ts    PASS    5.5s  4 step(s)
+  rust-cli         PASS    0.5s  4 step(s)
   static-site      PASS    0.1s  3 step(s)
+  svelte-kit-ts    PASS    7.1s  4 step(s)
 ```
 
 (Real timings from a warm package cache — a cold run takes about a minute because
@@ -123,7 +160,10 @@ without maintaining one template per stack.
 
 ## Adding a stack
 
-A stack is a directory with a manifest and a template tree:
+A stack is a directory with a manifest and a template tree. The manifest carries four
+optional keys beyond the basics — `detect` (how a directory is recognised as this stack),
+`detect_fallback` (a generic stack that must lose to a specific match), and the `adopt` /
+`adopt_tests` allow-lists used by `newstack adopt`:
 
 ```text
 src/newstack/data/stacks/my-stack/
@@ -145,10 +185,16 @@ src/newstack/data/stacks/my-stack/
   "next_steps": ["cd {path}", "uv run pytest"],
   "verify": [
     {"name": "test", "cmd": "uv run pytest", "tools": ["uv"], "timeout": 600}
-  ]
+  ],
+  "detect": [{"file": "pyproject.toml", "contains": "my-framework"}],
+  "adopt": [".github/workflows/ci.yml", ".gitignore"],
+  "adopt_tests": ["tests/test_smoke.py"]
 }
 ```
 
+`adopt` entries must exist in the template and must never be an identity file
+(`README.md`, `LICENSE`, `pyproject.toml`, `package.json`, `go.mod`, `Cargo.toml`) — a
+test enforces both rules.<br>
 `{{!` escapes a literal `{{`, and `${{ ... }}` (GitHub Actions) is left untouched.
 Point `NEWSTACK_STACKS` at a directory of your own stacks to use private ones — same
 manifest format, no fork required.
@@ -165,7 +211,7 @@ manifest format, no fork required.
 ## Roadmap
 
 - `newstack update` — re-apply upstream template changes to an existing project.
-- More stacks: Go service, Rust CLI, Django, Vue, SvelteKit.
+- More stacks: Vue, Next.js, Flask.
 - `--license apache-2.0|bsd-3` and other variable choices beyond the current defaults.
 
 ## Licence

{newstack-0.1.0 → newstack-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "newstack"
-version = "0.1.0"
+version = "0.3.0"
 description = "Scaffold a new project on any popular stack — every generated starter is proven green in CI."
 readme = "README.md"
 requires-python = ">=3.10"

{newstack-0.1.0 → newstack-0.3.0}/src/newstack/__init__.py

@@ -1,4 +1,4 @@
 """newstack — scaffold a new project on any popular stack, proven green in CI."""
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 __all__ = ["__version__"]

newstack-0.3.0/src/newstack/adopt.py

@@ -0,0 +1,160 @@
+"""Adopt an existing project: copy a stack's infrastructure, additively.
+
+The rule that makes this safe: an existing file is never opened for writing. Anything
+already present is reported as "kept", and anything that would need a merge inside a
+file (a ruff block in someone's pyproject, a test script in their package.json) is
+reported as a manual step instead of being attempted.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .registry import Stack, load_stacks
+from .render import TemplateError, render_tree
+
+# Files adopt must never copy into someone else's project: they carry identity
+# (licence, name, entrypoints) rather than infrastructure.
+FORBIDDEN = frozenset(
+    {
+        "README.md",
+        "README.rst",
+        "LICENSE",
+        "LICENSE.md",
+        "pyproject.toml",
+        "package.json",
+        "go.mod",
+        "Cargo.toml",
+    }
+)
+
+
+@dataclass
+class PendingFile:
+    rel: str
+    payload: bytes
+    executable: bool = False
+
+
+@dataclass
+class AdoptionPlan:
+    stack: Stack
+    root: Path
+    detected: bool = True
+    add: list[PendingFile] = field(default_factory=list)
+    keep: list[str] = field(default_factory=list)
+    manual: list[str] = field(default_factory=list)
+    tests_available: bool = False
+
+    @property
+    def added(self) -> list[str]:
+        return [item.rel for item in self.add]
+
+    def as_dict(self) -> dict:
+        return {
+            "stack": self.stack.name,
+            "root": str(self.root),
+            "detected": self.detected,
+            "added": self.added,
+            "kept": self.keep,
+            "manual": self.manual,
+            "tests_available": self.tests_available,
+        }
+
+
+def detect_stacks(root: Path) -> list[Stack]:
+    """Stacks whose markers match *root*; generic fallbacks are dropped on a specific match."""
+    stacks = load_stacks()
+    matched = [stack for stack in stacks.values() if stack.detect and stack.matches(root)]
+    specific = [stack for stack in matched if not stack.detect_fallback]
+    fallbacks = [stack for stack in matched if stack.detect_fallback]
+    return specific or fallbacks
+
+
+def _manual_steps(stack: Stack, root: Path) -> list[str]:
+    steps: list[str] = []
+    if stack.language == "python":
+        target = root / "pyproject.toml"
+        if not target.is_file():
+            steps.append("no pyproject.toml found: `newstack new` is a better fit than adopt")
+        else:
+            steps.append(
+                "merge the stack's [tool.ruff] / [tool.pytest.ini_options] blocks into "
+                "pyproject.toml by hand (adopt never edits existing files)"
+            )
+    elif stack.language in {"node", "html"}:
+        target = root / "package.json"
+        if target.is_file():
+            steps.append(
+                "add the stack's lint/test scripts to package.json by hand "
+                "(adopt never edits existing files)"
+            )
+    elif stack.language == "go":
+        if not (root / ".gitignore").exists():
+            steps.append("consider adding bin/ to your .gitignore for build output")
+    elif stack.language == "rust":
+        steps.append("Cargo.lock should be committed for binaries; .gitignore keeps /target out")
+    return steps
+
+
+def plan_adoption(
+    stack: Stack,
+    root: Path,
+    context: dict,
+    *,
+    with_tests: bool = False,
+    detected: bool = True,
+) -> AdoptionPlan:
+    """Work out what adopt would do, without touching the filesystem."""
+    if not stack.adopt:
+        raise TemplateError(f"stack '{stack.name}' declares no adoptable files")
+
+    wanted = list(stack.adopt)
+    if with_tests:
+        wanted.extend(stack.adopt_tests)
+
+    forbidden = sorted(set(wanted) & FORBIDDEN)
+    if forbidden:
+        raise TemplateError(
+            f"stack '{stack.name}' tries to adopt files that carry project identity: "
+            f"{', '.join(forbidden)}"
+        )
+
+    entries, _dirs = render_tree(stack.template_dir, context)
+    by_path = {rel: (payload, executable) for rel, payload, executable in entries}
+
+    missing = [rel for rel in wanted if rel not in by_path]
+    if missing:
+        raise TemplateError(
+            f"stack '{stack.name}' lists adoptable files that are not in its template: "
+            f"{', '.join(missing)}"
+        )
+
+    plan = AdoptionPlan(stack=stack, root=root, detected=detected)
+    plan.tests_available = bool(stack.adopt_tests) and with_tests
+    for rel in wanted:
+        if (root / rel).exists():
+            plan.keep.append(rel)
+            continue
+        payload, executable = by_path[rel]
+        plan.add.append(PendingFile(rel=rel, payload=payload, executable=executable))
+
+    plan.manual = _manual_steps(stack, root)
+    return plan
+
+
+def apply_plan(plan: AdoptionPlan) -> list[str]:
+    """Write the planned files. Only touches paths that did not exist when planned."""
+    written: list[str] = []
+    for item in plan.add:
+        target = plan.root / item.rel
+        if target.exists():  # someone else created it since planning: leave it alone
+            plan.keep.append(item.rel)
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(item.payload)
+        if item.executable:
+            target.chmod(0o755)
+        written.append(item.rel)
+    return written

{newstack-0.1.0 → newstack-0.3.0}/src/newstack/cli.py

@@ -12,6 +12,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from . import __version__
+from .adopt import apply_plan, detect_stacks, plan_adoption
 from .registry import RegistryError, Stack, get_stack, load_stacks
 from .render import TemplateError, generate
 from .verify import check_stack, missing_tools
@@ -72,6 +73,24 @@ def _git_config(key: str) -> str:
     return value
 
 
+class _SafeDict(dict):
+    """format_map target that leaves unknown keys visible instead of raising."""
+
+    def __missing__(self, key: str) -> str:
+        return "{" + key + "}"
+
+
+def _format_step(step: str, context: dict, path: Path) -> str:
+    return step.format_map(
+        _SafeDict(
+            path=path,
+            project_name=context["project_name"],
+            package_name=context["package_name"],
+            npm_name=context["npm_name"],
+        )
+    )
+
+
 def build_context(stack: Stack, destination: Path, args: argparse.Namespace) -> dict:
     project_name = args.name or destination.name
     author = args.author or _git_config("user.name") or "Your Name"
@@ -200,18 +219,77 @@ def _print_new_report(
         print(f"  {'github':<13} {report['github']}")
 
     if stack.next_steps:
-        steps = [
-            step.format(
-                path=destination,
-                package_name=context["package_name"],
-                npm_name=context["npm_name"],
-                project_name=context["project_name"],
+        print("\n  next:")
+        for step in stack.next_steps:
+            print(f"    {_format_step(step, context, destination)}")
+    print()
+
+
+def cmd_adopt(args: argparse.Namespace) -> int:
+    root = Path(args.path).expanduser().resolve()
+    if not root.is_dir():
+        raise TemplateError(f"not a directory: {root}")
+
+    if args.stack:
+        stack = get_stack(args.stack)
+        detected = False
+    else:
+        candidates = detect_stacks(root)
+        if not candidates:
+            raise TemplateError(
+                "could not recognise this project's stack — pass --stack "
+                "(see `newstack list`)"
             )
-            for step in stack.next_steps
-        ]
+        if len(candidates) > 1:
+            names = ", ".join(candidate.name for candidate in candidates)
+            print(f"newstack: this directory matches more than one stack: {names}", file=sys.stderr)
+            print("newstack: pass --stack <name> to choose one", file=sys.stderr)
+            return 2
+        stack = candidates[0]
+        detected = True
+
+    context = build_context(stack, root, args)
+    plan = plan_adoption(
+        stack, root, context, with_tests=args.with_tests, detected=detected
+    )
+
+    if not args.dry_run:
+        apply_plan(plan)
+
+    if args.json:
+        payload = plan.as_dict()
+        payload["dry_run"] = args.dry_run
+        print(json.dumps(payload, indent=2))
+        return 0
+
+    _print_adopt_report(plan, context, dry_run=args.dry_run)
+    return 0
+
+
+def _print_adopt_report(plan, context: dict, *, dry_run: bool) -> None:
+    print(f"\nnewstack {__version__}  ·  adopt  →  {plan.root}\n")
+    how = "auto-detected" if plan.detected else "--stack"
+    print(f"  {'stack':<12} {plan.stack.name} ({how})")
+    verb = "would add" if dry_run else "added"
+    print(f"  {verb:<12} {len(plan.add)} files")
+    for item in plan.add:
+        print(f"      + {item.rel}")
+    if plan.keep:
+        print(f"  {'kept':<12} {len(plan.keep)} existing files, left untouched")
+        for rel in plan.keep:
+            print(f"      = {rel}")
+    if plan.manual:
+        print(f"  {'manual':<12} {plan.manual[0]}")
+        for extra in plan.manual[1:]:
+            print(f"  {'':<12} {extra}")
+    if not plan.add:
+        print(f"  {'nothing':<12} the infrastructure files are already present")
+    if not plan.tests_available and plan.stack.adopt_tests:
+        print(f"  {'tests':<12} not copied — rerun with --with-tests if you want starter tests")
+    if plan.stack.next_steps:
         print("\n  next:")
-        for step in steps:
-            print(f"    {step}")
+        print(f"    review the additions:  git -C {plan.root} status --short")
+        print("    checks run on push:    the workflow above is the only thing that changed")
     print()
 
 
@@ -349,6 +427,20 @@ def build_parser() -> argparse.ArgumentParser:
     new.add_argument("--json", action="store_true", help="machine readable output")
     new.set_defaults(handler=cmd_new)
 
+    adopt = sub.add_parser(
+        "adopt", help="retrofit a stack's CI/lint files onto an existing project"
+    )
+    adopt.add_argument("path", help="directory of the existing project")
+    adopt.add_argument("--stack", help="force a stack instead of auto-detecting")
+    adopt.add_argument(
+        "--with-tests", action="store_true", help="also copy the stack's starter tests"
+    )
+    adopt.add_argument("--dry-run", action="store_true", help="report without writing anything")
+    adopt.add_argument("--author", help="author name for rendered files")
+    adopt.add_argument("--email", help="author email for rendered files")
+    adopt.add_argument("--json", action="store_true", help="machine readable output")
+    adopt.set_defaults(handler=cmd_adopt, name=None, description=None)
+
     lst = sub.add_parser("list", help="list available stacks")
     lst.add_argument("--json", action="store_true")
     lst.set_defaults(handler=cmd_list)