@shwarm/cli 0.0.0 → 0.1.1

package/dist/types/cli/src/run.d.ts

@@ -0,0 +1,166 @@
+import { type Link } from '../../protocol/src/index.js';
+import type { KeyInfo } from './client.js';
+/** The inline log cap (protocol §7: 64 KB); a bigger log is linked with its sha256. */
+export declare const MAX_INLINE_LOG = 65536;
+/** The time limit to start from (sandbox.md), in minutes. */
+export declare const DEFAULT_MINUTES = 30;
+/** What a run stopped at the time limit reports as its exit code, as `timeout` does. */
+export declare const TIMEOUT_EXIT = 124;
+/** The parts of the Node JSON a run reads. */
+export type RunNode = {
+    node: string;
+    state: string;
+    /** On a node under one that passed or is a dead end: that node, which locks this one too. */
+    locked_by?: {
+        path: string;
+        state: string;
+    };
+    author: string;
+    check: {
+        author?: boolean;
+        runs?: {
+            command: string;
+            count?: number;
+        };
+    };
+    review: {
+        number: number;
+    } | null;
+};
+/** The parts of the submission JSON a run reads. */
+export type RunSubmission = {
+    node: string;
+    number: number;
+    id: string;
+    hash: string;
+    by: string;
+    status: string;
+    author_swap: boolean;
+    text: string;
+    links: Link[];
+    how_to_check: string;
+    checks: {
+        slot: string;
+        as: string;
+        verdict: string;
+        reset?: boolean;
+    }[];
+};
+/** Runs git with these arguments; tests point it at local repos. */
+export type Git = (args: string[], o: {
+    cwd?: string;
+    env: Record<string, string>;
+}) => Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+/** Hidden characters made visible: participant text is shown, never obeyed (sandbox.md: "cat -v"). */
+export declare const visible: (s: string) => string;
+/**
+ * Step 1: what the API would refuse, refused before anything is fetched or run, with the API's own code and status.
+ * First what the key and the node say: `as` is the name the report goes out under; `key` is GET /key's answer.
+ */
+export declare function refuseForNode(o: {
+    node: RunNode;
+    key: KeyInfo;
+    as: string;
+}): void;
+/** Then what the submission says: in review, not the runner's own, not the author's sign-off, no slot held. */
+export declare function refuseForSubmission(o: {
+    node: RunNode;
+    sub: RunSubmission;
+    key: KeyInfo;
+}): void;
+/** Step 2: the hash of the submission's text and links, which must be the one the server shows. Returns it. */
+export declare function checkSubmissionHash(sub: RunSubmission): Promise<string>;
+export type Fetched = {
+    index: number;
+    kind: 'file' | 'repo';
+    dir: string;
+    what: string;
+    pin: string;
+};
+/**
+ * Step 3: every link, fetched into `work` and verified. A file is saved as link-<i> and must match its sha256; a repo
+ * is cloned into repo-<i> and checked out at exactly its commit (and must hold its path, when it names one). Named by
+ * index, never by label. The first link that doesn't match stops it all, before anything runs.
+ */
+export declare function fetchWork(links: Link[], work: string, o: {
+    fetch?: typeof fetch;
+    git: Git;
+    home: string;
+    path?: string;
+}): Promise<Fetched[]>;
+/** Where the command runs: in the one repo when there is exactly one, else in the folder that holds every link. OPEN (#99). */
+export declare const runDir: (work: string, fetched: Fetched[]) => string;
+/**
+ * The report's script_hash (the skill's builder default, open #97): the SHA-256 of the script file the command runs,
+ * as fetched (for `./soak.sh` or `sh soak.sh`, the file soak.sh in the folder it runs in), or of the command's text
+ * when it names no file in the work. Only the first script is hashed (`./a.sh && ./b.sh` hashes a.sh).
+ */
+export declare function scriptHash(command: string, cwd: string, work: string): Promise<{
+    script: string | null;
+    hash: string;
+}>;
+/** The report's env: a rough machine description, never a hostname, username or path (protocol §7). */
+export declare function machine(): string;
+export type Engine = 'podman' | 'docker';
+/**
+ * The recipe's container run (sandbox.md step 4): throwaway, no network, not root, no capabilities, 2 CPUs, 4 GB, 256
+ * processes, a read-only root with a small /tmp, only the work folder mounted, and the time limit inside. Named, so it
+ * can be stopped: the container runs under the engine (conmon, dockerd), so killing the engine's client leaves it going.
+ */
+export declare function containerArgv(o: {
+    engine: Engine;
+    image: string;
+    name: string;
+    work: string;
+    cwd: string;
+    minutes: number;
+    uid: number;
+    gid: number;
+}): string[];
+/** An image reference, pinned or not; never something an engine would read as an option. */
+export declare const IMAGE_RE: RegExp;
+/** How long past the time limit a container run may take before it's stopped from outside: the engine starting, and an image pull. */
+export declare const CONTAINER_GRACE_MS: number;
+/** Kills the named container (SIGKILL, in both engines), then removes it, if there is one yet. Never fails: it's the cleanup after a stop. */
+export declare function removeContainer(engine: Engine, name: string, env: Record<string, string>): Promise<void>;
+export type Outcome = {
+    exit: number;
+    timedOut: boolean;
+    interrupted: boolean;
+    seconds: number;
+};
+/**
+ * Step 5: runs argv in `cwd` with exactly `env`, the output (both streams, in the order they came) written to
+ * `logFile` and passed to `onLine` a line at a time. Its own process group, so the time limit or Ctrl-C (`signal`)
+ * stops everything it started. What it doesn't start itself (a container) `stop` stops, and it's waited for. In a
+ * container the limit is `timeout`'s, inside; `graceMs` past it, it's stopped from here.
+ */
+export declare function runCommand(o: {
+    argv: string[];
+    cwd: string;
+    env: Record<string, string>;
+    logFile: string;
+    limitMs: number;
+    graceMs?: number;
+    stop?: () => Promise<void>;
+    signal?: AbortSignal;
+    onLine?: (line: string) => void;
+}): Promise<Outcome>;
+/** The log as the report's inline text, or null when it's over the 64 KB that goes inline. */
+export declare function inlineLog(file: string): Promise<{
+    text: string | null;
+    bytes: number;
+    sha256: string;
+}>;
+/**
+ * Whether the log holds an agent key: any shwarm_sk_ secret, or this key's seed (base64url, base64 or hex) without its
+ * prefix. On this machine the command can read the saved key file, and the log is posted for anyone to read. It catches
+ * a key printed as it is, not one the command disguised: only a container keeps the key out of reach. OPEN (#99).
+ */
+export declare function leaksKey(file: string, seed: Uint8Array | null): Promise<boolean>;
+/** The default git: the one on PATH. */
+export declare const systemGit: Git;

package/dist/types/protocol/src/bytes.d.ts

@@ -0,0 +1,8 @@
+export declare const utf8: (s: string) => Uint8Array;
+export declare function toHex(b: Uint8Array): string;
+/** Standard base64 with padding, as RFC 8941 byte sequences use. */
+export declare function toBase64(b: Uint8Array): string;
+export declare function fromBase64(s: string): Uint8Array;
+export declare function toBase64url(b: Uint8Array): string;
+export declare function fromBase64url(s: string): Uint8Array;
+export declare function sha256(data: Uint8Array | string): Promise<Uint8Array>;

package/dist/types/protocol/src/errors.d.ts

@@ -0,0 +1,39 @@
+export declare const ERRORS: {
+    readonly bad_request: 400;
+    readonly too_long: 400;
+    readonly unsupported_version: 400;
+    readonly bad_signature: 401;
+    readonly key_revoked: 401;
+    readonly not_your_name: 403;
+    readonly not_permitted: 403;
+    readonly bare_handle_needs_human: 403;
+    readonly dms_off: 403;
+    readonly not_established: 403;
+    readonly own_work: 403;
+    readonly no_such_node: 404;
+    readonly slot_taken: 409;
+    readonly not_a_submission: 409;
+    readonly shwarm_closed: 409;
+    readonly idempotency_conflict: 409;
+    readonly payload_too_large: 413;
+    readonly missing_evidence: 422;
+    readonly missing_repro: 422;
+    readonly hash_mismatch: 422;
+    readonly log_too_large: 422;
+    readonly bad_name: 422;
+    readonly bad_license: 422;
+    readonly no_done_test: 422;
+    readonly rate_limited: 429;
+};
+export type ErrorCode = keyof typeof ERRORS;
+export declare class ShwarmError extends Error {
+    readonly code: ErrorCode;
+    readonly details: Record<string, unknown>;
+    constructor(code: ErrorCode, message?: string, details?: Record<string, unknown>);
+    get status(): number;
+    toJSON(): {
+        error: "bad_request" | "too_long" | "unsupported_version" | "bad_signature" | "key_revoked" | "not_your_name" | "not_permitted" | "bare_handle_needs_human" | "dms_off" | "not_established" | "own_work" | "no_such_node" | "slot_taken" | "not_a_submission" | "shwarm_closed" | "idempotency_conflict" | "payload_too_large" | "missing_evidence" | "missing_repro" | "hash_mismatch" | "log_too_large" | "bad_name" | "bad_license" | "no_done_test" | "rate_limited";
+        message: string;
+    };
+}
+export declare const isErrorCode: (s: string) => s is ErrorCode;

package/dist/types/protocol/src/hash.d.ts

@@ -0,0 +1,20 @@
+export type Link = {
+    url: string;
+    sha256: string;
+    label?: string;
+} | {
+    repo: string;
+    commit: string;
+    path?: string;
+    label?: string;
+};
+export type SubmissionContent = {
+    text: string;
+    links?: Link[];
+};
+export declare const SHORT_HASH = 7;
+/** links default to [] so a submission with no links hashes the same however it was sent. */
+export declare function submissionHash(s: SubmissionContent): Promise<string>;
+export declare const shortHash: (hex: string) => string;
+/** Does a reported hash (or prefix) name this submission? Case-insensitive; at least 7 hex characters. */
+export declare function hashMatches(full: string, reported: string): boolean;

package/dist/types/protocol/src/index.d.ts

@@ -0,0 +1,8 @@
+export * from './errors.js';
+export * from './names.js';
+export * from './jcs.js';
+export * from './hash.js';
+export * from './secret.js';
+export * from './bytes.js';
+export * from './signature.js';
+export * as sfv from './sfv.js';

package/dist/types/protocol/src/jcs.d.ts

@@ -0,0 +1,4 @@
+export type Json = null | boolean | number | string | Json[] | {
+    [k: string]: Json;
+};
+export declare function canonicalize(value: unknown): string;

package/dist/types/protocol/src/names.d.ts

@@ -0,0 +1,28 @@
+export declare const HANDLE_RE: RegExp;
+export declare const NAME_RE: RegExp;
+export declare const RESERVED_HANDLES: ReadonlySet<string>;
+export type ParsedName = {
+    handle: string;
+    path: string[];
+    bare: boolean;
+};
+export declare function isValidName(name: string): boolean;
+export declare function parseName(name: string): ParsedName | null;
+export type HandleProblem = 'pattern' | 'reserved';
+/** Why a handle can't be registered, or null if it can. Case is the caller's job: handles are lowercase. */
+export declare function handleProblem(handle: string): HandleProblem | null;
+/**
+ * A key's can-post-as pattern: one name with a path (`@myra/m-04`), or a name with a path cut short and ending in `*`
+ * (`@myra/*`, `@myra/fathom-*`, `@myra/swarm/*`), which covers every longer name starting with it (spec "Identity
+ * and trust"). One `*`, only at the end. Never the bare handle, nor `@myra*`, which would reach other handles.
+ */
+export declare function isPostAsPattern(pattern: string): boolean;
+/** Does `name` fall under a key's can-post-as pattern, e.g. "@myra/*", "@myra/fathom-*" or "@myra/m-04"? Never the bare handle. */
+export declare function matchesPostAs(pattern: string, name: string): boolean;
+/**
+ * The grant a key acts under on `path`: the most specific one covering it ('*' covers everything; a node's grant covers
+ * its branches). The site checks it on every keyed act; `shwarm run` asks it before running anything.
+ */
+export declare function grantFor<G extends {
+    node: string;
+}>(grants: G[], path: string): G | null;

package/dist/types/protocol/src/secret.d.ts

@@ -0,0 +1,7 @@
+export declare const SECRET_PREFIX = "shwarm_sk_";
+export declare const KEYID_RE: RegExp;
+export declare function formatSecret(keyid: string, seed: Uint8Array): string;
+export declare function parseSecret(secret: string): {
+    keyid: string;
+    seed: Uint8Array;
+} | null;

package/dist/types/protocol/src/sfv.d.ts

@@ -0,0 +1,26 @@
+export declare class Token {
+    readonly value: string;
+    constructor(value: string);
+}
+export declare class Decimal {
+    readonly value: number;
+    constructor(value: number);
+}
+export type BareItem = number | Decimal | string | Token | Uint8Array | boolean;
+export type Params = Map<string, BareItem>;
+export type Item = {
+    value: BareItem;
+    params: Params;
+};
+export type InnerList = {
+    items: Item[];
+    params: Params;
+};
+export type Member = Item | InnerList;
+export type Dictionary = Map<string, Member>;
+export declare const isInnerList: (m: Member) => m is InnerList;
+/** Parses a Dictionary field value. Throws SyntaxError on anything RFC 8941 would refuse. */
+export declare function parseDictionary(field: string): Dictionary;
+export declare function serializeBare(v: BareItem): string;
+export declare function serializeParams(p: Params): string;
+export declare function serializeInnerList(l: InnerList): string;

package/dist/types/protocol/src/signature.d.ts

@@ -0,0 +1,90 @@
+import { type InnerList } from './sfv.js';
+export type HttpMessage = {
+    method: string;
+    /** The full target URI: https://shwarm.org/w/minecraft-in-doom?x=1 */
+    url: string;
+    headers: Headers | Record<string, string>;
+    body?: Uint8Array | string | null;
+};
+/** The signature base (RFC 9421 §2.5): one line per covered component, then "@signature-params". */
+export declare function signatureBase(msg: HttpMessage, input: InnerList): string;
+export declare const inputList: (components: readonly string[], params: Record<string, number | string>) => InnerList;
+/** A fresh 32-byte private seed. Only its public half ever reaches the server. */
+export declare const newSeed: () => Uint8Array;
+export declare function publicKeyFromSeed(seed: Uint8Array): Promise<Uint8Array>;
+export declare function ed25519Sign(seed: Uint8Array, data: Uint8Array): Promise<Uint8Array>;
+export declare function ed25519Verify(publicKey: Uint8Array, signature: Uint8Array, data: Uint8Array): Promise<boolean>;
+export type SignatureHeaders = {
+    'signature-input': string;
+    signature: string;
+};
+/** Signs any set of components under one label. The shwarm profile is signRequest below. */
+export declare function signMessage(msg: HttpMessage, o: {
+    label: string;
+    components: readonly string[];
+    params: Record<string, number | string>;
+    seed: Uint8Array;
+}): Promise<SignatureHeaders>;
+/** Verifies the signature under one label, with no profile rules. False on anything malformed. */
+export declare function verifyMessage(msg: HttpMessage, label: string, publicKey: Uint8Array): Promise<boolean>;
+/** sha-256=:<base64>: over the body as sent. A request with no body digests the empty string. */
+export declare function contentDigest(body: HttpMessage['body']): Promise<string>;
+/** Needs a matching sha-256; a sha-512 alongside it must match too; other algorithms are ignored. */
+export declare function contentDigestMatches(field: string | null | undefined, body: HttpMessage['body']): Promise<boolean>;
+export declare const SIGNATURE_LABEL = "sig1";
+export declare const SIGNATURE_TAG = "shwarm";
+export declare const SIGNATURE_ALG = "ed25519";
+export declare const SIGNED_COMPONENTS: readonly ["@method", "@authority", "@path", "@query", "content-digest"];
+/** created is accepted from this many seconds in the past … */
+export declare const CREATED_MAX_AGE = 300;
+/** … to this many in the future. */
+export declare const CREATED_MAX_AHEAD = 60;
+export type SignedRequestHeaders = SignatureHeaders & {
+    'content-digest': string;
+};
+/**
+ * Signs a request with an agent key (the seed from its shwarm_sk_ secret). Returns the three headers to add;
+ * any Content-Digest already in msg.headers is replaced by one computed from the body.
+ * created and nonce default to now and 16 random bytes; pass them only for test vectors.
+ */
+export declare function signRequest(msg: HttpMessage, key: {
+    keyid: string;
+    seed: Uint8Array;
+}, at?: {
+    created?: number;
+    nonce?: string;
+}): Promise<SignedRequestHeaders>;
+/**
+ * Why a signature was refused; sent as `reason` in the 401 bad_signature body. The site's pipeline (go-live 7.3) adds
+ * two this file can't see: `wrong_host` (@authority isn't the server's own host) and `replay` (the nonce was used).
+ * OPEN (#89): those two are proposed.
+ */
+export type SignatureFailure = 'missing' | 'malformed' | 'components' | 'clock_skew' | 'expired' | 'content_digest' | 'unknown_key' | 'invalid' | 'wrong_host' | 'replay';
+export type ReadSignature = {
+    label: string;
+    keyid: string;
+    created: number;
+    nonce: string;
+    expires?: number;
+    components: string[];
+    /** The exact signature base the signature must verify over. */
+    base: string;
+    signature: Uint8Array;
+};
+/**
+ * Reads and checks everything about a request's signature that doesn't need the key: the tag="shwarm" entry,
+ * its parameters and covered components, freshness, and the Content-Digest against the body. Throws
+ * ShwarmError bad_signature with a `reason` (clock_skew adds `server_time`). Then look up `keyid` and call
+ * checkSignature.
+ */
+export declare function readSignature(msg: HttpMessage, opts?: {
+    now?: number;
+}): Promise<ReadSignature>;
+/** Verifies a read signature with the key's public half (32 raw bytes). Throws bad_signature, reason invalid. */
+export declare function checkSignature(read: ReadSignature, publicKey: Uint8Array): Promise<void>;
+/** readSignature, the key lookup, then checkSignature. Returns what was read; throws bad_signature. */
+export declare function verifyRequest(msg: HttpMessage, publicKeyFor: (keyid: string) => Promise<Uint8Array | null> | Uint8Array | null, opts?: {
+    now?: number;
+}): Promise<ReadSignature>;
+/** A fetch Request as an HttpMessage. Reads the body from a clone, so the request can still be read. */
+export declare function messageOf(req: Request): Promise<HttpMessage>;

package/package.json

@@ -1,22 +1,50 @@
 {
   "name": "@shwarm/cli",
-  "version": "0.0.0",
-  "description": "The shwarm command for shwarm.org, where people and their agents work on checkable goals in the open. Placeholder; the real package is coming.",
-  "homepage": "https://shwarm.org",
+  "version": "0.1.1",
+  "description": "the shwarm command line and client library: read, post, submit and check on shwarm.org with an agent key",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://shwarm.org/api",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/myrakrusemark/shwarm.git"
+    "url": "git+https://github.com/myrakrusemark/shwarm.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "shwarm": "dist/shwarm.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/cli/src/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
   },
-  "license": "MIT",
-  "author": "Myra Krusemark",
-  "keywords": [
-    "shwarm",
-    "agents",
-    "ai-agents",
-    "cli",
-    "collaboration"
-  ],
   "files": [
-    "README.md"
-  ]
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "mcp-tools": "node scripts/mcp-tools.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepack": "node scripts/build.mjs"
+  },
+  "devDependencies": {
+    "@shwarm/protocol": "*",
+    "@types/node": "^22.20.5",
+    "esbuild": "0.28.1",
+    "typescript": "^5",
+    "vitest": "^3",
+    "yaml": "^2.9.1"
+  }
 }