propr-cli 0.8.3

package/dist/config/ConfigManager.js

@@ -0,0 +1,360 @@
+/**
+ * CLI Configuration Manager
+ *
+ * Manages persistent configuration for the CLI, storing settings in a JSON file
+ * located in the user's home directory (~/.propr/config.json).
+ *
+ * Features:
+ * - Reads and writes configuration to a JSON file
+ * - Handles missing configuration files gracefully
+ * - Handles corrupted configuration files with fallback behavior
+ * - Provides type-safe getter and setter methods
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { DEFAULT_CONFIG } from "./types.js";
+/**
+ * Default configuration directory name.
+ */
+const CONFIG_DIR_NAME = ".propr";
+/**
+ * Default configuration file name.
+ */
+const CONFIG_FILE_NAME = "config.json";
+/**
+ * ConfigManager handles persistent CLI configuration.
+ */
+export class ConfigManager {
+    configDir;
+    configFilePath;
+    config;
+    initialized = false;
+    /**
+     * Creates a new ConfigManager instance.
+     *
+     * @param customConfigDir - Optional custom configuration directory path.
+     *                          Defaults to ~/.propr
+     */
+    constructor(customConfigDir) {
+        this.configDir = customConfigDir ?? path.join(os.homedir(), CONFIG_DIR_NAME);
+        this.configFilePath = path.join(this.configDir, CONFIG_FILE_NAME);
+        this.config = { ...DEFAULT_CONFIG };
+    }
+    /**
+     * Initializes the ConfigManager by loading the configuration file.
+     * This method is idempotent and safe to call multiple times.
+     *
+     * @returns A promise that resolves when initialization is complete.
+     */
+    async init() {
+        if (this.initialized) {
+            return;
+        }
+        await this.load();
+        this.initialized = true;
+    }
+    /**
+     * Ensures the configuration directory exists.
+     *
+     * @returns A promise that resolves when the directory exists.
+     */
+    async ensureConfigDir() {
+        try {
+            await fs.promises.mkdir(this.configDir, { recursive: true });
+        }
+        catch (error) {
+            // Directory already exists or other error
+            if (error.code !== "EEXIST") {
+                throw error;
+            }
+        }
+    }
+    /**
+     * Loads the configuration from the file.
+     * If the file doesn't exist, uses default values.
+     * If the file is corrupted, resets to defaults and warns the user.
+     *
+     * @returns A promise that resolves when the configuration is loaded.
+     */
+    async load() {
+        try {
+            const data = await fs.promises.readFile(this.configFilePath, "utf-8");
+            const parsed = JSON.parse(data);
+            // Validate that parsed data is an object
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                console.warn(`Warning: Configuration file at ${this.configFilePath} contains invalid data. Using defaults.`);
+                this.config = { ...DEFAULT_CONFIG };
+                return this.config;
+            }
+            // Merge with defaults to ensure all keys are present
+            this.config = {
+                ...DEFAULT_CONFIG,
+                ...this.sanitizeConfig(parsed),
+            };
+            return this.config;
+        }
+        catch (error) {
+            const err = error;
+            if (err.code === "ENOENT") {
+                // File doesn't exist - use defaults (this is normal on first run)
+                this.config = { ...DEFAULT_CONFIG };
+                return this.config;
+            }
+            if (err instanceof SyntaxError) {
+                // JSON parsing error - corrupted file
+                console.warn(`Warning: Configuration file at ${this.configFilePath} is corrupted (invalid JSON). Using defaults.`);
+                this.config = { ...DEFAULT_CONFIG };
+                return this.config;
+            }
+            // Other errors (permission issues, etc.)
+            console.warn(`Warning: Could not read configuration file at ${this.configFilePath}: ${err.message}. Using defaults.`);
+            this.config = { ...DEFAULT_CONFIG };
+            return this.config;
+        }
+    }
+    /**
+     * Sanitizes the loaded configuration to ensure only valid keys are included.
+     *
+     * @param data - The raw parsed configuration data.
+     * @returns A sanitized configuration object.
+     */
+    sanitizeConfig(data) {
+        const sanitized = {};
+        if (typeof data.githubToken === "string") {
+            sanitized.githubToken = data.githubToken;
+        }
+        if (typeof data.remoteUrl === "string") {
+            sanitized.remoteUrl = data.remoteUrl;
+        }
+        if (typeof data.defaultProject === "string") {
+            sanitized.defaultProject = data.defaultProject;
+        }
+        if (typeof data.stackRoot === "string") {
+            sanitized.stackRoot = data.stackRoot;
+        }
+        if (typeof data.uiEnabled === "boolean") {
+            sanitized.uiEnabled = data.uiEnabled;
+        }
+        if (typeof data.docsEnabled === "boolean") {
+            sanitized.docsEnabled = data.docsEnabled;
+        }
+        return sanitized;
+    }
+    /**
+     * Saves the current configuration to the file.
+     *
+     * @returns A promise that resolves when the configuration is saved.
+     */
+    async save() {
+        await this.ensureConfigDir();
+        // Only write non-undefined values
+        const dataToWrite = {};
+        for (const [key, value] of Object.entries(this.config)) {
+            if (value !== undefined) {
+                dataToWrite[key] = value;
+            }
+        }
+        const content = JSON.stringify(dataToWrite, null, 2);
+        await fs.promises.writeFile(this.configFilePath, content, "utf-8");
+    }
+    /**
+     * Gets a configuration value by key.
+     *
+     * @param key - The configuration key to retrieve.
+     * @returns The configuration value, or undefined if not set.
+     */
+    get(key) {
+        return this.config[key];
+    }
+    /**
+     * Sets a configuration value by key.
+     *
+     * @param key - The configuration key to set.
+     * @param value - The value to set.
+     * @returns A promise that resolves when the value is saved.
+     */
+    async set(key, value) {
+        this.config[key] = value;
+        await this.save();
+    }
+    /**
+     * Gets the GitHub token.
+     *
+     * @returns The GitHub token, or undefined if not set.
+     */
+    getGithubToken() {
+        return this.get("githubToken");
+    }
+    /**
+     * Sets the GitHub token.
+     *
+     * @param token - The GitHub token to set.
+     * @returns A promise that resolves when the token is saved.
+     */
+    async setGithubToken(token) {
+        await this.set("githubToken", token);
+    }
+    /**
+     * Clears the GitHub token.
+     *
+     * @returns A promise that resolves when the token is cleared.
+     */
+    async clearGithubToken() {
+        await this.set("githubToken", undefined);
+    }
+    /**
+     * Gets the remote API URL.
+     *
+     * @returns The remote URL, or undefined if not set.
+     */
+    getRemoteUrl() {
+        return this.get("remoteUrl");
+    }
+    /**
+     * Sets the remote API URL.
+     *
+     * @param url - The remote URL to set.
+     * @returns A promise that resolves when the URL is saved.
+     */
+    async setRemoteUrl(url) {
+        await this.set("remoteUrl", url);
+    }
+    /**
+     * Gets the default project.
+     *
+     * @returns The default project (owner/repo format), or undefined if not set.
+     */
+    getDefaultProject() {
+        return this.get("defaultProject");
+    }
+    /**
+     * Sets the default project.
+     *
+     * @param project - The default project to set (owner/repo format).
+     * @returns A promise that resolves when the project is saved.
+     */
+    async setDefaultProject(project) {
+        await this.set("defaultProject", project);
+    }
+    /**
+     * Gets the local stack root directory (where .env, data/, logs/, repos/ live).
+     *
+     * @returns The stack root path, or undefined if not set.
+     */
+    getStackRoot() {
+        return this.get("stackRoot");
+    }
+    /**
+     * Sets the local stack root directory.
+     *
+     * @param root - Absolute path to the stack root.
+     */
+    async setStackRoot(root) {
+        await this.set("stackRoot", root);
+    }
+    /**
+     * Gets the desired UI service state. Defaults to true when unset.
+     */
+    getUiEnabled() {
+        return this.get("uiEnabled") ?? true;
+    }
+    /**
+     * Sets the desired UI service state.
+     */
+    async setUiEnabled(enabled) {
+        await this.set("uiEnabled", enabled);
+    }
+    /**
+     * Gets the desired docs service state. Defaults to false when unset.
+     */
+    getDocsEnabled() {
+        return this.get("docsEnabled") ?? false;
+    }
+    /**
+     * Sets the desired docs service state.
+     */
+    async setDocsEnabled(enabled) {
+        await this.set("docsEnabled", enabled);
+    }
+    /**
+     * Gets all configuration values.
+     *
+     * @returns A copy of the current configuration.
+     */
+    getAll() {
+        return { ...this.config };
+    }
+    /**
+     * Resets the configuration to default values.
+     *
+     * @param persist - Whether to persist the reset to the file. Defaults to true.
+     * @returns A promise that resolves when the reset is complete.
+     */
+    async reset(persist = true) {
+        this.config = { ...DEFAULT_CONFIG };
+        if (persist) {
+            await this.save();
+        }
+    }
+    /**
+     * Deletes the configuration file.
+     *
+     * @returns A promise that resolves when the file is deleted.
+     */
+    async deleteConfigFile() {
+        try {
+            await fs.promises.unlink(this.configFilePath);
+        }
+        catch (error) {
+            const err = error;
+            if (err.code !== "ENOENT") {
+                throw error;
+            }
+            // File doesn't exist - nothing to delete
+        }
+        this.config = { ...DEFAULT_CONFIG };
+    }
+    /**
+     * Gets the path to the configuration file.
+     *
+     * @returns The configuration file path.
+     */
+    getConfigFilePath() {
+        return this.configFilePath;
+    }
+    /**
+     * Gets the path to the configuration directory.
+     *
+     * @returns The configuration directory path.
+     */
+    getConfigDir() {
+        return this.configDir;
+    }
+    /**
+     * Checks if the configuration file exists.
+     *
+     * @returns A promise that resolves to true if the file exists.
+     */
+    async configFileExists() {
+        try {
+            await fs.promises.access(this.configFilePath, fs.constants.F_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/**
+ * Creates and initializes a ConfigManager instance.
+ * This is a convenience function for one-off usage.
+ *
+ * @param customConfigDir - Optional custom configuration directory path.
+ * @returns A promise that resolves to an initialized ConfigManager.
+ */
+export async function createConfigManager(customConfigDir) {
+    const manager = new ConfigManager(customConfigDir);
+    await manager.init();
+    return manager;
+}

package/dist/config/index.js

@@ -0,0 +1,8 @@
+/**
+ * CLI Configuration Module
+ *
+ * Exports the ConfigManager and related types for managing
+ * persistent CLI configuration.
+ */
+export { ConfigManager, createConfigManager } from "./ConfigManager.js";
+export { DEFAULT_CONFIG } from "./types.js";

package/dist/config/types.js

@@ -0,0 +1,16 @@
+/**
+ * CLI Configuration Types
+ *
+ * These types define the configuration schema for the CLI.
+ */
+/**
+ * Default configuration values.
+ */
+export const DEFAULT_CONFIG = {
+    githubToken: undefined,
+    remoteUrl: undefined,
+    defaultProject: undefined,
+    stackRoot: undefined,
+    uiEnabled: undefined,
+    docsEnabled: undefined,
+};

package/dist/index.js

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { config } from "dotenv";
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { createConfigManager } from "./config/index.js";
+import { createIssueCommand, createPlanCommand, createTaskCommand, createRepoCommand, createAgentCommand, createSettingCommand, createLogCommand, createTodoCommand, createRemoteStatusCommand, createQueueCommand, createInitCommand, createCheckCommand, createStartCommand, createStackStatusCommand, createStopCommand, createUiCommand, createDocsCommand, createTankCommand, createRelayCommand, runChecks, printChecks, STACK_CONFIG_CHECK_NAME, } from "./commands/index.js";
+// Re-export configuration module for programmatic use
+export { ConfigManager, createConfigManager, DEFAULT_CONFIG, } from "./config/index.js";
+// Re-export API module for programmatic use
+export { ApiClient, createApiClient, createApiClientWithConfig, ApiError, UnauthorizedError, ForbiddenError, NotFoundError, BadRequestError, InternalServerError, NetworkError, TimeoutError, createApiError, } from "./api/index.js";
+// Re-export utilities module for programmatic use
+export { resolveProject, ProjectResolutionError, formatOutput, printOutput, readJsonInput, validateJsonFields, isPlainObject, JsonInputError, } from "./utils/index.js";
+// Load environment variables
+config();
+const packageJson = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8"));
+const program = new Command();
+program
+    .name("propr")
+    .description("ProPR control plane + backend client - run a local stack and implement GitHub issues with AI agents")
+    .version(packageJson.version ?? "0.0.0")
+    .option("-p, --project <project>", "Specify the target project (owner/repo)")
+    .addHelpText("before", `
+ProPR CLI - AI-Powered GitHub Issue Implementation
+
+Run a local ProPR Docker stack (check / init / start / status / stop) and
+drive the backend (plans, issues, tasks, repos, agents).
+`)
+    .addHelpText("after", `
+Quick Start (local stack):
+  $ propr                           Verify the environment (same as 'propr check')
+  $ propr init stack                Scaffold .env + data/logs/repos, detect agents
+  $ propr start                     Start the stack with a live dashboard
+  $ propr status                    Show local stack status
+  $ propr stop                      Stop the stack
+
+Quick Start (backend client):
+  $ propr remote <url>              Set the backend API URL
+  $ propr login <token>             Authenticate with GitHub
+  $ propr use <owner/repo>          Set default project
+  $ propr plan list                 View available implementation plans
+  $ propr issue implement <id>      Implement a GitHub issue
+
+JSON Output:
+  Most commands support --json (-j) for machine-readable output:
+  $ propr plan list --json
+  $ propr agent list -j
+
+Examples:
+  $ propr remote https://api.propr.example.com
+  $ propr login ghp_xxxxxxxxxxxx
+  $ propr use myorg/myrepo
+  $ propr plan create "Add dark mode toggle" --wait
+  $ propr issue implement abc123/1 --wait --auto-merge
+  $ propr task list -s processing
+  $ propr remote-status
+
+Command Groups:
+  Control Plane:  check, init [repo|stack], start, status, stop, ui, docs, tank
+  GitHub Relay:   relay [enroll|list|revoke]
+  Configuration:  remote, use, login, logout
+  Plans:          plan [create|list|get|delete|abort]
+  Implementation: issue [implement]
+  Tasks:          task [list|get|stop|delete|revert]
+  Repositories:   repo [list|add|remove|toggle|index|status]
+  Agents:         agent [list|add|enable|disable|delete]
+  Settings:       setting [get|update]
+  To-Dos:         todo [list|get|add|complete|delete]
+  Logs:           log [list]
+  Backend:        remote-status, queue
+
+For more information on a command, run:
+  $ propr <command> --help
+`);
+// Remote command - set the API base URL
+program
+    .command("remote <url>")
+    .description("Set the remote API base URL for ProPR backend")
+    .addHelpText("after", `
+Example:
+  $ propr remote https://api.propr.example.com
+`)
+    .action(async (url) => {
+    try {
+        const configManager = await createConfigManager();
+        await configManager.setRemoteUrl(url);
+        console.log(`Remote URL set to: ${url}`);
+        console.log(`Configuration saved to: ${configManager.getConfigFilePath()}`);
+    }
+    catch (error) {
+        console.error(`Error setting remote URL: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Use command - set the default project
+program
+    .command("use <project>")
+    .description("Set the default project (repository) for subsequent commands")
+    .addHelpText("after", `
+Argument:
+  project    Repository in owner/repo format (e.g., myorg/myrepo)
+
+Example:
+  $ propr use myorg/myrepo
+`)
+    .action(async (project) => {
+    try {
+        const configManager = await createConfigManager();
+        await configManager.setDefaultProject(project);
+        console.log(`Default project set to: ${project}`);
+        console.log(`Configuration saved to: ${configManager.getConfigFilePath()}`);
+    }
+    catch (error) {
+        console.error(`Error setting default project: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Login command - authenticate with GitHub
+program
+    .command("login [token]")
+    .description("Authenticate with GitHub (interactive via gh CLI, or provide a PAT)")
+    .addHelpText("after", `
+Argument:
+  token    GitHub Personal Access Token (optional)
+
+When no token is provided, the CLI uses 'gh' (GitHub CLI) to authenticate:
+  - If you're already logged in to gh, your token is used automatically
+  - If not, 'gh auth login' is launched interactively
+
+Examples:
+  $ propr login                       # Interactive login via gh CLI
+  $ propr login ghp_xxxxxxxxxxxx      # Use a PAT directly
+`)
+    .action(async (token) => {
+    try {
+        const configManager = await createConfigManager();
+        if (token) {
+            // Direct PAT flow
+            const validPrefixes = ["ghp_", "gho_", "ghu_", "ghs_", "ghr_"];
+            const hasValidPrefix = validPrefixes.some((prefix) => token.startsWith(prefix));
+            if (!hasValidPrefix && token.length < 40) {
+                console.warn("Warning: The provided token does not appear to be a valid GitHub token format.");
+                console.warn("GitHub personal access tokens typically start with 'ghp_'.");
+                console.log("");
+            }
+            await configManager.setGithubToken(token);
+            console.log("Authentication successful!");
+            console.log(`Token saved to: ${configManager.getConfigFilePath()}`);
+            return;
+        }
+        // Interactive flow via gh CLI
+        const { execSync, spawnSync } = await import("child_process");
+        // Check if gh is installed
+        try {
+            execSync("gh --version", { stdio: "ignore" });
+        }
+        catch {
+            console.error("Error: GitHub CLI (gh) is not installed.");
+            console.log("");
+            console.log("Install it from: https://cli.github.com");
+            console.log("");
+            console.log("Or provide a token directly:");
+            console.log("  $ propr login <token>");
+            process.exit(1);
+        }
+        // Try to get an existing token
+        try {
+            const existingToken = execSync("gh auth token", { encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] }).trim();
+            if (existingToken) {
+                await configManager.setGithubToken(existingToken);
+                console.log("Authenticated using existing gh CLI session.");
+                console.log(`Token saved to: ${configManager.getConfigFilePath()}`);
+                return;
+            }
+        }
+        catch {
+            // Not logged in yet — proceed to interactive login
+        }
+        // Launch interactive gh auth login
+        console.log("No existing gh session found. Starting interactive login...");
+        console.log("");
+        const result = spawnSync("gh", ["auth", "login", "-s", "repo,read:org"], {
+            stdio: "inherit",
+        });
+        if (result.status !== 0) {
+            console.error("Error: GitHub login failed or was cancelled.");
+            process.exit(1);
+        }
+        // Grab the token after successful login
+        const ghToken = execSync("gh auth token", { encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] }).trim();
+        if (!ghToken) {
+            console.error("Error: Could not retrieve token after login.");
+            process.exit(1);
+        }
+        await configManager.setGithubToken(ghToken);
+        console.log("");
+        console.log("Authentication successful!");
+        console.log(`Token saved to: ${configManager.getConfigFilePath()}`);
+    }
+    catch (error) {
+        console.error(`Error during login: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Logout command - clear the GitHub token
+program
+    .command("logout")
+    .description("Clear the stored GitHub token from configuration")
+    .addHelpText("after", `
+Example:
+  $ propr logout
+`)
+    .action(async () => {
+    try {
+        const configManager = await createConfigManager();
+        const existingToken = configManager.getGithubToken();
+        if (!existingToken) {
+            console.log("No token is currently configured.");
+            return;
+        }
+        await configManager.clearGithubToken();
+        console.log("Successfully logged out.");
+        console.log("GitHub token has been removed from configuration.");
+    }
+    catch (error) {
+        console.error(`Error clearing token: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Control-plane commands (local Docker stack)
+program.addCommand(createCheckCommand());
+program.addCommand(createStartCommand());
+program.addCommand(createStackStatusCommand());
+program.addCommand(createStopCommand());
+program.addCommand(createUiCommand());
+program.addCommand(createDocsCommand());
+program.addCommand(createTankCommand());
+program.addCommand(createRelayCommand());
+// Setup + backend client command groups
+program.addCommand(createInitCommand());
+program.addCommand(createPlanCommand());
+program.addCommand(createIssueCommand());
+program.addCommand(createTaskCommand());
+program.addCommand(createRepoCommand());
+program.addCommand(createAgentCommand());
+program.addCommand(createSettingCommand());
+program.addCommand(createLogCommand());
+program.addCommand(createTodoCommand());
+program.addCommand(createRemoteStatusCommand());
+program.addCommand(createQueueCommand());
+// Bare `propr` (no args): run the environment check, then hint at next steps.
+if (!process.argv.slice(2).length) {
+    void (async () => {
+        try {
+            const outcome = await runChecks();
+            printChecks(outcome);
+            console.log("");
+            if (outcome.results.some((r) => r.name === STACK_CONFIG_CHECK_NAME && r.status !== "ok")) {
+                console.log("Next: `propr init stack` to scaffold a stack, then `propr start`.");
+            }
+            else {
+                console.log("Next: `propr start` to launch the stack  ·  `propr --help` for all commands.");
+            }
+            process.exit(outcome.anyFail ? 1 : 0);
+        }
+        catch (error) {
+            console.error(`Error: ${error.message}`);
+            console.log("Run 'propr --help' for usage information.");
+            process.exit(1);
+        }
+    })();
+}
+else {
+    program.parse();
+}

package/dist/orchestrator/format.js

@@ -0,0 +1,31 @@
+/**
+ * Shared rendering for stack status — used by `propr status` (one-shot) and the
+ * `propr start` TUI's non-TTY fallback.
+ */
+export function stateGlyph(s) {
+    if (!s.exists)
+        return "·";
+    if (s.running)
+        return "●";
+    return "○";
+}
+/** A single padded status row, e.g. "● api          running   Up 3 minutes". */
+export function formatServiceRow(s, nameWidth) {
+    const glyph = stateGlyph(s);
+    const name = s.service.padEnd(nameWidth);
+    const state = (s.exists ? s.state : "absent").padEnd(10);
+    const detail = s.exists ? s.status : "not created";
+    const ports = s.ports ? `  ${s.ports}` : "";
+    return `${glyph} ${name} ${state} ${detail}${ports}`;
+}
+/** Full status table as a string. */
+export function renderStatusTable(status) {
+    const nameWidth = Math.max(...status.services.map((s) => s.service.length), 8);
+    const lines = [];
+    lines.push(`Stack: ${status.stack}   network: ${status.network}   ${status.running ? "running" : "stopped"}`);
+    lines.push("─".repeat(60));
+    for (const s of status.services) {
+        lines.push(formatServiceRow(s, nameWidth));
+    }
+    return lines.join("\n");
+}