@fluxyr/quill-stack-flask 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { StackAdapter } from "@fluxyr/quill-core";
+export declare const flaskStack: StackAdapter;
+export default flaskStack;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAEL,YAAY,EAMb,MAAM,oBAAoB,CAAC;AAO5B,eAAO,MAAM,UAAU,EAAE,YAexB,CAAC;AAIF,eAAe,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,67 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flaskStack = void 0;
+/**
+ * @fluxyr/quill-stack-flask — the reference stack: Python/Flask/SQLAlchemy, flavored
+ * after fluxyr (Base-62 short IDs, BaseModel, account-scoped blueprints).
+ *
+ * Importing this module registers the "flask" stack with @fluxyr/quill-core. Core
+ * conventions are shared (owned by @fluxyr/quill-core); this stack contributes only the
+ * framework binding, the scaffold templates, and verify().
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const quill_core_1 = require("@fluxyr/quill-core");
+const verify_1 = require("./verify");
+const PKG_ROOT = path.resolve(__dirname, "..");
+const BINDING = path.join(PKG_ROOT, "prompts", "binding.md");
+const TEMPLATES = path.join(PKG_ROOT, "templates");
+exports.flaskStack = {
+    name: "flask",
+    scaffoldTemplates() {
+        return (0, quill_core_1.readTemplatesDir)(TEMPLATES);
+    },
+    buildSystemPrompt(ctx) {
+        const binding = fs.existsSync(BINDING) ? fs.readFileSync(BINDING, "utf8") : "";
+        return (0, quill_core_1.composeStackSystemPrompt)(ctx.corePrompts, binding);
+    },
+    verify(generatedDir) {
+        return (0, verify_1.verifyFlask)(generatedDir);
+    },
+};
+(0, quill_core_1.registerStack)(exports.flaskStack);
+exports.default = exports.flaskStack;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;GAOG;AACH,uCAAyB;AACzB,2CAA6B;AAC7B,mDAQ4B;AAC5B,qCAAuC;AAEvC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;AAC7D,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;AAEtC,QAAA,UAAU,GAAiB;IACtC,IAAI,EAAE,OAAO;IAEb,iBAAiB;QACf,OAAO,IAAA,6BAAgB,EAAC,SAAS,CAAC,CAAC;IACrC,CAAC;IAED,iBAAiB,CAAC,GAAiB;QACjC,MAAM,OAAO,GAAG,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/E,OAAO,IAAA,qCAAwB,EAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC5D,CAAC;IAED,MAAM,CAAC,YAAoB;QACzB,OAAO,IAAA,oBAAW,EAAC,YAAY,CAAC,CAAC;IACnC,CAAC;CACF,CAAC;AAEF,IAAA,0BAAa,EAAC,kBAAU,CAAC,CAAC;AAE1B,kBAAe,kBAAU,CAAC"}

package/dist/verify.d.ts

@@ -0,0 +1,3 @@
+import { VerifyResult } from "@fluxyr/quill-core";
+export declare function verifyFlask(generatedDir: string): Promise<VerifyResult>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AA6ClD,wBAAsB,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAiE7E"}

package/dist/verify.js

@@ -0,0 +1,145 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyFlask = verifyFlask;
+/**
+ * Verification for the Flask stack — feeds the repair loop.
+ *
+ * Stages, in order:
+ *   1. Syntax check (compileall) — always runs; hard gate.
+ *   2. Import / app-factory smoke — runs if Flask is importable.
+ *   3. pytest — runs if Flask + pytest are importable.
+ *
+ * When the app's dependencies are not installed, stages 2-3 are skipped (a soft
+ * pass) rather than reported as failures, so the repair loop never fights a
+ * missing-deps condition. Install deps (see requirements.txt) for full checks.
+ */
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function run(cmd, args, cwd) {
+    const r = (0, child_process_1.spawnSync)(cmd, args, {
+        cwd,
+        encoding: "utf8",
+        maxBuffer: 32 * 1024 * 1024,
+        env: process.env,
+    });
+    const out = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim();
+    return { code: r.error ? 127 : r.status ?? 1, out };
+}
+/** Candidate interpreters, most specific first. */
+function interpreters(generatedDir) {
+    const c = [];
+    if (process.env.QUILL_PY)
+        c.push(process.env.QUILL_PY);
+    const venv = path.join(generatedDir, ".venv", "bin", "python");
+    if (fs.existsSync(venv))
+        c.push(venv);
+    c.push("python3", "python");
+    return c;
+}
+/** Find an interpreter that can `import flask`, or null. */
+function pyWithFlask(generatedDir) {
+    for (const py of interpreters(generatedDir)) {
+        const r = run(py, ["-c", "import flask"], generatedDir);
+        if (r.code === 0)
+            return py;
+    }
+    return null;
+}
+function anyPython(generatedDir) {
+    for (const py of interpreters(generatedDir)) {
+        const r = run(py, ["--version"], generatedDir);
+        if (r.code === 0)
+            return py;
+    }
+    return null;
+}
+async function verifyFlask(generatedDir) {
+    const basePy = anyPython(generatedDir);
+    if (!basePy) {
+        return {
+            ok: false,
+            summary: "no python interpreter found",
+            feedback: "No python3 interpreter is available to verify the app.",
+        };
+    }
+    // Stage 1 — syntax.
+    const targets = ["app", "tests", "wsgi.py", "config.py"].filter((t) => fs.existsSync(path.join(generatedDir, t)));
+    const compile = run(basePy, ["-m", "compileall", "-q", ...targets], generatedDir);
+    if (compile.code !== 0) {
+        return {
+            ok: false,
+            summary: "syntax error",
+            feedback: `Syntax check failed (compileall):\n${compile.out}`,
+        };
+    }
+    // Stages 2-3 require Flask.
+    const py = pyWithFlask(generatedDir);
+    if (!py) {
+        return {
+            ok: true,
+            summary: "syntax ok; deps not installed (import/tests skipped)",
+            feedback: "",
+        };
+    }
+    // Stage 2 — import / app factory smoke.
+    const smoke = run(py, ["-c", "import app; a = app.create_app(); print('factory ok')"], generatedDir);
+    if (smoke.code !== 0) {
+        return {
+            ok: false,
+            summary: "import/app-factory error",
+            feedback: `The app failed to import / build via create_app():\n${smoke.out}`,
+        };
+    }
+    // Stage 3 — pytest.
+    const hasTests = fs.existsSync(path.join(generatedDir, "tests")) &&
+        fs
+            .readdirSync(path.join(generatedDir, "tests"))
+            .some((f) => f.startsWith("test_") && f.endsWith(".py"));
+    if (!hasTests) {
+        return { ok: true, summary: "factory ok; no tests found", feedback: "" };
+    }
+    const pytest = run(py, ["-m", "pytest", "-q"], generatedDir);
+    if (pytest.code !== 0) {
+        return {
+            ok: false,
+            summary: "pytest failing",
+            feedback: `pytest failed:\n${pytest.out}`,
+        };
+    }
+    return { ok: true, summary: "syntax + factory + pytest pass", feedback: "" };
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@fluxyr/quill-stack-flask",
+  "version": "0.1.0",
+  "description": "Quill reference stack: Python/Flask/SQLAlchemy (fluxyr-flavored).",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "prompts",
+    "templates"
+  ],
+  "dependencies": {
+    "@fluxyr/quill-core": "0.1.0"
+  },
+  "license": "MIT",
+  "author": "Fluxyr",
+  "homepage": "https://github.com/fluxyr-app/quill#readme",
+  "bugs": {
+    "url": "https://github.com/fluxyr-app/quill/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fluxyr-app/quill.git",
+    "directory": "packages/stack-flask"
+  },
+  "keywords": [
+    "quill",
+    "code-generation",
+    "llm",
+    "micro-prompts",
+    "openrouter",
+    "scaffolding"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/prompts/binding.md

@@ -0,0 +1,69 @@
+# Framework binding — Python / Flask / SQLAlchemy
+
+This app targets **Python + Flask + SQLAlchemy**. Realize the language-agnostic
+conventions above in this framework as described here. This binding is owned by the
+stack; the conventions are the durable, framework-independent spec.
+
+## Identifiers (short-ID scheme)
+
+Implement the short-ID behavior in these files (none are shipped — create them):
+
+- `app/utils/uuid.py` — the encoder/decoder. For example a `Uuid` class with
+  `shorten(value)`, `unshorten(value)`, `is_short_id(value)`, plus a module-level
+  `resolve_id(raw) -> uuid.UUID | None` accepting a short ID or a full UUID string.
+  Base-62 alphabet is `0-9`, `A-Z`, `a-z`; short IDs are exactly 22 chars.
+- `app/converters.py` — `ShortIDConverter(werkzeug.routing.BaseConverter)`:
+  `to_python` decodes a short ID (or full UUID) to a `uuid.UUID`; `to_url` shortens.
+  The app factory registers it under the key `sid`.
+- `app/json_provider.py` — `ShortIDJSONProvider(flask.json.provider.DefaultJSONProvider)`
+  whose `default` serializes any `uuid.UUID` as a short ID. The app factory installs
+  it if present.
+
+Consequences: route id params are declared `<sid:...>` and arrive as `uuid.UUID`;
+returning `to_dict()` (or any `uuid.UUID`) already emits short IDs; resolve inbound
+body ids with `resolve_id(...)` before querying.
+
+## Resources (SQLAlchemy models)
+
+- Define each resource in `app/models/<resource>.py` as a class extending `BaseModel`
+  (from `app/models/base.py`), which already provides the UUID `id`,
+  `created_at`/`updated_at`, and `to_dict()`/`save()`/`delete()`/`find_by_id()`/`find_all()`.
+  Do not reimplement those.
+- Import the db handle as `from app.extensions import db`. Columns are `db.Column(...)`
+  with explicit types and nullability.
+- Foreign keys:
+  `db.Column(SAUuid(as_uuid=True), db.ForeignKey('<table>.id', ondelete='CASCADE'|'RESTRICT'), nullable=False)`
+  with `from sqlalchemy import Uuid as SAUuid`.
+- Constraints/indexes go in `__table_args__` (e.g.
+  `db.UniqueConstraint('user_id', 'name', name='uix_user_project_name')`).
+- `__tablename__` is the snake_case plural. New model modules are auto-imported by the
+  app factory.
+
+## Endpoints (Flask blueprints)
+
+- One blueprint per resource in `app/routes/<resource>.py`, named `<resource>_bp`. The
+  app factory auto-registers every Blueprint found under `app/routes/` — do not edit it.
+- Paths: `/accounts/<sid:account_id>/<resource>` and
+  `/accounts/<sid:account_id>/<resource>/<sid:<resource>_id>`.
+- Return `jsonify(model.to_dict())` for an item, `jsonify([m.to_dict() for m in ...])`
+  for a collection; `201` on create.
+
+## Authorization
+
+- Decorate every protected handler with `@auth_required` from `app/utils/decorators.py`
+  (currently a pass-through stub — keep it in place; do not add auth dependencies).
+
+## Errors & tests
+
+- Use `error_response(message, status, code=None)` and `success_response(data, status)`
+  from `app/utils/responses.py`. Error shape: `{"error": {"message": ..., "code"?: ...}}`.
+- Put tests in `tests/test_<resource>.py` using the `app` and `client` fixtures from
+  `tests/conftest.py` (in-memory SQLite, tables created per test). Assert returned ids
+  are 22-char short IDs.
+
+## House rules (this stack)
+
+- Stay within the shipped stack: Flask, Flask-SQLAlchemy, SQLAlchemy, pytest. Add no new
+  dependencies unless a feature requires it. The app must run on SQLite with no external
+  services. Never modify the short-ID files once generated, `BaseModel`, the app
+  factory's registration logic, or `conftest.py`.

package/templates/app/__init__.py

@@ -0,0 +1,58 @@
+"""Application factory.
+
+Blueprints and models are auto-discovered: drop a new module under
+``app/routes/`` that defines a ``Blueprint`` (conventionally ``<name>_bp``) and a
+model under ``app/models/`` and they are wired up automatically — no manual
+registration edits required.
+"""
+import importlib
+import pkgutil
+
+from flask import Flask, Blueprint
+
+from app.extensions import db, migrate
+
+
+def _import_submodules(package_name: str) -> None:
+    package = importlib.import_module(package_name)
+    for _, name, _ in pkgutil.iter_modules(package.__path__):
+        importlib.import_module(f"{package_name}.{name}")
+
+
+def create_app(config_object: str = "config.Config") -> Flask:
+    app = Flask(__name__)
+    app.config.from_object(config_object)
+
+    # Wire the short-ID scheme (generated per the identifiers convention):
+    # UUIDs serialize as 22-char Base-62 on the wire, and <sid:...> route params
+    # arrive as uuid.UUID objects. Loaded defensively so the app still boots
+    # before that layer has been generated.
+    try:
+        from app.json_provider import ShortIDJSONProvider
+
+        app.json = ShortIDJSONProvider(app)
+    except Exception:
+        pass
+    try:
+        from app.converters import ShortIDConverter
+
+        app.url_map.converters["sid"] = ShortIDConverter
+    except Exception:
+        pass
+
+    db.init_app(app)
+    migrate.init_app(app, db)
+
+    # Populate SQLAlchemy metadata by importing every model module.
+    _import_submodules("app.models")
+
+    # Auto-register every Blueprint defined under app.routes.
+    import app.routes as routes_pkg
+
+    for _, name, _ in pkgutil.iter_modules(routes_pkg.__path__):
+        module = importlib.import_module(f"app.routes.{name}")
+        for attr in vars(module).values():
+            if isinstance(attr, Blueprint):
+                app.register_blueprint(attr)
+
+    return app

package/templates/app/extensions.py

@@ -0,0 +1,6 @@
+"""Flask extensions, instantiated without an app (initialized in the factory)."""
+from flask_sqlalchemy import SQLAlchemy
+from flask_migrate import Migrate
+
+db = SQLAlchemy()
+migrate = Migrate()

package/templates/app/models/base.py

@@ -0,0 +1,59 @@
+"""Base model with common fields. All models must extend BaseModel."""
+import uuid
+from datetime import datetime, timezone
+
+from sqlalchemy import select, Uuid as SAUuid
+
+from app.extensions import db
+
+
+class BaseModel(db.Model):
+    """Base model class with common fields.
+
+    Provides a Base-62 short-ID-friendly UUID primary key plus created_at /
+    updated_at timestamps, and small persistence helpers. The ``Uuid`` column
+    type is dialect-agnostic (native UUID on Postgres, CHAR(32) on SQLite).
+    """
+    __abstract__ = True
+
+    id = db.Column(SAUuid(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    created_at = db.Column(
+        db.DateTime,
+        default=lambda: datetime.now(timezone.utc).replace(tzinfo=None),
+        nullable=False,
+    )
+    updated_at = db.Column(
+        db.DateTime,
+        default=lambda: datetime.now(timezone.utc).replace(tzinfo=None),
+        onupdate=lambda: datetime.now(timezone.utc).replace(tzinfo=None),
+        nullable=False,
+    )
+
+    def to_dict(self):
+        """Convert model instance to a dictionary (UUIDs serialize as short IDs)."""
+        return {
+            column.name: getattr(self, column.name)
+            for column in self.__table__.columns
+        }
+
+    def save(self):
+        """Persist the model instance."""
+        db.session.add(self)
+        db.session.commit()
+        return self
+
+    def delete(self):
+        """Delete the model instance."""
+        db.session.delete(self)
+        db.session.commit()
+        return self
+
+    @classmethod
+    def find_by_id(cls, id):
+        """Find a model instance by primary key."""
+        return db.session.get(cls, id)
+
+    @classmethod
+    def find_all(cls):
+        """Return all model instances."""
+        return db.session.execute(select(cls)).scalars().all()

package/templates/app/routes/health.py

@@ -0,0 +1,9 @@
+"""Health check route (kept minimal; safe to keep as the app grows)."""
+from flask import Blueprint, jsonify
+
+health_bp = Blueprint("health", __name__)
+
+
+@health_bp.route("/health", methods=["GET"])
+def health():
+    return jsonify({"status": "ok"})

package/templates/app/utils/decorators.py

@@ -0,0 +1,16 @@
+"""Route decorators.
+
+``auth_required`` is a pass-through stub so generated apps run out of the box
+while preserving the authentication convention. Replace its body with real
+authentication (JWT/session/Clerk) when wiring auth for production.
+"""
+from functools import wraps
+
+
+def auth_required(func):
+    """Authentication gate (stub — currently a pass-through)."""
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs)
+
+    return wrapper

package/templates/app/utils/responses.py

@@ -0,0 +1,15 @@
+"""Standard JSON response helpers. Use these for all route responses."""
+from flask import jsonify
+
+
+def error_response(message: str, status: int = 400, code: str | None = None):
+    """Return a standardized JSON error: {"error": {"message", "code"?}}."""
+    payload = {"error": {"message": message}}
+    if code:
+        payload["error"]["code"] = code
+    return jsonify(payload), status
+
+
+def success_response(data, status: int = 200):
+    """Return a JSON success response."""
+    return jsonify(data), status

package/templates/config.py

@@ -0,0 +1,10 @@
+"""Application configuration."""
+import os
+
+
+class Config:
+    """Base config. Defaults to a local SQLite database for zero-setup runs."""
+
+    SQLALCHEMY_DATABASE_URI = os.environ.get("DATABASE_URL", "sqlite:///quill_app.db")
+    SQLALCHEMY_TRACK_MODIFICATIONS = False
+    SECRET_KEY = os.environ.get("SECRET_KEY", "dev-secret-change-me")

package/templates/requirements.txt

@@ -0,0 +1,5 @@
+Flask>=3.0
+Flask-SQLAlchemy>=3.1
+Flask-Migrate>=4.0
+SQLAlchemy>=2.0
+pytest>=8.0

package/templates/tests/conftest.py

@@ -0,0 +1,24 @@
+"""Shared pytest fixtures. Generated tests should use the `app` and `client` fixtures."""
+import pytest
+
+from app import create_app
+from app.extensions import db as _db
+
+
+@pytest.fixture
+def app():
+    app = create_app()
+    app.config.update(
+        TESTING=True,
+        SQLALCHEMY_DATABASE_URI="sqlite:///:memory:",
+    )
+    with app.app_context():
+        _db.create_all()
+        yield app
+        _db.session.remove()
+        _db.drop_all()
+
+
+@pytest.fixture
+def client(app):
+    return app.test_client()

package/templates/tests/test_smoke.py

@@ -0,0 +1,11 @@
+"""Baseline smoke tests for the scaffold. Feature prompts add their own tests."""
+
+
+def test_app_factory(app):
+    assert app is not None
+
+
+def test_health(client):
+    resp = client.get("/health")
+    assert resp.status_code == 200
+    assert resp.get_json()["status"] == "ok"

package/templates/wsgi.py

@@ -0,0 +1,7 @@
+"""WSGI entrypoint. Run with: FLASK_APP=wsgi flask run"""
+from app import create_app
+
+app = create_app()
+
+if __name__ == "__main__":
+    app.run(debug=True)