@spendgraph/cli 0.2.0

package/README.md

@@ -0,0 +1,149 @@
+# @spendgraph/cli
+
+`sg` drives the spendgraph dashboard from a terminal: write a prompt, declare a
+tool, mint a key, read what a project spent.
+
+It is a front-end over `@spendgraph/sdk` and nothing else. Every command is one
+SDK call, so the base URL, auth, retries and error shapes are decided in one
+place and this package only decides what to call and how to print it.
+
+## Credentials
+
+Two halves, and which one you hold decides what you reach.
+
+```sh
+export SPENDGRAPH_BASE_URL=https://your-app.workers.dev
+export SPENDGRAPH_API_KEY=sg_…      # prompts, tools, usage, stats
+export SPENDGRAPH_SESSION=…         # keys, projects, pricing, credentials
+export SPENDGRAPH_PROJECT=prj_…     # the default --project
+```
+
+Better, set them once and forget them:
+
+```sh
+sg config set --base-url https://your-app.workers.dev --api-key sg_…
+```
+
+That writes `~/.config/spendgraph/config.json` (or under `$XDG_CONFIG_HOME`),
+mode `0600` because it holds a key. After it, `sg` works from any directory with
+nothing exported and no `.env` anywhere.
+
+Values resolve in layers, highest first:
+
+| | |
+| --- | --- |
+| 1 | a `--flag` |
+| 2 | the exported environment |
+| 3 | the nearest `.env`, searching upward from the working directory |
+| 4 | the global config |
+
+So a project that needs different credentials puts them in its own `.env` and
+they beat the global default, the way a local git config does. Only `.env` is
+read, never `.env.local`; `--env-file <path>` replaces the search.
+
+```sh
+sg config show      # what is in effect, and which layer each value came from
+sg config path      # where the config and the .env in effect live
+sg config reaches   # which groups your credentials actually open
+sg config unset SPENDGRAPH_API_KEY
+sg config clear --yes
+```
+
+`show` and `set` mask the key rather than echoing it.
+
+**Reading is not writing.** An `sg_` key lists and gets prompts and tools and
+writes usage, but every *write* to a prompt or a tool — `create`, `update`,
+`promote` — calls a route that requires a signed-in session, as does everything
+under `key`, `project`, `pricing` and `credential`. `sg config reaches` prints
+the split for the credentials you actually hold.
+
+There is no API-key path to the session half, deliberately: `credential` holds
+provider keys and `key` mints API keys. A 401 there is the server saying the
+session is missing, and `sg` says so rather than repeating the status.
+
+Any flag beats the environment: `--base-url`, `--api-key`, `--session`,
+`--project`.
+
+## Shape
+
+```sh
+sg                      # the groups
+sg tool                 # a group's commands
+sg tool create --help   # the same, with usage
+```
+
+Simple fields are flags. Anything structured — a prompt's `blocks`, a tool's
+`args`, a dataset — goes in `--file`, which takes a JSON object. Flags given
+alongside `--file` win, so one field changes without restating the rest:
+
+```sh
+sg tool create --file ./tools/deeprecall.json --description "Searches the KB"
+```
+
+`projectId` in the file is enough on its own; `--project` is only needed when
+the file does not carry one.
+
+## The four things you probably came for
+
+```sh
+# declare a tool
+sg tool create --name deeprecall \
+  --description "Searches the knowledge base and answers from it." \
+  --effect readonly --arg question:string:required
+
+# change one
+sg tool update tl_123 --file ./tools/deeprecall.json
+
+# write a prompt
+sg prompt create --name decompose --file ./prompts/decompose.json
+
+# write a new version of one, then make it current
+sg prompt update pr_123 --file ./prompts/decompose.json
+sg prompt promote pr_123 pv_456
+```
+
+`--arg` is `name:type` or `name:type:required`, comma-separated for more than
+one. It covers a plain argument; a `FieldSpec` with an enum or a description
+belongs in `--file` under `args`.
+
+## Output
+
+A list of flat rows prints as a table, everything else as JSON. `--json` forces
+JSON whole, which is what you want in a pipe:
+
+```sh
+sg tool list --json | jq '.tools[] | select(.effect == "destructive")'
+```
+
+## Skills, for an agent
+
+`sg` ships its own operating manual as agent skills, generated from the command
+registry rather than written down beside it — a command added anywhere appears
+in the reference on the next run, so it cannot go stale.
+
+```sh
+sg skill list                    # what is on offer
+sg skill show spendgraph-cli     # the SKILL.md, on stdout
+sg skill install                 # write them under .claude/skills
+sg skill install --dir ./skills --force
+```
+
+| skill | for |
+| --- | --- |
+| `spendgraph-cli` | the whole CLI: credentials, flags, output, exit codes, every command |
+| `spendgraph-prompt-authoring` | writing and versioning prompts, declaring tools, the JSON shapes |
+
+These three commands never reach the API, so they work with no credentials set —
+an agent can read the manual before it has anything to authenticate with.
+An existing `SKILL.md` is left alone unless `--force` says otherwise.
+
+## Exit codes
+
+| | |
+| --- | --- |
+| 0 | the server answered |
+| 1 | the server refused |
+| 2 | the command line was wrong, and nothing was sent |
+
+The difference between 1 and 2 is worth scripting against: a 2 never reached the
+network, so retrying it changes nothing.

package/dist/args.d.ts

@@ -0,0 +1,13 @@
+/** One command line, split into the words that name a command and the flags that configure it. */
+export interface Parsed {
+    words: string[];
+    flags: Record<string, string | boolean>;
+}
+/**
+ * Splits argv into words and flags.
+ *
+ * `--name value`, `--name=value` and a bare `--name` all set `name`; `--no-name`
+ * clears it. A value starting with a single dash is still a value, so a negative
+ * number reaches the command rather than being read as the next flag.
+ */
+export declare function parse(argv: string[]): Parsed;

package/dist/args.js

@@ -0,0 +1,44 @@
+const isFlag = (token) => token.startsWith("--");
+/**
+ * Splits argv into words and flags.
+ *
+ * `--name value`, `--name=value` and a bare `--name` all set `name`; `--no-name`
+ * clears it. A value starting with a single dash is still a value, so a negative
+ * number reaches the command rather than being read as the next flag.
+ */
+export function parse(argv) {
+    const words = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "-h") {
+            flags.help = true;
+            continue;
+        }
+        if (!isFlag(token)) {
+            words.push(token);
+            continue;
+        }
+        const [name, inline] = split(token.slice(2));
+        if (inline !== undefined) {
+            flags[name] = inline;
+            continue;
+        }
+        if (name.startsWith("no-")) {
+            flags[name.slice(3)] = false;
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next !== undefined && !isFlag(next)) {
+            flags[name] = next;
+            i++;
+            continue;
+        }
+        flags[name] = true;
+    }
+    return { words, flags };
+}
+function split(token) {
+    const at = token.indexOf("=");
+    return at === -1 ? [token, undefined] : [token.slice(0, at), token.slice(at + 1)];
+}

package/dist/cli.d.ts

@@ -0,0 +1,22 @@
+import { type Env } from "./env.js";
+/** Where the CLI writes. Injected so a test reads the output instead of the terminal. */
+export interface Io {
+    out(text: string): void;
+    err(text: string): void;
+}
+/** What a caller may replace: where the environment comes from, and how requests are sent. */
+export interface Options {
+    env?: Env;
+    fetch?: typeof fetch;
+    /** Where to look for a `.env`, searching upward. Left unset, none is read. */
+    cwd?: string;
+    /** The global config file. Left unset, the one under `$XDG_CONFIG_HOME` is used. */
+    store?: string;
+}
+/**
+ * Runs one command line and returns the exit code.
+ *
+ * 0 is a reply, 1 is the server refusing, 2 is the line being wrong — so a
+ * script can tell a bad request from a bad password without parsing text.
+ */
+export declare function main(argv: string[], io: Io, opts?: Options): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,78 @@
+import { SpendgraphError } from "@spendgraph/sdk";
+import { parse } from "./args.js";
+import { connect, credentials } from "./connect.js";
+import { loadEnv } from "./env.js";
+import { readStore, storePath } from "./store.js";
+import { context } from "./context.js";
+import { UsageError } from "./errors.js";
+import { groupHelp, overview } from "./help.js";
+import { render } from "./output.js";
+import { commandNamed, groupNamed } from "./registry.js";
+const HINT = "A dashboard session is needed: for everything under key, project, pricing and credential, and for every write to a prompt or a tool. An sg_ key reads prompts and tools and writes usage. Set SPENDGRAPH_SESSION.";
+/**
+ * Runs one command line and returns the exit code.
+ *
+ * 0 is a reply, 1 is the server refusing, 2 is the line being wrong — so a
+ * script can tell a bad request from a bad password without parsing text.
+ */
+export async function main(argv, io, opts = {}) {
+    const parsed = parse(argv);
+    const [groupName, commandName, ...positional] = parsed.words;
+    const wantsHelp = parsed.flags.help === true;
+    if (!groupName || groupName === "help") {
+        io.out(overview());
+        return 0;
+    }
+    const group = groupNamed(groupName);
+    if (!group) {
+        io.err(`No such group "${groupName}". Run \`sg\` for the list.`);
+        return 2;
+    }
+    if (!commandName || wantsHelp) {
+        io.out(groupHelp(group));
+        return 0;
+    }
+    const command = commandNamed(group, commandName);
+    if (!command) {
+        io.err(`No such command "${groupName} ${commandName}".`);
+        io.err(groupHelp(group));
+        return 2;
+    }
+    try {
+        const base = opts.env ?? process.env;
+        const loaded = opts.cwd
+            ? loadEnv({
+                cwd: opts.cwd,
+                base,
+                explicit: flagged(parsed.flags["env-file"]),
+                store: store(base, flagged(parsed.flags.store) ?? opts.store),
+            })
+            : { env: base, source: {} };
+        const sg = command.local ? null : connect(credentials(parsed, loaded.env), opts.fetch);
+        const reply = await command.run(context(sg, parsed, positional, loaded));
+        io.out(render(reply, parsed.flags.json === true));
+        return 0;
+    }
+    catch (err) {
+        return failed(err, io);
+    }
+}
+const flagged = (value) => typeof value === "string" ? value : undefined;
+function store(base, override) {
+    const path = override ?? storePath(base);
+    return { path, values: readStore(path) };
+}
+function failed(err, io) {
+    if (err instanceof UsageError) {
+        io.err(err.message);
+        return 2;
+    }
+    if (err instanceof SpendgraphError) {
+        io.err(`${err.status} ${err.code}: ${err.message}`);
+        if (err.status === 401 || err.status === 403)
+            io.err(HINT);
+        return 1;
+    }
+    io.err(err instanceof Error ? err.message : String(err));
+    return 1;
+}

package/dist/commands/config.d.ts

@@ -0,0 +1,3 @@
+import type { Group } from "../types.js";
+/** The global config, and what the CLI resolved from it, a `.env` and the environment. */
+export declare const config: Group;

package/dist/commands/config.js

@@ -0,0 +1,135 @@
+import { existsSync, rmSync } from "node:fs";
+import { UsageError } from "../errors.js";
+import { readStore, SETTABLE, storePath, writeStore } from "../store.js";
+const SECRET = new Set(["SPENDGRAPH_API_KEY", "SPENDGRAPH_SESSION"]);
+const FLAGS = {
+    SPENDGRAPH_BASE_URL: "base-url",
+    SPENDGRAPH_API_KEY: "api-key",
+    SPENDGRAPH_SESSION: "session",
+    SPENDGRAPH_PROJECT: "project",
+};
+const mask = (value) => value.length <= 8 ? "…" : `${value.slice(0, 4)}…${value.slice(-4)}`;
+const shown = (variable, value) => (SECRET.has(variable) ? mask(value) : value);
+const where = (ctx) => ctx.flag("store") ?? storePath(ctx.loaded.env);
+const NEEDS = {
+    either: "an api key or a session",
+    session: "a dashboard session",
+    key: "an api key",
+};
+const ACCESS = [
+    { group: "prompt", read: "either", write: "session" },
+    { group: "tool", read: "either", write: "session" },
+    { group: "spend", read: "either", write: "key" },
+    { group: "key", read: "session", write: "session" },
+    { group: "project", read: "session", write: "session" },
+    { group: "pricing", read: "session", write: "session" },
+    { group: "credential", read: "session", write: "session" },
+];
+function set(ctx) {
+    const path = where(ctx);
+    const current = readStore(path);
+    const given = Object.fromEntries(SETTABLE.map((variable) => [variable, ctx.flag(FLAGS[variable])]).filter(([, v]) => v));
+    if (!Object.keys(given).length) {
+        throw new UsageError(`Give at least one of ${SETTABLE.map((v) => `--${FLAGS[v]}`).join(", ")}.`);
+    }
+    const merged = { ...current, ...given };
+    writeStore(path, merged);
+    return {
+        saved: Object.keys(given).map((variable) => ({
+            variable,
+            value: shown(variable, merged[variable]),
+            file: path,
+        })),
+    };
+}
+function unset(ctx) {
+    const path = where(ctx);
+    const variable = ctx.need(0, "VARIABLE").toUpperCase();
+    if (!SETTABLE.includes(variable)) {
+        throw new UsageError(`Not a setting: ${variable}. One of ${SETTABLE.join(", ")}.`);
+    }
+    const current = readStore(path);
+    delete current[variable];
+    writeStore(path, current);
+    return { removed: [{ variable, file: path }] };
+}
+/** The global config, and what the CLI resolved from it, a `.env` and the environment. */
+export const config = {
+    name: "config",
+    summary: "credentials kept globally, and what the CLI resolved",
+    commands: [
+        {
+            name: "show",
+            summary: "the credentials in effect and which layer each came from",
+            local: true,
+            run: async (ctx) => ({
+                settings: SETTABLE.map((variable) => {
+                    const value = ctx.loaded.env[variable];
+                    return {
+                        variable,
+                        value: value ? shown(variable, value) : "(unset)",
+                        from: value ? (ctx.loaded.source[variable] ?? "environment") : "-",
+                    };
+                }),
+            }),
+        },
+        {
+            name: "set",
+            summary: "keep a credential globally, so no .env is needed",
+            local: true,
+            run: async (ctx) => set(ctx),
+        },
+        {
+            name: "unset",
+            summary: "drop one from the global config",
+            usage: "<VARIABLE>",
+            local: true,
+            run: async (ctx) => unset(ctx),
+        },
+        {
+            name: "path",
+            summary: "where the global config lives, and the .env in effect",
+            local: true,
+            run: async (ctx) => {
+                const path = where(ctx);
+                return {
+                    files: [
+                        { file: "config", path, exists: existsSync(path) },
+                        { file: ".env", path: ctx.loaded.file ?? "(none found)", exists: !!ctx.loaded.file },
+                    ],
+                };
+            },
+        },
+        {
+            name: "clear",
+            summary: "delete the global config entirely",
+            local: true,
+            run: async (ctx) => {
+                const path = where(ctx);
+                if (!ctx.bool("yes"))
+                    throw new UsageError(`Pass --yes to delete ${path}.`);
+                if (existsSync(path))
+                    rmSync(path);
+                return { cleared: [{ path }] };
+            },
+        },
+        {
+            name: "reaches",
+            summary: "which groups your credentials can read, and which they can write",
+            local: true,
+            run: async (ctx) => {
+                const key = !!ctx.loaded.env.SPENDGRAPH_API_KEY;
+                const session = !!ctx.loaded.env.SPENDGRAPH_SESSION;
+                const held = { key, session, either: key || session };
+                return {
+                    access: ACCESS.map((row) => ({
+                        group: row.group,
+                        read: held[row.read],
+                        write: held[row.write],
+                        "write needs": NEEDS[row.write],
+                    })),
+                };
+            },
+        },
+    ],
+};

package/dist/commands/dashboard.d.ts

@@ -0,0 +1,11 @@
+import type { Group } from "../types.js";
+/** Projects, their budgets and who is in them. */
+export declare const projects: Group;
+/** API keys. Minting one needs a dashboard session, never a key. */
+export declare const keys: Group;
+/** Provider keys the server calls out with. Session only, deliberately. */
+export declare const credentials: Group;
+/** What a model costs, and what the catalogue knows. */
+export declare const pricing: Group;
+/** What was spent, by whom, on what. */
+export declare const spend: Group;