@rooaak/cli 0.1.0-beta.1

package/README.md

@@ -0,0 +1,121 @@
+# @rooaak/cli
+
+Rooaak CLI companion package for `/api/v1` workflows.
+
+## Install
+
+### Global install
+
+```bash
+npm install -g @rooaak/cli
+rooaak version
+```
+
+### One-off (no install)
+
+```bash
+npx @rooaak/cli version
+```
+
+### From source (this repo)
+
+```bash
+cd /Users/darian/Documents/Dev/rooaak/rooaak-core/packages/rooaak-cli
+npm run build
+node ./rooaak.js version
+```
+
+## Authentication
+
+```bash
+rooaak auth login --api-key <YOUR_API_KEY>
+rooaak config whoami
+```
+
+Optional base URL override for staging/self-hosted environments:
+
+```bash
+rooaak auth login --api-key <YOUR_API_KEY> --base-url https://staging.example.com
+```
+
+## Interactive vs automation modes
+
+### Interactive mode (developer-first)
+
+Use `rooaak init` for the guided flow:
+
+```bash
+rooaak init
+```
+
+This walks through auth/profile setup, project + agent creation, and first test message.
+
+### Automation mode (script/CI/agent-safe)
+
+Use `--json` and `--non-interactive` for deterministic machine behavior:
+
+```bash
+rooaak auth login --api-key "$ROOAAK_API_KEY" --json --non-interactive
+rooaak projects create --name "automation-project" --json --non-interactive
+rooaak agents create --name "automation-agent" --json --non-interactive
+```
+
+Automation contract:
+
+- `stdout` contains one JSON object only.
+- `stderr` carries human hints/warnings/debug.
+- Required input must be passed explicitly (no prompts in `--non-interactive`).
+
+## AI coding agent guidance
+
+When driving the CLI from an AI agent or orchestration script:
+
+- Always pass `--json`.
+- Always pass `--non-interactive`.
+- Parse `stdout` as a strict JSON envelope.
+- Route `stderr` to logs/diagnostics only.
+- Branch logic by exit code.
+
+### Exit codes
+
+- `0`: success
+- `2`: usage/validation error
+- `3`: auth failure
+- `4`: permission/scope denied
+- `5`: not found
+- `6`: conflict/idempotency
+- `7`: remote/server/transient failure
+
+### Example machine-safe command
+
+```bash
+rooaak messages send \
+  --agent-id "$AGENT_ID" \
+  --session-id "$SESSION_ID" \
+  --message "Hello" \
+  --json \
+  --non-interactive
+```
+
+## Drift checks and test gates
+
+Run from `/Users/darian/Documents/Dev/rooaak/rooaak-core`:
+
+```bash
+npm run openapi:v1:check
+npm run cli:v1:check-commands
+npm run test:run:cli
+```
+
+Opt-in staging e2e harness:
+
+```bash
+ROOAAK_CLI_E2E=1 \
+ROOAAK_CLI_E2E_BASE_URL=https://staging.example.com \
+ROOAAK_CLI_E2E_ADMIN_API_KEY=<ADMIN_KEY> \
+npm run test:run:cli:e2e
+```
+
+The staging e2e test is skipped by default and only runs when `ROOAAK_CLI_E2E=1`.
+`ROOAAK_CLI_E2E_BASE_URL` is required for e2e runs.
+Production hosts (`rooaak.com`, `www.rooaak.com`) are rejected by default; use `ROOAAK_CLI_E2E_ALLOW_PRODUCTION=1` only when intentional.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export declare function main(argv: string[]): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":"AAEA,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAE1D"}

package/dist/cli.js

@@ -0,0 +1,4 @@
+import { runCli } from "./src/lib/run.js";
+export async function main(argv) {
+    return runCli(argv);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { main } from "./cli.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { main } from "./cli.js";

package/dist/src/commands/auth-login.d.ts

@@ -0,0 +1,3 @@
+import type { CommandContext } from "../lib/types.js";
+export declare function authLoginCommand(ctx: CommandContext, argv: string[]): Promise<number>;
+//# sourceMappingURL=auth-login.d.ts.map

package/dist/src/commands/auth-login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-login.d.ts","sourceRoot":"","sources":["../../../src/commands/auth-login.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGtD,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA4F3F"}

package/dist/src/commands/auth-login.js

@@ -0,0 +1,97 @@
+import { resolveBaseUrl } from "../lib/base-url.js";
+import { normalizeLocalUsageError, toJsonErrorEnvelope, toJsonOkEnvelope } from "../lib/normalize-error.js";
+import { parseOptions } from "../lib/options.js";
+import { createProfileStore } from "../lib/profile-store.js";
+import { isValidProfileName } from "../lib/profile-name.js";
+import { createRenderer } from "../lib/renderer.js";
+import { ExitCode } from "../lib/exit-codes.js";
+export async function authLoginCommand(ctx, argv) {
+    const r = createRenderer(ctx);
+    const parsed = parseOptions(argv, [
+        { name: "--api-key", takesValue: true },
+        { name: "--profile", takesValue: true },
+    ]);
+    if (parsed.unknownOption) {
+        const err = normalizeLocalUsageError(`Unknown option: ${parsed.unknownOption}`);
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return ExitCode.Usage;
+    }
+    if (parsed.missingValueOption) {
+        const err = normalizeLocalUsageError(`Missing value for: ${parsed.missingValueOption}`);
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return ExitCode.Usage;
+    }
+    if (parsed.positionals.length > 0) {
+        // Never echo raw argv back (can contain secrets if user pasted something sensitive).
+        const err = normalizeLocalUsageError("Unexpected extra arguments", {
+            argc: parsed.positionals.length,
+        });
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return ExitCode.Usage;
+    }
+    const apiKey = parsed.values["--api-key"];
+    if (typeof apiKey !== "string" || apiKey.length === 0) {
+        const err = normalizeLocalUsageError("Missing required flag: --api-key");
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return ExitCode.Usage;
+    }
+    const profile = typeof parsed.values["--profile"] === "string" && parsed.values["--profile"].length > 0
+        ? parsed.values["--profile"]
+        : "default";
+    if (!isValidProfileName(profile)) {
+        const err = normalizeLocalUsageError("Invalid profile name", { profile });
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return ExitCode.Usage;
+    }
+    const store = createProfileStore({ configPath: ctx.profileConfigPath });
+    const existingRes = store.readConfig();
+    if (existingRes.kind === "corrupt") {
+        // Login is an allowed remediation path; overwrite but surface a hint.
+        r.warn(existingRes.message);
+    }
+    const existing = existingRes.kind === "ok" ? existingRes.config : null;
+    const existingProfile = existing?.profiles?.[profile];
+    const baseUrl = resolveBaseUrl({
+        cliFlag: ctx.flags.baseUrl,
+        env: ctx.env.ROOAAK_BASE_URL,
+        profile: existingProfile?.baseUrl,
+    });
+    const now = new Date().toISOString();
+    const next = {
+        version: 1,
+        currentProfile: profile,
+        profiles: {
+            ...(existing?.profiles ?? {}),
+            [profile]: {
+                apiKey,
+                baseUrl,
+                updatedAt: now,
+            },
+        },
+    };
+    store.writeConfig(next);
+    r.debug(`Wrote config: ${store.getConfigPath()}`);
+    if (ctx.flags.json) {
+        r.json(toJsonOkEnvelope({ profile, baseUrl }));
+    }
+    else {
+        r.text(`Saved profile '${profile}'.`);
+        r.text(`Base URL: ${baseUrl}`);
+    }
+    return ExitCode.Success;
+}

package/dist/src/commands/config-profile-use.d.ts

@@ -0,0 +1,3 @@
+import type { CommandContext } from "../lib/types.js";
+export declare function configProfileUseCommand(ctx: CommandContext, argv: string[]): Promise<number>;
+//# sourceMappingURL=config-profile-use.d.ts.map

package/dist/src/commands/config-profile-use.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-profile-use.d.ts","sourceRoot":"","sources":["../../../src/commands/config-profile-use.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA+ElG"}

package/dist/src/commands/config-profile-use.js

@@ -0,0 +1,88 @@
+import { ExitCode } from "../lib/exit-codes.js";
+import { exitCodeForError, normalizeLocalUsageError, toJsonErrorEnvelope, toJsonOkEnvelope, } from "../lib/normalize-error.js";
+import { isValidProfileName } from "../lib/profile-name.js";
+import { createProfileStore } from "../lib/profile-store.js";
+import { createRenderer } from "../lib/renderer.js";
+export async function configProfileUseCommand(ctx, argv) {
+    const r = createRenderer(ctx);
+    const name = argv[0];
+    if (!name) {
+        const err = normalizeLocalUsageError("Missing required argument: <name>");
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return ExitCode.Usage;
+    }
+    if (argv.length !== 1) {
+        const err = normalizeLocalUsageError("Unexpected extra arguments");
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return ExitCode.Usage;
+    }
+    if (!isValidProfileName(name)) {
+        const err = normalizeLocalUsageError("Invalid profile name", { profile: name });
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return ExitCode.Usage;
+    }
+    const store = createProfileStore({ configPath: ctx.profileConfigPath });
+    const res = store.readConfig();
+    if (res.kind === "missing") {
+        const err = {
+            code: "auth.not_logged_in",
+            message: "Not logged in",
+            details: {},
+            meta: {},
+        };
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error("Not logged in. Run `rooaak auth login --api-key ...`.");
+        return exitCodeForError(err);
+    }
+    if (res.kind === "corrupt") {
+        const err = {
+            code: "config.corrupt",
+            message: res.message,
+            details: { path: res.path },
+            meta: {},
+        };
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return exitCodeForError(err);
+    }
+    const config = res.config;
+    if (!config.profiles[name]) {
+        const err = {
+            code: "not_found.profile",
+            message: `Profile not found: ${name}`,
+            details: { profile: name },
+            meta: {},
+        };
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return exitCodeForError(err);
+    }
+    const next = {
+        version: 1,
+        currentProfile: name,
+        profiles: config.profiles,
+    };
+    store.writeConfig(next);
+    if (ctx.flags.json) {
+        r.json(toJsonOkEnvelope({ profile: name }));
+    }
+    else {
+        r.text(`Using profile '${name}'.`);
+    }
+    return ExitCode.Success;
+}

package/dist/src/commands/config-whoami.d.ts

@@ -0,0 +1,3 @@
+import type { CommandContext } from "../lib/types.js";
+export declare function configWhoamiCommand(ctx: CommandContext, argv: string[]): Promise<number>;
+//# sourceMappingURL=config-whoami.d.ts.map

package/dist/src/commands/config-whoami.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-whoami.d.ts","sourceRoot":"","sources":["../../../src/commands/config-whoami.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAOtD,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA+F9F"}

package/dist/src/commands/config-whoami.js

@@ -0,0 +1,101 @@
+import { resolveBaseUrl } from "../lib/base-url.js";
+import { ExitCode } from "../lib/exit-codes.js";
+import { exitCodeForError, toJsonErrorEnvelope, toJsonOkEnvelope, } from "../lib/normalize-error.js";
+import { createProfileStore } from "../lib/profile-store.js";
+import { createRenderer } from "../lib/renderer.js";
+import { createTransport } from "../lib/transport.js";
+export async function configWhoamiCommand(ctx, argv) {
+    const r = createRenderer(ctx);
+    const store = createProfileStore({ configPath: ctx.profileConfigPath });
+    if (argv.length !== 0) {
+        const err = {
+            code: "usage.validation_error",
+            message: "Unexpected arguments",
+            // Never echo raw argv back (can contain secrets if user pasted something sensitive).
+            details: { argc: argv.length },
+            meta: {},
+        };
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return exitCodeForError(err);
+    }
+    const cfgRes = store.readConfig();
+    if (cfgRes.kind === "missing") {
+        const err = {
+            code: "auth.not_logged_in",
+            message: "Not logged in. Run `rooaak auth login --api-key ...`.",
+            details: {},
+            meta: {},
+        };
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return exitCodeForError(err);
+    }
+    if (cfgRes.kind === "corrupt") {
+        const err = {
+            code: "config.corrupt",
+            message: cfgRes.message,
+            details: { path: cfgRes.path },
+            meta: {},
+        };
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return exitCodeForError(err);
+    }
+    const config = cfgRes.config;
+    const profileName = config.currentProfile;
+    const profile = config.profiles[profileName];
+    if (!profile?.apiKey) {
+        const err = {
+            code: "auth.not_logged_in",
+            message: "Not logged in. Run `rooaak auth login --api-key ...`.",
+            details: {},
+            meta: {},
+        };
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return exitCodeForError(err);
+    }
+    const baseUrl = resolveBaseUrl({
+        cliFlag: ctx.flags.baseUrl,
+        env: ctx.env.ROOAAK_BASE_URL,
+        profile: profile.baseUrl,
+    });
+    const transport = createTransport({
+        baseUrl,
+        apiKey: profile.apiKey,
+        fetchFn: ctx.fetchFn,
+    });
+    r.debug(`GET ${baseUrl}/api/v1/agents?limit=1`);
+    const httpRes = await transport.getJson("/api/v1/agents?limit=1");
+    if (!httpRes.ok) {
+        const err = httpRes.error;
+        if (ctx.flags.json)
+            r.json(toJsonErrorEnvelope(err));
+        else
+            r.error(err.message);
+        return exitCodeForError(err);
+    }
+    const meta = { status: httpRes.status, requestId: httpRes.requestId };
+    const data = {
+        profile: profileName,
+        baseUrl,
+        authenticated: true,
+    };
+    if (ctx.flags.json) {
+        r.json(toJsonOkEnvelope(data, meta));
+    }
+    else {
+        r.text(`Authenticated (profile: '${profileName}').`);
+        r.text(`Base URL: ${baseUrl}`);
+    }
+    return ExitCode.Success;
+}

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

@@ -0,0 +1,3 @@
+import type { CommandContext } from "../lib/types.js";
+export declare function helpCommand(ctx: CommandContext): number;
+//# sourceMappingURL=help.d.ts.map

package/dist/src/commands/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/commands/help.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,wBAAgB,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CA8DvD"}

package/dist/src/commands/help.js

@@ -0,0 +1,61 @@
+import { ExitCode } from "../lib/exit-codes.js";
+import { toJsonOkEnvelope } from "../lib/normalize-error.js";
+import { createRenderer } from "../lib/renderer.js";
+export function helpCommand(ctx) {
+    const r = createRenderer(ctx);
+    if (ctx.flags.json) {
+        // Machine mode: single JSON object on stdout, no prose.
+        r.json(toJsonOkEnvelope({
+            type: "help",
+            usage: "rooaak <group> <command> [flags]",
+            commands: [
+                { name: "help", description: "Show help" },
+                { name: "version", description: "Print version" },
+                { name: "init", description: "Guided onboarding: project -> agent -> first message" },
+                { name: "auth login", description: "Store API key in a local profile" },
+                { name: "config whoami", description: "Validate current profile against the API" },
+                { name: "config profile use <name>", description: "Switch active profile" },
+            ],
+            flags: [
+                { name: "--help", description: "Show help" },
+                { name: "--version", description: "Print version" },
+                { name: "--json", description: "Machine output (single JSON object on stdout)" },
+                { name: "--non-interactive", description: "Fail fast instead of prompting" },
+                { name: "--quiet", description: "Suppress non-error output on stderr" },
+                { name: "--verbose", description: "Debug output on stderr (no secrets)" },
+                { name: "--base-url <url>", description: "Override API base URL" },
+            ],
+            env: [{ name: "ROOAAK_BASE_URL", description: "API base URL (used if --base-url is not provided)" }],
+        }));
+        return ExitCode.Success;
+    }
+    ctx.stdout.write([
+        "Usage:",
+        "  rooaak <group> <command> [flags]",
+        "",
+        "Commands:",
+        "  help                         Show help",
+        "  version                      Print version",
+        "  init                         Guided onboarding: project -> agent -> first message",
+        "  auth login                    Store API key in a local profile",
+        "  config whoami                 Validate current profile against the API",
+        "  config profile use <name>     Switch active profile",
+        "",
+        "Global flags:",
+        "  -h, --help             Show help",
+        "  -v, --version          Print version",
+        "  --json                 Machine output (single JSON object on stdout)",
+        "  --non-interactive      Fail fast instead of prompting",
+        "  --quiet                Suppress non-error output on stderr",
+        "  --verbose              Debug output on stderr (no secrets)",
+        "  --base-url <url>       Override API base URL",
+        "",
+        "Environment:",
+        "  ROOAAK_BASE_URL         API base URL (used if --base-url is not provided)",
+        "",
+        "Generated command help:",
+        "  rooaak <resource> <action> --help",
+        ""
+    ].join("\n") + "\n");
+    return ExitCode.Success;
+}

package/dist/src/commands/init/index.d.ts

@@ -0,0 +1,3 @@
+import type { CommandContext } from "../../lib/types.js";
+export declare function initCommand(ctx: CommandContext, argv: string[]): Promise<number>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/commands/init/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/init/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AA4XzD,wBAAsB,WAAW,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAgctF"}