@chore-o-matic/catalog 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @chore-o-matic/catalog
+
+The capability catalog for [Chore-o-matic](https://chore-o-matic.sh). Entry manifests
+describing tools, channels, and (future) agent templates that a chore-agent can be given.
+
+Distributed as an npm package. Downstream components (the interview meta-agent, the
+generator, the specification validator) depend on this package for tool discovery and
+`use:` reference resolution.
+
+Tool and channel implementations live in [`eve-contrib`](../../../eve-contrib/) as generic
+`@chore-o-matic/eve-*` eve packages. This catalog adds chore-o-matic-specific metadata:
+house-voice descriptions, approval defaults, connection slot definitions, and config
+schemas.
+
+## Install
+
+```bash
+npm install @chore-o-matic/catalog
+```
+
+## Use
+
+```ts
+import { resolveUse, entriesByKind, allEntries } from "@chore-o-matic/catalog";
+
+// Resolve a spec's `use:` reference to a catalog entry.
+const entry = resolveUse("google-calendar.read");
+
+// Get all tool entries (grounds the interview meta-agent).
+const tools = entriesByKind("tool");
+
+// Get all entries (tools + channels + future templates).
+const everything = allEntries();
+```
+
+## Entry ids
+
+Ids are dotted, human-readable, and stable across package renames:
+
+- `google-calendar.read`
+- `google-calendar.create-event`
+- `sendgrid.send-email`
+- `google-sheets.append-row`
+- `webhook.send`
+- `whatsapp`
+
+The spec's `use:` field holds the id. The resolver maps it to the implementation package
+and member.
+
+## Adding a capability
+
+1. Publish an `@chore-o-matic/eve-*` package in `eve-contrib` with the tool/channel factory.
+2. Add an entry manifest in `src/entries/`.
+3. Publish a new version of this package.
+
+No downstream component changes required — the interview and generator read entries
+dynamically.
+
+## Develop
+
+```bash
+npm run build      # tsc -> dist/
+npm run typecheck
+npm test           # hermetic unit tests
+```

package/dist/entries/channels/whatsapp.d.ts

@@ -0,0 +1,2 @@
+import type { ChannelEntry } from "../../types.js";
+export declare const whatsapp: ChannelEntry;

package/dist/entries/channels/whatsapp.js

@@ -0,0 +1,25 @@
+export const whatsapp = {
+    id: "whatsapp",
+    kind: "channel",
+    description: "Talk to the agent over WhatsApp. Clients message in, the agent replies back.",
+    visibility: "public",
+    approvalDefault: false,
+    source: {
+        type: "package",
+        package: "@chore-o-matic/eve-whatsapp",
+        member: "whatsappChannel",
+    },
+    connectionSlots: [
+        {
+            slot: "whatsapp",
+            provider: "meta",
+            authMethod: "static-token",
+            envVars: [
+                { name: "WHATSAPP_ACCESS_TOKEN", description: "Permanent system-user token (outbound sends)" },
+                { name: "WHATSAPP_PHONE_NUMBER_ID", description: "Business phone number id (outbound endpoint)" },
+                { name: "WHATSAPP_APP_SECRET", description: "Meta app secret for webhook signature verification" },
+                { name: "WHATSAPP_VERIFY_TOKEN", description: "Webhook subscription handshake token" },
+            ],
+        },
+    ],
+};

package/dist/entries/index.d.ts

@@ -0,0 +1,2 @@
+import type { CatalogEntry } from "../types.js";
+export declare const entries: CatalogEntry[];

package/dist/entries/index.js

@@ -0,0 +1,18 @@
+import { googleCalendarRead, googleCalendarCreateEvent } from "./tools/google-calendar.js";
+import { googleSheetsAppendRow } from "./tools/google-sheets.js";
+import { sendgridSendEmail } from "./tools/sendgrid.js";
+import { webhookSend } from "./tools/webhook.js";
+import { whatsapp } from "./channels/whatsapp.js";
+import { templates } from "./templates/index.js";
+export const entries = [
+    // Tools
+    googleCalendarRead,
+    googleCalendarCreateEvent,
+    googleSheetsAppendRow,
+    sendgridSendEmail,
+    webhookSend,
+    // Channels
+    whatsapp,
+    // Agent templates (future)
+    ...templates,
+];

package/dist/entries/templates/index.d.ts

@@ -0,0 +1 @@
+export declare const templates: never[];

package/dist/entries/templates/index.js

@@ -0,0 +1,5 @@
+// Agent template entries — placeholder for future use.
+// Agent templates will describe reusable agent configurations that the generator
+// can use as starting points. The entry type will be "agent-template" with its own
+// source shape. Empty array for now; exported to keep the barrel stable.
+export const templates = [];

package/dist/entries/tools/google-calendar.d.ts

@@ -0,0 +1,3 @@
+import type { ToolEntry } from "../../types.js";
+export declare const googleCalendarRead: ToolEntry;
+export declare const googleCalendarCreateEvent: ToolEntry;

package/dist/entries/tools/google-calendar.js

@@ -0,0 +1,54 @@
+export const googleCalendarRead = {
+    id: "google-calendar.read",
+    kind: "tool",
+    description: "Read upcoming events from a Google Calendar. Shows what's on the schedule.",
+    visibility: "public",
+    approvalDefault: false,
+    source: {
+        type: "package",
+        package: "@chore-o-matic/eve-gcal",
+        member: "readCalendar",
+    },
+    connectionSlots: [
+        {
+            slot: "google",
+            provider: "google",
+            authMethod: "oauth",
+            scopes: ["calendar.events.readonly"],
+            envVars: [{ name: "GOOGLE_ACCESS_TOKEN", description: "Google OAuth access token" }],
+        },
+    ],
+    configSchema: {
+        type: "object",
+        properties: {
+            calendar: { type: "string", description: "Calendar ID. Defaults to 'primary'." },
+        },
+    },
+};
+export const googleCalendarCreateEvent = {
+    id: "google-calendar.create-event",
+    kind: "tool",
+    description: "Create a new event on a Google Calendar. Adds to the schedule.",
+    visibility: "public",
+    approvalDefault: true,
+    source: {
+        type: "package",
+        package: "@chore-o-matic/eve-gcal",
+        member: "createEvent",
+    },
+    connectionSlots: [
+        {
+            slot: "google",
+            provider: "google",
+            authMethod: "oauth",
+            scopes: ["calendar.events"],
+            envVars: [{ name: "GOOGLE_ACCESS_TOKEN", description: "Google OAuth access token" }],
+        },
+    ],
+    configSchema: {
+        type: "object",
+        properties: {
+            calendar: { type: "string", description: "Calendar ID. Defaults to 'primary'." },
+        },
+    },
+};

package/dist/entries/tools/google-sheets.d.ts

@@ -0,0 +1,2 @@
+import type { ToolEntry } from "../../types.js";
+export declare const googleSheetsAppendRow: ToolEntry;

package/dist/entries/tools/google-sheets.js

@@ -0,0 +1,29 @@
+export const googleSheetsAppendRow = {
+    id: "google-sheets.append-row",
+    kind: "tool",
+    description: "Append a row to a Google Sheets spreadsheet. Records data at the bottom of a sheet.",
+    visibility: "public",
+    approvalDefault: false,
+    source: {
+        type: "package",
+        package: "@chore-o-matic/eve-sheets",
+        member: "appendRow",
+    },
+    connectionSlots: [
+        {
+            slot: "google",
+            provider: "google",
+            authMethod: "oauth",
+            scopes: ["spreadsheets"],
+            envVars: [{ name: "GOOGLE_ACCESS_TOKEN", description: "Google OAuth access token" }],
+        },
+    ],
+    configSchema: {
+        type: "object",
+        properties: {
+            spreadsheetId: { type: "string", description: "The spreadsheet ID." },
+            sheetName: { type: "string", description: "The sheet/tab name. Defaults to 'Sheet1'." },
+        },
+        required: ["spreadsheetId"],
+    },
+};

package/dist/entries/tools/sendgrid.d.ts

@@ -0,0 +1,2 @@
+import type { ToolEntry } from "../../types.js";
+export declare const sendgridSendEmail: ToolEntry;

package/dist/entries/tools/sendgrid.js

@@ -0,0 +1,27 @@
+export const sendgridSendEmail = {
+    id: "sendgrid.send-email",
+    kind: "tool",
+    description: "Send an email through SendGrid. Delivers a message to a recipient.",
+    visibility: "public",
+    approvalDefault: true,
+    source: {
+        type: "package",
+        package: "@chore-o-matic/eve-sendgrid",
+        member: "sendEmail",
+    },
+    connectionSlots: [
+        {
+            slot: "sendgrid",
+            provider: "sendgrid",
+            authMethod: "api-key",
+            envVars: [{ name: "SENDGRID_API_KEY", description: "SendGrid API key" }],
+        },
+    ],
+    configSchema: {
+        type: "object",
+        properties: {
+            fromEmail: { type: "string", description: "Sender email address." },
+            fromName: { type: "string", description: "Sender display name." },
+        },
+    },
+};

package/dist/entries/tools/webhook.d.ts

@@ -0,0 +1,2 @@
+import type { ToolEntry } from "../../types.js";
+export declare const webhookSend: ToolEntry;

package/dist/entries/tools/webhook.js

@@ -0,0 +1,28 @@
+export const webhookSend = {
+    id: "webhook.send",
+    kind: "tool",
+    description: "Send an HTTP POST to a webhook URL. Notifies an external service.",
+    visibility: "public",
+    approvalDefault: false,
+    source: {
+        type: "package",
+        package: "@chore-o-matic/eve-webhook",
+        member: "sendWebhook",
+    },
+    connectionSlots: [
+        {
+            slot: "webhook",
+            provider: "webhook",
+            authMethod: "webhook-secret",
+            envVars: [
+                { name: "WEBHOOK_URL", description: "The webhook endpoint URL (contains the secret)." },
+            ],
+        },
+    ],
+    configSchema: {
+        type: "object",
+        properties: {
+            headers: { type: "object", description: "Additional HTTP headers." },
+        },
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { resolveUse, entriesByKind, allEntries } from "./resolver.js";
+export type { CatalogEntry, ToolEntry, ChannelEntry, BaseEntry, EntryKind, PackageSource, ConnectionSlot, AuthMethod, EnvVar, } from "./types.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { resolveUse, entriesByKind, allEntries } from "./resolver.js";

package/dist/resolver.d.ts

@@ -0,0 +1,11 @@
+import type { CatalogEntry, EntryKind } from "./types.js";
+/**
+ * Resolve a spec's `use:` reference to a catalog entry.
+ * Returns `undefined` when the id is not in the catalog (a dangling reference
+ * downstream means a spec goes serviceable, not a crash — §7 Validity).
+ */
+export declare function resolveUse(id: string): CatalogEntry | undefined;
+/** All entries of a given kind. Used by the interview meta-agent to ground capability honesty. */
+export declare function entriesByKind(kind: EntryKind): CatalogEntry[];
+/** All catalog entries (tools + channels + future templates). */
+export declare function allEntries(): readonly CatalogEntry[];

package/dist/resolver.js

@@ -0,0 +1,17 @@
+import { entries } from "./entries/index.js";
+/**
+ * Resolve a spec's `use:` reference to a catalog entry.
+ * Returns `undefined` when the id is not in the catalog (a dangling reference
+ * downstream means a spec goes serviceable, not a crash — §7 Validity).
+ */
+export function resolveUse(id) {
+    return entries.find((e) => e.id === id);
+}
+/** All entries of a given kind. Used by the interview meta-agent to ground capability honesty. */
+export function entriesByKind(kind) {
+    return entries.filter((e) => e.kind === kind);
+}
+/** All catalog entries (tools + channels + future templates). */
+export function allEntries() {
+    return entries;
+}

package/dist/types.d.ts

@@ -0,0 +1,48 @@
+export type CatalogEntry = ToolEntry | ChannelEntry;
+export type EntryKind = "tool" | "channel";
+export interface BaseEntry {
+    /** Dotted, human-readable, stable across package renames. e.g. "google-calendar.read". */
+    id: string;
+    kind: EntryKind;
+    /** House-voice description. Appears in the catalog-first opening and in the meta-agent's mouth. */
+    description: string;
+    /** "public" for catalog entries, "account" for studio-private entries (FR-23/24). */
+    visibility: "public" | "account";
+    /** Whether the tool/channel requires approval by default (NFR-6: least privilege). */
+    approvalDefault: boolean;
+    /** Credential requirements. The spec names slots; this context defines what each slot needs. */
+    connectionSlots: ConnectionSlot[];
+    /** Optional config schema (JSON Schema) for tool/channel configuration in the spec. */
+    configSchema?: Record<string, unknown>;
+}
+export interface ToolEntry extends BaseEntry {
+    kind: "tool";
+    source: PackageSource;
+}
+export interface ChannelEntry extends BaseEntry {
+    kind: "channel";
+    source: PackageSource;
+}
+export interface PackageSource {
+    type: "package";
+    /** npm package name, e.g. "@chore-o-matic/eve-gcal". */
+    package: string;
+    /** Exported member name, e.g. "readCalendar", "whatsappChannel". */
+    member: string;
+}
+export interface ConnectionSlot {
+    /** Slot name, e.g. "google", "sendgrid", "whatsapp". */
+    slot: string;
+    /** Provider identifier, e.g. "google", "meta", "sendgrid". */
+    provider: string;
+    authMethod: AuthMethod;
+    /** OAuth scopes when authMethod is "oauth". */
+    scopes?: string[];
+    /** Environment variables the deployment needs for this slot. */
+    envVars: EnvVar[];
+}
+export type AuthMethod = "oauth" | "api-key" | "static-token" | "webhook-secret" | "none";
+export interface EnvVar {
+    name: string;
+    description: string;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+// Catalog entry types. Each entry describes a capability a chore-agent can be given.
+// Implementations live in eve-contrib as @chore-o-matic/eve-* packages; this package
+// adds chore-o-matic-specific metadata (house voice, approval defaults, connection slots).
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@chore-o-matic/catalog",
+  "version": "0.1.0",
+  "description": "Capability catalog for Chore-o-matic — tool, channel, and agent template entries.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "chore-o-matic",
+    "catalog",
+    "eve",
+    "agent"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test",
+    "prepare": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^6.0.3"
+  }
+}