microcoreos 0.1.0__py3-none-any.whl

microcoreos/__init__.py

@@ -0,0 +1,23 @@
+"""
+MicroCoreOS — the public address of the framework.
+
+Plugins and tools import from HERE, never from the file that happens to define
+a name today:
+
+    from microcoreos import BasePlugin, BaseTool, ToolUnavailableError
+
+`Kernel`, `Container` and `Registry` stay in their submodules on purpose: they
+are boot-time machinery (`main.py`, tests), not plugin surface.
+"""
+
+from microcoreos.base_plugin import BasePlugin
+from microcoreos.base_tool import BaseTool, ToolUnavailableError
+from microcoreos.context import current_event_id_var, current_identity_var
+
+__all__ = [
+    "BasePlugin",
+    "BaseTool",
+    "ToolUnavailableError",
+    "current_event_id_var",
+    "current_identity_var",
+]

microcoreos/_template/.agent/skills/microcoreos-architecture/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: microcoreos-architecture
+description: Ensures adherence to MicroCoreOS "Atomic Microkernel" architecture. Use when creating or modifying core, tools, plugins, or domains.
+---
+
+# MicroCoreOS Architecture Skill
+
+## Reading Path
+
+**To write a plugin**: Read `AI_CONTEXT.md` + entity model in `domains/{domain}/models/`. Nothing else.
+**To create a full domain**: Use the `/new-domain` workflow.
+**Templates + anti-patterns + detailed rules**: `INSTRUCTIONS_FOR_AI.md`.
+
+## Pre-commit Checklist
+
+- [ ] `main.py` untouched
+- [ ] No cross-domain imports (use `event_bus`)
+- [ ] Entity in `models/` mirrors DB only — schemas inline in plugin
+- [ ] All request fields use `pydantic.Field` with constraints
+- [ ] `response_model=` passed to `add_endpoint`
+- [ ] Plugin is a single self-contained file
+- [ ] `async def` for I/O, `def` for CPU
+- [ ] Test file exists at `tests/test_{name}_plugin.py`
+- [ ] `uv run main.py` runs without errors (or `microcoreos` / `microcoreos run` if installed)

microcoreos/_template/.agent/skills/microcoreos-architecture/agent.md

@@ -0,0 +1,18 @@
+# Agent Persona for MicroCoreOS
+
+You are a **Systems Architect** specialized in high-performance, resilient micro-kernels.
+
+## Communication Style
+- Precise and technical.
+- Proactive in identifying architectural violations.
+- Transparent about performance trade-offs (e.g., threading, memory isolation).
+
+## Decision Framework
+- **Core First**: Is this change affecting the Core? If yes, look for an alternative in Plugins/Tools.
+- **Tool Isolation**: Does this Tool import another Tool? If so, REJECT the design and move the logic to a Plugin (Bridge).
+- **Sacred Rules Review**: Before implementation, verify against the "Three Golden Rules" in `SKILL.md`.
+- **Resilience**: Will a failure here crash the entire system?
+- **Observability**: Can this be monitored via the `registry`?
+
+- **No Boilerplate Thinking:** If you feel the urge to add setup code to `main.py`, STOP. The Kernel is auto-discovering. Do not write manual initialization code.
+- **The "Magic" is in the Kernel:** Trust the `Kernel` to inject arguments based on parameter names in the Plugin's constructor.

microcoreos/_template/.agent/workflows/feature-plan.md

@@ -0,0 +1,111 @@
+---
+description: Plan and build one or more features (plugins) on an EXISTING domain
+---
+
+# Feature Plan Workflow
+
+The smallest planning level: new plugins on a domain that already exists. No
+migrations, no new tools — if you need either, escalate to
+[new-domain.md](new-domain.md) or [multi-domain-plan.md](multi-domain-plan.md).
+
+## Prerequisites
+
+- Read `AI_CONTEXT.md` — the live inventory (tools, domains, events, routes).
+- Check `GET /system/events/schemas` (or the "Events emitted" lines in
+  `AI_CONTEXT.md`) for the payload contracts of any event you will consume.
+
+## Steps
+
+### 1. Write the mini-plan
+
+Write it to `plans/active_plan.yaml`: one `features:` entry per plugin
+(~10-15 lines each), plus a `flows:` entry ONLY if the feature publishes or
+consumes events — omit `flows` entirely otherwise. Same schema as the formal
+plan format (`docs/PARALLEL_DEVELOPMENT.md`), just without `phase_0`:
+
+```yaml
+plan:
+  domain: orders            # existing domain
+  features:
+    - plugin: CancelOrderPlugin
+      file: domains/orders/plugins/cancel_order_plugin.py
+      function: "Cancel an order and announce it"
+      route: { method: POST, path: /orders/{order_id}/cancel }
+      db: { writes: [orders], reads: [] }   # persistence contract — own-domain tables only
+      publishes:
+        - event: order.cancelled
+          model: OrderCancelledPayload
+          payload: { id: int, reason: str }
+      consumes: []
+      mocks: [db, event_bus]
+      test: tests/test_cancel_order.py
+  flows:
+    - name: order-cancellation
+      durability: ephemeral   # durable → in-flight events must survive a crash (needs sqlite/redis driver)
+      happy_path: "POST /orders/{id}/cancel → order.cancelled → RefundPlugin → order.refunded"
+      e2e_test: tests/test_order_cancellation_chain.py
+      sad_path_test: tests/test_order_cancellation_dlq.py  # mandatory: a link declares retries
+      links:
+        - consumes: order.cancelled
+          consumer: RefundPlugin
+          retries: 3
+          backoff: 1.0
+          idempotent: true        # mandatory when retries > 0 OR the flow is durable
+          idempotency_test: tests/test_refund.py::test_on_order_cancelled_delivered_twice
+          dlq_watcher: null
+          atomic_with_db: false   # true → this feature is the trigger for Issue 28 (outbox)
+          compensation: null
+      rpc_links: []               # every request() call, with timeout + on_timeout
+```
+
+### 2. Validate before writing code
+
+`POST /system/plan/validate` with the plan (YAML or JSON) — it runs the 14
+validity rules of `docs/PARALLEL_DEVELOPMENT.md` against this plan AND the
+live system. Zero `errors` before any code; `warnings` are advisory. The main
+things it catches at this level:
+
+- The `route` and `file` collide with nothing live.
+- Every consumed event exists (live system or this plan) and provides the
+  `requires` keys.
+- Every flow link has the sad-path checklist answered (`idempotent: true` +
+  `idempotency_test` where `retries > 0` or the flow is `durable`).
+- `sad_path_test` present where the flow declares retries / DLQ / compensation.
+- `db:` tables are owned by this domain.
+
+### 3. Implement
+
+One file per feature. Request, response AND event payload schemas inline.
+Publish with `XxxPayload(...).model_dump()` — bare call, no arguments.
+
+### 4. Test
+
+- One test per plugin proving the black-box contract: input → output, DB
+  effects on the declared tables, published payloads with the declared fields.
+  Mock exactly the tools the plan's `mocks:` lists; run the rest as real
+  in-memory instances (`INSTRUCTIONS_FOR_AI.md` § Testing).
+- One double-delivery test per idempotent link (same envelope twice → same
+  final state), at the path declared in `idempotency_test`.
+- One chain test per flow, using the helper:
+
+```python
+from tests.helpers.trace_chains import build_tree, assert_chain
+# trigger the flow, then:
+assert_chain(build_tree(bus.get_trace_history()), ["order.cancelled", "order.refunded"])
+```
+
+- One sad-path test per flow that declares retries / DLQ / compensation: force
+  the consumer to fail (mock that raises) and assert the decided outcome —
+  `_dlq.<event>` is causally chained to the event that failed, so the same
+  helper works: `assert_chain(tree, ["order.cancelled", "_dlq.order.cancelled"])`.
+
+### 5. Close
+
+```bash
+// turbo
+uv run main.py   # or: microcoreos (if you installed the package)
+```
+
+- `GET /system/lint` → no warnings, no `UNTYPED_PAYLOAD` for your events.
+- Regenerated `AI_CONTEXT.md` matches the plan (routes, events, keys).
+  **The feature is done when AI_CONTEXT == plan.**

microcoreos/_template/.agent/workflows/multi-domain-plan.md

@@ -0,0 +1,96 @@
+---
+description: Plan and build a large spec spanning multiple domains (full formal plan, parallel execution)
+---
+
+# Multi-Domain Plan Workflow
+
+The largest planning level: a spec that creates or touches several domains,
+with event chains crossing domain boundaries. The methodology is fully
+specified in `docs/PARALLEL_DEVELOPMENT.md` — this workflow is its checklist.
+
+**Everything is decided before any code exists**: every migration, model,
+tool, plugin, route, event (with its payload model), and every chain with its
+happy path and sad paths. Code-time conflicts are structurally impossible;
+what remains is getting the plan right.
+
+## Phase 1 — The full plan (the contract, authored FIRST)
+
+Write the complete YAML plan of `docs/PARALLEL_DEVELOPMENT.md` ("Formal plan
+format") to `plans/active_plan.yaml`: `phase_0` (every migration with its
+`tables:` ownership AND its full `columns:` — phase 0 is built from the plan,
+nothing is improvised later), `features` (one per plugin, with
+`publishes.model` / `consumes.requires` / the `db:` persistence contract),
+and `flows` — each with
+its `durability` (may in-flight events die with the process? `durable` needs
+the sqlite/redis driver) and the sad-path checklist per link:
+
+- `retries` / `backoff` — re-delivery policy
+- `idempotent` — MANDATORY `true` where `retries > 0` OR the flow is `durable`
+  (durable transports re-deliver after a crash even with zero retries)
+- `idempotency_test` — the double-delivery proof for every idempotent link
+- `dlq_watcher` — who consumes `_dlq.<event>` (`null` = loss explicitly
+  accepted; a non-null watcher must exist in the plan or live)
+- `atomic_with_db` — `true` means this chain cannot lose the event between DB
+  commit and publish → it is the implementation trigger for the Transactional
+  Outbox (ROADMAP Issue 28); flag it, do not improvise one
+- `compensation` — the event that undoes upstream work if the chain dies
+  (saga); it must be published AND consumed within the plan
+- `sad_path_test` (flow-level) — mandatory when any link declares retries,
+  a DLQ watcher or a compensation
+- `rpc_links` (flow-level) — every `request()` call, with `timeout` and
+  `on_timeout`
+
+Then run the 15 validity rules mechanically: `POST /system/plan/validate`
+with the plan (YAML or JSON) against the live system — zero `errors` before
+building anything. An invalid plan is a task-allocation error — fix the plan,
+never patch it in code.
+
+## Phase 0 — Foundation (built FROM the plan; serial, one author)
+
+1. New **tools** only if the spec demands infrastructure that does not exist
+   → follow [new-tool.md](new-tool.md), parity suite included. Written 1:1
+   from the plan's `contract:` (signatures + return shape), never inventing
+   a method — same rule as `columns:` for migrations.
+2. All **migrations** (`domains/*/migrations/*.sql`) with their **models**,
+   written 1:1 from the plan's `columns:`, sequential numbering, `-- depends:`
+   for cross-domain ordering.
+
+(1 and 2 are independent at write time — disjoint files; two agents in any
+order or in parallel is fine. Migrations keep one author for numbering.)
+
+3. Boot once (`uv run main.py`, or `microcoreos` if you installed the
+   package), only after everything is written →
+   regenerated `AI_CONTEXT.md` is the ground truth every agent receives
+   (it must include the new tools' interfaces). Freeze phase 0.
+
+## Phase 2 — Execution (parallel)
+
+Dispatch one agent per feature with the **canonical executor prompt**
+(`docs/PARALLEL_DEVELOPMENT.md` § Phase 2): a byte-identical shared prefix —
+`AI_CONTEXT.md` (which embeds the executor rules and templates as its
+"Plugin Authoring Guide" section) → full plan — plus one final per-agent line
+naming its feature. Dispatch executors **write-only, scoped to the two paths
+their plan entry declares** (`file:` + `test:` for a feature, the flow's two
+test paths for flow tests — no read/search/shell tools): the prefix is self-sufficient
+by construction, with one complete template per deliverable type embedded in
+`AI_CONTEXT.md` § Authoring Templates. Agents never open the plan or `AI_CONTEXT.md` themselves;
+the identical prefix lets any prefix-caching engine process the shared block
+once for the whole wave. Each agent produces exactly two files: its plugin
+and its unit test. Event payload schemas go inline in each publisher plugin
+(`XxxPayload(...).model_dump()`). Never assign two agents to the same feature.
+
+## Phase 3 — Integration boot (the safety net)
+
+```bash
+// turbo
+uv run main.py   # or: microcoreos (if you installed the package)
+```
+
+1. `GET /system/lint` → zero warnings (arch, drift, event contracts) and no
+   `UNTYPED_PAYLOAD` for the plan's events.
+2. `GET /system/events/schemas` → every planned event appears with its model.
+3. Full suite: `uv run -m pytest` — includes one chain e2e per flow
+   (`tests/helpers/trace_chains.py`: `assert_chain(build_tree(...), [...])`),
+   the sad-path tests (`_dlq.<event>` chains) and the double-delivery
+   idempotency tests the plan declared.
+4. Regenerated `AI_CONTEXT.md` == plan. **The spec is done when they match.**

microcoreos/_template/.agent/workflows/new-domain.md

@@ -0,0 +1,201 @@
+---
+description: Create a complete new domain with entity, migration, and CRUD plugins
+---
+
+# New Domain Workflow
+
+Creates a full domain from scratch: entity model, SQL migration, and one plugin per use case.
+
+> Planning levels: single features on an existing domain → [feature-plan.md](feature-plan.md) ·
+> one new domain → this workflow · several domains / cross-domain chains →
+> [multi-domain-plan.md](multi-domain-plan.md) · new infrastructure → [new-tool.md](new-tool.md).
+
+## Prerequisites
+- Read `AI_CONTEXT.md` for available tools.
+- Read `INSTRUCTIONS_FOR_AI.md` for rules and templates.
+
+## Steps
+
+### 0. Plan the domain first
+
+Write the plan of `docs/PARALLEL_DEVELOPMENT.md` ("Formal plan format") scoped
+to this domain: `phase_0` (its migrations + models, with table ownership AND
+every table's `columns:` — name, SQL type, constraints; steps 2-3 below are
+written from this, never invented), `features` (one per plugin, every
+published event with its payload `model` and fields, plus the `db:`
+persistence contract), and — ONLY if any plugin publishes or consumes events —
+`flows` (durability, happy path + the sad-path checklist per link — including
+the `atomic_with_db` outbox question — and the declared `idempotency_test` /
+`sad_path_test` files). A pure-CRUD domain has no `flows` section at all; a
+domain whose delete cascades through one event has exactly one flow.
+Validate with `POST /system/plan/validate` before writing code. Build in that
+order — tools first if any, then migrations + models, then plugins with their
+events. Nothing below this line should require a decision the plan did not
+already make. Expected size for a CRUD domain with one event chain: ~80-120
+lines of YAML, one pass.
+
+### 1. Create the domain folder structure
+
+```bash
+// turbo
+mkdir -p domains/{name}/models domains/{name}/migrations domains/{name}/plugins
+```
+
+Create `domains/{name}/__init__.py`:
+```python
+# Auto-discovered by the Kernel. No manual registration needed.
+```
+
+### 2. Create the Entity model
+
+File: `domains/{name}/models/{name}.py`
+
+This file contains ONE thing: the Pydantic model that mirrors the database table exactly.
+
+```python
+from pydantic import BaseModel
+
+class {Name}Entity(BaseModel):
+    id: int | None = None
+    # Add fields that match the DB columns exactly
+    # Use the DB column names (e.g. password_hash, not password)
+```
+
+### 3. Create the SQL migration
+
+File: `domains/{name}/migrations/001_create_{name}_table.sql`
+
+Write raw SQL that creates the table. Use `$1, $2...` placeholders in queries (PostgreSQL-style, auto-converted for SQLite).
+
+```sql
+CREATE TABLE IF NOT EXISTS {name}s (
+    id SERIAL PRIMARY KEY,
+    -- columns matching the entity model
+    created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+### 4. Create plugins (1 file = 1 use case)
+
+For each operation (create, get_all, get_by_id, update, delete), create a separate plugin file in `domains/{name}/plugins/`.
+
+**Critical rules**:
+- Define the **request schema** (what the HTTP client sends) at the **top of the plugin file**, NOT in the models folder.
+- Define the **response schema** (what the HTTP client receives) at the **top of the plugin file** too — never import the Entity for this; only expose the fields you actually return.
+- Define the **event payload schema** for every event this plugin publishes, also at the top of the file: `{Name}CreatedPayload(BaseModel)`. Publish with `.model_dump()` (bare call, no arguments). The publisher owns the event contract — consumers in other domains never import it; they declare their own model with only the fields they need (tolerant reader).
+- Always pass `response_model=` to `add_endpoint` — this generates complete OpenAPI docs.
+
+Example for create:
+
+File: `domains/{name}/plugins/create_{name}_plugin.py`
+
+```python
+from typing import Optional
+from pydantic import BaseModel
+from microcoreos import BasePlugin
+
+# ── Request schema lives HERE ──────────────────────
+class Create{Name}Request(BaseModel):
+    # Only input fields — no id, no internal fields
+    field1: str
+    field2: int
+
+# ── Response schema lives HERE ─────────────────────
+class {Name}Data(BaseModel):
+    id: int
+    field1: str
+    field2: int
+
+class Create{Name}Response(BaseModel):
+    success: bool
+    data: Optional[{Name}Data] = None
+    error: Optional[str] = None
+
+# ── Event payload schema lives HERE (publisher owns the contract) ──
+class {Name}CreatedPayload(BaseModel):
+    id: int
+
+class Create{Name}Plugin(BasePlugin):
+    def __init__(self, http, db, event_bus, logger):
+        self.http = http
+        self.db = db
+        self.bus = event_bus
+        self.logger = logger
+
+    async def on_boot(self):
+        self.http.add_endpoint(
+            "/{name}s", "POST", self.execute,
+            tags=["{Name}s"], request_model=Create{Name}Request,
+            response_model=Create{Name}Response,
+        )
+
+    async def execute(self, data: dict, context=None):
+        try:
+            req = Create{Name}Request(**data)
+            new_id = await self.db.execute(
+                "INSERT INTO {name}s (field1, field2) VALUES ($1, $2) RETURNING id",
+                [req.field1, req.field2]
+            )
+            self.logger.info(f"{Name} created with ID {new_id}")
+            await self.bus.publish("{name}.created", {Name}CreatedPayload(id=new_id).model_dump())
+            return {"success": True, "data": {"id": new_id, "field1": req.field1, "field2": req.field2}}
+        except Exception as e:
+            # Safe Error Reporting: log technically, respond safely (never str(e)).
+            self.logger.error(f"Failed to create {name}: {e}")
+            return {"success": False, "error": "Database operation failed"}
+```
+
+Repeat for: `get_{name}s_plugin.py`, `get_{name}_by_id_plugin.py`, `update_{name}_plugin.py`, `delete_{name}_plugin.py`.
+
+### 5. Verify
+
+```bash
+// turbo
+uv run main.py   # or: microcoreos (if you installed the package)
+```
+
+Check that:
+- Migration ran successfully (look for `[Migration] ✅` in logs)
+- Endpoints appear in the Swagger UI at `http://localhost:5000/docs`
+- `GET /system/lint` has no warnings and no `UNTYPED_PAYLOAD` for your events
+- `GET /system/events/schemas` lists every event the plan declared
+- `AI_CONTEXT.md` was regenerated with the new domain — **done when it matches the plan**
+
+### 6. Generate tests
+
+Create `tests/test_{name}_plugin.py` with one test per plugin. Mock exactly
+the tools the plan's `mocks:` field lists; run the rest as real in-memory
+instances (`INSTRUCTIONS_FOR_AI.md` § Testing). Example with everything
+mocked (`mocks: [http, db, event_bus, logger]`):
+
+```python
+import pytest
+from unittest.mock import MagicMock, AsyncMock
+from domains.{name}.plugins.create_{name}_plugin import Create{Name}Plugin
+
+@pytest.mark.anyio
+async def test_create_{name}_success():
+    plugin = Create{Name}Plugin(
+        http=MagicMock(),
+        db=AsyncMock(return_value=1),
+        event_bus=AsyncMock(),
+        logger=MagicMock(),
+    )
+    result = await plugin.execute({"field1": "value", "field2": 42})
+    assert result["success"] is True
+    assert result["data"]["id"] == 1
+
+@pytest.mark.anyio
+async def test_create_{name}_db_error():
+    plugin = Create{Name}Plugin(
+        http=MagicMock(),
+        db=AsyncMock(side_effect=Exception("DB down")),
+        event_bus=AsyncMock(),
+        logger=MagicMock(),
+    )
+    result = await plugin.execute({"field1": "value", "field2": 42})
+    assert result["success"] is False
+    assert "DB down" not in result["error"]  # Safe Errors: technical detail never reaches the client
+```
+
+Run with `uv run -m pytest tests/test_{name}_plugin.py`.

microcoreos/_template/.agent/workflows/new-tool.md

@@ -0,0 +1,72 @@
+---
+description: Create a new infrastructure Tool, or a replacement Tool that swaps an existing one (parity suite mandatory)
+---
+
+# New Tool Workflow
+
+Tools are the ONE legitimate place for shared infrastructure logic. Everything
+else about them exists so they can be swapped without touching a single plugin.
+
+## Prerequisites
+
+- Read `INSTRUCTIONS_FOR_AI.md` → "New Tool" and "The Parity Rule".
+- Decide which case you are in:
+  - **A. New capability** (a tool name that does not exist yet, e.g. `s3`).
+  - **B. Replacement** (same `name`, different backend, e.g. Redis state for
+    in-memory state). **The parity suite is NOT optional here.**
+
+## Rules (both cases)
+
+1. **Location**: `tools/{name}/{name}_tool.py` — or `extras/available_tools/{name}/`
+   if it should not be active by default (a replacement ALWAYS starts in
+   extras/: two tools with the same `name` silently overwrite each other).
+2. **The `name` property is the contract** — it is the DI injection key.
+3. **A tool never uses other tools.** If a capability needs `db` + `event_bus`
+   + `scheduler`, it is not a tool: compose it in the plugin layer
+   (precedents: DurableOneShotsPlugin, the deferred Outbox — Issue 28).
+4. **Self-documented**: every public method appears in
+   `get_interface_description()` — the anti-drift linter warns on discrepancies.
+5. **Config via `os.getenv()`** inside the tool (the `config` tool is for plugins).
+6. **Header spec**: the tool's docstring/header documents its replacement
+   contract — the exact API and semantics a substitute must honor.
+7. **External backend?** Make its connection-error class inherit
+   `ToolUnavailableError` so ToolProxy marks it DEAD on the first
+   infrastructure failure. In-memory/local tools skip this.
+
+## Steps
+
+### 1. Write the contract first
+
+The header spec + `get_interface_description()`. If this is case B, the
+contract already exists in the reference tool's header — read it, honor it.
+If the tool is phase 0 of a formal plan, the plan's `contract:` entry declares
+the signatures — honor it the way migrations honor `columns:`, never inventing
+a method. Keep the signatures backend-neutral: a payments contract that mirrors
+one provider's API makes the future swap cost what the abstraction saved.
+
+### 2. Implement
+
+No imports from other tools, no plugin imports, stateless where possible.
+
+### 3. Parity suite (case B: mandatory / case A: write it for the future)
+
+The same test battery runs against the reference implementation AND yours:
+
+- Canonical examples: `tests/tools/test_state_parity.py`,
+  `tests/tools/test_event_bus_broker_parity.py` (parameterized over transports).
+- If the backend needs a server, the suite skips itself when unavailable and
+  the server is added to CI services (`dev_infra/docker-compose.yml`).
+- **A replacement that does not pass the reference's parity suite is not a
+  replacement.** (Issue 22 — Contract Parity Rules.)
+
+### 4. Activate and verify end to end
+
+- Case B: move the reference out of `tools/`, move yours in (or set its env
+  switch), boot, and exercise a real flow through the swapped tool.
+- Check `AI_CONTEXT.md` regenerated with the tool's interface, and
+  `GET /system/status` shows it `OK`.
+
+### 5. Document
+
+- Add the tool to `README.md` (Available Tools / extras table).
+- If it introduced a new pattern or decision, record it in `ROADMAP.md`.

microcoreos/_template/.dockerignore

@@ -0,0 +1,23 @@
+# Dependencies and virtual environments
+.venv/
+
+# Secrets — never bake into the image
+.env
+
+# Local database files
+*.db
+*.sqlite3
+
+# Python cache
+__pycache__/
+*.py[cod]
+*.so
+
+# Dev tooling
+.github/
+dev_infra/
+tests/
+
+# OS artifacts
+.DS_Store
+Thumbs.db

microcoreos/_template/.env.example

@@ -0,0 +1,96 @@
+# ══════════════════════════════════════════════════════════════════
+# MicroCoreOS — Environment Variables Reference
+# Copy this file to .env and fill in your values.
+# ══════════════════════════════════════════════════════════════════
+
+
+# ─── HTTP Server ──────────────────────────────────────────────────
+HTTP_PORT=5000
+
+# Bind address. Default: 127.0.0.1 (dev-safe).
+# ⚠ PRODUCTION / DOCKER: must be 0.0.0.0 or the service won't accept external connections.
+# HTTP_HOST=0.0.0.0
+
+# CORS allowed origins. Default: * (allow all — dev-friendly).
+# Production: set to your actual frontend domain(s), comma-separated.
+# HTTP_CORS_ORIGINS=https://app.example.com,https://admin.example.com
+
+# Uvicorn log level. Default: warning (silent in prod).
+# Set to "info" to enable HTTP access logs (method, path, status, latency).
+# HTTP_LOG_LEVEL=info
+
+
+# ─── Authentication ───────────────────────────────────────────────
+# Not here by default: auth is an extra. `microcoreos add auth` appends
+# AUTH_SECRET_KEY and AUTH_TOKEN_EXPIRE_MINUTES to your .env.
+
+
+# ─── Database ─────────────────────────────────────────────────────
+
+# SQLite (default, zero-config — just run uv run main.py)
+SQLITE_DB_PATH=database.db
+
+# Migrations policy. Default: true (dev convenience — boot applies pending
+# migrations). ⚠ PRODUCTION: migrating from a replica is PROHIBITED — set
+# false in EVERY replica. Migrations run ONLY as a CI/CD pipeline step, in a
+# SINGLE instance, under explicit human supervision:
+#   DB_AUTO_MIGRATE=true uv run main.py --boot-tool db
+# DB_AUTO_MIGRATE=false
+
+# PostgreSQL (production — swap db tool, see INSTRUCTIONS_FOR_AI.md)
+# PG_HOST=localhost
+# PG_PORT=5432
+# PG_USER=postgres
+# PG_PASSWORD=postgres
+# PG_DATABASE=microcoreos
+
+
+# ─── Observability: Metrics ───────────────────────────────────────
+# Timing is ALWAYS ON — ToolProxy measures every tool call automatically.
+# No config needed. Access via:
+#   records = self.registry.get_metrics()
+#   self.registry.add_metrics_sink(callback)
+# Each record: {tool, method, duration_ms, success, timestamp}
+
+
+# ─── Observability: Health Check ──────────────────────────────────
+# ToolHealthPlugin runs in the background and calls db.health_check()
+# periodically, updating the registry status proactively.
+HEALTH_CHECK_INTERVAL=30   # seconds between checks (default: 30)
+
+
+# ─── Observability: OpenTelemetry ─────────────────────────────────
+# Disabled by default. When enabled, ALL tool calls get OTel spans
+# automatically via ToolProxy — no changes needed in plugins or tools.
+#
+# Install required packages first:
+#   uv add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-fastapi
+#
+OTEL_ENABLED=false
+OTEL_SERVICE_NAME=microcoreos
+
+# Export destination — leave commented to use console (dev mode)
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317   # Jaeger / Grafana Tempo / any OTLP backend
+
+# BatchSpanProcessor tuning (optional — OTel standard env vars)
+# OTEL_BSP_SCHEDULE_DELAY=5000        # ms between export batches (default: 5000)
+# OTEL_BSP_MAX_EXPORT_BATCH_SIZE=512  # spans per batch (default: 512)
+# OTEL_BSP_MAX_QUEUE_SIZE=2048        # in-memory buffer size (default: 2048)
+
+
+
+# ─── Chaos Engineering ────────────────────────────────────────────
+# Intentionally fails tools/plugins on boot to test fault tolerance.
+# NEVER enable in production.
+# CHAOS_ENABLED=true
+# ─── S3 Storage ───────────────────────────────────────────────────
+AWS_ACCESS_KEY_ID=your-access-key
+AWS_SECRET_ACCESS_KEY=your-secret-key
+AWS_DEFAULT_REGION=us-east-1
+AWS_S3_ENDPOINT_URL=http://localhost:9000
+AWS_S3_DEFAULT_BUCKET=microcoreos-bucket
+AWS_S3_SIZE_LIMIT_ENABLED=true
+AWS_S3_MAX_FILE_SIZE_MB=10
+AWS_S3_VERIFY_SSL=true
+
+