@aiaiai-pt/martha-cli 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to `@aiaiai-pt/martha-cli`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project adheres to semver — `0.x` releases may include breaking changes between minor versions.
 
+## [0.3.0] — 2026-05-10
+
+First-run UX for third-party developers and agent runtimes.
+
+### Added
+- `martha init` — interactive wizard that writes a profile to `~/.martha/config.yaml`. Two presets: `cloud` (martha.nomadriver.co + auth.nomadriver.co) and `local` (localhost:8080 + 8180). Idempotent with `--force`; rejects overwrites without it.
+- `martha doctor` — five-check diagnostic: API health, API/CLI version skew (via the new `GET /api/version` endpoint), Keycloak OIDC discovery, stored token validity, authenticated request. Exits non-zero only on FAIL, not WARN.
+- `martha skill` — prints the bundled `SKILL.md` to stdout. Agent runtimes that don't read filesystems by convention can now seed prompt context with `npx -y @aiaiai-pt/martha-cli@0.3.0 skill | head -200`.
+
+### Changed
+- Bundled binary is ~615 KB (small growth for the three new commands + their helpers).
+
+### Notes
+- Requires the Martha API to expose `GET /api/version` for the skew check; older APIs return 404 and `doctor` flags it as a warning, not a failure.
+- Skill discovery looks for `skills/martha-cli/SKILL.md` next to the bundle (npm install) or up the tree (dev checkout); both work.
+- Tracking: [#292](https://github.com/westeuropeco/martha/issues/292) Phase 1.
+
 ## [0.2.0] — 2026-05-09
 
 First public release on npm.

package/README.md

@@ -30,15 +30,20 @@ Requires Node.js >= 22.
 ## Quickstart
 
 ```bash
-# 1. Configure a profile (interactive wizard ships in 0.3.0; until then edit ~/.martha/config.yaml)
-martha config show
+# 1. Configure a profile — writes ~/.martha/config.yaml
+martha init                       # interactive (defaults to cloud preset)
+martha init --preset local        # localhost dev stack
+martha init --no-interactive --name staging --api-url https://...   # scripted
 
 # 2. Authenticate
 martha auth login                 # browser flow (PKCE)
 martha auth login --username u --password p   # headless
 export MARTHA_TOKEN=eyJhbGc...    # bypass login (CI / one-off)
 
-# 3. Run something
+# 3. Verify everything is wired up
+martha doctor                     # API + Keycloak + token + version skew
+
+# 4. Run something
 martha agents list
 martha functions list --json | jq '.[].name'
 martha chat my-agent "Summarise the latest task in tracker INGEST-42"
@@ -90,21 +95,19 @@ Exit codes: `0` success · `1` generic error · `2` auth failure · `3` not foun
 This package ships an agent-facing skill reference at `skills/martha-cli/SKILL.md` describing every command, JSON contract, and conceptual primitive (tenant, agent, function, task, etc.). Agent harnesses can pull it directly:
 
 ```bash
-# After global install
-cat $(npm root -g)/@aiaiai-pt/martha-cli/skills/martha-cli/SKILL.md
+# Print the skill to stdout (works for npm i -g and npx)
+martha skill
 
-# Or via npx (no install)
-npx -y -p @aiaiai-pt/martha-cli@latest sh -c 'cat $(dirname $(which martha))/../lib/node_modules/@aiaiai-pt/martha-cli/skills/martha-cli/SKILL.md' 2>/dev/null
+# Seed an agent's prompt context
+npx -y @aiaiai-pt/martha-cli@latest skill | head -200
 ```
 
-A first-class `martha skill` command lands in 0.3.0.
-
 ## Stability
 
 `0.x` releases may change CLI flags or JSON output between minor versions. Pin a version in CI/agent contexts:
 
 ```bash
-npx -y @aiaiai-pt/martha-cli@0.2.0 ...
+npx -y @aiaiai-pt/martha-cli@0.3.0 ...
 ```
 
 `1.0.0` will commit to a stable contract — see the [tracking issue](https://github.com/westeuropeco/martha/issues/292).

package/dist/index.js

@@ -10995,7 +10995,7 @@ import { createInterface as createInterface2 } from "node:readline";
 init_errors();
 
 // src/version.ts
-var CLI_VERSION = "0.2.0";
+var CLI_VERSION = "0.3.0";
 
 // src/commands/sessions.ts
 function relativeTime(iso) {
@@ -16742,6 +16742,362 @@ ${pages.length} pages`));
   });
 }
 
+// src/commands/init.ts
+import readline from "node:readline/promises";
+init_config();
+init_errors();
+var PRESETS = {
+  cloud: {
+    name: "cloud",
+    api_url: "https://martha.nomadriver.co",
+    keycloak_url: "https://auth.nomadriver.co",
+    keycloak_realm: "frank"
+  },
+  local: {
+    name: "local",
+    api_url: "http://localhost:8080",
+    keycloak_url: "http://localhost:8180",
+    keycloak_realm: "frank"
+  }
+};
+async function prompt2(rl, question, fallback) {
+  const answer = await rl.question(`  ${question} ${source_default.dim(`[${fallback}]`)} `);
+  return answer.trim() || fallback;
+}
+async function initCommand(opts) {
+  const presetKey = opts.preset ?? "cloud";
+  const preset = PRESETS[presetKey];
+  if (!preset) {
+    throw new CLIError(`Unknown preset: ${presetKey}. Choose one of: ${Object.keys(PRESETS).join(", ")}.`, 4 /* Validation */);
+  }
+  const profileName = opts.name ?? presetKey;
+  const config = loadConfig();
+  if (config.profiles[profileName] && !opts.force) {
+    throw new CLIError(`Profile ${source_default.cyan(profileName)} already exists. Re-run with --force to overwrite, or pass --profile <name> to add a new one.`, 5 /* Conflict */);
+  }
+  const interactive = !opts.noInteractive && process.stdin.isTTY && !opts.apiUrl && !opts.keycloakUrl && !opts.keycloakRealm;
+  let profile = {
+    api_url: opts.apiUrl ?? preset.api_url,
+    keycloak_url: opts.keycloakUrl ?? preset.keycloak_url,
+    keycloak_realm: opts.keycloakRealm ?? preset.keycloak_realm,
+    auth_type: "oidc"
+  };
+  if (interactive) {
+    console.log(source_default.bold(`
+Martha CLI — first-run setup
+`));
+    console.log(`  Preset:  ${source_default.cyan(preset.name)}`);
+    console.log(`  Profile: ${source_default.cyan(profileName)}`);
+    console.log(`  Press enter to accept defaults, or type a new value.
+`);
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    try {
+      profile.api_url = await prompt2(rl, "API URL:     ", profile.api_url);
+      profile.keycloak_url = await prompt2(rl, "Keycloak URL:", profile.keycloak_url);
+      profile.keycloak_realm = await prompt2(rl, "Keycloak realm:", profile.keycloak_realm);
+    } finally {
+      rl.close();
+    }
+  }
+  config.profiles[profileName] = profile;
+  config.current_profile = profileName;
+  saveConfig(config);
+  console.log();
+  console.log(source_default.green(`Profile saved.
+`));
+  console.log(`  Profile:     ${source_default.cyan(profileName)}`);
+  console.log(`  API URL:     ${profile.api_url}`);
+  console.log(`  Keycloak:    ${profile.keycloak_url}`);
+  console.log(`  Realm:       ${profile.keycloak_realm}`);
+  console.log();
+  console.log(source_default.dim("  Next:"));
+  console.log(source_default.dim("    martha auth login                    # browser PKCE"));
+  console.log(source_default.dim("    martha auth login --service-account  # CI/agent"));
+  console.log(source_default.dim("    martha doctor                        # verify setup"));
+}
+function registerInitCommand(program2) {
+  program2.command("init").description("Create or update a profile in ~/.martha/config.yaml").option("--preset <name>", "Preset: cloud or local", "cloud").option("--name <name>", "Profile name (defaults to preset name)").option("--force", "Overwrite an existing profile").option("--api-url <url>", "Override the API URL").option("--keycloak-url <url>", "Override the Keycloak URL").option("--keycloak-realm <realm>", "Override the Keycloak realm").option("--no-interactive", "Skip prompts; use defaults / overrides only").action(async (opts) => {
+    await initCommand(opts);
+  });
+}
+
+// src/commands/doctor.ts
+var FETCH_TIMEOUT_MS = 5000;
+async function fetchJSON(url, init) {
+  const res = await fetch(url, {
+    ...init,
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+  });
+  let json = null;
+  const ct = res.headers.get("content-type") ?? "";
+  if (ct.includes("application/json")) {
+    json = await res.json().catch(() => null);
+  }
+  return { ok: res.ok, status: res.status, json };
+}
+async function checkApiHealth(ctx) {
+  const url = `${ctx.profile.api_url}/health`;
+  try {
+    const { ok, status, json } = await fetchJSON(url);
+    if (ok && json?.status === "healthy") {
+      return {
+        name: "API health",
+        status: "pass",
+        detail: ctx.profile.api_url
+      };
+    }
+    return {
+      name: "API health",
+      status: "fail",
+      detail: `${url} → HTTP ${status}`,
+      remedy: "Check api_url in ~/.martha/config.yaml."
+    };
+  } catch (err) {
+    return {
+      name: "API health",
+      status: "fail",
+      detail: `${url} unreachable: ${err instanceof Error ? err.message : String(err)}`,
+      remedy: "Check api_url + your network."
+    };
+  }
+}
+async function checkApiVersion(ctx) {
+  const url = `${ctx.profile.api_url}/api/version`;
+  try {
+    const { ok, status, json } = await fetchJSON(url);
+    if (!ok || !json) {
+      if (status === 404) {
+        return {
+          name: "API version",
+          status: "warn",
+          detail: `${url} → 404 (server predates /api/version)`,
+          remedy: "Server upgrade recommended; harmless for now."
+        };
+      }
+      return {
+        name: "API version",
+        status: "fail",
+        detail: `${url} → HTTP ${status}`
+      };
+    }
+    const v = json;
+    const apiV = v.api_version ?? "unknown";
+    const minCli = v.min_cli_version;
+    if (minCli && compareSemver(CLI_VERSION, minCli) < 0) {
+      return {
+        name: "API version",
+        status: "fail",
+        detail: `api=${apiV} requires CLI >= ${minCli} (you have ${CLI_VERSION})`,
+        remedy: "Upgrade: npm i -g @aiaiai-pt/martha-cli@latest"
+      };
+    }
+    return {
+      name: "API version",
+      status: "pass",
+      detail: `api=${apiV} cli=${CLI_VERSION}`
+    };
+  } catch (err) {
+    return {
+      name: "API version",
+      status: "warn",
+      detail: `${url} unreachable: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+}
+async function checkKeycloak(ctx) {
+  const url = `${ctx.profile.keycloak_url}/realms/${ctx.profile.keycloak_realm}/.well-known/openid-configuration`;
+  try {
+    const { ok, status, json } = await fetchJSON(url);
+    if (ok && json?.issuer) {
+      return {
+        name: "Keycloak",
+        status: "pass",
+        detail: `${ctx.profile.keycloak_url} (realm=${ctx.profile.keycloak_realm})`
+      };
+    }
+    return {
+      name: "Keycloak",
+      status: "fail",
+      detail: `${url} → HTTP ${status}`,
+      remedy: `Verify keycloak_url + keycloak_realm in ~/.martha/config.yaml.`
+    };
+  } catch (err) {
+    return {
+      name: "Keycloak",
+      status: "fail",
+      detail: `${url} unreachable: ${err instanceof Error ? err.message : String(err)}`,
+      remedy: "Check keycloak_url + your network."
+    };
+  }
+}
+function checkAuth(ctx) {
+  const tokens = ctx.tokenStore.getTokens(ctx.profileName);
+  if (!tokens) {
+    return {
+      name: "Auth",
+      status: "warn",
+      detail: "no token stored",
+      remedy: "Run `martha auth login` (or set MARTHA_CLIENT_ID/SECRET for service accounts)."
+    };
+  }
+  const expired = ctx.tokenStore.isExpired(ctx.profileName);
+  if (expired) {
+    return {
+      name: "Auth",
+      status: "warn",
+      detail: `token expired (${tokens.auth_type})`,
+      remedy: "Run `martha auth login` to refresh."
+    };
+  }
+  const expiresAt = new Date(tokens.expires_at * 1000);
+  return {
+    name: "Auth",
+    status: "pass",
+    detail: `${tokens.auth_type} (${tokens.username ?? "n/a"}, exp ${expiresAt.toLocaleString()})`
+  };
+}
+async function checkAuthenticatedRequest(ctx) {
+  const tokens = ctx.tokenStore.getTokens(ctx.profileName);
+  if (!tokens || ctx.tokenStore.isExpired(ctx.profileName)) {
+    return {
+      name: "API auth",
+      status: "warn",
+      detail: "skipped — no valid token"
+    };
+  }
+  const url = `${ctx.profile.api_url}/api/admin/definitions/agents`;
+  try {
+    const { ok, status } = await fetchJSON(url, {
+      headers: { Authorization: `Bearer ${tokens.access_token}` }
+    });
+    if (ok) {
+      return { name: "API auth", status: "pass", detail: "token accepted" };
+    }
+    if (status === 401) {
+      return {
+        name: "API auth",
+        status: "fail",
+        detail: "401 — token rejected by API",
+        remedy: "Token may be for a different realm or expired. Re-run `martha auth login`."
+      };
+    }
+    if (status === 403) {
+      return {
+        name: "API auth",
+        status: "warn",
+        detail: "403 — token valid but lacks role for /api/admin/definitions/agents"
+      };
+    }
+    return {
+      name: "API auth",
+      status: "fail",
+      detail: `${url} → HTTP ${status}`
+    };
+  } catch (err) {
+    return {
+      name: "API auth",
+      status: "warn",
+      detail: `unreachable: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+}
+function compareSemver(a, b) {
+  const pa = a.split(".").map((n) => parseInt(n, 10));
+  const pb = b.split(".").map((n) => parseInt(n, 10));
+  for (let i = 0;i < 3; i++) {
+    const da = pa[i] ?? 0;
+    const db = pb[i] ?? 0;
+    if (da !== db)
+      return da - db;
+  }
+  return 0;
+}
+function statusGlyph(s) {
+  if (s === "pass")
+    return source_default.green("PASS");
+  if (s === "warn")
+    return source_default.yellow("WARN");
+  return source_default.red("FAIL");
+}
+async function doctorCommand(ctx) {
+  console.log(source_default.bold(`Martha CLI doctor
+`));
+  console.log(`  Profile:     ${source_default.cyan(ctx.profileName)}`);
+  console.log(`  CLI version: ${CLI_VERSION}`);
+  console.log();
+  const results = [];
+  results.push(await checkApiHealth(ctx));
+  results.push(await checkApiVersion(ctx));
+  results.push(await checkKeycloak(ctx));
+  results.push(checkAuth(ctx));
+  results.push(await checkAuthenticatedRequest(ctx));
+  for (const r of results) {
+    console.log(`  ${statusGlyph(r.status)}  ${r.name.padEnd(14)} ${source_default.dim(r.detail)}`);
+    if (r.remedy) {
+      console.log(`         ${source_default.dim("→ " + r.remedy)}`);
+    }
+  }
+  const failures = results.filter((r) => r.status === "fail").length;
+  const warnings = results.filter((r) => r.status === "warn").length;
+  console.log();
+  if (failures > 0) {
+    console.log(source_default.red(`  ${failures} check(s) failed.`));
+    process.exitCode = 1;
+  } else if (warnings > 0) {
+    console.log(source_default.yellow(`  All required checks passed (${warnings} warning(s)).`));
+  } else {
+    console.log(source_default.green(`  All checks passed.`));
+  }
+}
+function registerDoctorCommand(program2) {
+  program2.command("doctor").description("Run diagnostic checks against the active profile").action(async () => {
+    const ctx = createContext({
+      profileOverride: program2.opts().profile,
+      verbose: program2.opts().verbose
+    });
+    if (program2.opts().apiUrl) {
+      ctx.profile.api_url = program2.opts().apiUrl;
+    }
+    await doctorCommand(ctx);
+  });
+}
+
+// src/commands/skill.ts
+init_errors();
+import fs9 from "node:fs";
+import path5 from "node:path";
+import { fileURLToPath } from "node:url";
+function locateSkill() {
+  const here = path5.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    path5.join(here, "skills", "martha-cli", "SKILL.md"),
+    path5.join(here, "..", "skills", "martha-cli", "SKILL.md"),
+    path5.join(here, "..", "..", "..", "skills", "martha-cli", "SKILL.md"),
+    path5.join(here, "..", "..", "skills", "martha-cli", "SKILL.md")
+  ];
+  for (const p of candidates) {
+    if (fs9.existsSync(p))
+      return p;
+  }
+  return null;
+}
+async function skillCommand() {
+  const skillPath = locateSkill();
+  if (!skillPath) {
+    throw new CLIError("SKILL.md not found in the installed package. Reinstall via `npm i -g @aiaiai-pt/martha-cli` or `npx -y @aiaiai-pt/martha-cli@latest skill`.", 1 /* Error */);
+  }
+  const body = fs9.readFileSync(skillPath, "utf-8");
+  process.stdout.write(body);
+}
+function registerSkillCommand(program2) {
+  program2.command("skill").description("Print the bundled agent skill reference (SKILL.md) to stdout").action(async () => {
+    await skillCommand();
+  });
+}
+
 // src/index.ts
 var program2 = new Command;
 program2.name("martha").description("Terminal-first client for the Martha AI platform").version(CLI_VERSION).option("--profile <name>", "Use a named profile").option("--json", "Machine-readable JSON output").option("--quiet", "Suppress non-essential output").option("--verbose", "Verbose logging").option("--no-color", "Disable color output").option("--api-url <url>", "Override API base URL");
@@ -16802,6 +17158,9 @@ registerMessagingCommands(program2);
 registerClientCommands(program2);
 registerModelsCommand(program2);
 registerSessionCommands(program2);
+registerInitCommand(program2);
+registerDoctorCommand(program2);
+registerSkillCommand(program2);
 async function main() {
   try {
     await program2.parseAsync(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/martha-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Terminal-first client for the Martha AI platform",
   "homepage": "https://docs.martha.nomadriver.co",
   "repository": {