scribeclock 0.0.0-stage → 0.1.0

package/dist/context.js

@@ -0,0 +1,125 @@
+import { join } from "node:path";
+import { EXIT } from "./types.js";
+import { Output } from "./cli/output.js";
+import { CliError, authError, scopeError } from "./cli/errors.js";
+import { ConfigStore, configDir, profileFor, readRepoConfig, resolveEndpoint } from "./config.js";
+import { McpClient } from "./mcp/client.js";
+import { ToolCatalog, tokenFingerprint } from "./mcp/catalog.js";
+import { createCredentialStore, ResilientStore } from "./auth/store.js";
+import { TokenProvider } from "./auth/token.js";
+export function createContext(deps) {
+    const env = deps.env ?? process.env;
+    const cwd = deps.cwd ?? process.cwd();
+    const out = new Output({ stdout: deps.stdout, stderr: deps.stderr, color: deps.flags.color, env, quiet: deps.flags.quiet, json: deps.flags.json });
+    const dir = configDir(env);
+    const config = new ConfigStore(dir);
+    const endpoint = resolveEndpoint(deps.flags.url, env, config.read().endpoint);
+    const profile = profileFor(endpoint);
+    const fetchImpl = deps.fetch ?? globalThis.fetch;
+    const now = deps.now ?? (() => new Date());
+    let store;
+    if (deps.store)
+        store = deps.store;
+    else {
+        const { primary, fallback } = createCredentialStore({ configDir: dir, env, platform: deps.platform });
+        store = new ResilientStore(primary, fallback, (t) => out.warn(t));
+    }
+    const tokens = new TokenProvider({ env, store, profile, endpoint, fetch: fetchImpl, now });
+    const debug = deps.flags.debug ? (line) => out.info(out.dim(`[debug] ${line}`)) : undefined;
+    let client = deps.client ?? null;
+    const getClient = () => {
+        if (client)
+            return client;
+        client = new McpClient({ endpoint, tokens, fetch: fetchImpl, clientName: "scribeclock-cli", clientVersion: deps.version, debug });
+        return client;
+    };
+    const catalog = new ToolCatalog({
+        cacheDir: join(dir, "cache"),
+        endpoint,
+        tokenFingerprint: null, // set lazily once the token is known (below)
+        listTools: async () => getClient().listTools(),
+        fetch: fetchImpl,
+        now,
+        warn: (t) => out.warn(t),
+    });
+    const ctx = {
+        flags: deps.flags,
+        out,
+        env,
+        cwd,
+        platform: deps.platform ?? process.platform,
+        now,
+        version: deps.version,
+        endpoint,
+        profile,
+        config,
+        repo: readRepoConfig(cwd),
+        store,
+        tokens,
+        catalog,
+        fetch: fetchImpl,
+        stdin: deps.stdin ?? { isTTY: Boolean(process.stdin.isTTY), stream: process.stdin },
+        registry: deps.registry,
+        client: getClient,
+        org: () => deps.flags.org || ctx.repo.config.org || config.read().default_org || undefined,
+        async tools() {
+            // The cache is per token (tools/list is scope-filtered), so make sure one is known first.
+            if (!deps.client) {
+                const token = await tokens.getToken();
+                if (!token)
+                    throw authError();
+                catalog.setTokenFingerprint(tokenFingerprint(token));
+            }
+            return catalog.load();
+        },
+        async callRaw(tool, args = {}, opts = {}) {
+            const finalArgs = { ...args };
+            for (const k of Object.keys(finalArgs))
+                if (finalArgs[k] === undefined)
+                    delete finalArgs[k];
+            if (!opts.skipOrg && finalArgs.organization_id === undefined) {
+                const org = ctx.org();
+                if (org) {
+                    let takesOrg = true;
+                    try {
+                        const def = (await ctx.tools()).find((t) => t.name === tool);
+                        takesOrg = !def || Boolean(def.inputSchema?.properties?.organization_id);
+                    }
+                    catch {
+                        takesOrg = true;
+                    }
+                    if (takesOrg)
+                        finalArgs.organization_id = org;
+                }
+            }
+            debug?.(`call ${tool} ${JSON.stringify(Object.keys(finalArgs))}`);
+            const outcome = await getClient().callTool(tool, finalArgs);
+            if (!outcome.ok && outcome.error === "insufficient_scope") {
+                const d = outcome.data;
+                throw scopeError(typeof d.required_scope === "string" ? d.required_scope : undefined, Array.isArray(d.granted_scopes) ? d.granted_scopes.map(String) : undefined);
+            }
+            if (!outcome.ok && outcome.error === "invalid_token")
+                throw authError("The token was rejected.", "Run `scribeclock login` again.");
+            return outcome;
+        },
+        async call(tool, args = {}, opts = {}) {
+            const outcome = await ctx.callRaw(tool, args, opts);
+            if (!outcome.ok)
+                throw toolError(tool, outcome);
+            return outcome.data;
+        },
+    };
+    return ctx;
+}
+const CONFLICT_ERRORS = new Set(["already_assigned", "conflict", "overlap", "already_clocked_in", "locked"]);
+export function toolError(tool, outcome) {
+    const code = outcome.error ?? "error";
+    const message = outcome.message ?? "The request failed.";
+    const hint = typeof outcome.data.hint === "string" ? outcome.data.hint : undefined;
+    return new CliError(`${tool}: ${message}`, {
+        id: code,
+        code: CONFLICT_ERRORS.has(code) ? EXIT.CONFLICT : EXIT.ERROR,
+        hint,
+        details: outcome.data,
+    });
+}

package/dist/git.js

@@ -0,0 +1,144 @@
+import { execFileSync } from "node:child_process";
+import { basename } from "node:path";
+export function git(args, cwd) {
+    try {
+        return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 10000 }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function repoRoot(cwd) {
+    return git(["rev-parse", "--show-toplevel"], cwd);
+}
+export function remoteUrl(cwd) {
+    return git(["remote", "get-url", "origin"], cwd);
+}
+/** What the server's repo tools expect: the remote URL, else the folder name. */
+export function repoRef(cwd) {
+    const remote = remoteUrl(cwd);
+    if (remote)
+        return remote;
+    const root = repoRoot(cwd);
+    return root ? basename(root) : null;
+}
+/** owner/repo from a remote URL, when it looks like GitHub. */
+export function githubSlug(remote) {
+    if (!remote)
+        return null;
+    const m = /github\.com[:/]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(remote);
+    return m ? `${m[1]}/${m[2]}` : null;
+}
+export function currentBranch(cwd) {
+    const b = git(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
+    return b && b !== "HEAD" ? b : b;
+}
+export function lastCommit(cwd) {
+    const line = git(["log", "-1", "--format=%H%x1f%s"], cwd);
+    if (!line)
+        return null;
+    const [sha, message] = line.split("\x1f");
+    return { sha, message: message ?? "" };
+}
+/** The `git` object the coordination tools accept. */
+export function gitState(cwd) {
+    const state = {};
+    const porcelain = git(["status", "--porcelain"], cwd);
+    if (porcelain !== null) {
+        const files = [];
+        const conflicts = [];
+        for (const line of porcelain.split("\n")) {
+            if (!line.trim())
+                continue;
+            const code = line.slice(0, 2);
+            const path = line.slice(3).trim().replace(/^.* -> /, "");
+            if (/U|AA|DD/.test(code))
+                conflicts.push(path);
+            files.push(path);
+        }
+        state.uncommitted_files = files.slice(0, 200);
+        state.uncommitted_count = files.length;
+        if (conflicts.length)
+            state.conflicts = conflicts.slice(0, 100);
+    }
+    const counts = git(["rev-list", "--left-right", "--count", "@{u}...HEAD"], cwd);
+    if (counts) {
+        const [behind, ahead] = counts.split(/\s+/).map(Number);
+        state.behind = behind;
+        state.ahead = ahead;
+        state.unpushed_commits = ahead;
+    }
+    const lc = lastCommit(cwd);
+    if (lc)
+        state.last_commit = { sha: lc.sha.slice(0, 40), message: lc.message.slice(0, 300) };
+    return state;
+}
+/** Files touched by uncommitted changes plus the last commit (what a handoff / progress report lists). */
+export function changedFiles(cwd, sinceRef) {
+    const set = new Set();
+    const dirty = git(["status", "--porcelain"], cwd);
+    for (const line of (dirty ?? "").split("\n"))
+        if (line.trim())
+            set.add(line.slice(3).trim().replace(/^.* -> /, ""));
+    const range = sinceRef ? `${sinceRef}..HEAD` : "HEAD~1..HEAD";
+    const committed = git(["diff", "--name-only", range], cwd);
+    for (const f of (committed ?? "").split("\n"))
+        if (f.trim())
+            set.add(f.trim());
+    return [...set].slice(0, 200);
+}
+export function commitsSince(cwd, sinceIso, opts = {}) {
+    const args = ["log", `--since=${sinceIso}`, "--format=%H%x1f%h%x1f%s%x1f%cI", `--max-count=${opts.max ?? 50}`];
+    if (opts.untilIso)
+        args.push(`--until=${opts.untilIso}`);
+    if (opts.author)
+        args.push(`--author=${opts.author}`);
+    const raw = git(args, cwd);
+    if (!raw)
+        return [];
+    return raw
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+        const [sha, short, message, date] = line.split("\x1f");
+        return { sha, short, message, date };
+    });
+}
+export function gitUserEmail(cwd) {
+    return git(["config", "user.email"], cwd);
+}
+export function hooksPath(cwd) {
+    return git(["config", "core.hooksPath"], cwd);
+}
+/** `#123` in a commit message or branch; bare numbers in branch segments (feat/123-thing, task-123, sc-123). */
+export function taskKeyFromText(text) {
+    if (!text)
+        return null;
+    const hash = /(?:^|[^A-Za-z0-9&])#(\d{1,6})(?![0-9])/.exec(text);
+    if (hash)
+        return `#${hash[1]}`;
+    return null;
+}
+export function taskKeyFromBranch(branch) {
+    if (!branch)
+        return null;
+    const direct = taskKeyFromText(branch);
+    if (direct)
+        return direct;
+    const m = /(?:^|[/_-])(?:sc|task|t|issue)?-?(\d{1,6})(?=$|[/_-])/i.exec(branch);
+    return m ? `#${m[1]}` : null;
+}
+/** The task the current work belongs to: branch name first, then the last commit message. */
+export function detectTaskKey(cwd) {
+    const branch = currentBranch(cwd);
+    const fromBranch = taskKeyFromBranch(branch && branch !== "main" && branch !== "master" ? branch : null);
+    if (fromBranch)
+        return { key: fromBranch, source: "branch" };
+    const fromCommit = taskKeyFromText(lastCommit(cwd)?.message);
+    if (fromCommit)
+        return { key: fromCommit, source: "commit" };
+    return null;
+}
+export function tagDate(cwd, ref) {
+    return git(["log", "-1", "--format=%cI", ref], cwd);
+}

package/dist/index.js

@@ -0,0 +1,134 @@
+import { createRequire } from "node:module";
+import { parseGlobals } from "./cli/parser.js";
+import { renderCommandHelp, renderGlobalHelp } from "./cli/registry.js";
+import { CliError, isCliError, usageError } from "./cli/errors.js";
+import { closest } from "./cli/parser.js";
+import { createContext } from "./context.js";
+import { buildRegistry } from "./commands/index.js";
+import { runGeneratedToolCommand } from "./commands/tools.js";
+import { updateNotice } from "./update.js";
+import { EXIT } from "./types.js";
+import { Output } from "./cli/output.js";
+export const VERSION = (() => {
+    try {
+        return createRequire(import.meta.url)("../package.json").version;
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
+/** Entry point. Returns the exit code; never throws. */
+export async function main(argv, deps = {}) {
+    const registry = buildRegistry();
+    let parsed;
+    try {
+        parsed = parseGlobals(argv);
+    }
+    catch (err) {
+        const out = new Output({ stdout: deps.stdout, stderr: deps.stderr, env: deps.env });
+        return reportError(out, false, false, err);
+    }
+    const { flags, rest, passthrough } = parsed;
+    let ctx;
+    try {
+        ctx = createContext({ ...deps, argv, flags, passthrough, version: deps.version ?? VERSION, registry });
+    }
+    catch (err) {
+        const out = new Output({ stdout: deps.stdout, stderr: deps.stderr, env: deps.env, json: flags.json });
+        return reportError(out, flags.json, flags.debug, err);
+    }
+    try {
+        if (flags.version) {
+            if (flags.json)
+                ctx.out.jsonOut({ ok: true, version: ctx.version });
+            else
+                ctx.out.log(`scribeclock ${ctx.version}`);
+            return EXIT.OK;
+        }
+        if (rest.length === 0) {
+            renderGlobalHelp(ctx.out, registry, ctx.version, null);
+            return EXIT.OK;
+        }
+        const resolved = registry.resolve(rest);
+        if (resolved) {
+            if (flags.help && !resolved.command.allowUnknownFlags) {
+                renderCommandHelp(ctx.out, resolved.command);
+                return EXIT.OK;
+            }
+            if (flags.help && resolved.rest.length === 0) {
+                renderCommandHelp(ctx.out, resolved.command);
+                return EXIT.OK;
+            }
+            const inv = registry.invoke(resolved.command, resolved.words, resolved.rest, passthrough);
+            const code = (await resolved.command.run(ctx, inv)) ?? EXIT.OK;
+            updateNotice(ctx);
+            return code;
+        }
+        const word = rest[0];
+        if (word.startsWith("-"))
+            throw usageError(`Unknown option ${word}.`, "Run `scribeclock --help`.");
+        // A group word on its own ("scribeclock tasks") lists its subcommands.
+        const children = registry.children(word);
+        if (children.length && !/_/.test(word)) {
+            ctx.out.log(ctx.out.bold(`scribeclock ${word} <subcommand>`));
+            const w = Math.max(...children.map((c) => c.path.length));
+            for (const c of children)
+                ctx.out.log(`  ${ctx.out.cyan(c.path.padEnd(w))}  ${c.summary}`);
+            return flags.help ? EXIT.OK : EXIT.USAGE;
+        }
+        // Otherwise it may be a server tool, used directly as a command.
+        let code = null;
+        try {
+            code = await runGeneratedToolCommand(ctx, word, rest.slice(1));
+        }
+        catch (err) {
+            if (isCliError(err) && err.code === EXIT.AUTH && !/^[a-z][a-z0-9_-]*$/.test(word))
+                throw usageError(`Unknown command "${word}".`, "Run `scribeclock --help`.");
+            if (isCliError(err) && err.code === EXIT.AUTH) {
+                throw new CliError(`"${word}" is not a built-in command, and server tools need a login to be listed.`, { code: EXIT.AUTH, hint: "Run `scribeclock login` (or set SCRIBECLOCK_TOKEN), then try again. `scribeclock tools` shows the public tool names." });
+            }
+            throw err;
+        }
+        if (code !== null) {
+            updateNotice(ctx);
+            return code;
+        }
+        const candidates = [...registry.list().filter((c) => !c.hidden).map((c) => c.path.split(" ")[0]), ...(await ctx.tools().catch(() => [])).map((t) => t.name)];
+        const near = closest(word, Array.from(new Set(candidates)));
+        throw usageError(`Unknown command "${word}".`, near ? `Did you mean "${near}"? Run \`scribeclock --help\` for the list.` : "Run `scribeclock --help` for the list.");
+    }
+    catch (err) {
+        return reportError(ctx.out, flags.json, flags.debug, err);
+    }
+}
+function reportError(out, json, debug, err) {
+    if (isCliError(err)) {
+        if (json)
+            out.jsonOut({ ok: false, error: err.id, message: err.message, hint: err.hint, exit_code: err.code, details: err.details });
+        else {
+            out.error(err.message);
+            if (err.hint)
+                out.stderr.write(out.dim(indent(err.hint)) + "\n");
+            if (debug && err.details)
+                out.stderr.write(out.dim(JSON.stringify(err.details, null, 2)) + "\n");
+        }
+        return err.code;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    if (json)
+        out.jsonOut({ ok: false, error: "unexpected", message, exit_code: EXIT.ERROR });
+    else {
+        out.error(`Unexpected error: ${message}`);
+        if (debug && err instanceof Error && err.stack)
+            out.stderr.write(out.dim(err.stack) + "\n");
+        else
+            out.stderr.write(out.dim("  Re-run with --debug for the stack trace.") + "\n");
+    }
+    return EXIT.ERROR;
+}
+function indent(text) {
+    return text
+        .split("\n")
+        .map((l) => `  ${l}`)
+        .join("\n");
+}

package/dist/mcp/catalog.js

@@ -0,0 +1,97 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { writeJsonPrivate } from "../config.js";
+import { describeServer } from "./client.js";
+export const CATALOG_TTL_MS = 24 * 60 * 60 * 1000;
+/**
+ * The server's tools/list, cached per endpoint + token so a new MCP tool shows up in the CLI without
+ * a release. `scribeclock refresh` forces a reload; a stale cache is used when the server is down.
+ */
+export class ToolCatalog {
+    opts;
+    memo = null;
+    fingerprint;
+    constructor(opts) {
+        this.opts = opts;
+        this.fingerprint = opts.tokenFingerprint;
+    }
+    /** tools/list is filtered to the token's scopes, so the cache is keyed by (a hash of) the token. */
+    setTokenFingerprint(fp) {
+        if (fp !== this.fingerprint)
+            this.memo = null;
+        this.fingerprint = fp;
+    }
+    get cachePath() {
+        if (!this.fingerprint)
+            return null;
+        const key = createHash("sha256").update(`${this.opts.endpoint}\n${this.fingerprint}`).digest("hex").slice(0, 16);
+        return join(this.opts.cacheDir, `tools-${key}.json`);
+    }
+    readCache() {
+        const path = this.cachePath;
+        if (!path || !existsSync(path))
+            return null;
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            return parsed.version === 1 && Array.isArray(parsed.tools) ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    isFresh(cache) {
+        const now = (this.opts.now ?? (() => new Date()))().getTime();
+        return now - new Date(cache.fetched_at).getTime() < (this.opts.ttlMs ?? CATALOG_TTL_MS);
+    }
+    async load(opts = {}) {
+        if (this.memo && !opts.force)
+            return this.memo;
+        const cache = this.readCache();
+        if (cache && !opts.force && this.isFresh(cache)) {
+            this.memo = cache.tools;
+            return cache.tools;
+        }
+        try {
+            const tools = await this.opts.listTools();
+            this.memo = tools;
+            const path = this.cachePath;
+            if (path)
+                writeJsonPrivate(path, { version: 1, endpoint: this.opts.endpoint, fetched_at: (this.opts.now ?? (() => new Date()))().toISOString(), tools });
+            return tools;
+        }
+        catch (err) {
+            if (cache) {
+                this.opts.warn?.(`Using the cached tool list from ${cache.fetched_at} (could not refresh: ${err instanceof Error ? err.message : String(err)}).`);
+                this.memo = cache.tools;
+                return cache.tools;
+            }
+            throw err;
+        }
+    }
+    /** Tool names from the public server description — works before login (no schemas). */
+    async namesOnly() {
+        const described = await describeServer(this.opts.endpoint, this.opts.fetch);
+        return Array.isArray(described.tools) ? described.tools.map(String) : [];
+    }
+    /** Remove every cached catalog for this endpoint (logout). */
+    clearAll() {
+        if (!existsSync(this.opts.cacheDir))
+            return;
+        for (const f of readdirSync(this.opts.cacheDir)) {
+            if (!f.startsWith("tools-") || !f.endsWith(".json"))
+                continue;
+            try {
+                const parsed = JSON.parse(readFileSync(join(this.opts.cacheDir, f), "utf8"));
+                if (parsed.endpoint === this.opts.endpoint)
+                    unlinkSync(join(this.opts.cacheDir, f));
+            }
+            catch {
+                /* ignore unreadable cache files */
+            }
+        }
+    }
+}
+export function tokenFingerprint(token) {
+    return token ? createHash("sha256").update(token).digest("hex").slice(0, 24) : null;
+}

package/dist/mcp/client.js

@@ -0,0 +1,164 @@
+import { CliError, authError, scopeError, usageError } from "../cli/errors.js";
+export const PROTOCOL_VERSION = "2025-06-18";
+/** Stateless MCP Streamable-HTTP client: one POST per JSON-RPC request, bearer token on each. */
+export class McpClient {
+    endpoint;
+    tokens;
+    fetchImpl;
+    clientName;
+    clientVersion;
+    debug;
+    nextId = 1;
+    constructor(opts) {
+        this.endpoint = opts.endpoint;
+        this.tokens = opts.tokens;
+        this.fetchImpl = opts.fetch ?? globalThis.fetch;
+        this.clientName = opts.clientName ?? "scribeclock-cli";
+        this.clientVersion = opts.clientVersion ?? "0.0.0";
+        this.debug = opts.debug;
+    }
+    async post(token, body) {
+        const started = Date.now();
+        let res;
+        try {
+            res = await this.fetchImpl(this.endpoint, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    accept: "application/json, text/event-stream",
+                    "mcp-protocol-version": PROTOCOL_VERSION,
+                    authorization: `Bearer ${token}`,
+                    "user-agent": `${this.clientName}/${this.clientVersion}`,
+                },
+                body: JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            const cause = err instanceof Error ? err.cause?.message ?? err.message : String(err);
+            throw new CliError(`Could not reach ${this.endpoint} (${cause}).`, {
+                id: "network",
+                hint: "Check your network connection. If you meant another server, set SCRIBECLOCK_URL or pass --url.",
+            });
+        }
+        this.debug?.(`${body.method} → ${res.status} in ${Date.now() - started}ms`);
+        return res;
+    }
+    async rpc(method, params = {}) {
+        let token = await this.tokens.getToken();
+        if (!token)
+            throw authError();
+        const body = { jsonrpc: "2.0", id: this.nextId++, method, params };
+        let res = await this.post(token, body);
+        if (res.status === 401) {
+            const refreshed = await this.tokens.refresh();
+            if (!refreshed) {
+                throw authError("Your ScribeClock session is no longer valid (the token was rejected).", "Run `scribeclock login` again. If you use SCRIBECLOCK_TOKEN, create a new personal access token.");
+            }
+            token = refreshed;
+            res = await this.post(token, body);
+            if (res.status === 401)
+                throw authError("The server rejected the token even after refreshing it.", "Run `scribeclock logout` and then `scribeclock login`.");
+        }
+        if (res.status === 429) {
+            const retry = Math.min(5, Number(res.headers.get("retry-after") ?? "2") || 2);
+            await new Promise((r) => setTimeout(r, retry * 1000));
+            res = await this.post(token, body);
+        }
+        if (res.status === 202)
+            return undefined;
+        const text = await res.text();
+        let parsed = null;
+        try {
+            parsed = text ? JSON.parse(text) : null;
+        }
+        catch {
+            parsed = null;
+        }
+        if (res.status >= 400 || !parsed) {
+            const detail = parsed && !Array.isArray(parsed) && parsed.error ? parsed.error.message : text.slice(0, 200);
+            throw new CliError(`ScribeClock answered ${res.status}${detail ? `: ${detail}` : ""}.`, {
+                id: "server_error",
+                hint: res.status >= 500 ? "The server had a problem. Try again in a moment; `scribeclock doctor` checks reachability." : undefined,
+            });
+        }
+        const msg = Array.isArray(parsed) ? parsed[0] : parsed;
+        if (msg.error) {
+            const { code, message } = msg.error;
+            if (code === -32602)
+                throw usageError(message);
+            if (code === -32601)
+                throw new CliError(`The server does not support ${method}: ${message}`, { id: "method_not_found" });
+            throw new CliError(message, { id: "rpc_error", details: { code } });
+        }
+        return msg.result;
+    }
+    async initialize() {
+        return await this.rpc("initialize", {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: this.clientName, version: this.clientVersion },
+        });
+    }
+    async listTools() {
+        const result = await this.rpc("tools/list");
+        return Array.isArray(result?.tools) ? result.tools : [];
+    }
+    async callTool(name, args) {
+        const result = await this.rpc("tools/call", { name, arguments: args });
+        const outcome = parseToolResult(result);
+        if (!outcome.ok) {
+            if (outcome.error === "insufficient_scope") {
+                const d = outcome.data;
+                throw scopeError(typeof d.required_scope === "string" ? d.required_scope : undefined, Array.isArray(d.granted_scopes) ? d.granted_scopes.map(String) : undefined);
+            }
+            if (outcome.error === "invalid_token")
+                throw authError("The token was rejected.", "Run `scribeclock login` again.");
+        }
+        return outcome;
+    }
+}
+/** structuredContent wins; otherwise the first text block is parsed as JSON; otherwise the text itself. */
+export function parseToolResult(result) {
+    const content = Array.isArray(result?.content) ? result.content : [];
+    let data = result?.structuredContent && typeof result.structuredContent === "object" ? result.structuredContent : null;
+    if (!data) {
+        const text = content.find((c) => c.type === "text")?.text;
+        if (text) {
+            try {
+                const parsed = JSON.parse(text);
+                data = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : { value: parsed };
+            }
+            catch {
+                const m = /^Error \(([a-z_]+)\): (.*)$/s.exec(text);
+                data = m ? { ok: false, error: m[1], message: m[2] } : { text };
+            }
+        }
+        else {
+            data = {};
+        }
+    }
+    const isError = result?.isError === true || data.ok === false;
+    return {
+        ok: !isError,
+        data,
+        content,
+        error: isError ? (typeof data.error === "string" ? data.error : "error") : undefined,
+        message: isError ? (typeof data.message === "string" ? data.message : "The request failed.") : undefined,
+    };
+}
+/** `GET <endpoint>` — the server's self-description (tool names, connect snippets). No auth. */
+export async function describeServer(endpoint, fetchImpl = globalThis.fetch) {
+    let res;
+    try {
+        res = await fetchImpl(endpoint, { headers: { accept: "application/json" } });
+    }
+    catch (err) {
+        throw new CliError(`Could not reach ${endpoint} (${err instanceof Error ? err.message : String(err)}).`, { id: "network" });
+    }
+    if (!res.ok)
+        throw new CliError(`${endpoint} answered ${res.status}.`, { id: "server_error" });
+    const json = (await res.json());
+    if (json.transport !== "streamable-http")
+        throw new CliError(`${endpoint} does not look like a ScribeClock MCP server.`, { id: "not_mcp" });
+    return json;
+}