arc-kernel 0.1.0__tar.gz

arc_kernel-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

arc_kernel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vignesh Ramsh
+
+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.

arc_kernel-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: arc-kernel
+Version: 0.1.0
+Summary: ARC kernel — capability-based Python platform
+Project-URL: Homepage, https://github.com/vignesh-ramsh/arc
+Project-URL: Repository, https://github.com/vignesh-ramsh/arc
+Author: Vignesh Ramsh
+License-Expression: MIT
+License-File: LICENSE
+Keywords: arc,capability,cli,framework,kernel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=42.0
+Requires-Dist: msgspec>=0.18
+Requires-Dist: rich>=13.0
+Requires-Dist: tomlkit>=0.12
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# kernel
+
+The ARC kernel — repo/project name is `kernel`; the Python package it
+provides is `arc` (flat layout, no `src/`). This is what every project's
+`arc.<capability>` namespace is ultimately built on.
+
+```
+arc/                # this repo
+├── pyproject.toml      # name = "arc-kernel" (distribution — "arc" was taken
+│                          on PyPI), packages = ["arc"]
+├── README.md
+├── LICENSE
+├── .gitignore
+└── arc/                # the actual package — `import arc`
+    ├── __init__.py
+    ├── cli.py           # the `arc` command: init, install, build, settings, plugin
+    ├── registry.py
+    ├── settings.py
+    └── secrets.py
+```
+
+## Two-tier install model (mirrors frappe-bench / bench)
+
+1. **Bootstrap globally, once** — either `pip install arc-kernel` (or
+   `pipx install arc-kernel` / `uv tool install arc-kernel`, both preferred
+   over a bare `pip install` for a CLI tool) from PyPI, or
+   `uv tool install --editable .` from a local clone of this repo if you're
+   working on the kernel itself. Either way you get the `arc` command
+   anywhere on your machine.
+2. **Per project** — `arc init` clones THIS repo into `<project>/arc/` and wires
+   up a uv workspace. From then on, use `<project>/.venv/bin/arc` for project
+   commands — that copy is pinned to the exact commit this project was built
+   against, independent of the global bootstrap CLI's version.
+
+Note: inside a scaffolded project you'll see `project/arc/arc/` — the outer
+`arc/` is this project's kernel *slot* (a workspace member, named the way
+`apps/frappe` names its slot in a bench); the inner `arc/` is the actual
+Python package. Two different things, same name for a real reason — not
+duplication.
+
+## Commands
+
+```bash
+arc init [project_name] --kernel-repo <git-url-or-path> [--kernel-branch main] [--env dev]
+arc install <git-url> [--branch BRANCH] [--name NAME]
+arc build [-p/--plugin NAME] [--no-lock]
+arc settings get <key> [--reveal]
+arc settings set <key> <value> [--secret]
+arc settings delete <key>
+arc plugin list
+arc plugin enable <name>
+arc plugin disable <name>
+```
+
+`ARC_KERNEL_REPO` env var can be set once so `--kernel-repo` doesn't need to
+be typed on every `arc init`.
+
+## Plugin manifest format
+
+Every plugin repo has, at its root:
+
+```toml
+# plugin.toml — ARC-specific metadata only
+[plugin]
+name = "psqldb"
+version = "0.1.0"
+capability = "psqldb"          # exported as arc.<capability> at boot
+requires = []
+optional_requires = ["redix"]
+```
+
+```toml
+# pyproject.toml — standard Python packaging; real dependencies live HERE
+[project]
+name = "psqldb"
+dependencies = ["asyncpg>=0.29"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+```
+
+Following this same kernel's convention, plugin packages should also use a
+flat layout (`psqldb/psqldb/__init__.py` inside the plugin's own repo, not
+`psqldb/src/psqldb/`) — same reasoning, same fix, applied consistently.

arc_kernel-0.1.0/README.md

@@ -0,0 +1,85 @@
+# kernel
+
+The ARC kernel — repo/project name is `kernel`; the Python package it
+provides is `arc` (flat layout, no `src/`). This is what every project's
+`arc.<capability>` namespace is ultimately built on.
+
+```
+arc/                # this repo
+├── pyproject.toml      # name = "arc-kernel" (distribution — "arc" was taken
+│                          on PyPI), packages = ["arc"]
+├── README.md
+├── LICENSE
+├── .gitignore
+└── arc/                # the actual package — `import arc`
+    ├── __init__.py
+    ├── cli.py           # the `arc` command: init, install, build, settings, plugin
+    ├── registry.py
+    ├── settings.py
+    └── secrets.py
+```
+
+## Two-tier install model (mirrors frappe-bench / bench)
+
+1. **Bootstrap globally, once** — either `pip install arc-kernel` (or
+   `pipx install arc-kernel` / `uv tool install arc-kernel`, both preferred
+   over a bare `pip install` for a CLI tool) from PyPI, or
+   `uv tool install --editable .` from a local clone of this repo if you're
+   working on the kernel itself. Either way you get the `arc` command
+   anywhere on your machine.
+2. **Per project** — `arc init` clones THIS repo into `<project>/arc/` and wires
+   up a uv workspace. From then on, use `<project>/.venv/bin/arc` for project
+   commands — that copy is pinned to the exact commit this project was built
+   against, independent of the global bootstrap CLI's version.
+
+Note: inside a scaffolded project you'll see `project/arc/arc/` — the outer
+`arc/` is this project's kernel *slot* (a workspace member, named the way
+`apps/frappe` names its slot in a bench); the inner `arc/` is the actual
+Python package. Two different things, same name for a real reason — not
+duplication.
+
+## Commands
+
+```bash
+arc init [project_name] --kernel-repo <git-url-or-path> [--kernel-branch main] [--env dev]
+arc install <git-url> [--branch BRANCH] [--name NAME]
+arc build [-p/--plugin NAME] [--no-lock]
+arc settings get <key> [--reveal]
+arc settings set <key> <value> [--secret]
+arc settings delete <key>
+arc plugin list
+arc plugin enable <name>
+arc plugin disable <name>
+```
+
+`ARC_KERNEL_REPO` env var can be set once so `--kernel-repo` doesn't need to
+be typed on every `arc init`.
+
+## Plugin manifest format
+
+Every plugin repo has, at its root:
+
+```toml
+# plugin.toml — ARC-specific metadata only
+[plugin]
+name = "psqldb"
+version = "0.1.0"
+capability = "psqldb"          # exported as arc.<capability> at boot
+requires = []
+optional_requires = ["redix"]
+```
+
+```toml
+# pyproject.toml — standard Python packaging; real dependencies live HERE
+[project]
+name = "psqldb"
+dependencies = ["asyncpg>=0.29"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+```
+
+Following this same kernel's convention, plugin packages should also use a
+flat layout (`psqldb/psqldb/__init__.py` inside the plugin's own repo, not
+`psqldb/src/psqldb/`) — same reasoning, same fix, applied consistently.

arc_kernel-0.1.0/arc/__init__.py

@@ -0,0 +1,65 @@
+"""
+ARC kernel — capability-based Python platform.
+
+`import arc` is the only import application code ever needs (Architecture
+§3.2). After `arc.boot()`, every enabled plugin's capability is reachable as
+`arc.<capability>` via module-level `__getattr__` (PEP 562) — never
+`import arc.psqldb`.
+
+    import arc
+
+    arc.boot()
+    user = await arc.psqldb.fetch_one(...)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import codec, health  # noqa: F401 - attaches arc.codec / arc.health as real submodules
+from .kernel import (  # noqa: F401
+    ArcAdvisory,
+    Capability,
+    ExportError,
+    Kernel,
+    KernelError,
+)
+from .resolver import BootPlan, PluginSpec, ResolutionError  # noqa: F401
+from .runtime import BootError, boot, find_project_root, shutdown  # noqa: F401
+
+__version__ = "0.1.0"
+
+
+def __getattr__(name: str) -> Any:
+    """PEP 562: resolve arc.<capability> against the booted kernel (§3.2).
+
+    Only consulted for names not found in the module dict — which is exactly
+    why capability names may never collide with the kernel's own namespace
+    (enforced at resolution and export time; see arc.kernel).
+    """
+    from . import _state
+
+    kernel = _state.get_kernel()
+    if kernel is not None and kernel.has(name):
+        return kernel.get(name)
+    if kernel is None:
+        raise AttributeError(
+            f"module 'arc' has no attribute {name!r}. If {name!r} is a plugin "
+            f"capability, call arc.boot() first — capabilities are only "
+            f"attached to `arc` after boot."
+        )
+    raise AttributeError(
+        f"module 'arc' has no attribute {name!r}, and no enabled plugin "
+        f"exports a capability with that name "
+        f"(booted capabilities: {sorted(kernel.capabilities()) or 'none'})."
+    )
+
+
+def __dir__() -> list[str]:
+    from . import _state
+
+    names = set(globals())
+    kernel = _state.get_kernel()
+    if kernel is not None:
+        names.update(kernel.capabilities())
+    return sorted(names)

arc_kernel-0.1.0/arc/_state.py

@@ -0,0 +1,31 @@
+"""
+arc._state
+-----------------
+Process-wide runtime state: the single active Kernel for this process.
+
+Deliberately tiny and dependency-free. It exists so that `arc/__init__.py`
+(PEP 562 attribute lookup), `arc.runtime` (boot/shutdown) and `arc.settings`
+(module-level runtime API) can all reach the active kernel without importing
+each other in a circle.
+
+Access goes through get_kernel()/set_kernel() — never `from ... import`
+the variable itself, which would snapshot a stale binding.
+"""
+
+from __future__ import annotations
+
+import typing
+
+if typing.TYPE_CHECKING:
+    from .kernel import Kernel
+
+_active_kernel: "Kernel | None" = None
+
+
+def get_kernel() -> "Kernel | None":
+    return _active_kernel
+
+
+def set_kernel(kernel: "Kernel | None") -> None:
+    global _active_kernel
+    _active_kernel = kernel