@sprid/cli 0.1.5 → 0.1.7

package/src/docs/help.mjs

@@ -7,6 +7,7 @@ export const HELP_TOPICS = {
     'SPRID_PAT: personal access token; overrides ~/.sprid/credentials.json.',
     'SPRID_URL: API address; overrides the saved address. HTTPS except on loopback.',
     'SPRID_APP_URL: browser app address; otherwise derived from the API address.',
+    'DO_NOT_TRACK=1 or SPRID_TELEMETRY=0: send no usage telemetry, whatever sprid telemetry says.',
     'Workspace: --workspace/-w > .sprid/app.json workspaceId > saved choice > sole workspace > local workspace slug.',
     'Local media can pin tokenEnv in sprid.config; that token is required when configured.',
     'Never paste credentials into a command example or an agent conversation. Connect with --key <file>.',

package/src/telemetry.mjs

@@ -0,0 +1,140 @@
+// Usage telemetry: after a command finishes, one small POST to the Sprid API
+// saying which command ran, how it ended and how long it took. What is sent
+// is exactly `commandEvent`'s fields: the command, a subcommand only when it
+// is one this CLI documents, the exit code, an error KIND (an HTTP status or
+// usage/network/other, never the message), the duration, the CLI and Node
+// versions, the OS and whether it ran in CI. Never arguments, file paths,
+// slugs, output or anything read from disk.
+//
+// It goes to the API the CLI is already signed in to, under the same login,
+// and nowhere else. Signed out means nothing is sent. Off with
+// `sprid telemetry off`, DO_NOT_TRACK=1 or SPRID_TELEMETRY=0. The first run
+// that could send only prints the notice; nothing leaves before the person
+// has been told.
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { COMMAND_GROUPS } from './docs/commands.mjs';
+import { UsageError } from './args.mjs';
+
+const SEND_TIMEOUT_MS = 1000;
+/** Commands that report nothing: they are about the CLI itself, or run for hours. */
+const SILENT = new Set(['help', 'version', 'completion', 'mcp', 'telemetry']);
+
+export const NOTICE = 'Sprid CLI sends usage telemetry to your Sprid account: the command name, exit code and duration, never arguments or file contents. Turn it off with `sprid telemetry off` or DO_NOT_TRACK=1.';
+
+export function settingsPath(env = process.env) {
+  return join(env.HOME || homedir(), '.sprid', 'telemetry.json');
+}
+
+export function readSettings(env = process.env) {
+  try { return JSON.parse(readFileSync(settingsPath(env), 'utf8')) ?? {}; } catch { return {}; }
+}
+
+export function writeSettings(settings, env = process.env) {
+  const path = settingsPath(env);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, JSON.stringify(settings, null, 2) + '\n', { mode: 0o600 });
+}
+
+const truthy = value => ['1', 'true', 'yes'].includes(String(value ?? '').trim().toLowerCase());
+const falsy = value => ['0', 'false', 'no', 'off'].includes(String(value ?? '').trim().toLowerCase());
+
+/** Whether telemetry is on, and which setting decided it. The environment wins over the file. */
+export function telemetryState(env = process.env) {
+  if (truthy(env.DO_NOT_TRACK)) return { enabled: false, reason: 'DO_NOT_TRACK is set' };
+  if (falsy(env.SPRID_TELEMETRY)) return { enabled: false, reason: 'SPRID_TELEMETRY is off' };
+  const settings = readSettings(env);
+  if (settings.enabled === false) return { enabled: false, reason: 'turned off with sprid telemetry off' };
+  return { enabled: true, reason: settings.enabled === true ? 'turned on with sprid telemetry on' : 'on by default', noticed: Boolean(settings.noticedAt) };
+}
+
+let documented;
+/** The subcommands the help catalog names for each command, e.g. post → create, get, build... */
+export function documentedSubcommands() {
+  if (documented) return documented;
+  documented = new Map();
+  for (const { command, usage } of COMMAND_GROUPS.flatMap(group => group.entries)) {
+    const second = usage.split(/\s+/)[2] ?? '';
+    const words = second.replace(/[[\]]/g, '').split('|').filter(word => /^[a-z][a-z0-9-]*$/.test(word));
+    if (!documented.has(command)) documented.set(command, new Set());
+    for (const word of words) documented.get(command).add(word);
+  }
+  return documented;
+}
+
+export function subcommandOf(command, words) {
+  const first = (words ?? []).find(word => !String(word).startsWith('-'));
+  return first && documentedSubcommands().get(command)?.has(first) ? first : null;
+}
+
+export function errorKind(error) {
+  if (!error) return null;
+  if (error.name === 'UsageError' || error.exitCode === 2) return 'usage';
+  if (typeof error.status === 'number') return error.status === 0 ? 'network' : error.status;
+  return 'other';
+}
+
+export function commandEvent({ command, words, exitCode, durationMs, error, version, env = process.env, workspaceId = null, now = new Date() }) {
+  return {
+    command,
+    subcommand: subcommandOf(command, words),
+    exitCode: Math.max(0, Math.min(255, Number(exitCode) || 0)),
+    durationMs: Math.max(0, Math.round(durationMs)),
+    error: errorKind(error),
+    version,
+    platform: process.platform,
+    node: process.version,
+    ci: Boolean(env.CI && !falsy(env.CI)),
+    workspaceId,
+    at: now.toISOString(),
+  };
+}
+
+/**
+ * Report one finished command. Never throws and never waits longer than
+ * SEND_TIMEOUT_MS: a slow network costs the person at most a second, and a
+ * failure costs them nothing.
+ */
+export async function reportCommand(ctx, { command, words, exitCode, durationMs, error }) {
+  try {
+    if (SILENT.has(command)) return false;
+    const state = telemetryState(ctx.env);
+    if (!state.enabled) return false;
+    let auth;
+    try { auth = ctx.auth(); } catch { return false; }
+    if (!state.noticed) {
+      ctx.warn(`  ${NOTICE}`);
+      try { writeSettings({ ...readSettings(ctx.env), noticedAt: new Date().toISOString() }, ctx.env); } catch { /* A read-only home only means the notice repeats. */ }
+      return false;
+    }
+    const workspaceId = ctx._workspace?.id ?? auth.workspace?.id ?? null;
+    const event = commandEvent({ command, words, exitCode, durationMs, error, version: ctx.version, env: ctx.env, workspaceId });
+    const res = await ctx.fetch(`${auth.apiUrl}/api/cli/events`, {
+      method: 'POST',
+      redirect: 'error',
+      signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json', Authorization: `Bearer ${auth.token}`, 'User-Agent': `sprid/${ctx.version}` },
+      body: JSON.stringify({ events: [event] }),
+    });
+    await res.body?.cancel?.().catch?.(() => {});
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+/** sprid telemetry [status|on|off] */
+export async function telemetry(ctx) {
+  const action = ctx.positionals[0] ?? 'status';
+  if (action === 'on' || action === 'off') {
+    writeSettings({ ...readSettings(ctx.env), enabled: action === 'on', noticedAt: readSettings(ctx.env).noticedAt ?? new Date().toISOString() }, ctx.env);
+  } else if (action !== 'status') {
+    throw new UsageError(`Unknown telemetry action "${action}". Use status, on or off.`);
+  }
+  const state = telemetryState(ctx.env);
+  if (ctx.json) ctx.out({ enabled: state.enabled, reason: state.reason, settings: settingsPath(ctx.env) });
+  else ctx.print(`  Telemetry is ${state.enabled ? 'on' : 'off'} (${state.reason}).${state.enabled ? ' Sent: command, exit code, duration, versions, OS. Never arguments or file contents.' : ''}`);
+  return 0;
+}

package/src/tools.mjs

@@ -0,0 +1,85 @@
+// The server's tools, called the way an MCP client calls them. Every command
+// built on this runs through the same handler, scopes and tenant checks as an
+// agent's call, so the CLI cannot drift from what MCP does: REST = MCP = CLI.
+//
+// /api/mcp is stateless JSON-RPC, so a single POST per call is enough; no
+// initialize handshake is needed.
+
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { UsageError } from "./args.mjs";
+import { ApiError } from "./http.mjs";
+
+const MCP_PATH = "/api/mcp?surface=all";
+
+async function rpc(ctx, method, params) {
+  const res = await ctx.api().post(MCP_PATH, { jsonrpc: "2.0", id: 1, method, params });
+  if (res?.error) throw new ApiError(0, res.error.message ?? `The server refused ${method}.`);
+  return res?.result;
+}
+
+/** One tool's result, exactly as its handler returned it. */
+export async function callTool(ctx, name, args = {}) {
+  const result = await rpc(ctx, "tools/call", { name, arguments: args });
+  const text = result?.content?.find((c) => c.type === "text")?.text;
+  if (text === undefined) return result?.structuredContent ?? null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+/** Every tool this token's scopes allow, with its input schema. */
+export async function listTools(ctx) {
+  return (await rpc(ctx, "tools/list", {}))?.tools ?? [];
+}
+
+/** `--file args.json`, `--args '{"a":1}'`, or both (the flag wins per key). */
+export async function toolArgs(ctx) {
+  let args = {};
+  if (typeof ctx.flags.file === "string") args = await readJson(ctx, ctx.flags.file);
+  if (typeof ctx.flags.args === "string") {
+    try {
+      args = { ...args, ...JSON.parse(ctx.flags.args) };
+    } catch {
+      throw new UsageError("--args must be a JSON object, such as --args '{\"account\":\"myapp\"}'.");
+    }
+  }
+  return args;
+}
+
+export async function readJson(ctx, path) {
+  const full = resolve(ctx.cwd, path);
+  let text;
+  try {
+    text = await readFile(full, "utf8");
+  } catch {
+    throw new UsageError(`Cannot read ${path}.`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new UsageError(`${path} is not valid JSON.`);
+  }
+}
+
+/** A comma list flag as an array; undefined when the flag is absent. */
+export function listFlag(value) {
+  if (typeof value !== "string") return undefined;
+  const items = value.split(",").map((v) => v.trim()).filter(Boolean);
+  return items.length ? items : undefined;
+}
+
+/** A positive integer positional, or a usage error naming the command. */
+export function needInt(arg, usage) {
+  const n = Number(arg);
+  if (!Number.isInteger(n) || n <= 0) throw new UsageError(usage);
+  return n;
+}
+
+/** Human output for results with no bespoke renderer. */
+export function show(ctx, result) {
+  if (ctx.json) ctx.out(result);
+  else ctx.print(JSON.stringify(result, null, 2));
+}