@eliya-oss/agent-slack 0.1.0

package/dist/application/slack-call.js

@@ -0,0 +1,62 @@
+import { UnsafeMethodBlocked } from "../domain/errors.js";
+import { pagingFrom } from "../output/envelope.js";
+export const callSlack = async (services, options) => {
+    const safety = services.methodCatalog.safetyFor(options.method);
+    if (isUnsafe(safety) && (!options.allowWrite || !options.yes)) {
+        throw new UnsafeMethodBlocked(`Refusing unsafe Slack method ${options.method}`, {
+            method: options.method,
+            safety
+        });
+    }
+    if (!options.all) {
+        const result = await services.slackWebApi.call({
+            method: options.method,
+            token: options.token,
+            payload: options.payload
+        });
+        return {
+            method: options.method,
+            response: result.response,
+            items: extractItems(services, options.method, result.response)
+        };
+    }
+    const itemKey = services.methodCatalog.itemKeyFor(options.method);
+    const collected = [];
+    let cursor;
+    let lastResponse = {};
+    for (let page = 0; page < 100; page += 1) {
+        const payload = cursor === undefined ? options.payload : { ...options.payload, cursor };
+        const result = await services.slackWebApi.call({
+            method: options.method,
+            token: options.token,
+            payload
+        });
+        lastResponse = result.response;
+        collected.push(...extractItems(services, options.method, result.response));
+        const paging = pagingFrom(result.response);
+        if (paging.next_cursor === null || itemKey === null) {
+            break;
+        }
+        cursor = paging.next_cursor;
+    }
+    return {
+        method: options.method,
+        response: itemKey === null ? lastResponse : { ...lastResponse, [itemKey]: collected },
+        items: collected
+    };
+};
+const isUnsafe = (safety) => safety === "write" || safety === "destructive" || safety === "admin";
+const extractItems = (services, method, response) => {
+    const itemKey = services.methodCatalog.itemKeyFor(method);
+    if (itemKey === null) {
+        return [];
+    }
+    const value = response[itemKey];
+    if (Array.isArray(value)) {
+        return value;
+    }
+    if (value !== undefined && typeof value === "object" && value !== null) {
+        return Object.entries(value).map(([key, entry]) => ({ key, value: entry }));
+    }
+    return [];
+};

package/dist/cli/args.js

@@ -0,0 +1,70 @@
+import { UsageError } from "../domain/errors.js";
+const booleanFlags = new Set([
+    "all",
+    "allow-write",
+    "help",
+    "json",
+    "raw",
+    "trace",
+    "yes",
+    "no-cache",
+    "inclusive",
+    "oauth"
+]);
+export const parseArgs = (argv) => {
+    const flags = new Map();
+    const positionals = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === undefined) {
+            continue;
+        }
+        if (token === "--") {
+            positionals.push(...argv.slice(index + 1));
+            break;
+        }
+        if (!token.startsWith("--") || token === "-") {
+            positionals.push(token);
+            continue;
+        }
+        const raw = token.slice(2);
+        const eq = raw.indexOf("=");
+        const name = eq >= 0 ? raw.slice(0, eq) : raw;
+        if (name === "") {
+            throw new UsageError("Invalid empty flag");
+        }
+        if (eq >= 0) {
+            flags.set(name, raw.slice(eq + 1));
+            continue;
+        }
+        if (booleanFlags.has(name)) {
+            flags.set(name, true);
+            continue;
+        }
+        const value = argv[index + 1];
+        if (value === undefined || value.startsWith("--")) {
+            throw new UsageError(`Missing value for --${name}`, { flag: name });
+        }
+        flags.set(name, value);
+        index += 1;
+    }
+    return { tokens: argv, flags, positionals };
+};
+export const flagString = (parsed, name, fallback) => {
+    const value = parsed.flags.get(name);
+    if (typeof value === "string") {
+        return value;
+    }
+    return fallback;
+};
+export const flagBoolean = (parsed, name) => parsed.flags.get(name) === true;
+export const requireFlag = (parsed, name) => {
+    const value = flagString(parsed, name);
+    if (value === undefined) {
+        throw new UsageError(`Missing required --${name}`, { flag: name });
+    }
+    return value;
+};
+export const splitCsv = (value) => value === undefined || value.trim() === ""
+    ? []
+    : value.split(",").map((item) => item.trim()).filter(Boolean);

package/dist/cli/metadata.js

@@ -0,0 +1,330 @@
+export const commandMetadata = [
+    {
+        path: ["describe"],
+        summary: "Describe the full CLI command tree as JSON.",
+        flags: ["--json"],
+        safety: "read",
+        output: "command metadata",
+        examples: ["slk describe --json"]
+    },
+    {
+        path: ["completion"],
+        summary: "Generate shell completion words.",
+        args: ["bash|zsh"],
+        safety: "read",
+        output: "shell completion script",
+        examples: ["slk completion zsh > ~/.zfunc/_slk"]
+    },
+    {
+        path: ["auth", "status"],
+        summary: "Show the active Slack auth profile.",
+        flags: ["--profile", "--json"],
+        safety: "read",
+        output: "profile status",
+        examples: ["slk auth status --json"]
+    },
+    {
+        path: ["auth", "login"],
+        summary: "Create a Slack auth profile with OAuth or a seeded token.",
+        flags: ["--profile", "--oauth", "--client-id", "--client-secret", "--scopes", "--user-scopes", "--redirect-uri", "--auth-url-out", "--timeout-ms", "--token", "--json"],
+        safety: "read",
+        output: "profile status",
+        examples: [
+            "slk auth login --oauth --client-id 123.456 --client-secret secret --scopes channels:read,channels:history --json",
+            "SLK_TOKEN=xoxb-... slk auth login --profile work --scopes channels:read --json"
+        ]
+    },
+    {
+        path: ["auth", "scopes"],
+        summary: "Show granted scopes for the active profile.",
+        flags: ["--profile", "--json"],
+        safety: "read",
+        output: "scope list",
+        examples: ["slk auth scopes --json"]
+    },
+    {
+        path: ["auth", "profiles", "list"],
+        summary: "List local auth profiles.",
+        flags: ["--json"],
+        safety: "read",
+        output: "profile list",
+        examples: ["slk auth profiles list --json"]
+    },
+    {
+        path: ["auth", "logout"],
+        summary: "Delete a local auth profile.",
+        flags: ["--profile", "--json"],
+        safety: "destructive",
+        output: "deleted profile status",
+        examples: ["slk auth logout --profile work --yes --json"]
+    },
+    {
+        path: ["auth", "test"],
+        summary: "Call Slack auth.test for the active profile.",
+        methods: ["auth.test"],
+        scopes: [],
+        safety: "read",
+        output: "Slack auth.test response",
+        examples: ["slk auth test --json"]
+    },
+    {
+        path: ["team", "get"],
+        summary: "Show workspace info.",
+        methods: ["team.info"],
+        scopes: ["team:read"],
+        safety: "read",
+        output: "team info",
+        examples: ["slk team get --json"]
+    },
+    {
+        path: ["team", "profile", "get"],
+        summary: "Show workspace profile fields.",
+        methods: ["team.profile.get"],
+        scopes: ["users.profile:read"],
+        safety: "read",
+        output: "team profile fields",
+        examples: ["slk team profile get --json"]
+    },
+    {
+        path: ["enterprise", "get"],
+        summary: "Show enterprise/workspace identity from team info.",
+        methods: ["team.info"],
+        scopes: ["team:read"],
+        safety: "read",
+        output: "team or enterprise info",
+        examples: ["slk enterprise get --json"]
+    },
+    {
+        path: ["user", "list"],
+        summary: "List users visible to the active profile.",
+        flags: ["--limit", "--all", "--json"],
+        methods: ["users.list"],
+        scopes: ["users:read"],
+        safety: "read",
+        output: "user list",
+        examples: ["slk user list --limit 50 --json"]
+    },
+    {
+        path: ["user", "get"],
+        summary: "Show one user.",
+        args: ["USER_ID"],
+        methods: ["users.info"],
+        scopes: ["users:read"],
+        safety: "read",
+        output: "user info",
+        examples: ["slk user get U123 --json"]
+    },
+    {
+        path: ["user", "lookup"],
+        summary: "Find a user by email.",
+        flags: ["--email", "--json"],
+        methods: ["users.lookupByEmail"],
+        scopes: ["users:read.email"],
+        safety: "read",
+        output: "user info",
+        examples: ["slk user lookup --email dev@example.com --json"]
+    },
+    {
+        path: ["user", "presence", "get"],
+        summary: "Show user presence.",
+        args: ["USER_ID"],
+        methods: ["users.getPresence"],
+        scopes: ["users:read"],
+        safety: "read",
+        output: "presence",
+        examples: ["slk user presence get U123 --json"]
+    },
+    {
+        path: ["usergroups", "list"],
+        summary: "List Slack user groups.",
+        methods: ["usergroups.list"],
+        scopes: ["usergroups:read"],
+        safety: "read",
+        output: "user group list",
+        examples: ["slk usergroups list --json"]
+    },
+    {
+        path: ["usergroups", "users", "list"],
+        summary: "List users in a Slack user group.",
+        args: ["USERGROUP_ID"],
+        methods: ["usergroups.users.list"],
+        scopes: ["usergroups:read"],
+        safety: "read",
+        output: "user IDs",
+        examples: ["slk usergroups users list S123 --json"]
+    },
+    {
+        path: ["api", "call"],
+        summary: "Call any Slack Web API method using a raw JSON payload.",
+        args: ["METHOD", "PAYLOAD_STDIN_MARKER"],
+        flags: ["--payload", "--profile", "--token", "--all", "--raw", "--format", "--allow-write", "--yes", "--json"],
+        safety: "unknown",
+        output: "Slack Web API response",
+        examples: [
+            "slk api call conversations.history --payload '{\"channel\":\"C123\"}' --json",
+            "cat payload.json | slk api call conversations.history -"
+        ]
+    },
+    {
+        path: ["api", "methods", "list"],
+        summary: "List bundled Slack method metadata.",
+        flags: ["--family", "--json"],
+        safety: "read",
+        output: "method metadata list",
+        examples: ["slk api methods list --family conversations --json"]
+    },
+    {
+        path: ["api", "method", "describe"],
+        summary: "Describe one Slack method.",
+        args: ["METHOD"],
+        flags: ["--json"],
+        safety: "read",
+        output: "method metadata",
+        examples: ["slk api method describe conversations.replies --json"]
+    },
+    {
+        path: ["conversation", "list"],
+        summary: "List conversations visible to the active profile.",
+        methods: ["conversations.list"],
+        scopes: ["channels:read", "groups:read", "im:read", "mpim:read"],
+        safety: "read",
+        output: "conversation list",
+        examples: ["slk conversation list --types public_channel,private_channel --json"]
+    },
+    {
+        path: ["conversation", "history"],
+        summary: "Read conversation history.",
+        args: ["CHANNEL_ID"],
+        methods: ["conversations.history"],
+        scopes: ["channels:history", "groups:history", "im:history", "mpim:history"],
+        safety: "read",
+        output: "message list",
+        examples: ["slk conversation history C123 --limit 20 --json"]
+    },
+    {
+        path: ["conversation", "context"],
+        summary: "Return agent-friendly channel context.",
+        args: ["CHANNEL_ID"],
+        methods: ["conversations.history", "conversations.replies", "users.info"],
+        scopes: ["channels:history", "users:read"],
+        safety: "read",
+        output: "hydrated conversation context",
+        examples: ["slk conversation context C123 --since 24h --include users,threads --format ndjson"]
+    },
+    {
+        path: ["thread", "get"],
+        summary: "Read a complete Slack thread.",
+        flags: ["--channel", "--ts", "--include", "--json"],
+        methods: ["conversations.replies"],
+        scopes: ["channels:history", "groups:history", "im:history", "mpim:history"],
+        safety: "read",
+        output: "thread messages",
+        examples: ["slk thread get --channel C123 --ts 1710000000.000100 --include users --json"]
+    },
+    {
+        path: ["message", "get"],
+        summary: "Read one Slack message by channel and timestamp.",
+        flags: ["--channel", "--ts", "--json"],
+        methods: ["conversations.history"],
+        scopes: ["channels:history"],
+        safety: "read",
+        output: "message",
+        examples: ["slk message get --channel C123 --ts 1710000000.000100 --json"]
+    },
+    {
+        path: ["message", "permalink"],
+        summary: "Return a Slack permalink for a message.",
+        flags: ["--channel", "--ts", "--json"],
+        methods: ["chat.getPermalink"],
+        safety: "read",
+        output: "permalink",
+        examples: ["slk message permalink --channel C123 --ts 1710000000.000100 --json"]
+    },
+    {
+        path: ["search", "context"],
+        summary: "Search Slack for agent context.",
+        flags: ["--query", "--content-types", "--json"],
+        methods: ["assistant.search.context"],
+        scopes: ["search:read.public", "search:read.private"],
+        safety: "read",
+        output: "search context",
+        examples: ["slk search context --query 'project atlas' --json"]
+    },
+    {
+        path: ["file", "list"],
+        summary: "List files visible to the active profile.",
+        methods: ["files.list"],
+        scopes: ["files:read"],
+        safety: "read",
+        output: "file list",
+        examples: ["slk file list --channel C123 --json"]
+    },
+    {
+        path: ["file", "download"],
+        summary: "Download a Slack file to disk.",
+        args: ["FILE_ID"],
+        flags: ["--out", "--profile", "--token", "--json"],
+        methods: ["files.info"],
+        scopes: ["files:read"],
+        safety: "read",
+        output: "download status",
+        examples: ["slk file download F123 --out ./artifact.pdf --json"]
+    }
+];
+export const describeAllCommands = () => ({
+    name: "slk",
+    version: "0.1.0",
+    commands: commandMetadata
+});
+export const findCommandMetadata = (path) => commandMetadata.find((command) => command.path.join(" ") === path.join(" ")) ?? null;
+export const describeCommandGroup = (group) => ({
+    name: group,
+    commands: commandMetadata.filter((command) => command.path[0] === group)
+});
+export const renderHumanHelp = (path) => {
+    const command = findCommandMetadata(path);
+    if (command !== null) {
+        return [
+            `slk ${command.path.join(" ")}`,
+            "",
+            command.summary,
+            "",
+            command.args === undefined ? "" : `Arguments: ${command.args.join(" ")}`,
+            command.flags === undefined ? "" : `Flags: ${command.flags.join(", ")}`,
+            command.scopes === undefined ? "" : `Scopes: ${command.scopes.join(", ")}`,
+            `Safety: ${command.safety}`,
+            `Output: ${command.output}`,
+            "",
+            "Examples:",
+            ...command.examples.map((example) => `  ${example}`)
+        ].filter((line) => line !== "").join("\n") + "\n";
+    }
+    const commands = path.length === 0 ? commandMetadata : commandMetadata.filter((item) => item.path[0] === path[0]);
+    return [
+        "slk",
+        "",
+        "Agent-readable Slack CLI.",
+        "",
+        "Commands:",
+        ...commands.map((item) => `  ${item.path.join(" ").padEnd(28)} ${item.summary}`)
+    ].join("\n") + "\n";
+};
+export const renderCompletion = (shell) => {
+    const words = [...new Set(commandMetadata.flatMap((command) => command.path))];
+    const commandWords = commandMetadata.map((command) => command.path.join(" "));
+    if (shell === "bash") {
+        return `complete -W '${words.join(" ")}' slk\n`;
+    }
+    if (shell === "zsh") {
+        return [
+            "#compdef slk",
+            "_slk_commands=(",
+            ...commandWords.map((command) => `  '${command}:${summaryFor(command)}'`),
+            ")",
+            "_describe 'slk command' _slk_commands",
+            ""
+        ].join("\n");
+    }
+    return "";
+};
+const summaryFor = (path) => commandMetadata.find((command) => command.path.join(" ") === path)?.summary.replace(/'/g, "") ?? "";

package/dist/cli/types.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/errors.js

@@ -0,0 +1,68 @@
+export class TaggedSlkError extends Error {
+    details;
+    constructor(message, details = {}) {
+        super(message);
+        this.name = new.target.name;
+        this.details = details;
+    }
+}
+export class NotAuthenticated extends TaggedSlkError {
+    _tag = "NotAuthenticated";
+    exitCode = 4;
+}
+export class MissingScope extends TaggedSlkError {
+    _tag = "MissingScope";
+    exitCode = 4;
+}
+export class PermissionDenied extends TaggedSlkError {
+    _tag = "PermissionDenied";
+    exitCode = 4;
+}
+export class SlackRateLimited extends TaggedSlkError {
+    _tag = "SlackRateLimited";
+    exitCode = 6;
+    retryAfterSeconds;
+    constructor(message, details = {}) {
+        super(message, details);
+        this.retryAfterSeconds = details.retryAfterSeconds;
+    }
+}
+export class SlackApiFailed extends TaggedSlkError {
+    _tag = "SlackApiFailed";
+    exitCode = 1;
+    slackError;
+    constructor(message, details = {}) {
+        super(message, details);
+        this.slackError = details.slackError;
+    }
+}
+export class InvalidPayload extends TaggedSlkError {
+    _tag = "InvalidPayload";
+    exitCode = 2;
+}
+export class ResourceNotFound extends TaggedSlkError {
+    _tag = "ResourceNotFound";
+    exitCode = 3;
+}
+export class UnsafeMethodBlocked extends TaggedSlkError {
+    _tag = "UnsafeMethodBlocked";
+    exitCode = 5;
+}
+export class UsageError extends TaggedSlkError {
+    _tag = "UsageError";
+    exitCode = 2;
+}
+export class UnsupportedMethod extends TaggedSlkError {
+    _tag = "UnsupportedMethod";
+    exitCode = 2;
+}
+export const isSlkError = (error) => error instanceof TaggedSlkError;
+export const normalizeUnknownError = (error) => {
+    if (isSlkError(error)) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new SlackApiFailed(error.message, { cause: error.name });
+    }
+    return new SlackApiFailed("Unexpected failure", { cause: String(error) });
+};

package/dist/domain/ids.js

@@ -0,0 +1,31 @@
+const nonEmpty = (value, name) => {
+    if (value.trim() === "") {
+        throw new Error(`${name} cannot be empty`);
+    }
+    return value;
+};
+export const TeamId = {
+    make: (value) => nonEmpty(value, "TeamId")
+};
+export const EnterpriseId = {
+    make: (value) => nonEmpty(value, "EnterpriseId")
+};
+export const ChannelId = {
+    make: (value) => nonEmpty(value, "ChannelId")
+};
+export const UserId = {
+    make: (value) => nonEmpty(value, "UserId")
+};
+export const MessageTs = {
+    make: (value) => nonEmpty(value, "MessageTs")
+};
+export const SlackMethod = {
+    make: (value) => nonEmpty(value, "SlackMethod")
+};
+export const ProfileName = {
+    default: "default",
+    make: (value) => nonEmpty(value, "ProfileName")
+};
+export const Scope = {
+    make: (value) => nonEmpty(value, "Scope")
+};

package/dist/domain/slack.js

@@ -0,0 +1 @@
+export {};

package/dist/main.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { NodeRuntime } from "@effect/platform-node";
+import { Effect } from "effect";
+import { createLiveServices } from "./adapters/live.js";
+import { executeCli } from "./application/execute.js";
+const program = Effect.promise(async () => {
+    const result = await executeCli(process.argv.slice(2), createLiveServices());
+    if (result.stdout.length > 0) {
+        process.stdout.write(result.stdout);
+    }
+    if (result.stderr.length > 0) {
+        process.stderr.write(result.stderr);
+    }
+    process.exitCode = result.exitCode;
+});
+NodeRuntime.runMain(program, { disableErrorReporting: true });

package/dist/output/envelope.js

@@ -0,0 +1,60 @@
+import { randomUUID } from "node:crypto";
+import { isSlkError, normalizeUnknownError } from "../domain/errors.js";
+export const pagingFrom = (response) => {
+    const metadata = response.response_metadata;
+    const nextCursor = typeof metadata === "object" && metadata !== null && "next_cursor" in metadata
+        ? metadata.next_cursor
+        : undefined;
+    return {
+        next_cursor: typeof nextCursor === "string" && nextCursor.length > 0 ? nextCursor : null,
+        has_more: response.has_more === true || (typeof nextCursor === "string" && nextCursor.length > 0)
+    };
+};
+export const successEnvelope = (input) => ({
+    ok: true,
+    method: input.method,
+    team_id: input.profile?.teamId ?? null,
+    enterprise_id: input.profile?.enterpriseId ?? null,
+    profile: input.profile?.name ?? null,
+    data: input.data,
+    paging: input.paging ?? { next_cursor: null, has_more: false },
+    warnings: input.warnings ?? []
+});
+export const errorEnvelope = (error) => {
+    const normalized = normalizeUnknownError(error);
+    const detailsSlackError = typeof normalized.details.slackError === "string" ? normalized.details.slackError : undefined;
+    const slackError = "slackError" in normalized ? normalized.slackError ?? detailsSlackError : detailsSlackError;
+    const retryAfterSeconds = "retryAfterSeconds" in normalized ? normalized.retryAfterSeconds : undefined;
+    const suggestion = suggestionFor(normalized._tag);
+    const envelope = {
+        ok: false,
+        error: {
+            type: normalized._tag,
+            title: normalized.message,
+            ...(slackError === undefined ? {} : { slack_error: slackError }),
+            retriable: normalized._tag === "SlackRateLimited",
+            ...(retryAfterSeconds === undefined ? {} : { retry_after_seconds: retryAfterSeconds }),
+            ...(suggestion === undefined ? {} : { suggestion }),
+            trace_id: `slk_${randomUUID()}`,
+            ...(Object.keys(normalized.details).length === 0 ? {} : { details: normalized.details })
+        }
+    };
+    return { envelope, exitCode: normalized.exitCode };
+};
+const suggestionFor = (tag) => {
+    switch (tag) {
+        case "NotAuthenticated":
+            return "Run slk auth login or provide a seeded profile for tests.";
+        case "MissingScope":
+            return "Reinstall or reauthorize the Slack app with the missing scope.";
+        case "SlackRateLimited":
+            return "Retry after the provided delay or reduce page size.";
+        case "UnsafeMethodBlocked":
+            return "Pass --allow-write --yes only when the operator intentionally allows this call.";
+        default:
+            return undefined;
+    }
+};
+export const stringifyJson = (value) => `${JSON.stringify(value, null, 2)}\n`;
+export const toNdjson = (items) => items.map((item) => JSON.stringify(item)).join("\n") + (items.length > 0 ? "\n" : "");
+export const exitCodeOf = (error) => isSlkError(error) ? error.exitCode : 1;