@spekn/cli 1.0.0

package/dist/__tests__/export-cli.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/export-cli.test.js

@@ -0,0 +1,70 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const export_1 = require("../export");
+function createDeps() {
+    const state = {
+        stdout: '',
+        stderr: '',
+        writes: [],
+    };
+    const deps = {
+        createClient: () => ({
+            export: {
+                generate: {
+                    mutate: async () => ({
+                        content: 'GENERATED CONTENT\n',
+                        anchorCount: 2,
+                    }),
+                },
+            },
+        }),
+        writeFile: (filePath, content) => {
+            state.writes.push({ path: filePath, content });
+        },
+        stdout: (content) => {
+            state.stdout += content;
+        },
+        stderr: (content) => {
+            state.stderr += content;
+        },
+    };
+    return { state, deps };
+}
+async function testStdoutMode() {
+    const { state, deps } = createDeps();
+    const code = await (0, export_1.runExportCli)(['--project', '11111111-1111-4111-8111-111111111111', '--format', 'claude-md'], deps);
+    strict_1.default.equal(code, 0);
+    strict_1.default.equal(state.stdout, 'GENERATED CONTENT\n');
+    strict_1.default.equal(state.writes.length, 0);
+}
+async function testOutputMode() {
+    const { state, deps } = createDeps();
+    const code = await (0, export_1.runExportCli)([
+        '--project',
+        '11111111-1111-4111-8111-111111111111',
+        '--format',
+        'cursorrules',
+        '--output',
+        'tmp-export.txt',
+    ], deps);
+    strict_1.default.equal(code, 0);
+    strict_1.default.equal(state.writes.length, 1);
+    strict_1.default.ok(state.stdout.includes('Exported 2 anchors'));
+}
+async function testMissingRequiredArgs() {
+    const { state, deps } = createDeps();
+    const code = await (0, export_1.runExportCli)(['--format', 'claude-md'], deps);
+    strict_1.default.equal(code, 1);
+    strict_1.default.ok(state.stderr.includes('Missing required argument'));
+}
+async function main() {
+    await testStdoutMode();
+    await testOutputMode();
+    await testMissingRequiredArgs();
+    process.stdout.write('export-cli.test.ts passed\n');
+}
+void main();

package/dist/__tests__/tui-args-policy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/tui-args-policy.test.js

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const shared_1 = require("@spekn/shared");
+const args_1 = require("../tui/args");
+const policy_1 = require("../tui/capabilities/policy");
+function testParseArgs() {
+    const parsed = (0, args_1.parseTuiArgs)([
+        '--project-id',
+        '11111111-1111-4111-8111-111111111111',
+        '--api-url',
+        'http://localhost:9999',
+        '--view',
+        'export',
+        '--no-color',
+    ]);
+    strict_1.default.equal(parsed.projectId, '11111111-1111-4111-8111-111111111111');
+    strict_1.default.equal(parsed.apiUrl, 'http://localhost:9999');
+    strict_1.default.equal(parsed.initialView, 'export');
+    strict_1.default.equal(parsed.noColor, true);
+}
+function testTierLocks() {
+    const freePolicy = (0, policy_1.resolveNavPolicy)({
+        plan: shared_1.OrganizationPlan.FREE,
+        role: 'member',
+        workflowPhase: null,
+        permissions: [],
+    });
+    const bridge = freePolicy.find((item) => item.id === 'bridge');
+    const teamFeature = freePolicy.find((item) => item.id === 'active-runs');
+    strict_1.default.equal(bridge?.state, 'locked');
+    strict_1.default.equal(teamFeature?.state, 'locked');
+    const teamPolicy = (0, policy_1.resolveNavPolicy)({
+        plan: shared_1.OrganizationPlan.TEAM,
+        role: 'viewer',
+        workflowPhase: 'plan',
+        permissions: [],
+    });
+    const gates = teamPolicy.find((item) => item.id === 'phase-gates');
+    strict_1.default.equal(gates?.state, 'disabled');
+}
+function main() {
+    testParseArgs();
+    testTierLocks();
+    process.stdout.write('tui-args-policy.test.ts passed\n');
+}
+main();

package/dist/acp-S2MHZOAD.mjs

@@ -0,0 +1,23 @@
+// Bundled TUI entry (ESM) — loaded via dynamic import() from CJS main.js
+import {
+  AGENT_METHODS,
+  AgentSideConnection,
+  CLIENT_METHODS,
+  ClientSideConnection,
+  PROTOCOL_VERSION,
+  RequestError,
+  TerminalHandle,
+  init_acp,
+  ndJsonStream
+} from "./chunk-M4CS3A25.mjs";
+init_acp();
+export {
+  AGENT_METHODS,
+  AgentSideConnection,
+  CLIENT_METHODS,
+  ClientSideConnection,
+  PROTOCOL_VERSION,
+  RequestError,
+  TerminalHandle,
+  ndJsonStream
+};

package/dist/acp-UCCI44JY.mjs

@@ -0,0 +1,25 @@
+// Bundled TUI entry (ESM) — loaded via dynamic import() from CJS main.js
+import { createRequire as __createRequire } from 'module';
+const require = __createRequire(import.meta.url);
+import {
+  AGENT_METHODS,
+  AgentSideConnection,
+  CLIENT_METHODS,
+  ClientSideConnection,
+  PROTOCOL_VERSION,
+  RequestError,
+  TerminalHandle,
+  init_acp,
+  ndJsonStream
+} from "./chunk-3PAYRI4G.mjs";
+init_acp();
+export {
+  AGENT_METHODS,
+  AgentSideConnection,
+  CLIENT_METHODS,
+  ClientSideConnection,
+  PROTOCOL_VERSION,
+  RequestError,
+  TerminalHandle,
+  ndJsonStream
+};

package/dist/auth/credentials-store.d.ts

@@ -0,0 +1,2 @@
+export { CredentialsStore } from "@spekn/shared";
+export type { CliCredentials } from "@spekn/shared";

package/dist/auth/credentials-store.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CredentialsStore = void 0;
+var shared_1 = require("@spekn/shared");
+Object.defineProperty(exports, "CredentialsStore", { enumerable: true, get: function () { return shared_1.CredentialsStore; } });

package/dist/auth/device-flow.d.ts

@@ -0,0 +1,36 @@
+/**
+ * RFC 8628 Device Authorization Grant (Device Flow)
+ *
+ * Implements the OAuth 2.0 Device Authorization Grant for CLI authentication
+ * against a Keycloak realm.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc8628
+ */
+export interface DeviceFlowResult {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+    idToken?: string;
+}
+export interface DeviceFlowDeps {
+    stdout: {
+        write(s: string): void;
+    };
+    stderr: {
+        write(s: string): void;
+    };
+    openBrowser: (url: string) => Promise<void>;
+}
+/** Default browser opener — dynamically imports the `open` package. */
+declare const defaultOpenBrowser: (url: string) => Promise<void>;
+/**
+ * Perform the RFC 8628 Device Authorization Grant against a Keycloak realm.
+ *
+ * @param keycloakUrl - Base Keycloak URL, e.g. `https://auth.example.com`
+ * @param realm       - Keycloak realm name
+ * @param clientId    - OAuth2 client ID (must be a public client)
+ * @param deps        - Optional dependency overrides for testing / custom I/O
+ * @returns Resolved tokens once the user authorises the device
+ */
+export declare function performDeviceFlow(keycloakUrl: string, realm: string, clientId: string, deps?: Partial<DeviceFlowDeps>): Promise<DeviceFlowResult>;
+export { defaultOpenBrowser };

package/dist/auth/device-flow.js

@@ -0,0 +1,189 @@
+"use strict";
+/**
+ * RFC 8628 Device Authorization Grant (Device Flow)
+ *
+ * Implements the OAuth 2.0 Device Authorization Grant for CLI authentication
+ * against a Keycloak realm.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc8628
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultOpenBrowser = void 0;
+exports.performDeviceFlow = performDeviceFlow;
+const zod_1 = require("zod");
+const DeviceAuthorizationResponseSchema = zod_1.z.object({
+    device_code: zod_1.z.string(),
+    user_code: zod_1.z.string(),
+    verification_uri: zod_1.z.string(),
+    verification_uri_complete: zod_1.z.string(),
+    expires_in: zod_1.z.number(),
+    interval: zod_1.z.number(),
+});
+const TokenSuccessResponseSchema = zod_1.z.object({
+    access_token: zod_1.z.string(),
+    refresh_token: zod_1.z.string(),
+    expires_in: zod_1.z.number(),
+    id_token: zod_1.z.string().optional(),
+    token_type: zod_1.z.string(),
+});
+const TokenErrorResponseSchema = zod_1.z.object({
+    error: zod_1.z.string(),
+    error_description: zod_1.z.string().optional(),
+});
+/** Default browser opener — dynamically imports the `open` package. */
+const defaultOpenBrowser = async (url) => {
+    const { default: open } = await Promise.resolve().then(() => __importStar(require("open")));
+    await open(url);
+};
+exports.defaultOpenBrowser = defaultOpenBrowser;
+const defaultDeps = {
+    stdout: process.stdout,
+    stderr: process.stderr,
+    openBrowser: defaultOpenBrowser,
+};
+/** Resolves deps, filling in defaults for any omitted fields. */
+function resolveDeps(deps) {
+    return {
+        stdout: deps?.stdout ?? defaultDeps.stdout,
+        stderr: deps?.stderr ?? defaultDeps.stderr,
+        openBrowser: deps?.openBrowser ?? defaultDeps.openBrowser,
+    };
+}
+/** Pause for `ms` milliseconds. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Perform the RFC 8628 Device Authorization Grant against a Keycloak realm.
+ *
+ * @param keycloakUrl - Base Keycloak URL, e.g. `https://auth.example.com`
+ * @param realm       - Keycloak realm name
+ * @param clientId    - OAuth2 client ID (must be a public client)
+ * @param deps        - Optional dependency overrides for testing / custom I/O
+ * @returns Resolved tokens once the user authorises the device
+ */
+async function performDeviceFlow(keycloakUrl, realm, clientId, deps) {
+    const { stdout, stderr, openBrowser } = resolveDeps(deps);
+    // -------------------------------------------------------------------------
+    // Step 1: Request device code
+    // -------------------------------------------------------------------------
+    const deviceAuthUrl = `${keycloakUrl}/realms/${realm}/protocol/openid-connect/auth/device`;
+    const deviceAuthBody = new URLSearchParams({
+        client_id: clientId,
+        scope: "openid email profile offline_access spekn-api",
+    });
+    const deviceAuthResponse = await fetch(deviceAuthUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: deviceAuthBody.toString(),
+    });
+    if (!deviceAuthResponse.ok) {
+        const text = await deviceAuthResponse.text();
+        throw new Error(`Device authorization request failed (${deviceAuthResponse.status}): ${text}`);
+    }
+    const deviceAuth = DeviceAuthorizationResponseSchema.parse(await deviceAuthResponse.json());
+    const { device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval, } = deviceAuth;
+    // -------------------------------------------------------------------------
+    // Step 2: Display instructions to the user
+    // -------------------------------------------------------------------------
+    stdout.write(`\nTo sign in, open this URL in your browser:\n` +
+        `  ${verification_uri_complete}\n\n` +
+        `Enter code: ${user_code}\n\n` +
+        `Waiting for authorization...\n`);
+    // -------------------------------------------------------------------------
+    // Step 3: Open browser (best-effort)
+    // -------------------------------------------------------------------------
+    try {
+        await openBrowser(verification_uri_complete);
+    }
+    catch (err) {
+        // Silently ignore browser-open failures; user still has the URL above.
+        const message = err instanceof Error ? err.message : String(err);
+        stderr.write(`(Could not open browser automatically: ${message})\n`);
+    }
+    // -------------------------------------------------------------------------
+    // Step 4: Poll token endpoint
+    // -------------------------------------------------------------------------
+    const tokenUrl = `${keycloakUrl}/realms/${realm}/protocol/openid-connect/token`;
+    const deadline = Date.now() + expires_in * 1000;
+    // RFC 8628 §3.5: default interval is 5 seconds when not specified.
+    let pollInterval = (interval ?? 5) * 1000;
+    while (Date.now() < deadline) {
+        await sleep(pollInterval);
+        const tokenBody = new URLSearchParams({
+            grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+            device_code,
+            client_id: clientId,
+        });
+        const tokenResponse = await fetch(tokenUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: tokenBody.toString(),
+        });
+        if (tokenResponse.ok) {
+            // Success — return tokens.
+            const token = TokenSuccessResponseSchema.parse(await tokenResponse.json());
+            return {
+                accessToken: token.access_token,
+                refreshToken: token.refresh_token,
+                expiresIn: token.expires_in,
+                idToken: token.id_token,
+            };
+        }
+        // Non-200 responses carry an RFC 8628 error code in the JSON body.
+        const errorBody = TokenErrorResponseSchema.parse(await tokenResponse.json());
+        const errorCode = errorBody.error;
+        switch (errorCode) {
+            case "authorization_pending":
+                // User has not yet authorised — keep polling.
+                break;
+            case "slow_down":
+                // RFC 8628 §3.5: increase interval by 5 seconds and continue.
+                pollInterval += 5000;
+                break;
+            case "expired_token":
+                throw new Error("Device code expired. Please try again.");
+            case "access_denied":
+                throw new Error("Authorization denied by user.");
+            default:
+                throw new Error(`Unexpected token error "${errorCode}": ${errorBody.error_description ?? "no description"}`);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Step 5: Timeout — device code has expired without user action.
+    // -------------------------------------------------------------------------
+    throw new Error(`Authorization timed out after ${expires_in} seconds. Please try again.`);
+}

package/dist/auth/jwt.d.ts

@@ -0,0 +1 @@
+export { decodeJwtPayload, extractUserIdentity } from "@spekn/shared";

package/dist/auth/jwt.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractUserIdentity = exports.decodeJwtPayload = void 0;
+var shared_1 = require("@spekn/shared");
+Object.defineProperty(exports, "decodeJwtPayload", { enumerable: true, get: function () { return shared_1.decodeJwtPayload; } });
+Object.defineProperty(exports, "extractUserIdentity", { enumerable: true, get: function () { return shared_1.extractUserIdentity; } });

package/dist/auth/session.d.ts

@@ -0,0 +1,67 @@
+import type { CliCredentials } from "./credentials-store.js";
+import type { CredentialsStore } from "./credentials-store.js";
+import type { DeviceFlowDeps, DeviceFlowResult } from "./device-flow.js";
+interface BuildCredentialsInput {
+    result: DeviceFlowResult;
+    keycloakUrl: string;
+    realm: string;
+    organizationId?: string;
+}
+interface BuildCredentialsOutput {
+    credentials: CliCredentials;
+    user: {
+        sub: string;
+        email: string;
+        name?: string;
+    };
+}
+/**
+ * Build persisted CLI credentials from a successful Keycloak device-flow result.
+ */
+export declare function buildCredentialsFromDeviceFlow(input: BuildCredentialsInput): BuildCredentialsOutput;
+export interface EnsureAuthenticatedInput {
+    keycloakUrl: string;
+    realm: string;
+    credentialsStore: CredentialsStore;
+    performDeviceFlow: (keycloakUrl: string, realm: string, clientId: string, deps?: Partial<DeviceFlowDeps>) => Promise<DeviceFlowResult>;
+    stdout: {
+        write(s: string): void;
+    };
+    stderr: {
+        write(s: string): void;
+    };
+    forceDeviceFlow?: boolean;
+}
+export interface EnsureAuthenticatedResult {
+    accessToken: string;
+    credentials: CliCredentials;
+    user: {
+        sub: string;
+        email: string;
+        name?: string;
+    };
+    source: "existing" | "device_flow";
+}
+export interface ResolveOrganizationIdInput {
+    existingOrganizationId?: string;
+    envOrganizationId?: string;
+    fetchOrganizations: () => Promise<Array<{
+        id: string;
+        name: string;
+    }>>;
+    stdout?: {
+        write(s: string): void;
+    };
+}
+/**
+ * Ensure CLI authentication is available.
+ * - Reuses existing valid token by default.
+ * - Runs device flow when forced or when no valid token exists.
+ */
+export declare function ensureAuthenticated(input: EnsureAuthenticatedInput): Promise<EnsureAuthenticatedResult>;
+/**
+ * Resolve effective organization context:
+ * stored credentials first, then env, then API discovery fallback.
+ */
+export declare function resolveOrganizationId(input: ResolveOrganizationIdInput): Promise<string | undefined>;
+export {};

package/dist/auth/session.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCredentialsFromDeviceFlow = buildCredentialsFromDeviceFlow;
+exports.ensureAuthenticated = ensureAuthenticated;
+exports.resolveOrganizationId = resolveOrganizationId;
+const jwt_js_1 = require("./jwt.js");
+/**
+ * Build persisted CLI credentials from a successful Keycloak device-flow result.
+ */
+function buildCredentialsFromDeviceFlow(input) {
+    const claims = (0, jwt_js_1.decodeJwtPayload)(input.result.accessToken);
+    const user = (0, jwt_js_1.extractUserIdentity)(claims);
+    const credentials = {
+        accessToken: input.result.accessToken,
+        refreshToken: input.result.refreshToken,
+        expiresAt: Date.now() + input.result.expiresIn * 1000,
+        keycloakUrl: input.keycloakUrl,
+        realm: input.realm,
+        organizationId: input.organizationId,
+        user,
+    };
+    return { credentials, user };
+}
+/**
+ * Ensure CLI authentication is available.
+ * - Reuses existing valid token by default.
+ * - Runs device flow when forced or when no valid token exists.
+ */
+async function ensureAuthenticated(input) {
+    if (!input.forceDeviceFlow) {
+        const existingToken = await input.credentialsStore.getValidToken();
+        const existingCreds = input.credentialsStore.load();
+        if (existingToken && existingCreds) {
+            return {
+                accessToken: existingToken,
+                credentials: existingCreds,
+                user: existingCreds.user ?? {
+                    sub: "unknown",
+                    email: "unknown",
+                },
+                source: "existing",
+            };
+        }
+    }
+    const result = await input.performDeviceFlow(input.keycloakUrl, input.realm, "spekn-cli", { stdout: input.stdout, stderr: input.stderr });
+    const { credentials, user } = buildCredentialsFromDeviceFlow({
+        result,
+        keycloakUrl: input.keycloakUrl,
+        realm: input.realm,
+    });
+    input.credentialsStore.save(credentials);
+    return {
+        accessToken: result.accessToken,
+        credentials,
+        user,
+        source: "device_flow",
+    };
+}
+/**
+ * Resolve effective organization context:
+ * stored credentials first, then env, then API discovery fallback.
+ */
+async function resolveOrganizationId(input) {
+    if (input.existingOrganizationId) {
+        return input.existingOrganizationId;
+    }
+    if (input.envOrganizationId) {
+        return input.envOrganizationId;
+    }
+    try {
+        const orgs = await input.fetchOrganizations();
+        if (orgs.length === 0)
+            return undefined;
+        if (orgs.length > 1 && input.stdout) {
+            input.stdout.write(`\nYou belong to ${orgs.length} organizations:\n`);
+            for (const org of orgs) {
+                input.stdout.write(`  - ${org.name} (${org.id})\n`);
+            }
+            input.stdout.write(`\nAuto-selected first organization. Use SPEKN_ORGANIZATION_ID to override.\n`);
+        }
+        return orgs[0]?.id;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/auth-login.d.ts

@@ -0,0 +1,34 @@
+#!/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;
+/**
+ * Decode the payload of a JWT access token without verification.
+ * Returns the raw claims object, or null if decoding fails.
+ */
+declare function decodeJwtPayload(token: string): Record<string, unknown> | null;
+export declare function runAuthLoginCli(args: string[], deps?: Partial<Deps>): Promise<number>;
+declare function main(): Promise<void>;
+export { main, parseArgs, decodeJwtPayload };