@builtbyberry/prymer-cli 0.2.0

package/README.md

@@ -0,0 +1,74 @@
+# `prymer` — Prymer executing-hook helper
+
+A small, dependency-free CLI for the **executing-hook power mode**. The web
+connectors install _instructional_ hooks that nudge the model to call the Prymer
+MCP tools. This CLI instead runs the ritual itself, so the load step happens
+deterministically — even when the model forgets.
+
+It is built on Node's standard library only (no npm dependencies).
+
+## Install
+
+```bash
+npm install -g @builtbyberry/prymer-cli
+```
+
+## Authenticate
+
+1. In Prymer, open **Settings → Connected tools** and create a **hook credential**
+   for the channel you want this machine to use. The token (`swhk_…`) is shown
+   once.
+2. Store it:
+
+```bash
+prymer login --url https://your-prymer-host --token swhk_xxx
+```
+
+The token reaches exactly one channel and only the load + checkpoint verbs, so a
+leak is contained to that channel — never your whole account. On macOS it is kept
+in the login keychain; elsewhere in a `~/.prymer/*.json` file with `0600`
+permissions. Use `--profile <name>` to keep tokens for several channels side by
+side.
+
+## Use it in hooks
+
+```bash
+prymer install-hooks --client codex   # writes .codex/hooks.json
+prymer install-hooks --client claude  # writes .claude/settings.json
+```
+
+Both write a `SessionStart` hook that runs `prymer inject`. Codex and Claude Code
+both feed `SessionStart` stdout to the model as additional context, so the
+channel's context document loads automatically at the start of every session.
+
+## Commands
+
+| Command                                         | What it does                                                                                                                           |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `prymer login`                                  | Store a hook credential (verifies it before saving).                                                                                   |
+| `prymer logout`                                 | Remove a stored credential.                                                                                                            |
+| `prymer whoami`                                 | Show the stored host + a masked token.                                                                                                 |
+| `prymer inject`                                 | Print the channel's context document (for `SessionStart`). Fails quiet so it never breaks a session; use `--strict` to surface errors. |
+| `prymer checkpoint --title <t> --summary <s>`   | Append a checkpoint. Idempotent per session + state; only shares when the channel's capture mode is **Auto**.                          |
+| `prymer install-hooks --client <codex\|claude>` | Write the executing `SessionStart` hook for a client.                                                                                  |
+
+### Checkpointing
+
+`inject` is fully deterministic — no model needed. A checkpoint, by contrast,
+needs a summary worth keeping, so it's a step the agent (or you) takes when there
+is something to record rather than a blind Stop hook:
+
+```bash
+prymer checkpoint --session "$SESSION_ID" \
+  --title "Finished the billing fix" \
+  --summary "Switched to Stripe; tests green."
+```
+
+The idempotency key is derived from the session id + title + summary, so re-running
+the same checkpoint for the same session is a no-op rather than a duplicate.
+
+## Test
+
+```bash
+cd cli/prymer && npm test
+```

package/bin/prymer.js

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { parseArgs } from '../lib/args.js';
+import { deriveIdempotencyKey } from '../lib/checkpoint.js';
+import { hookFiles, SUPPORTED_CLIENTS } from '../lib/hooks.js';
+import { HttpError, request } from '../lib/http.js';
+import {
+    deleteCredentials,
+    loadCredentials,
+    saveCredentials,
+} from '../lib/store.js';
+
+const USAGE = `prymer — Prymer executing-hook helper
+
+Usage:
+  prymer login [--url <base-url>] [--token <hook-token>] [--profile <name>]
+  prymer logout [--profile <name>]
+  prymer whoami [--profile <name>]
+  prymer inject [--profile <name>] [--strict]
+  prymer checkpoint --title <t> --summary <s> [--content <c>] [--session <id>] [--key <k>] [--profile <name>]
+  prymer install-hooks --client <codex|claude> [--dir <path>]
+
+Create a hook token under Settings → Connected tools in Prymer, then run
+\`prymer login\`. Each token reaches one channel and only the load + checkpoint
+verbs. Profiles let you keep tokens for several channels side by side (default:
+"default").`;
+
+/**
+ * @param {string} baseUrl
+ * @param {string} path
+ * @returns {string}
+ */
+function endpoint(baseUrl, path) {
+    return `${baseUrl.replace(/\/+$/, '')}${path}`;
+}
+
+/**
+ * @param {string} question
+ * @returns {Promise<string>}
+ */
+async function prompt(question) {
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    try {
+        return (await rl.question(question)).trim();
+    } finally {
+        rl.close();
+    }
+}
+
+/**
+ * @param {Record<string, string|boolean>} flags
+ * @returns {string}
+ */
+function profileOf(flags) {
+    return typeof flags.profile === 'string' ? flags.profile : 'default';
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function mask(value) {
+    return value.length <= 8
+        ? '••••'
+        : `${value.slice(0, 6)}…${value.slice(-2)}`;
+}
+
+async function login(flags) {
+    const profile = profileOf(flags);
+
+    const url =
+        typeof flags.url === 'string'
+            ? flags.url
+            : await prompt('Prymer URL (e.g. https://prymer.example.com): ');
+    const token =
+        typeof flags.token === 'string'
+            ? flags.token
+            : await prompt('Hook token (swhk_…): ');
+
+    if (!url || !token) {
+        process.stderr.write('A URL and a token are both required.\n');
+        process.exitCode = 1;
+
+        return;
+    }
+
+    // Verify the credential before storing it, so a typo fails here, not later
+    // inside a hook where the error is invisible.
+    try {
+        await request('GET', endpoint(url, '/api/hooks/inject'), { token });
+    } catch (error) {
+        if (error instanceof HttpError && error.status === 401) {
+            process.stderr.write(
+                'That token was rejected. Check it and try again.\n',
+            );
+        } else {
+            process.stderr.write(`Could not reach Prymer: ${error.message}\n`);
+        }
+        process.exitCode = 1;
+
+        return;
+    }
+
+    saveCredentials(profile, { base_url: url, token });
+    process.stderr.write(`Saved credentials for profile "${profile}".\n`);
+}
+
+function logout(flags) {
+    const profile = profileOf(flags);
+    deleteCredentials(profile);
+    process.stderr.write(`Removed credentials for profile "${profile}".\n`);
+}
+
+function whoami(flags) {
+    const profile = profileOf(flags);
+    const creds = loadCredentials(profile);
+
+    if (!creds) {
+        process.stderr.write(
+            `No credentials for profile "${profile}". Run \`prymer login\`.\n`,
+        );
+        process.exitCode = 1;
+
+        return;
+    }
+
+    process.stdout.write(`${creds.base_url} (token ${mask(creds.token)})\n`);
+}
+
+async function inject(flags) {
+    const profile = profileOf(flags);
+    const strict = flags.strict === true;
+    const creds = loadCredentials(profile);
+
+    // A SessionStart hook must never break the session: with no credential (or
+    // any failure), inject stays quiet and exits 0 unless --strict is set.
+    if (!creds) {
+        process.stderr.write(
+            `prymer: no credential for profile "${profile}" — skipping context load.\n`,
+        );
+        process.exitCode = strict ? 1 : 0;
+
+        return;
+    }
+
+    try {
+        const { json } = await request(
+            'GET',
+            endpoint(creds.base_url, '/api/hooks/inject'),
+            {
+                token: creds.token,
+            },
+        );
+
+        const text =
+            json && typeof json.formatted === 'string' ? json.formatted : '';
+        if (text) {
+            process.stdout.write(`${text}\n`);
+        }
+    } catch (error) {
+        process.stderr.write(
+            `prymer: could not load context (${error.message}).\n`,
+        );
+        process.exitCode = strict ? 1 : 0;
+    }
+}
+
+async function checkpoint(flags) {
+    const profile = profileOf(flags);
+    const creds = loadCredentials(profile);
+
+    if (!creds) {
+        process.stderr.write(
+            `No credential for profile "${profile}". Run \`prymer login\`.\n`,
+        );
+        process.exitCode = 1;
+
+        return;
+    }
+
+    const title = typeof flags.title === 'string' ? flags.title : '';
+    const summary = typeof flags.summary === 'string' ? flags.summary : '';
+
+    if (!title || !summary) {
+        process.stderr.write('checkpoint needs --title and --summary.\n');
+        process.exitCode = 1;
+
+        return;
+    }
+
+    const sessionId =
+        typeof flags.session === 'string'
+            ? flags.session
+            : process.env.SWARM_SESSION_ID;
+    const idempotencyKey =
+        typeof flags.key === 'string'
+            ? flags.key
+            : deriveIdempotencyKey({ sessionId, title, summary });
+
+    try {
+        const { json } = await request(
+            'POST',
+            endpoint(creds.base_url, '/api/hooks/checkpoint'),
+            {
+                token: creds.token,
+                body: {
+                    idempotency_key: idempotencyKey,
+                    title,
+                    summary,
+                    ...(typeof flags.content === 'string'
+                        ? { content: flags.content }
+                        : {}),
+                },
+            },
+        );
+
+        if (json && json.shared === false) {
+            process.stderr.write(
+                `Not shared (${json.reason ?? 'unknown'}). The channel is not set to Auto capture.\n`,
+            );
+
+            return;
+        }
+
+        const idempotent = json && json.idempotent ? ' (already recorded)' : '';
+        process.stderr.write(`Checkpoint shared${idempotent}.\n`);
+    } catch (error) {
+        const detail =
+            error instanceof HttpError
+                ? JSON.stringify(error.body)
+                : error.message;
+        process.stderr.write(`Checkpoint failed: ${detail}\n`);
+        process.exitCode = 1;
+    }
+}
+
+function installHooks(flags) {
+    const client = typeof flags.client === 'string' ? flags.client : '';
+
+    if (!SUPPORTED_CLIENTS.includes(/** @type {any} */ (client))) {
+        process.stderr.write(
+            `--client must be one of: ${SUPPORTED_CLIENTS.join(', ')}.\n`,
+        );
+        process.exitCode = 1;
+
+        return;
+    }
+
+    const baseDir =
+        typeof flags.dir === 'string' ? resolve(flags.dir) : process.cwd();
+    const files = hookFiles(/** @type {'codex'|'claude'} */ (client));
+
+    for (const [relativePath, contents] of Object.entries(files)) {
+        const target = join(baseDir, relativePath);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, contents);
+        process.stderr.write(`Wrote ${relativePath}\n`);
+    }
+
+    process.stderr.write(
+        'Executing hooks installed. Run `prymer login` if you have not yet.\n',
+    );
+}
+
+async function main() {
+    const { command, flags } = parseArgs(process.argv.slice(2));
+
+    switch (command) {
+        case 'login':
+            return login(flags);
+        case 'logout':
+            return logout(flags);
+        case 'whoami':
+            return whoami(flags);
+        case 'inject':
+            return inject(flags);
+        case 'checkpoint':
+            return checkpoint(flags);
+        case 'install-hooks':
+            return installHooks(flags);
+        case undefined:
+        case 'help':
+        case '--help':
+        case '-h':
+            process.stdout.write(`${USAGE}\n`);
+
+            return;
+        default:
+            process.stderr.write(`Unknown command: ${command}\n\n${USAGE}\n`);
+            process.exitCode = 1;
+    }
+}
+
+main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+});

package/lib/args.js

@@ -0,0 +1,34 @@
+/**
+ * A tiny, dependency-free argv parser. `prymer <command> [--flag value] [--bool]
+ * [positional]`. A flag with no following value (or followed by another `--flag`)
+ * is treated as a boolean `true`.
+ *
+ * @param {string[]} argv  The args after the node binary + script (i.e. process.argv.slice(2)).
+ * @returns {{ command: string|undefined, flags: Record<string, string|boolean>, positionals: string[] }}
+ */
+export function parseArgs(argv) {
+    const [command, ...rest] = argv;
+    /** @type {Record<string, string|boolean>} */
+    const flags = {};
+    const positionals = [];
+
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+
+        if (arg.startsWith('--')) {
+            const key = arg.slice(2);
+            const next = rest[i + 1];
+
+            if (next === undefined || next.startsWith('--')) {
+                flags[key] = true;
+            } else {
+                flags[key] = next;
+                i++;
+            }
+        } else {
+            positionals.push(arg);
+        }
+    }
+
+    return { command, flags, positionals };
+}

package/lib/hooks.js

@@ -0,0 +1,73 @@
+/**
+ * Executing-hook templates. Unlike the *instructional* hooks the web connectors
+ * ship (which only print a nudge for the model to call an MCP tool), these run
+ * the `prymer` CLI directly, so the load step happens deterministically — even if
+ * the model forgets the ritual.
+ *
+ * SessionStart runs `prymer inject`, which prints the channel's context document
+ * to stdout; both Codex and Claude Code feed SessionStart stdout to the model as
+ * additional context. Checkpointing stays a step the agent takes when it has a
+ * summary to write (a blind Stop hook has nothing meaningful to checkpoint), so
+ * the templates document `prymer checkpoint` rather than firing it blindly.
+ */
+
+/**
+ * @param {string} json
+ * @returns {string}
+ */
+function pretty(json) {
+    return `${JSON.stringify(json, null, 2)}\n`;
+}
+
+/**
+ * The files to write for a given client, keyed by project-relative path.
+ *
+ * @param {'codex'|'claude'} client
+ * @returns {Record<string, string>}
+ */
+export function hookFiles(client) {
+    if (client === 'codex') {
+        return {
+            '.codex/hooks.json': pretty({
+                hooks: {
+                    SessionStart: [
+                        {
+                            matcher: 'startup|resume',
+                            hooks: [
+                                {
+                                    type: 'command',
+                                    command: 'prymer inject',
+                                    statusMessage: 'Loading Prymer context',
+                                },
+                            ],
+                        },
+                    ],
+                },
+            }),
+        };
+    }
+
+    if (client === 'claude') {
+        return {
+            '.claude/settings.json': pretty({
+                hooks: {
+                    SessionStart: [
+                        {
+                            hooks: [
+                                {
+                                    type: 'command',
+                                    command: 'prymer inject',
+                                },
+                            ],
+                        },
+                    ],
+                },
+            }),
+        };
+    }
+
+    throw new Error(`Unknown client: ${client} (expected codex or claude)`);
+}
+
+/** @type {ReadonlyArray<'codex'|'claude'>} */
+export const SUPPORTED_CLIENTS = ['codex', 'claude'];

package/lib/http.js

@@ -0,0 +1,96 @@
+import http from 'node:http';
+import https from 'node:https';
+
+/**
+ * An HTTP error carrying the parsed body, so callers can read the server's
+ * `reason` (e.g. `capture_mode_not_auto`) or message.
+ */
+export class HttpError extends Error {
+    /**
+     * @param {number} status
+     * @param {any} body
+     */
+    constructor(status, body) {
+        super(`HTTP ${status}`);
+        this.name = 'HttpError';
+        this.status = status;
+        this.body = body;
+    }
+}
+
+/**
+ * @param {string} data
+ * @returns {any}
+ */
+function safeJson(data) {
+    try {
+        return JSON.parse(data);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Make a JSON request with no third-party dependencies.
+ *
+ * @param {'GET'|'POST'} method
+ * @param {string} urlString
+ * @param {{ token?: string, body?: object }} [options]
+ * @returns {Promise<{ status: number, json: any }>}
+ */
+export function request(method, urlString, { token, body } = {}) {
+    return new Promise((resolve, reject) => {
+        let url;
+        try {
+            url = new URL(urlString);
+        } catch {
+            reject(new Error(`Invalid URL: ${urlString}`));
+
+            return;
+        }
+
+        const lib = url.protocol === 'http:' ? http : https;
+        const payload = body ? JSON.stringify(body) : null;
+
+        const req = lib.request(
+            url,
+            {
+                method,
+                headers: {
+                    Accept: 'application/json',
+                    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+                    ...(payload
+                        ? {
+                              'Content-Type': 'application/json',
+                              'Content-Length': Buffer.byteLength(payload),
+                          }
+                        : {}),
+                },
+            },
+            (res) => {
+                let data = '';
+                res.on('data', (chunk) => {
+                    data += chunk;
+                });
+                res.on('end', () => {
+                    const json = data ? safeJson(data) : null;
+                    const status = res.statusCode ?? 0;
+
+                    if (status >= 200 && status < 300) {
+                        resolve({ status, json });
+                    } else {
+                        reject(new HttpError(status, json ?? data));
+                    }
+                });
+            },
+        );
+
+        req.on('error', reject);
+
+        if (payload) {
+            req.write(payload);
+        }
+
+        req.end();
+    });
+}

package/lib/store.js

@@ -0,0 +1,124 @@
+import { execFileSync } from 'node:child_process';
+import {
+    chmodSync,
+    existsSync,
+    mkdirSync,
+    readFileSync,
+    rmSync,
+    writeFileSync,
+} from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Credential storage for the executing-hook power mode.
+ *
+ * A hook credential is a high-value secret (one channel, append-capable), so the
+ * gate's blast-radius decision is to keep it out of plaintext dotfiles where we
+ * can. On macOS we use the login keychain via the `security` CLI; everywhere else
+ * we fall back to a `~/.prymer` file with `0600` perms. Set `SWARM_NO_KEYCHAIN=1`
+ * to force the file path (used by the test suite, and by anyone who prefers it).
+ */
+
+const SERVICE = 'prymer';
+const FILE_DIR = join(homedir(), '.prymer');
+
+/**
+ * @param {string} profile
+ * @returns {string}
+ */
+function filePath(profile) {
+    return join(FILE_DIR, `credentials-${profile}.json`);
+}
+
+/**
+ * @returns {boolean}
+ */
+function useKeychain() {
+    return platform() === 'darwin' && process.env.SWARM_NO_KEYCHAIN !== '1';
+}
+
+/**
+ * @param {string} profile
+ * @param {{ base_url: string, token: string }} data
+ */
+export function saveCredentials(profile, data) {
+    const json = JSON.stringify(data);
+
+    if (useKeychain()) {
+        // -U updates the entry if it already exists rather than erroring.
+        execFileSync('security', [
+            'add-generic-password',
+            '-U',
+            '-s',
+            SERVICE,
+            '-a',
+            profile,
+            '-w',
+            json,
+        ]);
+
+        return;
+    }
+
+    mkdirSync(FILE_DIR, { recursive: true });
+    writeFileSync(filePath(profile), json, { mode: 0o600 });
+    chmodSync(filePath(profile), 0o600);
+}
+
+/**
+ * @param {string} profile
+ * @returns {{ base_url: string, token: string } | null}
+ */
+export function loadCredentials(profile) {
+    if (useKeychain()) {
+        try {
+            const out = execFileSync(
+                'security',
+                ['find-generic-password', '-s', SERVICE, '-a', profile, '-w'],
+                { encoding: 'utf8' },
+            );
+
+            return JSON.parse(out.trim());
+        } catch {
+            return null;
+        }
+    }
+
+    if (!existsSync(filePath(profile))) {
+        return null;
+    }
+
+    try {
+        return JSON.parse(readFileSync(filePath(profile), 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * @param {string} profile
+ */
+export function deleteCredentials(profile) {
+    if (useKeychain()) {
+        try {
+            execFileSync('security', [
+                'delete-generic-password',
+                '-s',
+                SERVICE,
+                '-a',
+                profile,
+            ]);
+        } catch {
+            // Nothing stored — deleting is a no-op.
+        }
+
+        return;
+    }
+
+    try {
+        rmSync(filePath(profile));
+    } catch {
+        // Nothing stored — deleting is a no-op.
+    }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+    "name": "@builtbyberry/prymer-cli",
+    "version": "0.2.0",
+    "description": "The Prymer executing-hook helper: load context at session start and checkpoint at session stop, deterministically, from a scoped channel credential.",
+    "type": "module",
+    "bin": {
+        "prymer": "bin/prymer.js"
+    },
+    "files": [
+        "bin",
+        "lib",
+        "README.md"
+    ],
+    "engines": {
+        "node": ">=18"
+    },
+    "scripts": {
+        "test": "node --test",
+        "prepublishOnly": "node --test"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/builtbyberry/swarmcloud.git",
+        "directory": "cli/prymer"
+    },
+    "homepage": "https://github.com/builtbyberry/swarmcloud/tree/main/cli/prymer#readme",
+    "bugs": "https://github.com/builtbyberry/swarmcloud/issues",
+    "keywords": [
+        "prymer",
+        "mcp",
+        "context",
+        "hooks",
+        "cli"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "license": "MIT"
+}