@flow-engineer/flow 0.2.0 → 0.2.2

package/coding-agents/tools-skill.md

@@ -6,7 +6,9 @@ description: Write or change a Flow Framework agent's tools and their test files
 # Writing tools for a Flow Framework agent
 
 Read the `flow-framework` skill (`skill.md`) first if you haven't. Tests that use these tool files are
-in the `flow-framework-tests` skill (`test-skill.md`).
+in the `flow-framework-tests` skill (`test-skill.md`). For a company with an existing app or API, build
+the context pack first (the `flow-framework-context` skill, `context-skill.md`) and write the tools from
+it.
 
 ## The tool
 
@@ -49,6 +51,77 @@ export const findSlots = tool({
   searched ("Mon Oct 12 through Sun Oct 18", "all open times") and never cut results short
   silently. If there are more, say so.
 
+## Tools from the context pack
+
+- One tool per task in `context/workflows.arazzo.yaml`, never one per endpoint: "place an order"
+  is one tool even when it is three API calls. A host or a small model chooses well among a few
+  task-shaped tools and badly among dozens of raw ones.
+- Take the input and output shapes from `context/openapi.yaml` with `context/overlay.yaml` applied,
+  the words and rules from `business.md`, and leave out the personal fields `data.md` marks unless
+  the task needs them.
+- `signIn` and `hints` come from `context/access.yaml` (below).
+- When the team sends a new spec, re-read the overlay and the workflows against it, change only the
+  tools whose operations changed, and run `flow check` and the tests.
+
+## The fields MCP and the CLI read
+
+The same tool is served to Claude and ChatGPT over MCP (`@flow-engineer/flow/mcp`) and as a command (`@flow-engineer/flow/cli`).
+These optional fields describe it there. **Chat ignores all of them**: they change nothing on
+WhatsApp, SMS or iMessage.
+
+```ts
+export const placeOrder = tool({
+  name: "place_order",
+  title: "Place an order",                         // default: "Place order", from the name
+  description: "Place a confirmed pickup order. Returns the order number and when it will be ready.",
+  input: z.object({ name: z.string(), items: z.array(item) }),
+  output: z.object({ order_id: z.string(), ready_by: z.string() }),  // the result's shape
+  status: { running: "Placing your order…", done: "Order placed" },  // at most 64 characters each
+  signIn: "required",                              // "required" (default) | "optional" | "none"
+  hints: { readOnly: false, destructive: false, idempotent: false, openWorld: false },
+  run: async (input, context) => pos.place(input, context.idempotencyKey),
+});
+```
+
+- `output`: over MCP the result is checked against it and sent as structured content, and the CLI
+  shows its fields with `--json` and `--fields`. Give it whenever the result has a fixed shape.
+- `signIn`: "none" for what anyone may do signed out (the menu, opening hours), "optional" for what
+  works either way and does more signed in, "required" (the default) for everything about a
+  person's own account. It applies only where sign-in is set up (the `flow-framework-auth` skill).
+- `hints` describe the tool to hosts, which ask the person before risky calls; nothing enforces
+  them. `readOnly` (default false: a tool counts as a write), `destructive` (a write that may delete
+  or overwrite; default true for writes), `idempotent` (calling again with the same input changes
+  nothing more; default false), `openWorld` (reaches outside the business's own systems, such as the
+  web; default true). Set them honestly: a read-only tool should say so, or hosts treat it as a
+  write and the CLI asks for `--yes`.
+- `flow check` (from the agent's folder) refuses what cannot be served exactly: a name outside
+  1 to 128 of `A-Z a-z 0-9 _ - .`, an empty description, a description naming a chat-only tool
+  (`send_*`, `share_updates`, `load_skill`), an input that is not a `z.object`, an input or output
+  with no exact JSON Schema (`z.date()`, transforms; use an ISO string), `readOnly` with
+  `destructive`, or a status line over 64 characters.
+
+## Tools from another MCP server
+
+An existing MCP server's tools become the agent's own, so the agent uses them on WhatsApp or
+iMessage like any tool:
+
+```ts
+import { mcpTools } from "@flow-engineer/flow/mcp";
+
+export const tools = [
+  ...myTools,
+  ...(await mcpTools({ name: "todoist", url: "https://ai.todoist.net/mcp", headers: { authorization: `Bearer ${process.env.TODOIST_KEY}` } })),
+];
+```
+
+- They are pinned: `flow mcp update` (from the agent's folder) writes the server's tools to
+  `mcp.lock.json`, and only those are used. Commit it with the tests. A tool the server changes or
+  removes later is refused with a clear error until the lock is updated, tested and committed; a
+  tool it adds is not offered until then. `only: [...]` keeps a few of its tools, `prefix` keeps
+  two servers' names apart, and `live: true` skips the lock (for a server you do not build around).
+- Each needs a `tests/tools/<tool>.yaml` like any tool. A tool without `readOnlyHint` counts as a
+  write. Keep keys in the environment, never in the lock.
+
 ## The tool's test file
 
 In tests no real tool runs: a model plays each tool from the scenario's world. `tests/tools/<tool>.yaml`
@@ -87,3 +160,7 @@ responses:
   never as written dates, which go stale.
 - Latency lives only here. Scenarios describe situations ("the point of sale is slow this
   morning"); the simulator picks the matching response and latency on each call.
+
+## Authenticated backend access
+
+A tool can use `await context.credentials!.get<YourClient>("backend")` when the agent/server supplies a `credentials` provider. That provider resolves access from Flow Framework’s verified `context.key`/`context.person`, independently of model input. Share it between chat and MCP; never put credentials into tool schemas, outputs, errors or logs. See `auth-skill.md` for verified-phone and OAuth entry points.

package/dist/cli/src/auth.d.ts

@@ -0,0 +1,11 @@
+import { type OAuthClientProvider } from "@modelcontextprotocol/client";
+import type { CliConfig } from "./commands.ts";
+export declare function configDir(config: CliConfig): string;
+/** An OAuth client provider whose state lives in the CLI's auth file, for one server. */
+export declare function storedProvider(config: CliConfig, server: string, redirectUrl?: string, signal?: AbortSignal): OAuthClientProvider;
+/** Terminal HTTP uses the same stored OAuth session as MCP, including refresh and issuer binding. */
+export declare function storedAccessToken(config: CliConfig, server: string, forceRefresh?: boolean, signal?: AbortSignal): Promise<string | undefined>;
+export declare function isSignedIn(config: CliConfig, server: string): boolean;
+export declare function signOut(config: CliConfig, server: string): void;
+/** Sign in: the browser goes to the organization's own login, and comes back to a loopback port. */
+export declare function signIn(config: CliConfig, server: string, signal?: AbortSignal): Promise<void>;

package/dist/cli/src/auth.js

@@ -0,0 +1,147 @@
+// The CLI's sign-in: the same OAuth a host such as Claude runs against the organization's MCP
+// server, as a native app with a loopback redirect, so people sign in on the organization's own
+// pages. Tokens are kept per server in ~/.config/<name>/auth.json (XDG_CONFIG_HOME), mode 600, and
+// refreshed by the SDK. A token in <NAME>_TOKEN (CI, agents) is used as is and never stored.
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { auth, discoverOAuthServerInfo, refreshAuthorization, } from "@modelcontextprotocol/client";
+export function configDir(config) {
+    return config.directory ?? join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), config.name);
+}
+function authFile(config) {
+    return join(configDir(config), "auth.json");
+}
+function readAll(config) {
+    const file = authFile(config);
+    return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+}
+function writeAll(config, all) {
+    mkdirSync(configDir(config), { recursive: true, mode: 0o700 });
+    const file = authFile(config);
+    writeFileSync(file, JSON.stringify(all, null, 2) + "\n", { mode: 0o600 });
+    chmodSync(file, 0o600);
+}
+/** An OAuth client provider whose state lives in the CLI's auth file, for one server. */
+export function storedProvider(config, server, redirectUrl, signal) {
+    const read = () => readAll(config)[server] ?? {};
+    const write = (change) => {
+        signal?.throwIfAborted();
+        const all = readAll(config);
+        all[server] = { ...all[server], ...change };
+        writeAll(config, all);
+    };
+    const metadata = {
+        client_name: `${config.name} CLI`,
+        application_type: "native",
+        redirect_uris: redirectUrl ? [redirectUrl] : [],
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        token_endpoint_auth_method: "none",
+    };
+    return {
+        get redirectUrl() {
+            return redirectUrl;
+        },
+        get clientMetadata() {
+            return metadata;
+        },
+        ...(config.clientMetadataUrl ? { clientMetadataUrl: config.clientMetadataUrl } : {}),
+        clientInformation: () => config.clientId ? { client_id: config.clientId } : read().client,
+        saveClientInformation: (client) => write({ client }),
+        tokens: () => read().tokens,
+        saveTokens: (tokens) => write({ tokens, tokensSavedAt: Date.now() }),
+        state: () => { const state = randomBytes(32).toString("base64url"); write({ state }); return state; },
+        discoveryState: () => read().discovery,
+        saveDiscoveryState: (discovery) => write({ discovery }),
+        redirectToAuthorization: async (url) => {
+            if (config.openUrl)
+                await config.openUrl(url.toString());
+            else
+                console.error(`Open this link to sign in:\n  ${url}`);
+        },
+        saveCodeVerifier: (verifier) => write({ verifier }),
+        codeVerifier: () => {
+            const verifier = read().verifier;
+            if (!verifier)
+                throw new Error("No sign-in in progress.");
+            return verifier;
+        },
+    };
+}
+/** Terminal HTTP uses the same stored OAuth session as MCP, including refresh and issuer binding. */
+export async function storedAccessToken(config, server, forceRefresh = false, signal) {
+    signal?.throwIfAborted();
+    const saved = readAll(config)[server];
+    if (!saved?.tokens)
+        return undefined;
+    const { tokens } = saved;
+    const expired = saved.tokensSavedAt !== undefined && tokens.expires_in !== undefined && saved.tokensSavedAt + tokens.expires_in * 1000 <= Date.now() + 30_000;
+    if (!expired && !forceRefresh)
+        return tokens.access_token;
+    if (!tokens.refresh_token || (!saved.client && !config.clientId))
+        return undefined;
+    const info = await discoverOAuthServerInfo(server);
+    const issuer = info.authorizationServerMetadata?.issuer ?? String(info.authorizationServerUrl);
+    if (tokens.issuer && tokens.issuer !== issuer)
+        throw new Error("The authorization server changed; sign in again.");
+    const fresh = await refreshAuthorization(info.authorizationServerUrl, { metadata: info.authorizationServerMetadata, clientInformation: config.clientId ? { client_id: config.clientId } : saved.client, refreshToken: tokens.refresh_token, resource: info.resourceMetadata?.resource });
+    await storedProvider(config, server, undefined, signal).saveTokens({ ...fresh, issuer });
+    return fresh.access_token;
+}
+export function isSignedIn(config, server) {
+    return Boolean(readAll(config)[server]?.tokens);
+}
+export function signOut(config, server) {
+    const all = readAll(config);
+    delete all[server];
+    writeAll(config, all);
+}
+/** Sign in: the browser goes to the organization's own login, and comes back to a loopback port. */
+export async function signIn(config, server, signal) {
+    signal?.throwIfAborted();
+    const callback = createServer();
+    await new Promise((resolve, reject) => { callback.once("error", reject); callback.listen(config.redirectPort ?? 0, "127.0.0.1", resolve); });
+    const { port } = callback.address();
+    const redirectUrl = `http://127.0.0.1:${port}/callback`;
+    let cancel;
+    try {
+        const provider = storedProvider(config, server, redirectUrl, signal);
+        const code = new Promise((resolve, reject) => {
+            cancel = () => reject(new Error("Sign-in cancelled."));
+            signal?.addEventListener("abort", cancel, { once: true });
+            if (signal?.aborted)
+                cancel();
+            callback.on("request", (req, res) => {
+                const url = new URL(req.url ?? "/", redirectUrl);
+                if (url.pathname !== "/callback")
+                    return void res.writeHead(404).end();
+                const error = url.searchParams.get("error");
+                const got = url.searchParams.get("code");
+                if (req.method !== "GET" || req.headers.host !== `127.0.0.1:${port}` || !readAll(config)[server]?.state || url.searchParams.get("state") !== readAll(config)[server]?.state) {
+                    res.writeHead(400, { "content-type": "text/plain" }).end("Invalid sign-in response.");
+                    return;
+                }
+                res.writeHead(200, { "content-type": "text/plain; charset=utf-8" }).end(got ? `Signed in. You can close this tab and go back to ${config.name}.` : `Sign-in failed: ${error ?? "no code"}.`);
+                if (got)
+                    resolve({ code: got, iss: url.searchParams.get("iss") ?? undefined });
+                else
+                    reject(new Error(`Sign-in failed: ${error ?? "no code came back"}.`));
+            });
+        });
+        // Cancellation may arrive while discovery or the authorization request is still in flight.
+        void code.catch(() => { });
+        const first = await auth(provider, { serverUrl: server });
+        if (first === "AUTHORIZED")
+            return;
+        const answer = await code;
+        await auth(provider, { serverUrl: server, authorizationCode: answer.code, iss: answer.iss });
+    }
+    finally {
+        if (cancel)
+            signal?.removeEventListener("abort", cancel);
+        callback.close();
+    }
+}

package/dist/cli/src/commands.d.ts

@@ -0,0 +1,119 @@
+import type { Command as StricliCommand, CommandContext } from "@stricli/core";
+export interface ToolCommand {
+    /** The tool this command calls. */
+    tool: string;
+    /** Input fields taken from positional arguments, in order (`order view 1042` → orderId). */
+    args?: string[];
+    /** For a list: the columns of the table people see. */
+    columns?: string[];
+    /** For one record: the fields people see, in order. */
+    view?: string[];
+    /** Another name for the command. */
+    alias?: string;
+    /** One line under the command in help (default: the tool's title). */
+    summary?: string;
+    examples?: string[];
+}
+/** What a command of the team's own gets as `this` (Stricli's context): the server's tools and the CLI's output. */
+export interface CliContext extends CommandContext {
+    readonly cli: {
+        /** Call one of the server's tools; resolves with its result, throws its error. */
+        call(tool: string, input: Record<string, unknown>): Promise<unknown>;
+        /** Print a value as the CLI prints tool results (a table, fields, or JSON with --json). */
+        print(value: unknown, options?: {
+            json?: boolean;
+            fields?: string[];
+            columns?: string[];
+        }): void;
+    };
+}
+/** A command of the team's own: any Stricli command (buildCommand from @stricli/core), one level down. */
+export interface CustomCommand {
+    command: StricliCommand<CliContext>;
+}
+export type CommandConfig = ToolCommand | CustomCommand;
+export interface CliConfig {
+    /** The command's name ("acme"): its help, its config folder (~/.config/<name>) and token variable. */
+    name: string;
+    /** The CLI client version sent to the server (default "1"). */
+    version?: string;
+    /** The organization's MCP endpoint. Else `--server` or <NAME>_SERVER. */
+    server?: string;
+    /** The agent terminal URL; default the server origin plus /agent/terminal. */
+    agent?: string;
+    /** The variable a token is read from for CI and agents (default <NAME>_TOKEN). */
+    tokenEnv?: string;
+    /** Override the local credential/conversation directory, e.g. for an isolated embedded session. */
+    directory?: string;
+    description?: string;
+    /** Commands by their words ("order place"): the first words are groups. Tools no command names keep their own name. */
+    commands?: Record<string, CommandConfig>;
+    /** One line about each group, shown in help ("order": "Place and track orders"). Default: its subcommands. */
+    groups?: Record<string, string>;
+    /** A Client ID Metadata Document URL for sign-in; without it the CLI registers itself (DCR). */
+    clientMetadataUrl?: string;
+    /** A registered public OAuth client, for providers without dynamic registration. No client secret in a distributed CLI. */
+    clientId?: string;
+    /** A provider requiring an exact registered loopback port can fix it here; default chooses a free port. */
+    redirectPort?: number;
+    /** How a sign-in link is opened (default: printed for the person to open). */
+    openUrl?: (url: string) => void | Promise<void>;
+}
+/** What the CLI knows of a tool, from the server's tools/list. */
+export interface ToolInfo {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema: {
+        properties?: Record<string, JsonSchema>;
+        required?: string[];
+        [key: string]: unknown;
+    };
+    outputSchema?: JsonSchema;
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+    };
+}
+export interface JsonSchema {
+    type?: string | string[];
+    enum?: unknown[];
+    items?: JsonSchema;
+    properties?: Record<string, JsonSchema>;
+    description?: string;
+    [key: string]: unknown;
+}
+export interface Command {
+    words: string[];
+    summary: string;
+    tool?: ToolInfo;
+    config?: CommandConfig;
+}
+export declare function defineCli(config: CliConfig): CliConfig;
+export declare function isCustom(config: CommandConfig): config is CustomCommand;
+/** Words the CLI keeps for itself. */
+export declare const BUILT_IN: Set<string>;
+/** "place_order" → "place-order". */
+export declare function derivedName(tool: string): string;
+/** Every command: the CLI file's, then each tool it does not name, under the tool's own name. */
+export declare function commandTable(config: CliConfig, tools: ToolInfo[]): Command[];
+/** The command the words start with, the longest match first, and the words left after it. */
+export declare function findCommand(commands: Command[], words: string[]): {
+    command: Command;
+    rest: string[];
+} | null;
+/** What is wrong in a CLI file against the server's tools, one sentence each; warnings apart. */
+export declare function cliProblems(config: CliConfig, tools: ToolInfo[]): {
+    errors: string[];
+    warnings: string[];
+};
+/** The CLI's SKILL.md for coding agents, made from the tools and the CLI file, never written by hand. */
+export declare function skillFile(config: CliConfig, tools: ToolInfo[]): string;
+export declare function tokenEnvOf(config: CliConfig): string;
+export declare function flagName(field: string): string;
+/** One line per flag: its name, type and what it is for. */
+export declare function flagList(tool: ToolInfo, args?: string[]): string[];
+/** A short picture of a JSON value's shape: "list of {item, size, milk?, quantity?}". */
+export declare function typeHint(s: JsonSchema): string;
+export type FlagKind = "string" | "number" | "integer" | "boolean" | "list" | "json";
+export declare function flagKind(s: JsonSchema): FlagKind;

package/dist/cli/src/commands.js

@@ -0,0 +1,212 @@
+// An organization's CLI commands: every tool of its MCP server is a command under its own name
+// (place_order → `place-order`), and the CLI file the team's coding agent writes (defineCli) adds
+// what needs judgement: command groups and verbs (`order place`, where `order` is a group whose
+// help lists its subcommands), the positional arguments, a table's columns, examples, aliases, and
+// commands of its own. cliProblems is the rule-based check that keeps that file true to the tools;
+// it never judges taste.
+export function defineCli(config) {
+    return config;
+}
+export function isCustom(config) {
+    return config.command !== undefined;
+}
+/** The MCP server's own way to read its skills: plumbing for hosts, not a command, unless the CLI file names it. */
+const HOST_ONLY = new Set(["read_skill"]);
+/** Words the CLI keeps for itself. */
+export const BUILT_IN = new Set(["auth", "tools", "skill"]);
+/** "place_order" → "place-order". */
+export function derivedName(tool) {
+    return tool.replace(/_/g, "-");
+}
+/** Every command: the CLI file's, then each tool it does not name, under the tool's own name. */
+export function commandTable(config, tools) {
+    const byName = new Map(tools.map((t) => [t.name, t]));
+    const commands = [];
+    const named = new Set();
+    for (const [words, c] of Object.entries(config.commands ?? {})) {
+        const split = words.trim().split(/\s+/);
+        if (isCustom(c)) {
+            commands.push({ words: split, summary: "", config: c });
+            continue;
+        }
+        const tool = byName.get(c.tool);
+        if (!tool)
+            continue;
+        named.add(c.tool);
+        commands.push({ words: split, summary: c.summary ?? tool.title ?? tool.name, tool, config: c });
+        if (c.alias)
+            commands.push({ words: c.alias.trim().split(/\s+/), summary: `Same as ${words}`, tool, config: c });
+    }
+    for (const tool of tools) {
+        if (!named.has(tool.name) && !HOST_ONLY.has(tool.name))
+            commands.push({ words: [derivedName(tool.name)], summary: tool.title ?? tool.name, tool });
+    }
+    return commands;
+}
+/** The command the words start with, the longest match first, and the words left after it. */
+export function findCommand(commands, words) {
+    let best = null;
+    for (const c of commands) {
+        if (c.words.length <= words.length && c.words.every((w, i) => w === words[i]) && (!best || c.words.length > best.words.length))
+            best = c;
+    }
+    return best ? { command: best, rest: words.slice(best.words.length) } : null;
+}
+/** Fields a list's rows or a record carry: the output schema's, or for an array, its items'. */
+function outputFields(tool) {
+    const schema = tool.outputSchema;
+    if (!schema)
+        return null;
+    const props = schema.properties ?? schema.items?.properties;
+    if (!props)
+        return null;
+    const fields = new Set(Object.keys(props));
+    // A list wrapped in an object ({ orders: [...] }) shows its rows' fields too.
+    for (const p of Object.values(props))
+        for (const k of Object.keys(p.items?.properties ?? {}))
+            fields.add(k);
+    return fields;
+}
+/** What is wrong in a CLI file against the server's tools, one sentence each; warnings apart. */
+export function cliProblems(config, tools) {
+    const errors = [];
+    const warnings = [];
+    const byName = new Map(tools.map((t) => [t.name, t]));
+    const words = new Map();
+    const claim = (w, owner) => {
+        const key = w.trim().split(/\s+/).join(" ");
+        if (words.has(key))
+            errors.push(`command "${key}": both ${words.get(key)} and ${owner} use it`);
+        else
+            words.set(key, owner);
+    };
+    const named = new Set();
+    for (const [w, c] of Object.entries(config.commands ?? {})) {
+        claim(w, `"${w}"`);
+        if (isCustom(c))
+            continue;
+        if (c.alias)
+            claim(c.alias, `the alias of "${w}"`);
+        const tool = byName.get(c.tool);
+        if (!tool) {
+            errors.push(`command "${w}": no tool named ${c.tool} on the server`);
+            continue;
+        }
+        named.add(c.tool);
+        const input = new Set(Object.keys(tool.inputSchema.properties ?? {}));
+        for (const a of c.args ?? [])
+            if (!input.has(a))
+                errors.push(`command "${w}": args names ${a}, which ${c.tool}'s input does not have`);
+        const output = outputFields(tool);
+        for (const key of ["columns", "view"]) {
+            for (const f of c[key] ?? []) {
+                if (!output)
+                    warnings.push(`command "${w}": ${key} names ${f}, but ${c.tool} declares no output to check it against`);
+                else if (!output.has(f.split(".")[0]))
+                    errors.push(`command "${w}": ${key} names ${f}, which ${c.tool}'s output does not have`);
+            }
+        }
+    }
+    for (const t of tools) {
+        if (named.has(t.name) || HOST_ONLY.has(t.name))
+            continue;
+        claim(derivedName(t.name), `tool ${t.name}`);
+        if (config.commands)
+            warnings.push(`tool ${t.name} has no command in the CLI file; it is reachable as "${derivedName(t.name)}"`);
+    }
+    for (const [key, owner] of words) {
+        const first = key.split(" ")[0];
+        if (BUILT_IN.has(first))
+            errors.push(`command "${key}": ${first} is the CLI's own (${[...BUILT_IN].join(", ")})`);
+        for (const other of words.keys()) {
+            if (other !== key && other.startsWith(`${key} `))
+                errors.push(`command "${key}" (${owner}): it is also the group of "${other}"; a word is a command or a group, not both`);
+        }
+    }
+    return { errors, warnings };
+}
+/** The CLI's SKILL.md for coding agents, made from the tools and the CLI file, never written by hand. */
+export function skillFile(config, tools) {
+    const name = config.name;
+    const lines = [
+        "---",
+        `name: ${name}-cli`,
+        `description: Use the ${name} command line${config.description ? ` (${config.description})` : ""}. Load before running ${name} commands or when asked to do something in ${name} from a terminal.`,
+        "---",
+        "",
+        `# The ${name} command line`,
+        "",
+        `Run \`${name} <command> --json\` and read the JSON; never parse the human output. \`--fields a,b\` keeps only those fields.`,
+        "Commands that change things accept `--dry-run` (shows the call, sends nothing) and, when they may delete or overwrite, need `--yes` without a terminal.",
+        `Sign in once with \`${name} auth login\`, or set ${tokenEnvOf(config)} in CI.`,
+        "",
+        "Exit codes: 0 done, 1 the tool failed (its message on stderr), 2 wrong command or arguments, 3 sign-in needed, 4 needs --yes, 5 the server could not be reached.",
+        "",
+        "## Talking to the agent",
+        "",
+        `\`${name} chat "<message>" --json\` sends one message to the agent; \`${name} chat\` opens an interactive loop (Ctrl-D or /exit to leave). Both need sign-in.`,
+        "The CLI keeps its conversation reference in chat.json in its config folder; --new forgets that reference and preserves shared person history. chat without a message needs a terminal (otherwise exits 2).",
+        "",
+        "## Commands",
+    ];
+    for (const c of commandTable(config, tools)) {
+        if (!c.tool)
+            continue;
+        lines.push("", `### ${name} ${c.words.join(" ")}`, "", c.summary);
+        if (c.tool) {
+            if (c.tool.description && c.tool.description !== c.summary)
+                lines.push("", c.tool.description);
+            const args = c.config && !isCustom(c.config) ? (c.config.args ?? []) : [];
+            const flags = flagList(c.tool, args);
+            if (args.length || flags.length)
+                lines.push("", `Usage: \`${name} ${c.words.join(" ")}${args.map((a) => ` <${a}>`).join("")}${flags.length ? " [flags]" : ""}\``);
+            for (const f of flags)
+                lines.push(`- ${f}`);
+            if (c.tool.annotations?.readOnlyHint !== true)
+                lines.push(`- Changes things${c.tool.annotations?.destructiveHint === false ? "" : " and may delete or overwrite: needs --yes"}.`);
+            if (c.tool.outputSchema)
+                lines.push("", "JSON output schema:", "", "```json", JSON.stringify(c.tool.outputSchema), "```");
+        }
+        for (const e of c.config && !isCustom(c.config) ? (c.config.examples ?? []) : [])
+            lines.push("", "```bash", e, "```");
+    }
+    return lines.join("\n") + "\n";
+}
+export function tokenEnvOf(config) {
+    return config.tokenEnv ?? `${config.name.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_TOKEN`;
+}
+export function flagName(field) {
+    return field.replace(/_/g, "-").replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/** One line per flag: its name, type and what it is for. */
+export function flagList(tool, args = []) {
+    const required = new Set(tool.inputSchema.required ?? []);
+    return Object.entries(tool.inputSchema.properties ?? {})
+        .filter(([field]) => !args.includes(field))
+        .map(([field, s]) => {
+        const kind = s.enum ? s.enum.join("|") : flagKind(s) === "json" ? `JSON: ${typeHint(s)} (or @file.json)` : flagKind(s);
+        return `\`--${flagName(field)}\` ${kind}${required.has(field) ? ", required" : ""}${s.description ? `: ${s.description}` : ""}`;
+    });
+}
+/** A short picture of a JSON value's shape: "list of {item, size, milk?, quantity?}". */
+export function typeHint(s) {
+    const type = Array.isArray(s.type) ? s.type.find((t) => t !== "null") : s.type;
+    if (type === "array")
+        return `list of ${s.items ? typeHint(s.items) : "values"}`;
+    if (type === "object" || s.properties) {
+        const required = new Set(s.required ?? []);
+        const keys = Object.keys(s.properties ?? {}).map((k) => (required.has(k) ? k : `${k}?`));
+        return keys.length ? `{${keys.join(", ")}}` : "object";
+    }
+    return s.enum ? s.enum.join("|") : (type ?? "value");
+}
+export function flagKind(s) {
+    const type = Array.isArray(s.type) ? s.type.find((t) => t !== "null") : s.type;
+    if (type === "array") {
+        const item = Array.isArray(s.items?.type) ? s.items?.type[0] : s.items?.type;
+        return item === "string" || item === "number" || item === "integer" ? "list" : "json";
+    }
+    if (type === "number" || type === "integer" || type === "boolean" || type === "string")
+        return type;
+    return s.enum ? "string" : "json";
+}

package/dist/cli/src/index.d.ts

@@ -0,0 +1,2 @@
+export { cliProblems, commandTable, defineCli, derivedName, skillFile, type CliConfig, type CliContext, type CommandConfig, type CustomCommand, type ToolCommand, type ToolInfo } from "./commands.ts";
+export { EXIT, processIO, runCli, type CliIO } from "./run.ts";

package/dist/cli/src/index.js

@@ -0,0 +1,5 @@
+// @flow-engineer/flow/cli: an organization's command line over its MCP server (the same tools, sign-in and
+// gating as Claude or ChatGPT get). `defineCli` is the team's CLI file; `runCli` runs it. Needs
+// @modelcontextprotocol/client and @stricli/core, optional peers of Flow Framework.
+export { cliProblems, commandTable, defineCli, derivedName, skillFile } from "./commands.js";
+export { EXIT, processIO, runCli } from "./run.js";

package/dist/cli/src/run.d.ts

@@ -0,0 +1,28 @@
+import { type CliConfig } from "./commands.ts";
+export declare const EXIT: {
+    readonly ok: 0;
+    readonly failed: 1;
+    readonly usage: 2;
+    readonly signIn: 3;
+    readonly approval: 4;
+    readonly unreachable: 5;
+};
+export interface CliIO {
+    /** An embedded client's environment; omitted uses the local process environment. */
+    env?: Record<string, string | undefined>;
+    /** Cancels an embedded sign-in or terminal request when its session ends. */
+    signal?: AbortSignal;
+    /** Write to stdout as is. */
+    write(text: string): void;
+    /** Write to stderr as is. */
+    writeError(text: string): void;
+    /** Whether a person is at a terminal to answer a question. */
+    interactive: boolean;
+    /** Lines from an interactive terminal, with an optional input prompt; injectable for embedded CLIs and tests. */
+    lines?: (prompt?: string) => AsyncIterable<string>;
+    /** Ask a yes-or-no question (only when interactive). */
+    confirm(question: string): Promise<boolean>;
+}
+export declare function processIO(): CliIO;
+/** Run the CLI once; resolves with its exit code. */
+export declare function runCli(config: CliConfig, argv: string[], io?: CliIO): Promise<number>;