@spekn/cli 1.0.0

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

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * 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>]
+ */
+import type { DeviceFlowDeps, DeviceFlowResult } from "../../auth/device-flow.js";
+import { CredentialsStore } from "../../auth/credentials-store.js";
+interface CLIOptions {
+    keycloakUrl: string;
+    realm: string;
+}
+interface Deps {
+    stdout: {
+        write(s: string): void;
+    };
+    stderr: {
+        write(s: string): void;
+    };
+    performDeviceFlow: (keycloakUrl: string, realm: string, clientId: string, deps?: Partial<DeviceFlowDeps>) => Promise<DeviceFlowResult>;
+    credentialsStore: CredentialsStore;
+}
+declare function parseArgs(args: string[]): CLIOptions;
+export declare function runAuthLoginCli(args: string[], deps?: Partial<Deps>): Promise<number>;
+declare function main(): Promise<void>;
+export { main, parseArgs };
+export { decodeJwtPayload } from "../../auth/jwt.js";

package/dist/commands/auth/login.js

@@ -0,0 +1,164 @@
+#!/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.decodeJwtPayload = void 0;
+exports.runAuthLoginCli = runAuthLoginCli;
+exports.main = main;
+exports.parseArgs = parseArgs;
+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 session_js_1 = require("../../auth/session.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 };
+}
+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 auth = await (0, session_js_1.ensureAuthenticated)({
+            keycloakUrl: options.keycloakUrl,
+            realm: options.realm,
+            credentialsStore: resolved.credentialsStore,
+            performDeviceFlow: resolved.performDeviceFlow,
+            stdout: resolved.stdout,
+            stderr: resolved.stderr,
+            forceDeviceFlow: true,
+        });
+        // 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 ${auth.accessToken}`,
+                    },
+                }),
+            ],
+        });
+        const organizationId = await (0, session_js_1.resolveOrganizationId)({
+            existingOrganizationId: auth.credentials.organizationId,
+            envOrganizationId: process.env.SPEKN_ORGANIZATION_ID,
+            fetchOrganizations: async () => (await client.organization.list.query()),
+            stdout: resolved.stdout,
+        });
+        const credentials = {
+            ...auth.credentials,
+            organizationId,
+        };
+        resolved.credentialsStore.save(credentials);
+        resolved.stdout.write(`Logged in as ${auth.user.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: auth.user.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();
+}
+var jwt_js_1 = require("../../auth/jwt.js");
+Object.defineProperty(exports, "decodeJwtPayload", { enumerable: true, get: function () { return jwt_js_1.decodeJwtPayload; } });

package/dist/commands/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/commands/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/commands/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/commands/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/commands/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 };