@xingular/harness 0.1.7 → 1.0.0

package/dist/sdk/hub/catalog.json

@@ -0,0 +1,123 @@
+{
+    "schemaVersion": 1,
+    "entries": [
+        {
+            "id": "xingular/evidence-first",
+            "title": "Evidence first",
+            "description": "Keep observations, inferences, and unknowns distinct.",
+            "publisher": "Xingular",
+            "license": "MIT",
+            "version": "1.0.0",
+            "category": "rule",
+            "channel": "official",
+            "tags": [
+                "rule"
+            ],
+            "requires": {
+                "harness": "0.1.6"
+            },
+            "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/evidence-first/1.0.0",
+            "delivery": {
+                "kind": "registry",
+                "registryKind": "rules",
+                "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/evidence-first/1.0.0/payload.json",
+                "sha256": "0f77661ea41e27bcb51aad982d15d493b893c5c1ba1eb6046a21315ddac07c5b",
+                "bundled": "{\n  \"items\": [\n    {\n      \"name\": \"hub-evidence-first\",\n      \"files\": [\n        {\n          \"path\": \"CONTENT.md\",\n          \"encoding\": \"utf8\",\n          \"content\": \"---\\nname: Evidence first\\ndescription: Distinguish observations, inferences, and unknowns.\\n---\\n\\nSupport factual claims with inspectable evidence. Label inferences and uncertainties. Correct a claim when better evidence changes it.\\n\"\n        }\n      ]\n    }\n  ]\n}\n"
+            }
+        },
+        {
+            "id": "xingular/github-connector",
+            "title": "GitHub connector",
+            "description": "A setup recipe for the GitHub MCP server; provide your own credentials.",
+            "publisher": "Xingular",
+            "license": "MIT",
+            "version": "1.0.0",
+            "category": "connector",
+            "channel": "official",
+            "tags": [
+                "connector"
+            ],
+            "requires": {
+                "harness": "0.1.6"
+            },
+            "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/github-connector/1.0.0",
+            "delivery": {
+                "kind": "document",
+                "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/github-connector/1.0.0/payload.json",
+                "sha256": "ec5bd9675e2977b9d880cf81732d84ac72b04af271048499415eaa6288896223",
+                "bundled": "{\n  \"id\": \"github-hub\",\n  \"name\": \"GitHub\",\n  \"description\": \"Repositories, issues, and pull requests\",\n  \"kind\": \"remote\",\n  \"docsUrl\": \"https://github.com/github/github-mcp-server\",\n  \"url\": \"https://api.githubcopilot.com/mcp/\",\n  \"auth\": \"headers\",\n  \"oauth\": null,\n  \"fields\": [\n    {\n      \"header\": \"Authorization\",\n      \"label\": \"Personal access token\",\n      \"prefix\": \"Bearer \",\n      \"help\": \"Provide a token for only the repositories and permissions you need.\"\n    }\n  ],\n  \"setup\": [\n    \"Create a personal access token in GitHub with the access you want to grant.\",\n    \"Review the connection before enabling it.\"\n  ],\n  \"notice\": null,\n  \"provenance\": null,\n  \"suggestedReadTools\": []\n}\n"
+            }
+        },
+        {
+            "id": "xingular/research-starter",
+            "title": "Research starter",
+            "description": "A starting agent for comparing sources and writing supported answers.",
+            "publisher": "Xingular",
+            "license": "MIT",
+            "version": "1.0.0",
+            "category": "agent-template",
+            "channel": "official",
+            "tags": [
+                "agent-template"
+            ],
+            "requires": {
+                "harness": "0.1.6"
+            },
+            "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/research-starter/1.0.0",
+            "delivery": {
+                "kind": "document",
+                "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/research-starter/1.0.0/payload.json",
+                "sha256": "a2f672583df6f4049cc153ba1e173192301220e5f8817f9ad5a4fe87af25f52b",
+                "bundled": "{\n  \"schemaVersion\": 1,\n  \"id\": \"research-starter\",\n  \"title\": \"Research starter\",\n  \"description\": \"Compare sources and explain the evidence behind an answer.\",\n  \"version\": \"1.0.0\",\n  \"author\": \"Xingular\",\n  \"license\": \"MIT\",\n  \"agent\": {\n    \"name\": \"Research starter\",\n    \"icon\": {\n      \"kind\": \"mascot\",\n      \"shape\": \"prism\",\n      \"color\": \"violet\",\n      \"material\": \"glass\"\n    },\n    \"description\": \"Investigates questions with sources.\",\n    \"instructions\": \"Help the user investigate a question. Start with reliable sources, explain what the evidence supports, cite the sources, and state unresolved questions. Ask the user when their goal is unclear.\",\n    \"model\": null,\n    \"effort\": \"high\",\n    \"tools\": [\n      \"read\",\n      \"grep\",\n      \"find\",\n      \"ls\",\n      \"web_search\",\n      \"web_fetch\"\n    ]\n  },\n  \"skills\": [],\n  \"connections\": []\n}\n"
+            }
+        },
+        {
+            "id": "xingular/source-review",
+            "title": "Review a source",
+            "description": "Check who wrote a source, what it supports, and what remains uncertain.",
+            "publisher": "Xingular",
+            "license": "MIT",
+            "version": "1.0.0",
+            "category": "skill",
+            "channel": "official",
+            "tags": [
+                "skill"
+            ],
+            "requires": {
+                "harness": "0.1.6"
+            },
+            "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/source-review/1.0.0",
+            "delivery": {
+                "kind": "registry",
+                "registryKind": "skills",
+                "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/source-review/1.0.0/payload.json",
+                "sha256": "bb0617889ee1ca39611a10952bec3086fa3986e9ce10a809c473c57acf47bc07",
+                "bundled": "{\n  \"items\": [\n    {\n      \"name\": \"hub-source-review\",\n      \"files\": [\n        {\n          \"path\": \"SKILL.md\",\n          \"encoding\": \"utf8\",\n          \"content\": \"---\\nname: hub-source-review\\ndescription: Review the evidence behind a source before using its claims.\\n---\\n\\n# Review a source\\n\\nRecord its author and date. Identify the original evidence. Write what the source supports and which uncertainties remain. Cite the source so the reader can inspect it.\\n\"\n        }\n      ]\n    }\n  ]\n}\n"
+            }
+        },
+        {
+            "id": "xingular/summarize-source",
+            "title": "Summarize a source",
+            "description": "Summarize a provided source and explain its limitations.",
+            "publisher": "Xingular",
+            "license": "MIT",
+            "version": "1.0.0",
+            "category": "prompt",
+            "channel": "official",
+            "tags": [
+                "prompt"
+            ],
+            "requires": {
+                "harness": "0.1.6"
+            },
+            "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/summarize-source/1.0.0",
+            "delivery": {
+                "kind": "registry",
+                "registryKind": "prompts",
+                "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/summarize-source/1.0.0/payload.json",
+                "sha256": "12a646d474fe3cd822970869c972d1d9400c7f6350388dc735dce5c31a22680a",
+                "bundled": "{\n  \"items\": [\n    {\n      \"name\": \"hub-summarize-source\",\n      \"files\": [\n        {\n          \"path\": \"CONTENT.md\",\n          \"encoding\": \"utf8\",\n          \"content\": \"---\\nname: summarize-source\\ndescription: Summarize the supplied source and its limits.\\n---\\n\\nSummarize the source below. Include its main claims, supporting evidence, limitations, and questions it leaves unanswered.\\n\\n$@\\n\"\n        }\n      ]\n    }\n  ]\n}\n"
+            }
+        }
+    ]
+}

package/dist/sdk/hub/cli.d.ts

@@ -0,0 +1,7 @@
+import { Harness, type HarnessOptions } from "../harness.js";
+export declare const HUB_USAGE = "Usage: xharness hub <list | show | install> [id@version] [options]\n\n  list [--refresh]             Browse the curated catalog and locally installed versions\n  show <id@version>            Show publisher, license, source, and delivery details\n  install <id@version>         Install the exact reviewed version, disabled and untrusted\n\n  --data <dir>                 Target data library (default: ~/.xingular-harness/data)\n  --state <dir>                Target device state (default: ~/.xingular-harness/state)\n  --refresh                    Refresh the public catalog; cached items remain usable offline\n";
+export declare function runHubCli(argv: string[], dependencies?: {
+    home?: string;
+    write?: (text: string) => void;
+    createHarness?: (options: HarnessOptions) => Harness;
+}): Promise<number>;

package/dist/sdk/hub/cli.js

@@ -0,0 +1,81 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { Harness } from "../harness.js";
+export const HUB_USAGE = `Usage: xharness hub <list | show | install> [id@version] [options]
+
+  list [--refresh]             Browse the curated catalog and locally installed versions
+  show <id@version>            Show publisher, license, source, and delivery details
+  install <id@version>         Install the exact reviewed version, disabled and untrusted
+
+  --data <dir>                 Target data library (default: ~/.xingular-harness/data)
+  --state <dir>                Target device state (default: ~/.xingular-harness/state)
+  --refresh                    Refresh the public catalog; cached items remain usable offline
+`;
+export async function runHubCli(argv, dependencies = {}) {
+    const write = dependencies.write ?? ((text) => void process.stdout.write(text));
+    const args = [];
+    const values = {};
+    let refresh = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--refresh')
+            refresh = true;
+        else if (arg === '--data' || arg === '--state') {
+            const value = argv[++index];
+            if (!value || value.startsWith('--')) {
+                write(`${arg} needs a directory.\n`);
+                return 2;
+            }
+            values[arg.slice(2)] = resolve(value);
+        }
+        else if (arg.startsWith('--')) {
+            write(`Unknown option ${arg}.\n`);
+            return 2;
+        }
+        else
+            args.push(arg);
+    }
+    const [command, target] = args;
+    if (!command || command === 'help') {
+        write(HUB_USAGE);
+        return 0;
+    }
+    if (!['list', 'show', 'install'].includes(command)) {
+        write(HUB_USAGE);
+        return 2;
+    }
+    const root = join(dependencies.home ?? homedir(), '.xingular-harness');
+    const options = { dataRoot: values.data ?? join(root, 'data'), stateDir: values.state ?? join(root, 'state') };
+    const harness = dependencies.createHarness?.(options) ?? new Harness(options);
+    try {
+        const overview = await harness.hub.list(refresh);
+        if (overview.error)
+            write(`Catalog refresh failed: ${overview.error} Using ${overview.origin} content.\n`);
+        if (command === 'list') {
+            write(`Library: ${options.dataRoot}\n${overview.entries.map((entry) => `${entry.id}@${entry.version}  ${entry.category}  ${entry.title}${overview.installed.some((receipt) => receipt.entry.id === entry.id && receipt.entry.version === entry.version) ? ' · installed' : ''}`).join('\n')}\n`);
+            return 0;
+        }
+        const split = target?.lastIndexOf('@') ?? -1;
+        if (!target || split < 1)
+            throw new Error('Name an exact item as publisher/name@version. Run hub list to see versions.');
+        const id = target.slice(0, split);
+        const version = target.slice(split + 1);
+        const entry = await harness.hub.get(id, version);
+        if (command === 'show') {
+            const { bundled: _bundled, ...delivery } = entry.delivery.kind === 'pi-package' ? { ...entry.delivery, bundled: undefined } : entry.delivery;
+            write(`${entry.title} (${target})\n${entry.description}\nPublisher: ${entry.publisher}\nLicense: ${entry.license}\nSource: ${entry.sourceUrl}\nDelivery: ${JSON.stringify(delivery)}\n`);
+        }
+        else {
+            const receipt = await harness.hub.install(id, version);
+            write(receipt.document ? `Saved ${target} in ${options.dataRoot}/hub/documents/${receipt.document}. Open this library in a compatible application to apply it.\n` : `Installed ${target}, switched off. Attach it separately${entry.delivery.kind === 'pi-package' ? ' and review/trust any code' : ''} before using it.\n`);
+        }
+        return 0;
+    }
+    catch (error) {
+        write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    finally {
+        await harness.close();
+    }
+}

package/dist/sdk/hub/hub.d.ts

@@ -0,0 +1,74 @@
+import type { Harness } from "../harness.js";
+import { type HubCatalog, type HubEntry, type HubOverview, type HubReceipt } from "./schema.js";
+export interface HubOptions {
+    catalogUrl?: string;
+    catalog?: HubCatalog;
+    fetch?: typeof globalThis.fetch;
+}
+/** Catalog data never loads extensions or changes attachment, trust, or connector scopes. */
+export declare class Hub {
+    private readonly harness;
+    private readonly fallback;
+    private readonly fetcher;
+    private readonly catalogUrl;
+    private watcher;
+    private refresh;
+    private installing;
+    private cachedPayload;
+    get busy(): boolean;
+    constructor(harness: Harness, options?: HubOptions);
+    private receipts;
+    private snapshot;
+    private receiptState;
+    private present;
+    list(refresh?: boolean): Promise<HubOverview>;
+    private bytes;
+    private refreshCatalog;
+    private decode;
+    private find;
+    get(id: string, version: string, preview?: boolean): Promise<HubEntry>;
+    private verifiedPayload;
+    preview(id: string, version: string, offset?: number): Promise<{
+        entry: {
+            id: string;
+            title: string;
+            description: string;
+            publisher: string;
+            license: string;
+            version: string;
+            category: string;
+            channel: "official" | "community";
+            tags: string[];
+            requires: Record<string, string>;
+            sourceUrl: string;
+            delivery: {
+                url: string;
+                sha256: string;
+                kind: "registry";
+                registryKind: "skills" | "prompts" | "rules";
+                bundled?: string | undefined;
+            } | {
+                url: string;
+                sha256: string;
+                kind: "document";
+                bundled?: string | undefined;
+            } | {
+                kind: "pi-package";
+                source: string;
+            };
+        };
+        content: string;
+        offset: number;
+        nextOffset: number;
+        totalBytes: number;
+        done: boolean;
+    }>;
+    install(id: string, version: string): Promise<HubReceipt>;
+    uninstall(id: string, version: string): Promise<HubReceipt>;
+    readDocument(id: string, version: string): {
+        entry: HubEntry;
+        content: string;
+    };
+    watch(root: string): void;
+    close(): void;
+}