@slopware/sloppy-linux-x64 0.1.0-alpha.0

package/examples/ops-compiler/app.js

@@ -0,0 +1,26 @@
+import { Health, Results, Sloppy } from "sloppy";
+
+const app = Sloppy.create();
+
+app.health()
+    .check("self", Health.self(), { tags: ["live", "ready", "startup"] })
+    .check("runtime", Health.runtime(), { tags: ["ready", "startup"], critical: true })
+    .check("memory", Health.memory(), { tags: ["health"], critical: false })
+    .expose({
+        health: "/health",
+        live: "/live",
+        ready: "/ready",
+        startup: "/startup",
+    });
+
+app.management({
+    path: "/_sloppy",
+    health: true,
+    metrics: true,
+    info: true,
+    runtime: true,
+});
+
+app.get("/orders/{id}", () => Results.ok({ ok: true }));
+
+export default app;

package/examples/ops-health-metrics-management/README.md

@@ -0,0 +1,14 @@
+# Operations Health Metrics Management
+
+This example wires the first-party operations backend:
+
+- liveness at `/live`;
+- readiness at `/ready`;
+- startup at `/startup`;
+- detailed health at `/health`;
+- protected management endpoints under `/_sloppy`;
+- Prometheus metrics at `/_sloppy/metrics`;
+- JSON metrics at `/_sloppy/metrics.json`.
+
+The management group uses a small local `protect` hook. Real deployments should
+use an auth policy or ingress policy appropriate for the environment.

package/examples/ops-health-metrics-management/app.js

@@ -0,0 +1,24 @@
+import { Health, Results, Sloppy } from "sloppy";
+
+const app = Sloppy.create();
+
+const ordersCreated = app.metrics.counter("orders_created_total", {
+    description: "Orders accepted by the example app.",
+});
+
+app.health()
+    .check("self", Health.self(), { tags: ["live", "ready", "startup"] })
+    .check("memory", Health.memory(), { tags: ["health"], critical: false, cacheMs: 1000 })
+    .expose();
+
+app.post("/orders", () => {
+    ordersCreated.inc({ route: "/orders" });
+    return Results.accepted({ accepted: true });
+});
+
+app.management({
+    path: "/_sloppy",
+    protect: (ctx) => ctx.request.headers.get("x-ops-key") === "local-dev-key",
+});
+
+export { app };

package/examples/orm-basic/README.md

@@ -0,0 +1,17 @@
+# ORM Basic
+
+This example shows the first-party `sloppy/orm` model and query shape for a
+small team/user API.
+
+It covers:
+
+- `table`, `column`, and `relation` declarations
+- generated insert, patch, row, and public DTO schemas
+- route `.accepts()` / `.returns()` metadata with ORM schemas
+- transactional insert with `.returning()`
+- split-query collection include with a soft-delete filter
+- public DTO projection that excludes a private password hash column
+
+The handlers expect `ctx.db` to be a Sloppy database provider connection. The
+same table metadata can generate provider-specific migration SQL through
+`orm.migrations.script([Teams, Users], { provider })`.

package/examples/orm-basic/app.js

@@ -0,0 +1,82 @@
+import { Results, Sloppy } from "sloppy";
+import { column, orm, relation, table } from "sloppy/orm";
+
+const Teams = table("teams", {
+    id: column.uuid().primaryKey(),
+    slug: column.text().notNull().unique(),
+    name: column.text().notNull(),
+    createdAt: column.instant().notNull().defaultNow(),
+});
+
+const Users = table("users", {
+    id: column.uuid().primaryKey(),
+    teamId: column.uuid().notNull().references(() => Teams.id),
+    email: column.text().notNull().unique(),
+    displayName: column.text().nullable(),
+    passwordHash: column.text().notNull().private(),
+    version: column.int().notNull().concurrencyToken(),
+    deletedAt: column.instant().nullable().softDelete(),
+    createdAt: column.instant().notNull().defaultNow(),
+});
+
+relation(Users, ({ one }) => ({
+    team: one(Teams, {
+        local: Users.teamId,
+        foreign: Teams.id,
+    }),
+}));
+
+relation(Teams, ({ many }) => ({
+    users: many(Users, {
+        local: Teams.id,
+        foreign: Users.teamId,
+    }),
+}));
+
+const app = Sloppy.create();
+
+app.post("/teams/{teamId:uuid}/users", async (ctx) => {
+    const input = await ctx.body.json(
+        Users.insertSchema.pick("email", "displayName", "passwordHash"),
+    );
+
+    const created = await orm.transaction(ctx.db, async (tx) => Users.insert(tx, {
+        id: crypto.randomUUID(),
+        teamId: ctx.params.teamId,
+        email: input.email,
+        displayName: input.displayName ?? null,
+        passwordHash: input.passwordHash,
+        version: 1,
+    }).returning());
+
+    return Results.json(
+        Users.public(created, ["id", "email", "displayName", "createdAt"]),
+        { status: 201 },
+    );
+})
+    .accepts(Users.insertSchema.pick("email", "displayName", "passwordHash"))
+    .returns(201, Users.publicSchema(["id", "email", "displayName", "createdAt"]));
+
+app.get("/teams/{teamId:uuid}", async (ctx) => {
+    const team = await orm
+        .from(Teams)
+        .where((t) => t.id.eq(ctx.params.teamId))
+        .include((t) => t.users.where((u) => u.deletedAt.isNull()).take(100))
+        .singleOrDefault(ctx.db);
+
+    if (team === null) {
+        return Results.notFound();
+    }
+
+    return Results.json({
+        id: team.id,
+        slug: team.slug,
+        name: team.name,
+        createdAt: team.createdAt,
+        users: team.users.map((user) =>
+            Users.public(user, ["id", "email", "displayName", "createdAt"])),
+    });
+});
+
+export { Teams, Users };
+export default app;

package/examples/orm-cursor-export/README.md

@@ -0,0 +1,16 @@
+# ORM Cursor Export
+
+This experimental documentation example shows the ORM cursor-to-NDJSON adapter:
+
+```ts
+const cursor = await orm.from(Users).cursor(ctx.db, {
+  batchSize: 512,
+  maxRows: 100000,
+});
+
+const stream = orm.stream.ndjson(cursor);
+```
+
+The cursor is incremental and closes on early exit or adapter completion.
+`Results.stream` remains the current bounded result descriptor; the ORM adapter
+keeps selected-column metadata available for the native streaming path.

package/examples/orm-cursor-export/app.js

@@ -0,0 +1,28 @@
+import { Sloppy, Results, column, orm, table } from "sloppy";
+
+const Users = table("users", {
+    id: column.uuid().primaryKey(),
+    email: column.text().notNull().unique(),
+    createdAt: column.instant().notNull().defaultNow(),
+});
+
+const app = Sloppy.create();
+
+app.get("/exports/users.ndjson", async (ctx) => {
+    const cursor = await orm
+        .from(Users)
+        .select((u) => ({ id: u.id, email: u.email }))
+        .orderBy((u) => u.id.asc())
+        .cursor(ctx.db, { batchSize: 512, maxRows: 100000 });
+
+    const stream = orm.stream.ndjson(cursor);
+    return Results.stream(async (writer) => {
+        for await (const chunk of stream) {
+            writer.writeText(chunk);
+        }
+    }, {
+        contentType: stream.contentType,
+    });
+});
+
+export default app;

package/examples/orm-migrations/README.md

@@ -0,0 +1,14 @@
+# ORM Migrations
+
+This example shows the ORM migration draft workflow for a built app.
+
+```powershell
+sloppy build
+sloppy orm migration script .sloppy --provider main
+sloppy orm migration add CreateUsers .sloppy --provider main
+sloppy orm migration status .sloppy --provider main
+sloppy orm migration apply .sloppy --provider main
+```
+
+`script` and `add` read static ORM table metadata from `app.plan.json`.
+Review the generated SQL before applying it.

package/examples/orm-migrations/migrations/.gitkeep

@@ -0,0 +1 @@
+

package/examples/orm-migrations/sloppy.json

@@ -0,0 +1,9 @@
+{
+  "entry": "src/app.ts",
+  "migrations": {
+    "main": {
+      "provider": "sqlite",
+      "path": "migrations/*.sql"
+    }
+  }
+}

package/examples/orm-migrations/src/app.ts

@@ -0,0 +1,34 @@
+import { Results, Sloppy, column, relation, table } from "sloppy";
+
+const Teams = table("teams", {
+  id: column.uuid().primaryKey(),
+  slug: column.text().notNull().unique(),
+  name: column.text().notNull(),
+});
+
+const Users = table("users", {
+  id: column.uuid().primaryKey(),
+  teamId: column.uuid().notNull().references(() => Teams.id),
+  email: column.text().notNull().unique(),
+  deletedAt: column.instant().nullable().softDelete(),
+});
+
+relation(Users, ({ one }) => ({
+  team: one(Teams, {
+    local: Users.teamId,
+    foreign: Teams.id,
+  }),
+}));
+
+const builder = Sloppy.createBuilder();
+builder.capabilities.addDatabase("data.main", {
+  provider: "sqlite",
+  database: "data/app.db",
+  access: "readwrite",
+});
+
+const app = builder.build();
+
+app.mapGet("/users", () => Results.json([]));
+
+export default app;

package/examples/orm-relations-includes/README.md

@@ -0,0 +1,10 @@
+# ORM Relations and Includes
+
+This documentation example focuses on relation metadata and include behavior:
+
+- `Users -> team` defaults to a join include.
+- `Teams -> users` defaults to a split-query collection include.
+- Filtered collection includes can use `where(...).take(...)`.
+
+The app expects `ctx.db` to be supplied by `TestHost` provider overrides or by a
+runtime provider configured in the Plan.

package/examples/orm-relations-includes/app.js

@@ -0,0 +1,47 @@
+import { Sloppy, Results, column, orm, relation, table } from "sloppy";
+
+const Teams = table("teams", {
+    id: column.uuid().primaryKey(),
+    slug: column.text().notNull().unique(),
+    name: column.text().notNull(),
+});
+
+const Users = table("users", {
+    id: column.uuid().primaryKey(),
+    teamId: column.uuid().notNull().references(() => Teams.id),
+    email: column.text().notNull().unique(),
+    displayName: column.text().nullable(),
+    deletedAt: column.instant().nullable().softDelete(),
+});
+
+relation(Teams, ({ many }) => ({
+    users: many(Users, { local: Teams.id, foreign: Users.teamId }),
+}));
+
+relation(Users, ({ one }) => ({
+    team: one(Teams, { local: Users.teamId, foreign: Teams.id }),
+}));
+
+const app = Sloppy.create();
+
+app.get("/teams/{teamId:uuid}", async (ctx) => {
+    const team = await orm
+        .from(Teams)
+        .where((t) => t.id.eq(ctx.params.teamId))
+        .include((t) => t.users.where((u) => u.deletedAt.isNull()).take(100))
+        .singleOrDefault(ctx.db);
+
+    return team === null ? Results.notFound() : Results.json(team);
+});
+
+app.get("/users/{userId:uuid}", async (ctx) => {
+    const user = await orm
+        .from(Users)
+        .where((u) => u.id.eq(ctx.params.userId))
+        .include((u) => u.team)
+        .singleOrDefault(ctx.db);
+
+    return user === null ? Results.notFound() : Results.json(user);
+});
+
+export default app;

package/examples/orm-testservices/README.md

@@ -0,0 +1,37 @@
+# ORM TestServices
+
+`TestServices.postgres()` and `TestServices.sqlServer()` are opt-in live
+provider helpers for app-host tests. They report `SKIPPED` when the matching
+environment variable or native bridge is unavailable.
+
+```ts
+import { Sloppy, TestHost, TestServices } from "sloppy";
+
+const app = Sloppy.create();
+// Register routes that use ctx.db.
+
+const pg = await TestServices.postgres({
+  migrations: "migrations/postgres/*.sql",
+});
+
+if (!pg.available) {
+  console.log(pg.status, pg.reason);
+} else {
+  const host = await TestHost.create(app, {
+    providers: {
+      main: pg.provider(),
+    },
+  });
+  try {
+    // Run requests and assertions.
+  } finally {
+    await host.close();
+    await pg.close();
+  }
+}
+```
+
+The default environment variables are:
+
+- `SLOPPY_POSTGRES_TEST_URL`
+- `SLOPPY_SQLSERVER_TEST_CONNECTION_STRING`

package/examples/orm-testservices/test.mjs

@@ -0,0 +1,32 @@
+import { Results, Sloppy, TestHost, TestServices, column, orm, table } from "sloppy";
+
+const Users = table("users", {
+  id: column.uuid().primaryKey(),
+  email: column.text().notNull().unique(),
+});
+
+const app = Sloppy.create();
+app.mapGet("/users", async (ctx) => {
+  const rows = await orm.from(Users).select((u) => ({ id: u.id, email: u.email })).toList(ctx.db);
+  return Results.json(rows);
+});
+
+const pg = await TestServices.postgres({
+  migrations: "migrations/postgres/*.sql",
+});
+
+if (!pg.available) {
+  console.log(`${pg.status}: ${pg.reason}`);
+} else {
+  const host = await TestHost.create(app, {
+    providers: {
+      main: pg.provider(),
+    },
+  });
+  try {
+    await host.get("/users").expectStatus(200);
+  } finally {
+    await host.close();
+    await pg.close();
+  }
+}

package/examples/os-runtime-api/README.md

@@ -0,0 +1,11 @@
+# OS Runtime API
+
+This source example shows the `sloppy/os` API shape for host information,
+current-process snapshots, redacted environment access, explicit-argv process
+execution, streaming process handles, and shutdown handler registration.
+
+## Limitations
+
+This example is limited to the Sloppy-owned OS runtime API shape shown in
+source. Shell execution, PTY behavior, daemon supervision, and raw native handle
+access are outside this example.

package/examples/os-runtime-api/app.js

@@ -0,0 +1,44 @@
+import { Environment, Process, Signals, System } from "sloppy/os";
+import { Deadline } from "sloppy/time";
+
+export function describeHost() {
+  const current = Process.info();
+  return {
+    platform: System.platform,
+    arch: System.arch,
+    cpuCount: System.cpuCount,
+    tempDirectory: System.tempDirectory,
+    setting: Environment.get("MY_APP_SETTING"),
+    pid: current.pid,
+    cwd: current.cwd,
+    argsAvailable: current.argsAvailable
+  };
+}
+
+export async function gitStatus(repo) {
+  return Process.run("git", ["status", "--short"], {
+    cwd: repo,
+    timeoutMs: 5000,
+    capture: "text"
+  });
+}
+
+export async function probeProcess(command, args) {
+  const proc = await Process.start(command, args, {
+    stdout: "pipe",
+    stderr: "pipe",
+    deadline: Deadline.after(5000)
+  });
+
+  const lines = [];
+  for await (const line of proc.stdout.readLines()) {
+    lines.push(line);
+  }
+
+  const exit = await proc.wait();
+  return { exit, lines };
+}
+
+Signals.onShutdown(async (ctx) => {
+  await Promise.resolve({ signal: ctx.signal, forced: ctx.forced });
+});

package/examples/package-zod-like/README.md

@@ -0,0 +1,28 @@
+# Package: zod-like
+
+This example uses a local fixture package to demonstrate Sloppy's installed
+package graph. It does not require internet access.
+
+The fixture package is intentionally small and zod-shaped: it exports a
+validator factory with `string()`, `number()`, and `object(...)` helpers. It is
+not the real Zod package.
+
+## Setup
+
+```sh
+npm install
+sloppy build
+sloppy deps .sloppy
+sloppy run -- Ada
+```
+
+`npm install` installs `fixtures/zod-like` through a local `file:` dependency.
+Real installed packages work when their JavaScript and runtime API usage are
+compatible with Sloppy's loader and Node compatibility shims.
+
+## What It Covers
+
+- installed package resolution from `node_modules`;
+- package.json `exports`;
+- ESM package import from Program Mode;
+- dependency graph inspection with `sloppy deps`.

package/examples/package-zod-like/fixtures/zod-like/index.js

@@ -0,0 +1,48 @@
+function issue(message) {
+    const error = new Error(message);
+    error.name = "ZodLikeError";
+    return error;
+}
+
+function string() {
+    return {
+        parse(value) {
+            if (typeof value !== "string") {
+                throw issue("expected string");
+            }
+            return value;
+        }
+    };
+}
+
+function number() {
+    return {
+        parse(value) {
+            if (typeof value !== "number" || Number.isNaN(value)) {
+                throw issue("expected number");
+            }
+            return value;
+        }
+    };
+}
+
+function object(shape) {
+    return {
+        parse(value) {
+            if (value === null || typeof value !== "object") {
+                throw issue("expected object");
+            }
+            const result = {};
+            for (const key of Object.keys(shape)) {
+                result[key] = shape[key].parse(value[key]);
+            }
+            return result;
+        }
+    };
+}
+
+export const z = Object.freeze({
+    string,
+    number,
+    object
+});

package/examples/package-zod-like/fixtures/zod-like/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "zod-like",
+  "version": "0.0.0-fixture",
+  "type": "module",
+  "exports": {
+    ".": {
+      "sloppy": "./index.js",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  }
+}

package/examples/package-zod-like/package.json

@@ -0,0 +1,7 @@
+{
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "zod-like": "file:./fixtures/zod-like"
+  }
+}

package/examples/package-zod-like/sloppy.json

@@ -0,0 +1,6 @@
+{
+  "kind": "program",
+  "entry": "src/main.ts",
+  "outDir": ".sloppy",
+  "environment": "Development"
+}

package/examples/package-zod-like/src/main.ts

@@ -0,0 +1,16 @@
+import { z } from "zod-like";
+
+const userSchema = z.object({
+    name: z.string(),
+    score: z.number()
+});
+
+export function main(args) {
+    const user = userSchema.parse({
+        name: args[0] ?? "Ada",
+        score: Number(args[1] ?? 42)
+    });
+
+    console.log(`validated ${user.name} score=${user.score}`);
+    return 0;
+}

package/examples/postgres-basic/README.md

@@ -0,0 +1,31 @@
+# PostgreSQL Basic Example
+
+This is an API-shape example for the PostgreSQL provider.
+
+It shows the intended module/capability/service registration shape, PostgreSQL `$1`
+query-template lowering, a simple bounded pool option, and transaction usage.
+
+Current limitations:
+
+- this example requires PostgreSQL, PostgreSQL client support, and a connection
+  string such as `SLOPPY_POSTGRES_TEST_URL`;
+- normal Sloppy apps, the Quickstart, SQLite, templates, and package support do
+  not require PostgreSQL or libpq;
+- not part of default CI live database execution;
+- the V8 bridge uses nonblocking libpq socket readiness and a bounded connection pool;
+- parameterized exec/query/queryOne and callback transactions are supported through the
+  stdlib bridge when the Plan enables `provider.postgres`;
+- no migrations;
+- no ORM;
+- TLS option hardening and advanced operational pooling policy remain separate provider
+  hardening work.
+
+Native live provider tests are opt-in:
+
+```powershell
+$env:SLOPPY_POSTGRES_TEST_URL="<redacted PostgreSQL connection string>"
+.\tools\windows\test-live-postgres.ps1
+```
+
+Do not paste credentials into PR bodies or diagnostics. Connection strings must be redacted
+before reporting.

package/examples/postgres-basic/app.js

@@ -0,0 +1,50 @@
+import { Sloppy, data, sql } from "sloppy";
+import { Environment } from "sloppy/os";
+
+function requireEnvironment(name) {
+    const value = Environment.get(name);
+    if (value === undefined || value === "") {
+        throw new Error(`Missing required environment value: ${name}`);
+    }
+    return value;
+}
+
+const PostgresModule = Sloppy.module("data.postgres")
+    .capabilities((caps) => {
+        caps.addDatabase("data.main", {
+            provider: "postgres",
+            configKey: "SLOPPY_POSTGRES_TEST_URL",
+            access: "readwrite",
+        });
+    })
+    .services((services) => {
+        services.addSingleton("data.main", () => data.postgres.open({
+            connectionString: requireEnvironment("SLOPPY_POSTGRES_TEST_URL"),
+            maxConnections: 2,
+        }));
+    });
+
+const app = Sloppy.createBuilder()
+    .addModule(PostgresModule)
+    .build();
+
+const lowered = sql.lower(["select id, name from users where name = ", ""], ["Ada"], {
+    placeholderStyle: data.postgres.placeholderStyle,
+});
+
+async function insertUser(db, name) {
+    return db.queryOne`
+        insert into users (name)
+        values (${name})
+        returning id, name
+    `;
+}
+
+async function renameUser(db, id, name) {
+    return db.transaction(async (tx) => {
+        await tx.exec`update users set name = ${name} where id = ${id}`;
+        return tx.queryOne`select id, name from users where id = ${id}`;
+    });
+}
+
+export { app, insertUser, lowered, renameUser };