@boxxy/contract 0.0.0-stage → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the boxxy authors
+
+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/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+<div align="center">
+  <h1>@boxxy/contract</h1>
 
-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.
+  <p>
+    <a href="https://www.npmjs.com/package/@boxxy/contract"><img src="https://img.shields.io/npm/v/@boxxy/contract" alt="npm version"></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  </p>
+
+  <p>
+    <a href="../../docs/design/boxxy/README.md">Documentation</a>
+  </p>
+</div>
+
+The oRPC contract of the boxxy API, and the table of who may call each procedure.
+
+The server builds its router from the contract, and the CLI builds its typed client from it. The
+package does no I/O: it holds only the procedures and their zod schemas.
+
+## Install
+
+Install the package from [npm](https://www.npmjs.com/package/@boxxy/contract) with Bun:
+
+```bash
+bun add @boxxy/contract
+```
+
+The package runs on [Bun](https://bun.sh) 1.3 or newer.
+
+## Features
+
+- `contract`, the 26 procedures in the groups `item`, `relation`, `attempt`, `plan`, `runner`,
+  `outbox`, `rules` and `report`. A procedure that is an MCP tool carries its tool name and
+  description.
+- `access`, one row for each procedure: who calls it, the actor its fact records, the MCP endpoint
+  that lists it, and the CLI command that calls it.
+
+## Documentation
+
+[API and auth in v1](../../docs/design/boxxy/v1-api-and-auth.md) describes the three doors, the
+procedures and the scope of the worker token.

package/dist/access.d.ts

@@ -0,0 +1,81 @@
+export type Caller = 'owner' | 'session' | 'hook';
+export interface Access {
+    readonly caller: Caller;
+    readonly actor: 'boxxy:owner:local' | 'boxxy:attempt:<id>' | 'boxxy:hook:<id>' | 'none';
+    readonly tool: 'owner' | 'session' | 'none';
+    readonly cli: string;
+}
+export declare const access: {
+    readonly 'item.file': Access;
+    readonly 'item.edit': Access;
+    readonly 'item.close': Access;
+    readonly 'item.retry': Access;
+    readonly 'item.wake': Access;
+    readonly 'item.note': Access;
+    readonly 'relation.add': Access;
+    readonly 'relation.remove': Access;
+    readonly 'plan.defer': Access;
+    readonly 'plan.undefer': Access;
+    readonly 'plan.expedite': Access;
+    readonly 'plan.unexpedite': Access;
+    readonly 'item.get': Access;
+    readonly 'item.list': Access;
+    readonly 'runner.status': Access;
+    readonly 'report.cost': Access;
+    readonly 'report.stageTimes': Access;
+    readonly 'attempt.current': {
+        readonly caller: 'session';
+        readonly actor: 'none';
+        readonly tool: 'session';
+        readonly cli: 'boxxy attempt current';
+    };
+    readonly 'attempt.evidence': {
+        readonly caller: 'session';
+        readonly actor: 'boxxy:attempt:<id>';
+        readonly tool: 'session';
+        readonly cli: 'boxxy attempt evidence --kind --ref [--observed]';
+    };
+    readonly 'attempt.closeOut': {
+        readonly caller: 'session';
+        readonly actor: 'boxxy:attempt:<id>';
+        readonly tool: 'session';
+        readonly cli: 'boxxy attempt close-out   (JSON on stdin)';
+    };
+    readonly 'attempt.bindSession': {
+        readonly caller: 'hook';
+        readonly actor: 'boxxy:hook:<id>';
+        readonly tool: 'none';
+        readonly cli: 'boxxy hook session-start   (hook payload on stdin)';
+    };
+    readonly 'attempt.recordPullRequest': {
+        readonly caller: 'hook';
+        readonly actor: 'boxxy:hook:<id>';
+        readonly tool: 'none';
+        readonly cli: 'boxxy hook post-tool-use   (hook payload on stdin)';
+    };
+    readonly 'runner.pause': {
+        readonly caller: 'owner';
+        readonly actor: 'none';
+        readonly tool: 'none';
+        readonly cli: 'boxxy runner pause';
+    };
+    readonly 'runner.resume': {
+        readonly caller: 'owner';
+        readonly actor: 'none';
+        readonly tool: 'none';
+        readonly cli: 'boxxy runner resume';
+    };
+    readonly 'outbox.retry': {
+        readonly caller: 'owner';
+        readonly actor: 'none';
+        readonly tool: 'none';
+        readonly cli: 'boxxy outbox retry';
+    };
+    readonly 'rules.dryRun': {
+        readonly caller: 'owner';
+        readonly actor: 'none';
+        readonly tool: 'none';
+        readonly cli: 'boxxy rules dry-run <file>';
+    };
+};
+export type ProcedureName = keyof typeof access;

package/dist/boxxy-client.d.ts

@@ -0,0 +1,3 @@
+import type { ContractRouterClient } from '@orpc/contract';
+import type { contract } from './contract.ts';
+export type BoxxyClient = ContractRouterClient<typeof contract>;