newstack 0.1.0__py3-none-any.whl

newstack/registry.py

@@ -0,0 +1,137 @@
+"""Stack discovery: every stack is a directory with a ``stack.json`` manifest."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+BUILTIN_ROOT = Path(__file__).resolve().parent / "data" / "stacks"
+ENV_VAR = "NEWSTACK_STACKS"
+
+
+class RegistryError(Exception):
+    """A stack manifest is missing or malformed."""
+
+
+@dataclass(frozen=True)
+class VerifyStep:
+    """One command that proves a generated project works."""
+
+    name: str
+    cmd: str
+    tools: tuple[str, ...] = ()
+    timeout: int = 600
+
+
+@dataclass(frozen=True)
+class Stack:
+    name: str
+    title: str
+    language: str
+    blurb: str
+    requires: tuple[str, ...]
+    verify: tuple[VerifyStep, ...]
+    default_description: str
+    next_steps: tuple[str, ...]
+    directory: Path
+
+    @property
+    def template_dir(self) -> Path:
+        return self.directory / "template"
+
+    @property
+    def docs_url(self) -> str:
+        return f"https://github.com/DawnofGenX/newstack/tree/main/src/newstack/data/stacks/{self.name}"
+
+
+def _as_tuple(value: object, field: str, where: Path) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise RegistryError(f"{where}: '{field}' must be a list of strings")
+    return tuple(value)
+
+
+def load_stack(directory: Path) -> Stack:
+    manifest = directory / "stack.json"
+    if not manifest.is_file():
+        raise RegistryError(f"{directory}: missing stack.json")
+    try:
+        data = json.loads(manifest.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise RegistryError(f"{manifest}: invalid JSON ({exc})") from exc
+    if not isinstance(data, dict):
+        raise RegistryError(f"{manifest}: top level must be an object")
+
+    for key in ("name", "title", "language", "blurb"):
+        if not isinstance(data.get(key), str) or not data[key].strip():
+            raise RegistryError(f"{manifest}: '{key}' must be a non-empty string")
+
+    if data["name"] != directory.name:
+        raise RegistryError(
+            f"{manifest}: name '{data['name']}' must match directory '{directory.name}'"
+        )
+
+    raw_verify = data.get("verify", [])
+    if not isinstance(raw_verify, list):
+        raise RegistryError(f"{manifest}: 'verify' must be a list")
+    steps: list[VerifyStep] = []
+    for index, item in enumerate(raw_verify):
+        if not isinstance(item, dict) or not isinstance(item.get("cmd"), str):
+            raise RegistryError(f"{manifest}: verify[{index}] needs a 'cmd' string")
+        steps.append(
+            VerifyStep(
+                name=str(item.get("name") or item["cmd"].split()[0]),
+                cmd=item["cmd"],
+                tools=_as_tuple(item.get("tools"), f"verify[{index}].tools", manifest),
+                timeout=int(item.get("timeout", 600)),
+            )
+        )
+
+    if not (directory / "template").is_dir():
+        raise RegistryError(f"{directory}: missing template/ directory")
+
+    return Stack(
+        name=data["name"],
+        title=data["title"],
+        language=data["language"],
+        blurb=data["blurb"],
+        requires=_as_tuple(data.get("requires"), "requires", manifest),
+        verify=tuple(steps),
+        default_description=str(data.get("default_description") or f"A {data['title']} project."),
+        next_steps=_as_tuple(data.get("next_steps"), "next_steps", manifest),
+        directory=directory,
+    )
+
+
+def search_roots() -> list[Path]:
+    """Built-in stacks first; ``NEWSTACK_STACKS`` entries may override them by name."""
+    roots = [BUILTIN_ROOT]
+    extra = os.environ.get(ENV_VAR, "")
+    for entry in extra.split(os.pathsep):
+        if entry.strip():
+            roots.append(Path(entry).expanduser())
+    return roots
+
+
+def load_stacks() -> dict[str, Stack]:
+    stacks: dict[str, Stack] = {}
+    for root in search_roots():
+        if not root.is_dir():
+            continue
+        for directory in sorted(p for p in root.iterdir() if p.is_dir()):
+            if (directory / "stack.json").is_file():
+                stack = load_stack(directory)
+                stacks[stack.name] = stack
+    return dict(sorted(stacks.items()))
+
+
+def get_stack(name: str) -> Stack:
+    stacks = load_stacks()
+    try:
+        return stacks[name]
+    except KeyError:
+        available = ", ".join(stacks) or "(none found)"
+        raise RegistryError(f"unknown stack '{name}' — available: {available}") from None

newstack/render.py

@@ -0,0 +1,163 @@
+"""Template rendering and file generation.
+
+Deliberately dependency-free: templates are plain files with ``{{ variable }}``
+placeholders, rendered by a regex substitution. No Jinja, no JS runtime, so
+``uvx newstack`` starts in well under a second and works offline.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+VAR_RE = re.compile(r"\{\{\s*([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*)\s*\}\}")
+
+
+class TemplateError(Exception):
+    """A template could not be rendered or written."""
+
+
+_MISSING = object()
+
+
+def _lookup(context: dict, dotted: str) -> object:
+    value: object = context
+    for part in dotted.split("."):
+        if isinstance(value, dict) and part in value:
+            value = value[part]
+        else:
+            return _MISSING
+    return value
+
+
+def render_string(text: str, context: dict, *, missing: list[str] | None = None) -> str:
+    """Replace every ``{{ key }}`` in *text* using *context* (dotted keys allowed).
+
+    Two escapes keep templating out of the way of the languages we generate:
+
+    * ``${{ ... }}`` is left untouched, so GitHub Actions expressions pass through.
+    * ``{{!`` emits a literal ``{{``.
+    """
+
+    def _sub(match: re.Match[str]) -> str:
+        if match.start() and text[match.start() - 1] == "$":
+            return match.group(0)
+        value = _lookup(context, match.group(1))
+        if value is _MISSING:
+            if missing is not None:
+                missing.append(match.group(1))
+            return match.group(0)
+        return "" if value is None else str(value)
+
+    return VAR_RE.sub(_sub, text).replace("{{!", "{{")
+
+
+@dataclass
+class GenerateResult:
+    root: Path
+    files: list[str] = field(default_factory=list)
+    directories: list[str] = field(default_factory=list)
+    overwritten: list[str] = field(default_factory=list)
+    dry_run: bool = False
+
+    @property
+    def count(self) -> int:
+        return len(self.files)
+
+
+def _safe_relpath(rel: str, source: str) -> str:
+    candidate = Path(rel)
+    if candidate.is_absolute() or ".." in candidate.parts:
+        raise TemplateError(f"refusing to write outside the project: {rel!r} (from {source})")
+    return candidate.as_posix()
+
+
+@dataclass(frozen=True)
+class _Entry:
+    rel: str
+    payload: bytes
+    executable: bool
+
+
+def _collect(template_dir: Path, context: dict) -> tuple[list[_Entry], list[str]]:
+    """Render the whole template in memory first, so a bad template writes nothing."""
+    missing: list[str] = []
+    entries: list[_Entry] = []
+    directories: list[str] = []
+
+    for src in sorted(template_dir.rglob("*")):
+        if src.is_dir() and src.name == "__pycache__":
+            continue
+        rel_src = src.relative_to(template_dir).as_posix()
+        rel = _safe_relpath(render_string(rel_src, context, missing=missing), rel_src)
+        if src.is_dir():
+            directories.append(rel)
+            continue
+
+        raw = src.read_bytes()
+        try:
+            text = raw.decode("utf-8")
+        except UnicodeDecodeError:
+            payload = raw
+        else:
+            payload = render_string(text, context, missing=missing).encode("utf-8")
+
+        executable = bool(os.access(src, os.X_OK) or src.suffix in {".sh", ".command"})
+        entries.append(_Entry(rel=rel, payload=payload, executable=executable))
+
+    if missing:
+        names = ", ".join(sorted(set(missing)))
+        raise TemplateError(f"unknown template variable(s) in {template_dir.name}: {names}")
+    return entries, directories
+
+
+def generate(
+    template_dir: Path | str,
+    destination: Path | str,
+    context: dict,
+    *,
+    force: bool = False,
+    dry_run: bool = False,
+) -> GenerateResult:
+    """Render *template_dir* into *destination*.
+
+    Raises :class:`TemplateError` on unknown variables, path escapes, or a
+    non-empty destination without ``force``. Nothing is written until the whole
+    template has rendered successfully.
+    """
+    template_dir = Path(template_dir)
+    destination = Path(destination)
+    if not template_dir.is_dir():
+        raise TemplateError(f"template directory not found: {template_dir}")
+
+    if destination.exists() and not destination.is_dir():
+        raise TemplateError(f"destination exists and is not a directory: {destination}")
+    if destination.is_dir() and any(destination.iterdir()) and not force:
+        raise TemplateError(
+            f"destination is not empty: {destination} (use --force to write into it anyway)"
+        )
+
+    entries, directories = _collect(template_dir, context)
+    result = GenerateResult(root=destination, dry_run=dry_run)
+    result.directories = directories
+    result.files = [entry.rel for entry in entries]
+
+    if dry_run:
+        return result
+
+    destination.mkdir(parents=True, exist_ok=True)
+    for rel_dir in directories:
+        (destination / rel_dir).mkdir(parents=True, exist_ok=True)
+
+    for entry in entries:
+        target = destination / entry.rel
+        if target.exists():
+            result.overwritten.append(entry.rel)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(entry.payload)
+        if entry.executable:
+            target.chmod(0o755)
+
+    return result

newstack/verify.py

@@ -0,0 +1,133 @@
+"""Prove a stack works: generate it into a throwaway directory and run its checks."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .registry import Stack
+from .render import generate, render_string
+
+
+@dataclass
+class StepOutcome:
+    name: str
+    ok: bool
+    seconds: float
+    skipped: str | None = None
+    output: str = ""
+
+
+@dataclass
+class CheckResult:
+    stack: str
+    title: str
+    ok: bool
+    seconds: float
+    directory: str
+    outcomes: list[StepOutcome] = field(default_factory=list)
+
+    @property
+    def skipped(self) -> list[str]:
+        return [o.name for o in self.outcomes if o.skipped]
+
+    @property
+    def failed(self) -> list[StepOutcome]:
+        return [o for o in self.outcomes if not o.ok and not o.skipped]
+
+    def as_dict(self) -> dict:
+        return {
+            "stack": self.stack,
+            "title": self.title,
+            "ok": self.ok,
+            "seconds": round(self.seconds, 2),
+            "directory": self.directory,
+            "steps": [
+                {
+                    "name": o.name,
+                    "ok": o.ok,
+                    "skipped": o.skipped,
+                    "seconds": round(o.seconds, 2),
+                    "output": o.output,
+                }
+                for o in self.outcomes
+            ],
+        }
+
+
+def missing_tools(stack: Stack) -> list[str]:
+    """Toolchains this stack needs that are not on PATH right now."""
+    needed = {tool for step in stack.verify for tool in step.tools}
+    return sorted(tool for tool in needed if shutil.which(tool) is None)
+
+
+def _tail(text: str, limit: int = 4000) -> str:
+    text = text.strip()
+    return text if len(text) <= limit else "…\n" + text[-limit:]
+
+
+def check_stack(
+    stack: Stack,
+    context: dict,
+    *,
+    keep: bool = False,
+    verbose: bool = False,
+    project_name: str = "check-app",
+) -> CheckResult:
+    root = Path(tempfile.mkdtemp(prefix=f"newstack-{stack.name}-"))
+    started = time.perf_counter()
+    result = CheckResult(
+        stack=stack.name, title=stack.title, ok=True, seconds=0.0, directory=str(root)
+    )
+    try:
+        generate(stack.template_dir, root, context)
+        if not stack.verify:
+            result.outcomes.append(StepOutcome(name="generate", ok=True, seconds=0.0))
+        for step in stack.verify:
+            absent = [tool for tool in step.tools if shutil.which(tool) is None]
+            if absent:
+                result.outcomes.append(
+                    StepOutcome(
+                        name=step.name,
+                        ok=False,
+                        seconds=0.0,
+                        skipped=f"missing {', '.join(absent)}",
+                    )
+                )
+                result.ok = False
+                continue
+            step_started = time.perf_counter()
+            try:
+                completed = subprocess.run(
+                    render_string(step.cmd, context),
+                    shell=True,
+                    cwd=root,
+                    capture_output=True,
+                    text=True,
+                    timeout=step.timeout,
+                )
+                ok = completed.returncode == 0
+                output = (completed.stdout or "") + (completed.stderr or "")
+            except subprocess.TimeoutExpired:
+                ok = False
+                output = f"timed out after {step.timeout}s"
+            result.outcomes.append(
+                StepOutcome(
+                    name=step.name,
+                    ok=ok,
+                    seconds=time.perf_counter() - step_started,
+                    output=_tail(output) if verbose or not ok else "",
+                )
+            )
+            if not ok:
+                result.ok = False
+                break
+    finally:
+        result.seconds = time.perf_counter() - started
+        if not keep:
+            shutil.rmtree(root, ignore_errors=True)
+    return result

newstack-0.1.0.dist-info/METADATA

@@ -0,0 +1,197 @@
+Metadata-Version: 2.5
+Name: newstack
+Version: 0.1.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
+Project-URL: Issues, https://github.com/DawnofGenX/newstack/issues
+Project-URL: Changelog, https://github.com/DawnofGenX/newstack/blob/main/CHANGELOG.md
+Author-email: Priyansh Kansara <pkansara0412@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: boilerplate,cli,generator,scaffold,scaffolding,starter,template
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+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)
+![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)
+
+**Scaffold a new project on any popular stack — and every starter it emits is proven green in CI.**
+
+```console
+$ newstack new python-lib ~/code/mylib
+newstack 0.1.0  ·  python-lib  →  /home/you/code/mylib
+
+  created       8 files
+  git           initialised on main, first commit made
+
+  next:
+    cd /home/you/code/mylib
+    uv sync
+    uv run pytest
+```
+
+## Why this exists
+
+`cookiecutter`, `copier`, `yeoman`, `degit`, `npm create …` and `gh repo create --template`
+all solve *part* of the problem. Two things are still missing in practice:
+
+1. **One tool for every stack.** Python templates are Python-only, JS templates are
+   JS-only, and `gh repo create --template` clones a whole repository with no variables.
+2. **A guarantee that the template still works.** Templates rot silently. You find out
+   the starter is broken *after* you have already started building on top of it.
+
+`newstack` fixes both. It is one zero-dependency CLI that carries a curated stack
+registry, and **every stack in that registry is generated and checked on every push**
+(`newstack check --all` in CI). If a starter breaks, the badge goes red — not your
+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
+```
+
+From a clone:
+
+```bash
+git clone https://github.com/DawnofGenX/newstack && cd newstack
+uv sync && uv run newstack list
+```
+
+## Use
+
+```bash
+newstack list                       # what is available, and what each stack needs
+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 check --all                # prove every stack on this machine
+newstack doctor                     # which toolchains do I have?
+```
+
+Every command takes `--json` where it makes sense, so the tool is scriptable.
+
+`newstack new` renders variables, initialises git with a first commit, and (with
+`--github`) creates the remote repository and pushes — one command from empty
+directory to CI-ready project.
+
+## Stacks
+
+| Stack | What you get | Toolchain |
+| --- | --- | --- |
+| `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` |
+| `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` |
+
+Each generated project ships its own `.github/workflows/` that is ready to run, plus a
+README, an MIT licence and a `.gitignore`.
+
+## The green guarantee
+
+A template is only as good as its last successful run, so `newstack` treats
+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)
+  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)
+  static-site      PASS    0.1s  3 step(s)
+```
+
+(Real timings from a warm package cache — a cold run takes about a minute because
+`npm install` and `uv pip install` have to fetch packages.)
+
+`check` generates the stack into a throwaway directory, runs the commands listed in its
+manifest (`install → lint → test → build`), reports per-step timings, and deletes the
+directory unless you pass `--keep`. The same command runs in this repository's CI, once
+per stack, on every push.
+
+## How it compares
+
+| | newstack | cookiecutter | copier | yeoman | degit / `npm create` | `gh repo create --template` |
+| --- | --- | --- | --- | --- | --- | --- |
+| Cross-language stacks in one tool | **yes** | no | no | partial | no | n/a |
+| Runtime dependencies | **0** | Python | Python + git | Node | Node | gh |
+| Generated starter verified in CI | **yes, per stack** | no | no | no | no | no |
+| Template updates after generation | no (roadmap) | no | **yes** (`copier update`) | no | no | no |
+| Creates the git repo + remote | **yes** (`--github`) | no | via hooks | no | no | yes |
+
+Pick `copier` if you need `copier update` three-way merges against a single template you
+own. Pick `newstack` when you want the same standard applied across several languages
+without maintaining one template per stack.
+
+## Adding a stack
+
+A stack is a directory with a manifest and a template tree:
+
+```text
+src/newstack/data/stacks/my-stack/
+├── stack.json
+└── template/
+    ├── README.md
+    └── ...                      # {{ project_name }}, {{ package_name }}, {{ npm_name }},
+                                 # {{ title }}, {{ description }}, {{ author }}, {{ email }},
+                                 # {{ year }}, {{ date }}
+```
+
+```json
+{
+  "name": "my-stack",
+  "title": "My stack",
+  "language": "python",
+  "blurb": "One line shown by `newstack list`",
+  "requires": ["uv"],
+  "next_steps": ["cd {path}", "uv run pytest"],
+  "verify": [
+    {"name": "test", "cmd": "uv run pytest", "tools": ["uv"], "timeout": 600}
+  ]
+}
+```
+
+`{{!` 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.
+
+## Design
+
+- **Zero runtime dependencies.** `argparse` and the standard library only, so `uvx newstack`
+  starts instantly and works offline.
+- **Templates are plain files.** No Jinja, no DSL — a reviewer can read a template and know
+  exactly what gets written.
+- **Verification is a product feature, not an afterthought.** `check` is the same code path
+  CI uses.
+
+## Roadmap
+
+- `newstack update` — re-apply upstream template changes to an existing project.
+- More stacks: Go service, Rust CLI, Django, Vue, SvelteKit.
+- `--license apache-2.0|bsd-3` and other variable choices beyond the current defaults.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).