@sincpro/client-framework 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,78 @@
+# AGENTS.md — working on @sincpro/client-framework
+
+Rules for any agent (or person) changing this package. Read [`MANIFESTO.md`](MANIFESTO.md) first:
+it says what this package is responsible for and what it is not. This file is how to keep it.
+
+## Before you change anything
+
+- **Read the manifesto.** A piece that serves nothing there does not go in; a piece it forbids
+  does not either. If you think it should, change the manifesto first and say why.
+- **Look at the backend.** This package mirrors sincpro_framework (`~/dev/sincpro_framework`):
+  `Feature`, `ApplicationService`, the context, the span per use case. When in doubt about a
+  word or a behaviour, read how the backend does it, not memory.
+- **Look at who uses it.** @sincpro/web-framework (`~/dev/sincpro_web_framework`) and
+  @sincpro/mobile (`~/dev/mobile/sincpro_mobile`). A piece only one of them needs, and that
+  needs a platform, belongs there.
+
+## Where things go
+
+| Folder               | What                                                                                    |
+| -------------------- | --------------------------------------------------------------------------------------- |
+| `src/client/`        | The seam with a server: `Transport`, REST, memory, `entity()`, the client contract, ids |
+| `src/model/`         | Model definitions: `defineMeta`, from a JSON Schema, the store of known ones            |
+| `src/services/`      | `Feature`, `ApplicationService`, the runtime, the execution and what binds to it        |
+| `src/observability/` | The ports a platform plugs: `Tracer`, `ErrorReporter`                                   |
+| `src/codegen/`       | The generator and its CLI (`sincpro-client generate`) — the only place Node is allowed  |
+| `src/testing/`       | `memoryTracer`, `memoryReporter` — the ports in memory, for tests                       |
+| `tests/`             | vitest in Node; `tests/support/` holds the fake domains and forge's real contracts      |
+
+## Hard rules (the build enforces them — `make doctor`)
+
+- **Platform-neutral.** No React, no `react-native`, no web-ui, no composer, no @sincpro/mobile;
+  no `document`, `window`, `localStorage`, `navigator`. What a platform must give, it gives
+  through a port.
+- **Node only in the generator.** `node:` imports, `process` and `Buffer` live in `src/codegen/`
+  and nowhere else; nothing in the runtime imports `codegen/`.
+- **Self-imports, no extensions.** Inside `src/`, import `@sincpro/client-framework/<path>` —
+  never a relative path, never `.ts`.
+
+## Conventions
+
+- Code, comments and docs in English: this package is open source.
+- `Context:` blocks at the top of a file are the design record: why it is the way it is. Keep
+  them true.
+- A change ships with a test in `tests/` that fails without it, run in Node.
+- Public means exported from `src/index.ts`. No side effects at import (`sideEffects: false`).
+- A port (an `interface`) only where there are two implementations; a class or a type otherwise.
+
+## Known traps
+
+- **A run sees the instance through a view of its own.** Inside a method, `this.deps`,
+  `this.context` and `this.features` are that run's — bound to its execution. So a Feature keeps
+  nothing of a request on `this`, and declares no `#private` fields (they refuse the view); use
+  TypeScript's `private`.
+- **A span is named by the key, not the class** (`bindServices(runtime, "project", { sendIssue })`
+  → `project/sendIssue`; an ApplicationService's Features by their keys too): a production build
+  renames classes. Only an unbound Feature falls back to its class name.
+- **The trace reaches the wire through `deps`.** A dependency is bound to the run when it is a
+  `Transport` or carries `BIND` (every generated client does, through `bindable`); anything else
+  is handed as it is. A client built outside `deps` and closed over sends no trace.
+- **What the generator writes is compared byte for byte** (`tests/support/forge-contract/`, out
+  of prettier and eslint). After changing the generator on purpose, run `make codegen-fixtures`
+  and read the diff.
+- **A module name the generator writes is built in parts** (`codegen/names.ts`, `FRAMEWORK`): the
+  build's `tsc-alias` rewrites this package's specifiers inside strings too.
+- **Reported means unexpected.** A `TransportError` the server answered with a 4xx is `refused`,
+  an `AbortError` is `aborted`; neither is reported (`outcomeOf`). Change that with
+  `RuntimeOptions.outcomeOf`, never by catching in a Feature.
+
+## Before you hand it back
+
+```bash
+make verify-format   # eslint --fix + prettier + typecheck + doctor
+make test
+make build
+```
+
+Never bump `version` in `package.json` — the release pipeline does. Never commit; a person
+does.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SINCPRO S.R.L
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MANIFESTO.md

@@ -0,0 +1,124 @@
+# Manifesto
+
+> **@sincpro/client-framework is the client side of
+> [sincpro_framework](https://github.com/Sincpro-SRL/sincpro_framework), for every platform:
+> where a client's logic lives, how every use case is traced and reported, how an application is
+> made of domains, and how it talks to a service through a client generated from that service's
+> contract. No React, no DOM, no platform.**
+
+This is the founding statement of the repository: what it is responsible for, what it is not,
+how it is composed and where it is going. Every change is measured against it. If a change needs
+something this page does not say, change this page first, and say why.
+
+## Why it exists
+
+Sincpro builds business software with one backend framework and several clients: the web
+([@sincpro/web-framework](https://github.com/Sincpro-SRL/sincpro_web_framework)), mobile
+([@sincpro/mobile](https://github.com/Sincpro-SRL/sincpro_mobile)), server-side renders, scripts,
+tests. Each one was growing the same core on its own — mobile wrote `Feature` and
+`ApplicationService` with interceptors; the web wrote the transport, the entities and the
+generator from the contract — and a use case written for one could not run on the other.
+
+The backend already answers how a use case is written, traced and reported. This package gives
+every client the same answer, once: **a Feature written here runs in a browser, on a phone, in a
+server-side render, in a script and in a test, unchanged.**
+
+## What it is responsible for
+
+1. **Use cases.** `Feature` is one use case, with its dependencies injected; `ApplicationService`
+   is a Feature that also executes the Features of its own domain — never another
+   ApplicationService. All of a client's logic lives in them.
+2. **Interception.** Every public method of a use case passes through interceptors, and that is
+   what makes the defaults free: the trace, the error report, the context. The author of a
+   Feature writes none of it.
+3. **Observability, as ports.** `Tracer` and `ErrorReporter` are the contract: one span per use
+   case, named `<domain>/<Feature>` like the backend's; the unexpected reported with its trace id;
+   what the server already explained (a validation, a conflict) not reported. The platform plugs
+   the implementation — OpenTelemetry, GlitchTip, a queue on the phone, memory in a test.
+4. **Context.** The levels a call sees — the application, its domain, the call itself — and what
+   travels to the server with it (`traceparent`, `sincpro-context`). Carried by each call, never
+   kept in a global: two calls at once never mix their parents.
+5. **Domains and the application.** A bounded context is declared once — its client, its use
+   cases, what they depend on — and an application is the set of domains it loads. Domains never
+   import each other; they talk by reference.
+6. **The client.** The `Transport` port and its implementations (REST, memory), `entity()` with
+   typed commands and answers, the service's client contract, model definitions read once from
+   the server, client-side ids (UUID v7) and the server's `Problem`.
+7. **The generator.** From a service's client contract to each domain's types, client and
+   entities — generated, never edited, and as platform-neutral as everything else here.
+8. **Testing.** An in-memory transport, tracer and reporter, so a use case is proven in Node with
+   nothing else.
+
+## What it is not
+
+- **Not a UI.** No React, no components, no hooks: drawing belongs to @sincpro/web-framework on
+  the web and to @sincpro/mobile on a phone.
+- **Not a shell, a router or a window manager.** Where things open is the platform's.
+- **Not a cache or a state manager.** Holding server state for screens is the platform's job,
+  with the libraries that do it best.
+- **Not offline storage.** SQLite on a phone or IndexedDB in a point of sale are platform
+  adapters.
+- **Not a telemetry or error-tracking SDK.** It defines the ports and calls them; it bundles no
+  vendor.
+- **Not where business rules live.** The server keeps them; a client reads what it publishes.
+- **Not an event bus**, and not a dispatcher: a use case is executed by calling it, and the
+  interceptors are what make that call traced and reported.
+
+## What we believe
+
+1. **Platform-neutral, or it does not go in.** It runs on Node, in a browser and on React Native.
+   What it needs from a platform it asks through a port, never by reaching for it. The build
+   enforces it.
+2. **The backend's words.** Feature, ApplicationService, domain, context, the span name — the
+   same as sincpro_framework, so whoever knows the backend already knows the client.
+3. **Nothing escapes the interceptors.** Reusing a use case is executing its Feature. A helper
+   that wraps one skips the trace and the report — that is how an incident ends up with nothing
+   to look at.
+4. **Context travels with the call.** Never in a global stack: clients run many things at once.
+5. **A port where there are two implementations, a class where there is one.** `Transport` has
+   REST and memory; `Tracer` has a platform's and a test's.
+6. **Generated, never edited.** Applications extend by composition; regenerating never loses
+   work.
+7. **The server is the source of truth.** A client reads the model, the preview and the refusal,
+   and never re-implements a rule.
+8. **Small, and paid for only when used.** No side effects at import, tree-shakable, and no
+   dependency it can avoid.
+9. **Grow by evidence.** Nothing before its second use; every change ships with a test that fails
+   without it.
+
+## How it is composed
+
+```text
+@sincpro/criteria           the contract with the server: Criteria, Meta, Page, Problem
+        ▲
+@sincpro/client-framework   this package — platform-neutral
+        │   Feature · ApplicationService · interceptors · context per call
+        │   Domain · application · Tracer and ErrorReporter ports
+        │   Transport · entity() · client contract · model definitions · ids
+        │   the generator · in-memory doubles for tests
+        ▲
+@sincpro/web-framework      the web: hooks, components on @sincpro/web-ui, the shell on
+                            @sincpro/web-composer, the browser's tracing and error reporting
+@sincpro/mobile             mobile: the React Native shell, SQLite, its queue, its exporter
+```
+
+Dependencies point down only. This package knows nothing above it.
+
+## Where it stands
+
+**The first cut is here.** The client and the generator came out of @sincpro/web-framework,
+where they already ran without the DOM. `Feature` and `ApplicationService` came from
+@sincpro/mobile, with each call carrying its own execution instead of a global stack. And the
+ports for tracing and error reporting are in, with the trace and the context written on every
+request a use case sends.
+
+**Next:** the domains and the application. The plan is written in @sincpro/web-framework
+(`docs/prd/PRD_02_marco-de-trabajo.md`, in Spanish like the rest of Sincpro's design records).
+
+## How we decide
+
+This page is the yardstick. A piece that serves nothing here does not go in. A piece this page
+forbids does not go in either. To change what this page says, change the page first — in the
+open, with the reason.
+
+Open source, under the [MIT license](LICENSE).

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# @sincpro/client-framework
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The client side of [sincpro_framework](https://github.com/Sincpro-SRL/sincpro_framework), for
+every platform.** Write a use case once — a `Feature`, or an `ApplicationService` that composes
+Features — and run it in a browser, on a phone, in a server-side render, in a script or in a test.
+Every use case is traced and every unexpected error reported, continuing the backend's trace,
+without its author writing either. A service's client contract becomes typed code for each of
+its domains.
+
+> **Status: 0.x, the first cut.** The API may still change before 1.0. In: the client, the
+> generator, `Feature` and `ApplicationService` with their interceptors, and the ports for tracing
+> and error reporting. Read the [manifesto](MANIFESTO.md) for what this package is responsible
+> for, what it is not and where it is going.
+
+## A use case, traced and reported by default
+
+```ts
+import {
+  ApplicationService,
+  bindServices,
+  createRuntime,
+  Feature,
+} from "@sincpro/client-framework";
+
+class SendIssue extends Feature<{ project: ProjectClient }> {
+  execute(input: dto.CommandSendIssue) {
+    return this.deps.project.sendIssue(input); // carries this run's traceparent
+  }
+}
+
+class CloseIssue extends ApplicationService<{ preview: PreviewClose; send: SendIssue }> {
+  async execute(input: CloseIssueInput) {
+    const preview = await this.features.preview.execute(input); // a child span
+    if (preview.warnings.length > 0) return { blocked: preview };
+    return this.features.send.execute({ ...input, message: "closed" }); // another child
+  }
+}
+
+const runtime = createRuntime({ tracer, reporter, context: () => ({ tenant_id: "acme" }) });
+const project = bindServices(runtime, "project", {
+  closeIssue: new CloseIssue({ preview: new PreviewClose(deps), send: new SendIssue(deps) }),
+});
+await project.closeIssue.execute(input); // project/closeIssue → project/preview, project/send
+```
+
+`tracer` and `reporter` are the platform's: OpenTelemetry and GlitchTip in a browser, a queue on
+a phone, `memoryTracer()` and `memoryReporter()` (`@sincpro/client-framework/testing`) in a test.
+A use case that was never bound runs too, with nothing tracing.
+
+## Where it sits
+
+```text
+@sincpro/criteria           the contract with the server
+        ▲
+@sincpro/client-framework   use cases · interceptors · context · ports · domains · the client
+        ▲
+@sincpro/web-framework      the web          @sincpro/mobile      a phone
+```
+
+No React, no DOM, no platform: what a platform must provide — how a span is exported, where an
+error is reported — it plugs through a port.
+
+## Development
+
+Node 26 (`nvm use`).
+
+```bash
+make init            # pre-commit + dependencies
+make test            # vitest, in Node
+make verify-format   # format + lint + doctor; fails if the tree is left dirty (what CI runs)
+make build           # tsc into dist/
+```
+
+`make doctor` enforces what the type checker cannot: the source imports itself, never a relative
+path; no React, no UI, no browser global; Node only inside the generator. Read
+[`AGENTS.md`](AGENTS.md) before changing anything, and [`CONTRIBUTING.md`](CONTRIBUTING.md)
+before opening a pull request.
+
+## CI/CD
+
+Every workflow in `.github/workflows/` delegates to
+[`Sincpro-SRL/.github`](https://github.com/Sincpro-SRL/.github) and only calls `make` targets:
+checks on every pull request and push to `main`, a release draft on `main`, publication to npm
+when a release is published, and notifications. The version is written by the release pipeline,
+never by hand.
+
+## License
+
+[MIT](LICENSE)

package/dist/client/contract.d.ts

@@ -0,0 +1,34 @@
+import { type Contract, type Meta } from "@sincpro/criteria";
+/**
+ * A bounded context's client contract, as the application keeps it: the snapshot
+ * `sincpro-web generate` writes (`contract.json`), or the document a service serves
+ * (`GET /client-contract/<context>.json`). Only its models are read here.
+ *
+ * Context: the generated entities are keyed `<domain>:<kind>` (`project:issue`) — the key the
+ * workspace refers to them by and the meta store keeps their definitions under —, so the rule
+ * that turns a model's name into its kind lives once, here, and both the generator and the
+ * preload read it.
+ */
+export type ClientContract = {
+    models: Readonly<Record<string, Contract>>;
+    $defs?: Readonly<Record<string, Contract>>;
+};
+/** `ProjectEvent` → `project_event`: the kind in an entity's key. */
+export declare function kindOf(model: string): string;
+/** The key of a model's entity: `entityKeyOf("project", "ProjectEvent")` → `"project:project_event"`. */
+export declare function entityKeyOf(domain: string, model: string): string;
+/**
+ * The version of every entity of `contract`, by its model's name — what `restTransport`
+ * compares each answer with (`snapshot`) to say when the generated code is behind the server.
+ *
+ *     restTransport({ base: "/v1", snapshot: versionsOf(contract), onVersionDrift: warn })
+ */
+export declare function versionsOf(contract: ClientContract): Record<string, string>;
+/**
+ * The definition of every model of `contract`, by its entity's key — what `FrameworkProvider
+ * metas` preloads, so the first screen draws its labels with no request at all. The transport
+ * still reads the live definition and asks again when an answer says another version.
+ *
+ *     <FrameworkProvider transport={transport} metas={metasOf(contract, "project")}>
+ */
+export declare function metasOf(contract: ClientContract, domain: string): Record<string, Meta>;

package/dist/client/contract.js

@@ -0,0 +1,41 @@
+import { metaFromContract } from "@sincpro/criteria";
+/** `ProjectEvent` → `project_event`: the kind in an entity's key. */
+export function kindOf(model) {
+    return model
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1_$2")
+        .toLowerCase();
+}
+/** The key of a model's entity: `entityKeyOf("project", "ProjectEvent")` → `"project:project_event"`. */
+export function entityKeyOf(domain, model) {
+    return `${domain}:${kindOf(model)}`;
+}
+/**
+ * The version of every entity of `contract`, by its model's name — what `restTransport`
+ * compares each answer with (`snapshot`) to say when the generated code is behind the server.
+ *
+ *     restTransport({ base: "/v1", snapshot: versionsOf(contract), onVersionDrift: warn })
+ */
+export function versionsOf(contract) {
+    return Object.fromEntries(Object.entries(contract.models).flatMap(([name, model]) => {
+        const version = model["x-sincpro"]?.version;
+        return model["x-sincpro"]?.identity != null && typeof version === "string"
+            ? [[name, version]]
+            : [];
+    }));
+}
+/**
+ * The definition of every model of `contract`, by its entity's key — what `FrameworkProvider
+ * metas` preloads, so the first screen draws its labels with no request at all. The transport
+ * still reads the live definition and asks again when an answer says another version.
+ *
+ *     <FrameworkProvider transport={transport} metas={metasOf(contract, "project")}>
+ */
+export function metasOf(contract, domain) {
+    // A related model, or a value a record holds, is pointed at by its name (`#/models/Run`).
+    const related = { ...(contract.$defs ?? {}), ...contract.models };
+    return Object.fromEntries(Object.entries(contract.models)
+        // Only an entity has a key of its own; a value it holds is described inside it.
+        .filter(([, model]) => model["x-sincpro"]?.identity != null)
+        .map(([name, model]) => [entityKeyOf(domain, name), metaFromContract(model, related)]));
+}

package/dist/client/discovery.d.ts

@@ -0,0 +1,47 @@
+import { type Meta } from "@sincpro/criteria";
+/**
+ * The discovery document of a bounded context, as far as this reads it: its paths, each
+ * operation with the entities it belongs to, and the published contract of every model.
+ *
+ * Context: sincpro_framework describes a model once — JSON Schema with `x-sincpro`, under the
+ * document's `components.schemas` — and every read answers only the version of it
+ * (`model_version`). So the definition a list, a form and a select are built from is read here,
+ * once, and asked for again only when an answer says another version.
+ */
+export type DiscoveryDocument = {
+    paths?: Readonly<Record<string, Readonly<Record<string, DiscoveryOperation>>>>;
+    components?: {
+        schemas?: Readonly<Record<string, DocumentSchema>>;
+    };
+};
+export type DiscoveryOperation = {
+    "x-sincpro-entities"?: readonly string[];
+    responses?: Readonly<Record<string, {
+        content?: Readonly<Record<string, {
+            schema?: DocumentSchema;
+        }>>;
+    }>>;
+};
+type DocumentSchema = {
+    $ref?: string;
+    items?: DocumentSchema;
+    anyOf?: readonly DocumentSchema[];
+    properties?: Readonly<Record<string, DocumentSchema>>;
+    "x-sincpro"?: {
+        entity?: string;
+        version?: string;
+    };
+};
+/**
+ * The model a request to `path` answers, by the name of its contract in the document: the
+ * entity the operation says it belongs to, else the one its answer holds.
+ *
+ *     modelAt(published, "/v1/projects/p1", "get")   // "Project"
+ */
+export declare function modelAt(published: DiscoveryDocument, path: string, method: string): string | undefined;
+/** The definition of the model named `name`, read from its contract, and its version. */
+export declare function definitionOf(published: DiscoveryDocument, name: string): {
+    meta: Meta;
+    version: string | null;
+} | undefined;
+export {};

package/dist/client/discovery.js

@@ -0,0 +1,68 @@
+import { metaFromContract, versionOf } from "@sincpro/criteria";
+function nameOfRef(ref) {
+    return ref === undefined ? undefined : ref.slice(ref.lastIndexOf("/") + 1);
+}
+/** Whether a document path (`/v1/projects/{id}`) answers a request path (`/v1/projects/p1`). */
+function answers(template, path) {
+    const pattern = template
+        .split("/")
+        .map((part) => /^\{[^}]+\}$/.test(part) ? "[^/]+" : part.replace(/[.*+?^$()|[\]\\]/g, "\\$&"))
+        .join("/");
+    return new RegExp(`^${pattern}$`).test(path);
+}
+/** The entity a schema describes, or the one its records hold: an answer's records field. */
+function entityIn(schema, schemas, seen = new Set()) {
+    if (schema === undefined)
+        return undefined;
+    const named = nameOfRef(schema.$ref);
+    if (named !== undefined) {
+        if (seen.has(named))
+            return undefined;
+        seen.add(named);
+        const target = schemas[named];
+        return target?.["x-sincpro"]?.entity !== undefined
+            ? named
+            : entityIn(target, schemas, seen);
+    }
+    for (const one of [schema.items, ...(schema.anyOf ?? [])]) {
+        const found = entityIn(one, schemas, seen);
+        if (found !== undefined)
+            return found;
+    }
+    for (const one of Object.values(schema.properties ?? {})) {
+        const found = entityIn(one, schemas, seen);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+/**
+ * The model a request to `path` answers, by the name of its contract in the document: the
+ * entity the operation says it belongs to, else the one its answer holds.
+ *
+ *     modelAt(published, "/v1/projects/p1", "get")   // "Project"
+ */
+export function modelAt(published, path, method) {
+    const schemas = published.components?.schemas ?? {};
+    for (const [template, item] of Object.entries(published.paths ?? {})) {
+        if (!answers(template, path))
+            continue;
+        const operation = item[method.toLowerCase()];
+        if (operation === undefined)
+            continue;
+        const declared = operation["x-sincpro-entities"]?.[0];
+        if (declared !== undefined && schemas[declared] !== undefined)
+            return declared;
+        const answered = operation.responses?.["200"]?.content?.["application/json"]?.schema;
+        return entityIn(answered, schemas);
+    }
+    return undefined;
+}
+/** The definition of the model named `name`, read from its contract, and its version. */
+export function definitionOf(published, name) {
+    const schemas = (published.components?.schemas ?? {});
+    const contract = schemas[name];
+    if (contract?.["x-sincpro"] === undefined)
+        return undefined;
+    return { meta: metaFromContract(contract, schemas), version: versionOf(contract) };
+}