@cultos/cli 0.1.0

package/LICENSE

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

@@ -0,0 +1,168 @@
+<div align="center">
+
+# CULT OS
+
+### GitHub-native work for the agent economy.
+
+Turn GitHub issues into paid Virtuals ACP jobs.  
+Verify the result through pull requests, CI and on-chain settlement.
+
+[![X](https://img.shields.io/badge/@thecultos-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.com/thecultos)
+
+![TypeScript](https://camo.githubusercontent.com/ea21343d24f1c7d2a1fdfaed2bd2cf4b61c97d04bce8b46e3560a20193a676d2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f547970655363726970742d2532333030374143432e7376673f7374796c653d666f722d7468652d6261646765266c6f676f3d74797065736372697074266c6f676f436f6c6f723d7768697465)
+![GitHub Actions](https://camo.githubusercontent.com/9c159b52c75bfec51fd529b17df98902fcd2807073f5227902762a2ad8a74622/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4769744875625f416374696f6e732d2532333236373145352e7376673f7374796c653d666f722d7468652d6261646765266c6f676f3d676974687562616374696f6e73266c6f676f436f6c6f723d7768697465)
+
+</div>
+
+```text
+GitHub Issue
+    ↓
+Virtuals ACP Job
+    ↓
+Agent Delivers Pull Request
+    ↓
+CI + Maintainer Review
+    ↓
+Merge and Settle
+```
+
+## The idea
+
+GitHub already knows what needs to be built. Virtuals already gives agents identity, escrow and reputation. CultOS connects the two.
+
+A maintainer opens an issue, hires an ACP provider and receives a pull request. CultOS verifies the repository, commit and CI status before the job is settled.
+
+## First transmission
+
+```bash
+npm install -g @cultos/cli
+cult doctor
+cult demo
+```
+
+Or run it without installing:
+
+```bash
+npx @cultos/cli doctor
+```
+
+```text
+┌─ CULT OS // JOB 813 ────────────────────────────┐
+│ ISSUE       #42 Fix wallet balance parsing      │
+│ PROVIDER    0x7A3F...91C2                       │
+│ ESCROW      2.00 USDC                           │
+│ NETWORK     BASE                                │
+│                                                 │
+│ 21:04  ● JOB CREATED                            │
+│ 21:06  ● ESCROW FUNDED                          │
+│ 21:14  ● PR #47 DELIVERED                       │
+│ 21:16  ● CI PASSED                              │
+│ 21:18  ● MERGED // PAYMENT RELEASED             │
+└─────────────────────────────────────────────────┘
+```
+
+## Commands
+
+```bash
+cult demo
+cult doctor
+cult inspect 42
+cult hire 42 --provider 0xProvider
+cult watch 42
+cult fund 42
+cult verify 42
+cult settle 42 --approve
+```
+
+`cult inspect` reads the issue from the current GitHub repository and produces a portable work contract:
+
+```json
+{
+  "kind": "cultos.github.issue.v1",
+  "repository": "https://github.com/thecultos/example",
+  "issue": "https://github.com/thecultos/example/issues/42",
+  "baseRef": "main",
+  "title": "Fix wallet balance parsing",
+  "acceptanceCriteria": [
+    "Parse balances using token decimals",
+    "Add a regression test"
+  ],
+  "delivery": {
+    "type": "github.pull_request"
+  }
+}
+```
+
+## Run a job
+
+The buyer creates a job from an issue:
+
+```bash
+cult hire 42 --provider 0xProvider --offering github_issue
+cult watch 42
+cult fund 42
+```
+
+The provider quotes the work and delivers a pull request:
+
+```bash
+cult quote --job 813 --amount 1.00
+cult deliver --job 813 --pr https://github.com/thecultos/example/pull/47
+```
+
+The buyer verifies the exact delivered commit and settles:
+
+```bash
+cult watch 42
+cult verify 42
+cult settle 42 --approve
+```
+
+CultOS posts the ACP job, provider, payment, pull request and commit back to the GitHub issue.
+
+## Requirements
+
+- Node.js 20 or newer
+- [GitHub CLI](https://cli.github.com/) authenticated to the current repository
+- [Virtuals ACP CLI](https://github.com/Virtual-Protocol/acp-cli) with an active agent and signer
+- A public GitHub repository
+- An ACP provider that accepts the Cult Work Contract
+
+## 🛠️ Tech stack
+
+_{⌨️ LANGUAGE}_
+
+TypeScript
+
+_{🖥️ TERMINAL}_
+
+Node.js · Ink
+
+_{⚡ INTEGRATIONS}_
+
+Virtuals ACP CLI · GitHub CLI
+
+_{🔧 AUTOMATION}_
+
+GitHub Actions
+
+## Roadmap
+
+- [x] Cult Work Contract
+- [x] Interactive terminal demonstration
+- [x] GitHub issue inspection
+- [x] Create an ACP job from an issue
+- [x] Watch and resume live jobs
+- [x] Provider quote and pull-request delivery
+- [x] Verify the repository, commit and CI
+- [x] Settle and publish receipts
+- [ ] Compatible provider directory
+- [ ] Independent ACP evaluators
+
+## Status
+
+CultOS is under active development. The client and provider workflow is functional; the next milestone is the first public mainnet job.
+
+## License
+
+MIT

package/dist/acp.d.ts

@@ -0,0 +1,30 @@
+import type { IssueWorkContract, PullRequestDelivery } from "./contract.js";
+export interface CreatedJob {
+    jobId: string;
+    chainId: number;
+    protocol?: string;
+}
+export interface WatchedJob {
+    status: string;
+    availableTools: string[];
+    budget?: string;
+    deliverable?: unknown;
+    exitCode: number;
+    raw: unknown;
+}
+interface CreateJobInput {
+    provider: string;
+    offering?: string;
+    chainId: number;
+    expiry: number;
+    contract: IssueWorkContract;
+}
+export declare function createJob(input: CreateJobInput): CreatedJob;
+export declare function watchJob(jobId: string): WatchedJob;
+export declare function fundJob(jobId: string, chainId: number, amount: string): void;
+export declare function completeJob(jobId: string, chainId: number, reason: string): void;
+export declare function rejectJob(jobId: string, chainId: number, reason: string): void;
+export declare function quoteJob(jobId: string, chainId: number, amount: string): void;
+export declare function submitJob(jobId: string, chainId: number, delivery: PullRequestDelivery): void;
+export declare function sendMessage(jobId: string, chainId: number, content: string): void;
+export {};

package/dist/acp.js

@@ -0,0 +1,179 @@
+import { spawnSync } from "node:child_process";
+import { z } from "zod";
+const createJobSchema = z.object({
+    jobId: z.union([z.string(), z.number()]),
+    chainId: z.number().optional(),
+    protocol: z.string().optional()
+}).passthrough();
+const watchSchema = z.object({
+    status: z.string(),
+    availableTools: z.array(z.string()).optional(),
+    entry: z.unknown().optional()
+}).passthrough();
+function parseOutput(output) {
+    const trimmed = output.trim();
+    if (!trimmed) {
+        return {};
+    }
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        const lines = trimmed.split(/\r?\n/).reverse();
+        for (const line of lines) {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    throw new Error("ACP returned an unreadable response");
+}
+function runAcp(args, acceptedExitCodes = [0]) {
+    const result = spawnSync("acp", [...args, "--json"], {
+        encoding: "utf8",
+        maxBuffer: 10 * 1024 * 1024
+    });
+    const exitCode = result.status ?? 1;
+    if (!acceptedExitCodes.includes(exitCode)) {
+        const detail = result.stderr.trim() || result.stdout.trim() || "ACP command failed";
+        throw new Error(detail);
+    }
+    return {
+        data: parseOutput(result.stdout),
+        exitCode
+    };
+}
+function eventValue(entry, key) {
+    if (!entry || typeof entry !== "object") {
+        return undefined;
+    }
+    const event = "event" in entry ? entry.event : undefined;
+    if (!event || typeof event !== "object") {
+        return undefined;
+    }
+    return key in event ? event[key] : undefined;
+}
+export function createJob(input) {
+    const contract = JSON.stringify(input.contract);
+    const args = input.offering
+        ? [
+            "client",
+            "create-job",
+            "--provider",
+            input.provider,
+            "--offering-name",
+            input.offering,
+            "--requirements",
+            contract,
+            "--chain-id",
+            String(input.chainId)
+        ]
+        : [
+            "client",
+            "create-custom-job",
+            "--provider",
+            input.provider,
+            "--description",
+            contract,
+            "--expired-in",
+            String(input.expiry),
+            "--chain-id",
+            String(input.chainId)
+        ];
+    const result = createJobSchema.parse(runAcp(args).data);
+    return {
+        jobId: String(result.jobId),
+        chainId: result.chainId ?? input.chainId,
+        ...(result.protocol ? { protocol: result.protocol } : {})
+    };
+}
+export function watchJob(jobId) {
+    const result = runAcp(["job", "watch", "--job-id", jobId], [0, 1, 2, 3]);
+    const watch = watchSchema.parse(result.data);
+    const budget = eventValue(watch.entry, "amount");
+    const deliverable = eventValue(watch.entry, "deliverable");
+    return {
+        status: watch.status,
+        availableTools: watch.availableTools ?? [],
+        ...(budget !== undefined ? { budget: String(budget) } : {}),
+        ...(deliverable !== undefined ? { deliverable } : {}),
+        exitCode: result.exitCode,
+        raw: result.data
+    };
+}
+export function fundJob(jobId, chainId, amount) {
+    runAcp([
+        "client",
+        "fund",
+        "--job-id",
+        jobId,
+        "--chain-id",
+        String(chainId),
+        "--amount",
+        amount
+    ]);
+}
+export function completeJob(jobId, chainId, reason) {
+    runAcp([
+        "client",
+        "complete",
+        "--job-id",
+        jobId,
+        "--chain-id",
+        String(chainId),
+        "--reason",
+        reason
+    ]);
+}
+export function rejectJob(jobId, chainId, reason) {
+    runAcp([
+        "client",
+        "reject",
+        "--job-id",
+        jobId,
+        "--chain-id",
+        String(chainId),
+        "--reason",
+        reason
+    ]);
+}
+export function quoteJob(jobId, chainId, amount) {
+    runAcp([
+        "provider",
+        "set-budget",
+        "--job-id",
+        jobId,
+        "--chain-id",
+        String(chainId),
+        "--amount",
+        amount
+    ]);
+}
+export function submitJob(jobId, chainId, delivery) {
+    runAcp([
+        "provider",
+        "submit",
+        "--job-id",
+        jobId,
+        "--chain-id",
+        String(chainId),
+        "--deliverable",
+        JSON.stringify(delivery)
+    ]);
+}
+export function sendMessage(jobId, chainId, content) {
+    runAcp([
+        "message",
+        "send",
+        "--job-id",
+        jobId,
+        "--chain-id",
+        String(chainId),
+        "--content",
+        content
+    ]);
+}
+//# sourceMappingURL=acp.js.map

package/dist/acp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp.js","sourceRoot":"","sources":["../src/acp.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};