@spekn/cli 1.0.0

package/dist/utils/cli-runtime.d.ts

@@ -0,0 +1,5 @@
+export declare function hasHelpFlag(args: string[]): boolean;
+export declare function errorMessage(error: unknown): string;
+export declare function runCliMain(main: (argv?: string[]) => Promise<number> | number, options?: {
+    errorPrefix?: string;
+}): Promise<void>;

package/dist/utils/cli-runtime.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasHelpFlag = hasHelpFlag;
+exports.errorMessage = errorMessage;
+exports.runCliMain = runCliMain;
+function hasHelpFlag(args) {
+    return args.includes("--help") || args.includes("-h");
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function runCliMain(main, options) {
+    try {
+        const exitCode = await main(process.argv.slice(2));
+        process.exit(exitCode);
+    }
+    catch (error) {
+        const prefix = options?.errorPrefix ? `${options.errorPrefix}: ` : "";
+        console.error(`${prefix}${errorMessage(error)}`);
+        process.exit(1);
+    }
+}

package/dist/utils/help-error.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Thrown when the user requests --help. Caught in the CLI main function
+ * to display usage information and exit cleanly.
+ */
+export declare class HelpRequestedError extends Error {
+    constructor();
+}

package/dist/utils/help-error.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HelpRequestedError = void 0;
+/**
+ * Thrown when the user requests --help. Caught in the CLI main function
+ * to display usage information and exit cleanly.
+ */
+class HelpRequestedError extends Error {
+    constructor() {
+        super("__HELP__");
+        this.name = "HelpRequestedError";
+    }
+}
+exports.HelpRequestedError = HelpRequestedError;

package/dist/utils/interaction.d.ts

@@ -0,0 +1,19 @@
+export interface InteractionSelectOption {
+    value: string;
+    label: string;
+}
+interface InteractionSelectRequest {
+    title: string;
+    message: string;
+    options: InteractionSelectOption[];
+    allowSkip?: boolean;
+    timeoutMs?: number;
+}
+/**
+ * Request a selection from an external automation controller over stdio.
+ * Protocol:
+ *   - emits a single line to stderr prefixed with "[spekn-interaction] "
+ *   - expects one JSON line on stdin: {"id":"...","value":"..."} or {"id":"...","skip":true}
+ */
+export declare function requestSelectionFromController(req: InteractionSelectRequest): Promise<string | "skip" | null>;
+export {};

package/dist/utils/interaction.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestSelectionFromController = requestSelectionFromController;
+function isJsonStdioMode() {
+    return process.env.SPEKN_INTERACTION_MODE === "json-stdio";
+}
+function readSingleLine(timeoutMs) {
+    return new Promise((resolve) => {
+        if (!process.stdin || process.stdin.destroyed) {
+            resolve(null);
+            return;
+        }
+        // In subprocess/pipe mode, use direct buffered reads to avoid readline
+        // edge-cases where line events can be dropped on fast close/EOF.
+        process.stdin.resume();
+        let buffer = "";
+        let settled = false;
+        const cleanup = () => {
+            process.stdin.off("data", onData);
+            process.stdin.off("end", onEnd);
+            process.stdin.off("error", onError);
+        };
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            cleanup();
+            resolve(value);
+        };
+        const onData = (chunk) => {
+            buffer += String(chunk);
+            const newlineIndex = buffer.search(/\r?\n|\r/);
+            if (newlineIndex >= 0) {
+                const line = buffer.slice(0, newlineIndex).trim();
+                settle(line);
+            }
+        };
+        const onEnd = () => settle(null);
+        const onError = () => settle(null);
+        const timer = setTimeout(() => settle(null), timeoutMs);
+        process.stdin.on("data", onData);
+        process.stdin.once("end", onEnd);
+        process.stdin.once("error", onError);
+    });
+}
+/**
+ * Request a selection from an external automation controller over stdio.
+ * Protocol:
+ *   - emits a single line to stderr prefixed with "[spekn-interaction] "
+ *   - expects one JSON line on stdin: {"id":"...","value":"..."} or {"id":"...","skip":true}
+ */
+async function requestSelectionFromController(req) {
+    if (!isJsonStdioMode()) {
+        return null;
+    }
+    const id = `select-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const timeoutMs = req.timeoutMs ?? 120000;
+    const payload = {
+        type: "spekn.interaction.request",
+        id,
+        kind: "select",
+        title: req.title,
+        message: req.message,
+        options: req.options,
+        allowSkip: req.allowSkip === true,
+    };
+    process.stderr.write(`[spekn-interaction] ${JSON.stringify(payload)}\n`);
+    const line = await readSingleLine(timeoutMs);
+    if (!line) {
+        return null;
+    }
+    let parsed = null;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || parsed.id !== id) {
+        return null;
+    }
+    if (parsed.skip === true && req.allowSkip) {
+        return "skip";
+    }
+    if (typeof parsed.value === "string") {
+        const allowed = new Set(req.options.map((option) => option.value));
+        if (allowed.has(parsed.value)) {
+            return parsed.value;
+        }
+    }
+    return null;
+}

package/dist/utils/structured-log.d.ts

@@ -0,0 +1,7 @@
+export type StructuredLogLevel = "debug" | "info" | "warn" | "error";
+export declare function appendCliStructuredLog(input: {
+    source: string;
+    level: StructuredLogLevel;
+    message: string;
+    details?: Record<string, unknown>;
+}): void;

package/dist/utils/structured-log.js

@@ -0,0 +1,112 @@
+"use strict";
+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.appendCliStructuredLog = appendCliStructuredLog;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const GLOBAL_CONFIG_PATH = path.join(os.homedir(), ".spekn", "config.json");
+const DEFAULT_GLOBAL_CONFIG = {
+    logging: {
+        enabled: false,
+        path: "~/.spekn/error.log",
+        level: "info",
+    },
+};
+const LOG_LEVEL_RANK = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+function expandHomePath(filePath) {
+    if (filePath === "~")
+        return os.homedir();
+    if (filePath.startsWith("~/"))
+        return path.join(os.homedir(), filePath.slice(2));
+    return filePath;
+}
+function loadGlobalContextConfig() {
+    try {
+        const raw = fs.readFileSync(GLOBAL_CONFIG_PATH, "utf-8");
+        const parsed = JSON.parse(raw);
+        const levelCandidate = parsed?.logging?.level;
+        const level = levelCandidate === "debug" ||
+            levelCandidate === "info" ||
+            levelCandidate === "warn" ||
+            levelCandidate === "error"
+            ? levelCandidate
+            : DEFAULT_GLOBAL_CONFIG.logging.level;
+        return {
+            logging: {
+                enabled: typeof parsed?.logging?.enabled === "boolean"
+                    ? parsed.logging.enabled
+                    : DEFAULT_GLOBAL_CONFIG.logging.enabled,
+                path: typeof parsed?.logging?.path === "string" && parsed.logging.path.trim().length > 0
+                    ? parsed.logging.path
+                    : DEFAULT_GLOBAL_CONFIG.logging.path,
+                level,
+            },
+        };
+    }
+    catch {
+        return DEFAULT_GLOBAL_CONFIG;
+    }
+}
+function appendCliStructuredLog(input) {
+    try {
+        const config = loadGlobalContextConfig();
+        if (!config.logging.enabled)
+            return;
+        if (LOG_LEVEL_RANK[input.level] < LOG_LEVEL_RANK[config.logging.level])
+            return;
+        const logPath = path.resolve(expandHomePath(config.logging.path));
+        fs.mkdirSync(path.dirname(logPath), { recursive: true, mode: 0o700 });
+        const payload = {
+            timestamp: new Date().toISOString(),
+            source: input.source,
+            level: input.level,
+            message: input.message,
+            details: input.details ?? {},
+        };
+        fs.appendFileSync(logPath, `${JSON.stringify(payload)}\n`, {
+            encoding: "utf-8",
+            mode: 0o600,
+        });
+    }
+    catch {
+        // best effort logging only
+    }
+}

package/dist/utils/trpc-url.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Shared utility for normalizing tRPC API URLs.
+ */
+export declare function normalizeTrpcUrl(apiUrl: string): string;

package/dist/utils/trpc-url.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeTrpcUrl = normalizeTrpcUrl;
+/**
+ * Shared utility for normalizing tRPC API URLs.
+ */
+function normalizeTrpcUrl(apiUrl) {
+    if (apiUrl.endsWith("/trpc")) {
+        return apiUrl;
+    }
+    if (apiUrl.endsWith("/")) {
+        return `${apiUrl}trpc`;
+    }
+    return `${apiUrl}/trpc`;
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@spekn/cli",
+  "version": "1.0.0",
+  "description": "Spekn CLI — Spec-Driven Development toolchain",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "spekn": "dist/main.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22",
+    "npm": ">=10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/spekn/spekn.git",
+    "directory": "packages/cli"
+  },
+  "keywords": [
+    "spekn",
+    "sdd",
+    "spec-driven-development",
+    "cli",
+    "specifications",
+    "ai-agents"
+  ],
+  "scripts": {
+    "build": "npm -w @spekn/tui run build && tsc --build && tsup && mkdir -p dist/tui && cp ../tui/dist/index.mjs dist/tui/index.mjs && mkdir -p dist/resources/prompts && cp -R src/resources/prompts/. dist/resources/prompts/",
+    "dev": "tsc --build --watch",
+    "clean": "rm -rf dist",
+    "project-delete": "ts-node src/commands/project-clean.ts"
+  },
+  "dependencies": {
+    "@inkjs/ui": "^2.0.0",
+    "@trpc/client": "^10.45.4",
+    "commander": "^14.0.3",
+    "ink": "^6.8.0",
+    "js-yaml": "^4.1.0",
+    "open": "^10.2.0",
+    "pg": "^8.18.0",
+    "react": "^19.2.0",
+    "typeorm": "^0.3.28",
+    "zustand": "^5.0.8",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@spekn/agents": "*",
+    "@spekn/bridge": "*",
+    "@spekn/check": "*",
+    "@spekn/shared": "*",
+    "@spekn/tui": "*",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}