@slopware/sloppy-darwin-arm64 0.1.0-alpha.0

package/examples/dogfood/dogfood.json

@@ -0,0 +1,136 @@
+{
+  "schemaVersion": 1,
+  "catalog": "Sloppy dogfood and example evidence catalog",
+  "statusVocabulary": [
+    "available",
+    "v8-gated",
+    "package-gated",
+    "live-provider-gated",
+    "blocked",
+    "unavailable"
+  ],
+  "resultVocabulary": [
+    "PASS",
+    "FAIL",
+    "SKIPPED",
+    "UNAVAILABLE",
+    "NOT RUN"
+  ],
+  "scenarios": [
+    {
+      "id": "hello-artifact",
+      "feature": "hello",
+      "status": "v8-gated",
+      "lane": "artifact",
+      "source": "examples/compiler-hello/app.js",
+      "artifactFixture": "compiler/tests/fixtures/hello-mapget/expected",
+      "once": {
+        "method": "GET",
+        "target": "/"
+      },
+      "stdoutContains": [
+        "Hello from Sloppy"
+      ],
+      "requiresV8": true,
+      "defaultNonV8Result": "UNAVAILABLE",
+      "evidence": "V8-enabled sloppy run --artifacts evidence is required for positive execution; default non-V8 runs must report the V8 requirement."
+    },
+    {
+      "id": "hello-source-input",
+      "feature": "hello",
+      "status": "v8-gated",
+      "lane": "source-input",
+      "sourceFixture": "tests/fixtures/source-input/hello-minimal",
+      "example": "examples/hello-minimal/src/main.ts",
+      "once": {
+        "method": "GET",
+        "target": "/hello/Ada"
+      },
+      "stdoutContains": [
+        "\"hello\":\"Ada\""
+      ],
+      "requiresV8": true,
+      "defaultNonV8Result": "UNAVAILABLE",
+      "evidence": "Source-input compile/diagnostic behavior is validated by the fixture harness; positive handler execution requires a V8-enabled build."
+    },
+    {
+      "id": "prealpha-control-plane",
+      "feature": "app host dogfood",
+      "status": "v8-gated",
+      "lane": "project source-input",
+      "project": "examples/prealpha-control-plane",
+      "source": "examples/prealpha-control-plane/src/main.js",
+      "once": {
+        "method": "GET",
+        "target": "/projects?owner=runtime"
+      },
+      "stdoutContains": [
+        "Compiler Platform"
+      ],
+      "requiresCompiler": true,
+      "requiresV8": true,
+      "defaultNonV8Result": "UNAVAILABLE",
+      "evidence": "The app host coverage suite imports the same route modules through Testing.createHost; CMake source-input lanes verify project-mode artifacts, CLI inspection, non-V8 diagnostics, and V8-gated once execution."
+    },
+    {
+      "id": "package-hello-artifact",
+      "feature": "package",
+      "status": "package-gated",
+      "lane": "package outside-checkout",
+      "metadataFixture": "tests/fixtures/package/windows-default/case.json",
+      "requiresPackage": true,
+      "requiresV8": false,
+      "defaultMissingPackageResult": "SKIPPED",
+      "evidence": "Package-mode dogfood runs only when an archive path is supplied; missing package input is reported as skipped."
+    },
+    {
+      "id": "http-app",
+      "feature": "HTTP",
+      "status": "v8-gated",
+      "lane": "runtime transport",
+      "blockedBy": [],
+      "reason": "HTTP/1.1 server behavior is covered by transport and source-input run lanes. Positive app execution still requires a V8-enabled runtime."
+    },
+    {
+      "id": "https-app",
+      "feature": "HTTPS/TLS",
+      "status": "v8-gated",
+      "lane": "experimental TLS transport",
+      "blockedBy": [],
+      "reason": "Inbound TLS listener support is experimental and covered by opt-in transport lanes. Positive app execution still requires a V8-enabled runtime."
+    },
+    {
+      "id": "sqlite-app",
+      "feature": "SQLite",
+      "status": "v8-gated",
+      "lane": "source-input framework",
+      "blockedBy": [],
+      "reason": "Typed SQLite provider metadata and wrappers are emitted for framework apps. Positive CRUD execution still requires the native provider bridge and a V8-enabled runtime."
+    },
+    {
+      "id": "postgresql-app",
+      "feature": "PostgreSQL",
+      "status": "live-provider-gated",
+      "lane": "live-provider app",
+      "blockedBy": [],
+      "reason": "PostgreSQL dogfood requires live-provider evidence and service configuration outside default CI."
+    },
+    {
+      "id": "sqlserver-app",
+      "feature": "SQL Server",
+      "status": "live-provider-gated",
+      "lane": "live-provider app",
+      "blockedBy": [],
+      "reason": "SQL Server dogfood requires live-provider evidence, ODBC driver availability, and service configuration outside default CI."
+    },
+    {
+      "id": "framework-app",
+      "feature": "Framework",
+      "status": "v8-gated",
+      "lane": "source-input framework",
+      "sourceFixture": "tests/fixtures/source-input/framework-foundation",
+      "blockedBy": [],
+      "reason": "Framework source-input extraction covers static middleware, CORS, request IDs, request logging, controllers, services, and app-host test evidence. Positive emitted-app execution still requires a V8-enabled runtime."
+    }
+  ]
+}

package/examples/dynamic-module-include/README.md

@@ -0,0 +1,20 @@
+# Dynamic Module Include
+
+This example demonstrates computed dynamic imports over a sealed module graph.
+
+`src/main.ts` imports a plugin by name:
+
+```ts
+await import("./plugins/" + name + ".js");
+```
+
+The possible plugins are included by `moduleInclude` in `sloppy.json`.
+
+```sh
+sloppy build
+sloppy deps .sloppy
+sloppy run -- alpha
+```
+
+Dynamic import controls when a known module is evaluated. It is not
+unrestricted runtime file or package discovery.

package/examples/dynamic-module-include/public/readme.txt

@@ -0,0 +1 @@
+This asset is included to show assetInclude metadata next to moduleInclude.

package/examples/dynamic-module-include/sloppy.json

@@ -0,0 +1,12 @@
+{
+  "kind": "program",
+  "entry": "src/main.ts",
+  "outDir": ".sloppy",
+  "environment": "Development",
+  "moduleInclude": [
+    "src/plugins/*.js"
+  ],
+  "assetInclude": [
+    "public/**/*"
+  ]
+}

package/examples/dynamic-module-include/src/main.ts

@@ -0,0 +1,6 @@
+export async function main(args) {
+    const name = args[0] ?? "alpha";
+    const plugin = await import("./plugins/" + name + ".js");
+    console.log(plugin.describe());
+    return 0;
+}

package/examples/dynamic-module-include/src/plugins/alpha.js

@@ -0,0 +1,3 @@
+export function describe() {
+    return "alpha plugin";
+}

package/examples/dynamic-module-include/src/plugins/beta.js

@@ -0,0 +1,3 @@
+export function describe() {
+    return "beta plugin";
+}

package/examples/ergonomics/README.md

@@ -0,0 +1,42 @@
+# Ergonomics Example
+
+Bootstrap developer ergonomics API-shape example.
+This example shows the current bootstrap surface: route groups, result helpers,
+schema metadata, config, logging, and services. It uses the current bootstrap stdlib
+source path and is validated as an API-shape example.
+
+What works today:
+
+- `Sloppy.createBuilder()` creates the JavaScript-only bootstrap builder.
+- Config, memory logging, and string-token services can be registered before `build()`.
+- `app.mapGroup("/users")` creates an in-memory route group.
+- Group child routes compose prefixes, so `"/users"` plus `"{id:int}"` becomes
+  `"/users/{id:int}"`.
+- `withTags("Users")` and `withName("Users")` store group metadata on child route
+  snapshots.
+- `Results.ok`, `Results.accepted`, and `Results.noContent` create frozen descriptors.
+- `schema.object(...)` and `schema.string().min(...)` create inspectable validation
+  metadata and standalone validators.
+- CTest statically verifies this example imports the current stdlib path and uses the
+  expected API shape.
+
+Current product state:
+
+- This source-stdlib example is documentation-first and checked by CTest as an API-shape
+  fixture.
+- `sloppy run --artifacts` currently runs emitted artifacts such as
+  `examples/compiler-hello`.
+- `sloppyc` compilation, route-group/schema extraction, and `app.plan.json` emission
+  for this broader builder shape are planned separately.
+- The bounded `sloppy run` path currently loads generated artifacts. Source-shape loading,
+  request-context materialization, and request body/query parsing for this example belong
+  to later app-host runtime work.
+- Native HTTP route parameters reach JavaScript handler context in later runtime work; this
+  example uses `route.id ?? "demo"` to stay honest in bootstrap mode.
+- Validation metadata currently remains route metadata. Automatic `400` responses belong
+  to a later validation pipeline.
+- OpenAPI generation is planned separately.
+- `app.run` and `app.listen` belong to later app-host runtime work.
+
+This directory remains a checked-in documentation and fixture example for the current
+application host shape.

package/examples/ergonomics/app.js

@@ -0,0 +1,38 @@
+import { Sloppy, Results, schema } from "sloppy";
+
+const builder = Sloppy.createBuilder();
+
+builder.config.addObject({
+    "app.name": "Sloppy Ergonomics Demo",
+});
+
+builder.logging.addMemorySink();
+builder.services.addSingleton("users.message", () => "hello from the bootstrap app host");
+
+const app = builder.build();
+
+const SearchQuery = schema.object({
+    q: schema.string().min(1),
+});
+
+const users = app.mapGroup("/users")
+    .withTags("Users")
+    .withName("Users");
+
+users.mapGet("{id:int}", ({ route, services }) => {
+    return Results.ok({
+        id: route.id ?? "demo",
+        message: services.get("users.message"),
+    });
+}).withName("Users.Get");
+
+users.mapGet("/search", { query: SearchQuery }, () => {
+    return Results.accepted({
+        status: "shape-only",
+    });
+}).withName("Users.Search");
+
+app.mapGet("/health", () => Results.noContent())
+    .withName("Health");
+
+export default app;

package/examples/framework-controller/README.md

@@ -0,0 +1,12 @@
+# Framework Controller Example
+
+Bootstrap controller API-shape example.
+This example shows the implemented bootstrap `app.mapController(...)` surface, explicit
+method mapping, and constructor injection through the same service provider used by route
+handlers.
+
+## Limitations
+
+This is a bootstrap controller example, not a `sloppyc` source-input example.
+Controller class compiler extraction, decorators, reflection-style scanning,
+and package discovery are outside this example.

package/examples/framework-controller/app.js

@@ -0,0 +1,31 @@
+import { Sloppy, Results } from "sloppy";
+
+class GreetingService {
+    constructor() {
+        this.prefix = "user";
+    }
+}
+
+class UsersController {
+    static inject = ["GreetingService"];
+
+    constructor(greeting) {
+        this.greeting = greeting;
+    }
+
+    get(ctx) {
+        return Results.ok({
+            message: `${this.greeting.prefix}-${ctx.route.id}`,
+        });
+    }
+}
+
+const app = Sloppy.create();
+
+app.services.addScoped("GreetingService", () => new GreetingService());
+
+app.mapController("/users", UsersController, (users) => {
+    users.get("/{id:int}", "get").withName("Users.Get");
+});
+
+export default app;

package/examples/framework-di-services/README.md

@@ -0,0 +1,17 @@
+# Framework DI Services Example
+
+A runnable example showing request-scoped dependency injection.
+
+The app registers singleton, scoped, and transient services with literal service
+tokens. The compiler emits service registration metadata, and the generated
+runtime wrapper creates one request scope for handler injection.
+
+```powershell
+.\build\windows-relwithdebinfo\sloppy.exe run examples/framework-di-services/app.ts --once GET /di/42
+```
+
+## Scope
+
+This example covers literal service registration and request-scoped injection.
+Service scanning, external package modules, and decorator discovery are not
+shown here.

package/examples/framework-di-services/app.ts

@@ -0,0 +1,40 @@
+import { Sloppy, Results, Route, Service } from "sloppy";
+
+type GreetingService = {
+    prefix: string;
+};
+
+type RequestCounter = {
+    value: number;
+};
+
+type TransientStamp = {
+    value: string;
+};
+
+const app = Sloppy.create();
+
+app.services.addSingleton("GreetingService", () => ({
+    prefix: "user",
+}));
+
+app.services.addScoped("RequestCounter", () => ({
+    value: 7,
+}));
+
+app.services.addTransient("TransientStamp", () => ({
+    value: "transient",
+}));
+
+app.get("/di/{id:int}", (
+    id: Route<number>,
+    greeting: Service<GreetingService>,
+    counter: Service<RequestCounter>,
+    stamp: Service<TransientStamp>,
+) => Results.ok({
+    message: `${greeting.prefix}-${id}`,
+    counter: counter.value,
+    stamp: stamp.value,
+})).withName("Di.Get");
+
+export default app;

package/examples/framework-explicit-binding/README.md

@@ -0,0 +1,12 @@
+# Framework Explicit Binding Example
+
+A compile-time example for explicit handler-parameter binding.
+
+The handler uses explicit `Route`, `Query`, `Header`, `Body`, and request-context
+binding wrappers. This produces deterministic binding metadata for the current
+supported wrapper subset.
+
+## Scope
+
+The example is limited to the explicit binding wrappers shown in `app.ts`.
+Decorators, service scanning, and broad coercion behavior are not covered here.

package/examples/framework-explicit-binding/app.ts

@@ -0,0 +1,34 @@
+import {
+    Sloppy,
+    Results,
+    Body,
+    Header,
+    Query,
+    RequestContext,
+    Route,
+} from "sloppy";
+
+type UserPatch = {
+    displayName?: string;
+    tags?: string[];
+};
+
+const app = Sloppy.create();
+
+app.patch("/tenants/{tenantId}/users/{id:int}", (
+    tenantId: Route<string>,
+    id: Route<number>,
+    traceId: Header<"x-trace-id">,
+    includeAudit: Query<boolean>,
+    patch: Body<UserPatch>,
+    ctx: RequestContext,
+) => Results.ok({
+    tenantId,
+    id,
+    traceId,
+    includeAudit,
+    patch,
+    method: ctx.request.method,
+})).withName("Users.Patch");
+
+export default app;

package/examples/framework-hello/README.md

@@ -0,0 +1,16 @@
+# Framework Hello Example
+
+A minimal runnable example for the current compiler/runtime subset.
+
+It shows a TypeScript source file going through the source-input path, Plan
+metadata emission, typed route parameter materialization, and a `Results.ok(...)`
+response from V8.
+
+```powershell
+.\build\windows-relwithdebinfo\sloppy.exe run examples/framework-hello/app.ts --once GET /hello/Ada
+```
+
+## Scope
+
+This example covers a single hello route. Package resolution, live providers,
+and broader HTTP features are covered by separate examples.

package/examples/framework-hello/app.ts

@@ -0,0 +1,16 @@
+import { Sloppy, Results, RequestContext, Route } from "sloppy";
+
+const app = Sloppy.create();
+
+app.get("/health", () => Results.text("ok")).withName("Health.Get");
+
+app.get("/hello/{name}", (
+    name: Route<string>,
+    ctx: RequestContext,
+) => Results.ok({
+    hello: name,
+    method: ctx.request.method,
+    path: ctx.request.path,
+})).withName("Hello.Get");
+
+export default app;

package/examples/framework-postgres-crud/README.md

@@ -0,0 +1,73 @@
+# Framework PostgreSQL CRUD Example
+
+## What this shows
+
+A users API backed by PostgreSQL:
+
+- typed `Body<T>` and `Route<T>` handler parameters;
+- `Postgres<"main">` typed provider injection;
+- PostgreSQL placeholders (`$1`, `$2`);
+- request `signal` and `deadline` passed to database calls;
+- `Results.ok`, `Results.notFound`, and `Results.created`.
+
+## Requirements
+
+- A V8-enabled `sloppy` runtime.
+- A PostgreSQL service with a test database and `users` table.
+- PostgreSQL client support. Current alpha packages use system or
+  build-provided libpq; package-local PostgreSQL provider packages are not
+  shipped yet.
+- `Sloppy__Providers__postgres__main__connectionString` set in the environment.
+
+You do not need PostgreSQL or libpq for normal Sloppy apps, the Quickstart,
+Program Mode, SQLite, templates, or package support.
+
+Example table shape:
+
+```sql
+create table users (
+  id serial primary key,
+  name text not null,
+  email text not null unique
+);
+```
+
+## Run
+
+Set the connection string and run the PostgreSQL integration checks:
+
+```powershell
+$env:Sloppy__Providers__postgres__main__connectionString = "postgres://<user>:<password>@<host>:<port>/<db>"
+.\tools\windows\test-live-postgres.ps1
+```
+
+## Expected result
+
+The script runs the PostgreSQL native and bridge tests selected by:
+
+```powershell
+ctest --test-dir build\windows-relwithdebinfo --output-on-failure -R "data\.postgres\.live_provider|conformance\.postgres\.(native_live|bridge_live)"
+```
+
+With the table and connection string configured, `GET /users` returns JSON rows
+from the PostgreSQL database.
+
+## Files to look at
+
+- `app.ts` — `Postgres<"main">` injection and PostgreSQL SQL statements.
+- Generated `.sloppy/app.plan.json` — inferred `postgres/main` provider metadata.
+- `docs/api/data.md` — PostgreSQL setup and connection string convention.
+
+## Scope
+
+Schema setup is manual for this example. Migrations, ORM-style modeling,
+deployment guidance, and future PostgreSQL provider-package distribution are
+outside this example. Package dependency behavior is covered by the
+package/dependency examples.
+
+## Related docs
+
+- `docs/api/data.md`
+- `docs/reference/providers.md`
+- `docs/reference/framework.md`
+- `docs/internals/provider-runtime.md`

package/examples/framework-postgres-crud/app.ts

@@ -0,0 +1,64 @@
+import {
+    Body,
+    Email,
+    NonEmptyString,
+    PositiveInt,
+    RequestContext,
+    Results,
+    Route,
+    Sloppy,
+} from "sloppy";
+import { Postgres } from "sloppy/providers/postgres";
+
+type UserCreate = {
+    name: NonEmptyString;
+    email: Email;
+};
+
+type UserDto = {
+    id: number;
+    name: string;
+    email: string;
+};
+
+const app = Sloppy.create();
+
+app.get("/users", async (db: Postgres<"main">, ctx: RequestContext) => {
+    const users = await db.query<UserDto>(
+        "select id, name, email from users order by id",
+        [],
+        { signal: ctx.signal, deadline: ctx.deadline },
+    );
+    return Results.ok(users);
+}).withName("Users.List");
+
+app.get("/users/{id:int}", async (
+    id: Route<PositiveInt>,
+    db: Postgres<"main">,
+    ctx: RequestContext,
+) => {
+    const user = await db.queryOne<UserDto>(
+        "select id, name, email from users where id = $1",
+        [id],
+        { signal: ctx.signal, deadline: ctx.deadline },
+    );
+    return user === null ? Results.notFound() : Results.ok(user);
+}).withName("Users.Get");
+
+app.post("/users", async (
+    input: Body<UserCreate>,
+    db: Postgres<"main">,
+    ctx: RequestContext,
+) => {
+    const user = await db.queryOne<UserDto>(
+        "insert into users (name, email) values ($1, $2) returning id, name, email",
+        [input.name, input.email],
+        { signal: ctx.signal, deadline: ctx.deadline },
+    );
+    if (user === null) {
+        throw new Error("PostgreSQL user insert did not return a row.");
+    }
+    return Results.created(`/users/${user.id}`, user);
+}).withName("Users.Create");
+
+export default app;

package/examples/framework-sqlite-crud/README.md

@@ -0,0 +1,52 @@
+# Framework SQLite CRUD Example
+
+## What this shows
+
+A small users API backed by SQLite:
+
+- typed `Body<T>` and `Route<T>` handler parameters;
+- `Sqlite<"main">` typed provider injection;
+- provider config from `appsettings.json`;
+- request `signal` and `deadline` passed through to database calls;
+- `Results.ok`, `Results.notFound`, and `Results.created`.
+
+## Requirements
+
+- A V8-enabled `sloppy` runtime.
+- The SQLite provider bridge available in that runtime.
+
+## Run
+
+From the repository root:
+
+```powershell
+.\build\windows-relwithdebinfo\sloppy.exe run examples/framework-sqlite-crud/app.ts --once GET /users
+```
+
+## Expected response
+
+A JSON array of seeded users:
+
+```json
+[{"id":1,"name":"Ada Lovelace","email":"ada@example.test"},{"id":2,"name":"Grace Hopper","email":"grace@example.test"}]
+```
+
+## Files to look at
+
+- `app.ts` — typed handlers, SQLite injection, seed data, and CRUD routes.
+- `appsettings.json` — provider configuration for `sqlite/main`.
+- Generated `.sloppy/app.plan.json` — inferred provider/capability metadata
+  and route bindings after `sloppy build`.
+
+## Scope
+
+This is not an ORM or migration layer. PostgreSQL and SQL Server versions of the
+same shape live in separate examples and need their own database setup.
+
+## Related docs
+
+- `docs/api/data.md`
+- `docs/guide/sqlite.md`
+- `docs/reference/providers.md`
+- `docs/reference/framework.md`
+- `docs/internals/provider-runtime.md`