@spekn/cli 1.0.0

package/dist/auth-login.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * auth login CLI command
+ *
+ * Authenticates the CLI user via the Keycloak Device Authorization Grant
+ * (RFC 8628) and persists credentials to ~/.spekn/credentials.json.
+ *
+ * Usage: spekn auth login [--keycloak-url <url>] [--realm <realm>]
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuthLoginCli = runAuthLoginCli;
+exports.main = main;
+exports.parseArgs = parseArgs;
+exports.decodeJwtPayload = decodeJwtPayload;
+const client_1 = require("@trpc/client");
+const device_flow_js_1 = require("./auth/device-flow.js");
+const credentials_store_js_1 = require("./auth/credentials-store.js");
+const help_error_1 = require("./utils/help-error");
+const trpc_url_1 = require("./utils/trpc-url");
+const structured_log_1 = require("./utils/structured-log");
+const defaultDeps = {
+    stdout: process.stdout,
+    stderr: process.stderr,
+    performDeviceFlow: device_flow_js_1.performDeviceFlow,
+    credentialsStore: new credentials_store_js_1.CredentialsStore(),
+};
+function resolveDeps(deps) {
+    return {
+        stdout: deps?.stdout ?? defaultDeps.stdout,
+        stderr: deps?.stderr ?? defaultDeps.stderr,
+        performDeviceFlow: deps?.performDeviceFlow ?? defaultDeps.performDeviceFlow,
+        credentialsStore: deps?.credentialsStore ?? defaultDeps.credentialsStore,
+    };
+}
+function printHelp(stderr) {
+    stderr.write(`
+auth login - Authenticate the Spekn CLI via browser-based device flow
+
+USAGE:
+  spekn auth login [options]
+
+OPTIONS:
+  --keycloak-url <url>   Keycloak base URL (default: KEYCLOAK_URL or https://auth.spekn.com)
+  --realm <realm>        Keycloak realm name (default: KEYCLOAK_REALM or spekn)
+  --help                 Show this help message
+
+ENVIRONMENT:
+  KEYCLOAK_URL           Keycloak base URL
+  KEYCLOAK_REALM         Keycloak realm name
+
+EXAMPLES:
+  spekn auth login
+  spekn auth login --keycloak-url https://auth.example.com --realm my-realm
+`);
+}
+function parseArgs(args) {
+    const keycloakUrlDefault = process.env["KEYCLOAK_URL"] ?? "https://auth.spekn.com";
+    const realmDefault = process.env["KEYCLOAK_REALM"] ?? "spekn";
+    let keycloakUrl = keycloakUrlDefault;
+    let realm = realmDefault;
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--help" || arg === "-h") {
+            throw new help_error_1.HelpRequestedError();
+        }
+        if (arg === "--keycloak-url" && args[index + 1]) {
+            keycloakUrl = args[++index];
+            continue;
+        }
+        if (arg.startsWith("--keycloak-url=")) {
+            keycloakUrl = arg.slice("--keycloak-url=".length);
+            continue;
+        }
+        if (arg === "--realm" && args[index + 1]) {
+            realm = args[++index];
+            continue;
+        }
+        if (arg.startsWith("--realm=")) {
+            realm = arg.slice("--realm=".length);
+            continue;
+        }
+    }
+    return { keycloakUrl, realm };
+}
+/**
+ * Decode the payload of a JWT access token without verification.
+ * Returns the raw claims object, or null if decoding fails.
+ */
+function decodeJwtPayload(token) {
+    try {
+        const parts = token.split(".");
+        if (parts.length !== 3) {
+            return null;
+        }
+        // Base64url → standard base64
+        const base64 = parts[1]
+            .replace(/-/g, "+")
+            .replace(/_/g, "/");
+        // Pad to a multiple of 4
+        const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), "=");
+        const json = Buffer.from(padded, "base64").toString("utf-8");
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}
+async function runAuthLoginCli(args, deps) {
+    const resolved = resolveDeps(deps);
+    try {
+        const options = parseArgs(args);
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.auth.login",
+            level: "info",
+            message: "Starting auth login",
+            details: { keycloakUrl: options.keycloakUrl, realm: options.realm },
+        });
+        const result = await resolved.performDeviceFlow(options.keycloakUrl, options.realm, "spekn-cli", { stdout: resolved.stdout, stderr: resolved.stderr });
+        // Decode the JWT payload to extract user identity fields.
+        const claims = decodeJwtPayload(result.accessToken);
+        const sub = typeof claims?.["sub"] === "string" ? claims["sub"] : "unknown";
+        const email = typeof claims?.["email"] === "string" ? claims["email"] : "unknown";
+        const name = typeof claims?.["name"] === "string"
+            ? claims["name"]
+            : typeof claims?.["preferred_username"] === "string"
+                ? claims["preferred_username"]
+                : undefined;
+        // Fetch the user's organizations from the API to resolve organizationId
+        const apiUrl = process.env.SPEKN_API_URL ?? "https://app.spekn.com";
+        const client = (0, client_1.createTRPCProxyClient)({
+            links: [
+                (0, client_1.httpBatchLink)({
+                    url: (0, trpc_url_1.normalizeTrpcUrl)(apiUrl),
+                    headers: {
+                        authorization: `Bearer ${result.accessToken}`,
+                    },
+                }),
+            ],
+        });
+        let organizationId;
+        try {
+            const orgs = await client.organization.list.query();
+            if (orgs.length === 1) {
+                organizationId = orgs[0].id;
+            }
+            else if (orgs.length > 1) {
+                resolved.stdout.write(`\nYou belong to ${orgs.length} organizations:\n`);
+                for (const org of orgs) {
+                    resolved.stdout.write(`  - ${org.name} (${org.id})\n`);
+                }
+                resolved.stdout.write(`\nAuto-selected first organization. Use SPEKN_ORGANIZATION_ID to override.\n`);
+                organizationId = orgs[0].id;
+            }
+        }
+        catch {
+            // Non-fatal — user can set SPEKN_ORGANIZATION_ID manually
+        }
+        const credentials = {
+            accessToken: result.accessToken,
+            refreshToken: result.refreshToken,
+            expiresAt: Date.now() + result.expiresIn * 1000,
+            keycloakUrl: options.keycloakUrl,
+            realm: options.realm,
+            organizationId,
+            user: { sub, email, name },
+        };
+        resolved.credentialsStore.save(credentials);
+        resolved.stdout.write(`Logged in as ${email}\n`);
+        if (organizationId) {
+            resolved.stdout.write(`Organization: ${organizationId}\n`);
+        }
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.auth.login",
+            level: "info",
+            message: "Auth login completed",
+            details: { email, organizationId },
+        });
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof help_error_1.HelpRequestedError) {
+            printHelp(resolved.stderr);
+            return 0;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        resolved.stderr.write(`Error: ${message}\n`);
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.auth.login",
+            level: "error",
+            message,
+        });
+        return 1;
+    }
+}
+async function main() {
+    const exitCode = await runAuthLoginCli(process.argv.slice(2));
+    process.exit(exitCode);
+}
+if (require.main === module) {
+    void main();
+}

package/dist/auth-logout.d.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * auth logout CLI command
+ *
+ * Revokes the stored refresh token against Keycloak (best-effort) and then
+ * removes the local credentials file at ~/.spekn/credentials.json.
+ *
+ * Usage: spekn auth logout
+ */
+import { CredentialsStore } from "./auth/credentials-store.js";
+interface Deps {
+    stdout: {
+        write(s: string): void;
+    };
+    stderr: {
+        write(s: string): void;
+    };
+    credentialsStore: CredentialsStore;
+    /** POST to the Keycloak logout endpoint. Injected for testing. */
+    revokeToken: (logoutUrl: string, body: URLSearchParams) => Promise<void>;
+}
+declare function parseArgs(args: string[]): void;
+export declare function runAuthLogoutCli(args: string[], deps?: Partial<Deps>): Promise<number>;
+declare function main(): Promise<void>;
+export { main, parseArgs };

package/dist/auth-logout.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * auth logout CLI command
+ *
+ * Revokes the stored refresh token against Keycloak (best-effort) and then
+ * removes the local credentials file at ~/.spekn/credentials.json.
+ *
+ * Usage: spekn auth logout
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuthLogoutCli = runAuthLogoutCli;
+exports.main = main;
+exports.parseArgs = parseArgs;
+const credentials_store_js_1 = require("./auth/credentials-store.js");
+const help_error_1 = require("./utils/help-error");
+const structured_log_1 = require("./utils/structured-log");
+/** Default revocation implementation — best-effort, ignores errors. */
+async function defaultRevokeToken(logoutUrl, body) {
+    await fetch(logoutUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+    });
+}
+const defaultDeps = {
+    stdout: process.stdout,
+    stderr: process.stderr,
+    credentialsStore: new credentials_store_js_1.CredentialsStore(),
+    revokeToken: defaultRevokeToken,
+};
+function resolveDeps(deps) {
+    return {
+        stdout: deps?.stdout ?? defaultDeps.stdout,
+        stderr: deps?.stderr ?? defaultDeps.stderr,
+        credentialsStore: deps?.credentialsStore ?? defaultDeps.credentialsStore,
+        revokeToken: deps?.revokeToken ?? defaultDeps.revokeToken,
+    };
+}
+function printHelp(stderr) {
+    stderr.write(`
+auth logout - Revoke the current session and remove stored credentials
+
+USAGE:
+  spekn auth logout
+
+OPTIONS:
+  --help   Show this help message
+
+EXAMPLES:
+  spekn auth logout
+`);
+}
+function parseArgs(args) {
+    for (const arg of args) {
+        if (arg === "--help" || arg === "-h") {
+            throw new help_error_1.HelpRequestedError();
+        }
+    }
+}
+async function runAuthLogoutCli(args, deps) {
+    const resolved = resolveDeps(deps);
+    try {
+        parseArgs(args);
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.auth.logout",
+            level: "info",
+            message: "Starting auth logout",
+        });
+        const credentials = resolved.credentialsStore.load();
+        if (credentials !== null && credentials.refreshToken) {
+            const logoutUrl = `${credentials.keycloakUrl}/realms/${credentials.realm}/protocol/openid-connect/logout`;
+            const body = new URLSearchParams({
+                client_id: "spekn-cli",
+                refresh_token: credentials.refreshToken,
+            });
+            try {
+                await resolved.revokeToken(logoutUrl, body);
+            }
+            catch {
+                // Best-effort: ignore revocation errors so local credentials are always
+                // cleared even when Keycloak is unreachable.
+            }
+        }
+        resolved.credentialsStore.clear();
+        resolved.stdout.write("Logged out successfully.\n");
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.auth.logout",
+            level: "info",
+            message: "Auth logout completed",
+        });
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof help_error_1.HelpRequestedError) {
+            printHelp(resolved.stderr);
+            return 0;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        resolved.stderr.write(`Error: ${message}\n`);
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.auth.logout",
+            level: "error",
+            message,
+        });
+        return 1;
+    }
+}
+async function main() {
+    const exitCode = await runAuthLogoutCli(process.argv.slice(2));
+    process.exit(exitCode);
+}
+if (require.main === module) {
+    void main();
+}

package/dist/auth-status.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * auth status CLI command
+ *
+ * Displays the current authentication state: logged-in user, token expiry,
+ * and organization (if set). Attempts a silent token refresh when the stored
+ * token is expired but a refresh token is available.
+ *
+ * Usage: spekn auth status
+ */
+import { CredentialsStore } from "./auth/credentials-store.js";
+interface Deps {
+    stdout: {
+        write(s: string): void;
+    };
+    stderr: {
+        write(s: string): void;
+    };
+    credentialsStore: CredentialsStore;
+}
+declare function parseArgs(args: string[]): void;
+export declare function runAuthStatusCli(args: string[], deps?: Partial<Deps>): Promise<number>;
+declare function main(): Promise<void>;
+export { main, parseArgs };

package/dist/auth-status.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * auth status CLI command
+ *
+ * Displays the current authentication state: logged-in user, token expiry,
+ * and organization (if set). Attempts a silent token refresh when the stored
+ * token is expired but a refresh token is available.
+ *
+ * Usage: spekn auth status
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuthStatusCli = runAuthStatusCli;
+exports.main = main;
+exports.parseArgs = parseArgs;
+const credentials_store_js_1 = require("./auth/credentials-store.js");
+const help_error_1 = require("./utils/help-error");
+const structured_log_1 = require("./utils/structured-log");
+const defaultDeps = {
+    stdout: process.stdout,
+    stderr: process.stderr,
+    credentialsStore: new credentials_store_js_1.CredentialsStore(),
+};
+function resolveDeps(deps) {
+    return {
+        stdout: deps?.stdout ?? defaultDeps.stdout,
+        stderr: deps?.stderr ?? defaultDeps.stderr,
+        credentialsStore: deps?.credentialsStore ?? defaultDeps.credentialsStore,
+    };
+}
+function printHelp(stderr) {
+    stderr.write(`
+auth status - Show the current authentication status
+
+USAGE:
+  spekn auth status
+
+OPTIONS:
+  --help   Show this help message
+
+EXAMPLES:
+  spekn auth status
+`);
+}
+function parseArgs(args) {
+    for (const arg of args) {
+        if (arg === "--help" || arg === "-h") {
+            throw new help_error_1.HelpRequestedError();
+        }
+    }
+}
+async function runAuthStatusCli(args, deps) {
+    const resolved = resolveDeps(deps);
+    try {
+        parseArgs(args);
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.auth.status",
+            level: "info",
+            message: "Checking auth status",
+        });
+        const credentials = resolved.credentialsStore.load();
+        if (credentials === null) {
+            resolved.stdout.write("Not logged in. Run `spekn auth login` to authenticate.\n");
+            return 1;
+        }
+        const token = await resolved.credentialsStore.getValidToken();
+        if (token === null) {
+            resolved.stdout.write("Session expired. Run `spekn auth login` to re-authenticate.\n");
+            return 1;
+        }
+        // Reload credentials after a potential refresh so we report the updated
+        // expiry time rather than the stale one.
+        const fresh = resolved.credentialsStore.load() ?? credentials;
+        const email = fresh.user?.email ?? "unknown";
+        const expiresAt = new Date(fresh.expiresAt).toLocaleString();
+        const orgId = fresh.organizationId ?? "not set";
+        resolved.stdout.write(`Logged in as ${email}\n`);
+        resolved.stdout.write(`Token expires: ${expiresAt}\n`);
+        resolved.stdout.write(`Organization: ${orgId}\n`);
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.auth.status",
+            level: "info",
+            message: "Auth status available",
+            details: { email, organizationId: orgId },
+        });
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof help_error_1.HelpRequestedError) {
+            printHelp(resolved.stderr);
+            return 0;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        resolved.stderr.write(`Error: ${message}\n`);
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.auth.status",
+            level: "error",
+            message,
+        });
+        return 1;
+    }
+}
+async function main() {
+    const exitCode = await runAuthStatusCli(process.argv.slice(2));
+    process.exit(exitCode);
+}
+if (require.main === module) {
+    void main();
+}

package/dist/backlog-generate.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * backlog-generate CLI Tool
+ *
+ * Auto-generate tasks from specification anchors.
+ *
+ * Usage: npm run backlog-generate <spec-file-path> [OPTIONS]
+ * Example: npm run backlog-generate specs/WORKFLOW.md --project-id=<uuid>
+ */
+declare function main(argv?: string[]): Promise<number>;
+export { main };