propr-cli 0.8.3

package/dist/commands/initCommands.js

@@ -0,0 +1,167 @@
+/**
+ * Local repository initialization command.
+ *
+ * Scaffolds the .propr directory used by ProPR agent execution containers.
+ */
+import { Command } from "commander";
+import path from "path";
+import { chmod, mkdir, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import { printOutput } from "../utils/io.js";
+import { createInitStackCommand } from "./initStack.js";
+const SETUP_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+# This hook runs before each ProPR implementation execution.
+# Available environment variables:
+#   PROPR_WORKSPACE   Mounted repository path inside the agent container
+#   PROPR_CACHE_DIR   Writable cache directory outside the repository
+#   PROPR_AGENT_TYPE  claude, codex, antigravity, opencode, or vibe
+
+cd "$PROPR_WORKSPACE"
+
+if [ -f ".propr/package.json" ]; then
+  export npm_config_cache="$PROPR_CACHE_DIR/npm"
+  mkdir -p "$npm_config_cache"
+
+  cd ".propr"
+  if [ -f "package-lock.json" ]; then
+    npm ci
+  else
+    npm install
+  fi
+fi
+
+# Example for Alpine-based agent images:
+# sudo apk add --no-cache jq
+`;
+const PACKAGE_JSON = `{
+  "name": "propr-repo-tools",
+  "private": true,
+  "version": "0.0.0",
+  "description": "Repository-local tools installed before ProPR agent executions",
+  "dependencies": {}
+}
+`;
+const GITIGNORE = `node_modules/
+cache/
+.cache/
+`;
+const README = `# ProPR Repository Setup
+
+This directory configures repository-local setup for ProPR agent executions.
+
+Before each implementation execution, ProPR runs:
+
+\`\`\`bash
+.propr/setup.sh
+\`\`\`
+
+Use \`.propr/package.json\` for npm packages that agents need while working in this repository.
+Use \`sudo apk add --no-cache <package>\` in \`setup.sh\` for Alpine system packages.
+
+Runtime caches and installed packages should stay out of commits.
+`;
+const SCAFFOLD_FILES = [
+    { relativePath: "setup.sh", content: SETUP_SH, mode: 0o755 },
+    { relativePath: "package.json", content: PACKAGE_JSON },
+    { relativePath: ".gitignore", content: GITIGNORE },
+    { relativePath: "README.md", content: README },
+];
+export async function scaffoldProprDirectory(options = {}) {
+    const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+    const proprDir = path.join(cwd, ".propr");
+    const result = {
+        directory: proprDir,
+        created: [],
+        skipped: [],
+        overwritten: [],
+    };
+    await mkdir(proprDir, { recursive: true });
+    for (const file of SCAFFOLD_FILES) {
+        const filePath = path.join(proprDir, file.relativePath);
+        const exists = existsSync(filePath);
+        if (exists && !options.force) {
+            result.skipped.push(file.relativePath);
+            continue;
+        }
+        await writeFile(filePath, file.content, "utf-8");
+        if (file.mode !== undefined) {
+            await chmod(filePath, file.mode);
+        }
+        if (exists) {
+            result.overwritten.push(file.relativePath);
+        }
+        else {
+            result.created.push(file.relativePath);
+        }
+    }
+    return result;
+}
+function displayInitResult(result) {
+    console.log(`Initialized ProPR repository setup at: ${result.directory}`);
+    if (result.created.length > 0) {
+        console.log(`Created: ${result.created.join(", ")}`);
+    }
+    if (result.overwritten.length > 0) {
+        console.log(`Overwritten: ${result.overwritten.join(", ")}`);
+    }
+    if (result.skipped.length > 0) {
+        console.log(`Skipped existing files: ${result.skipped.join(", ")}`);
+        console.log("Use --force to overwrite existing scaffold files.");
+    }
+    console.log("");
+    console.log("Add npm packages with:");
+    console.log("  cd .propr && npm install <package>");
+    console.log("");
+    console.log("Add system packages by editing .propr/setup.sh:");
+    console.log("  sudo apk add --no-cache <package>");
+}
+async function runRepoScaffold(options) {
+    try {
+        const result = await scaffoldProprDirectory({ force: options.force });
+        if (printOutput(result, !!options.json)) {
+            return;
+        }
+        displayInitResult(result);
+    }
+    catch (error) {
+        console.error(`Error initializing .propr directory: ${error.message}`);
+        process.exit(1);
+    }
+}
+export function createInitCommand() {
+    const command = new Command("init");
+    // Default action (no subcommand) scaffolds the .propr repo files — preserved
+    // for backward compatibility.
+    command
+        .description("Scaffold local setup. Default/`repo`: .propr files. `stack`: a stack root.")
+        .option("-f, --force", "Overwrite existing scaffold files")
+        .option("-j, --json", "Output result as JSON")
+        .addHelpText("after", `
+Subcommands:
+  $ propr init            Scaffold .propr repository setup files (default)
+  $ propr init repo       Same as the default — scaffold .propr files
+  $ propr init stack      Scaffold a local stack root (.env, data/, logs/, repos/)
+
+Examples:
+  $ propr init
+  $ propr init --force
+  $ propr init stack
+`)
+        .action(async (options) => {
+        await runRepoScaffold(options);
+    });
+    // Explicit alias for the default repo scaffold.
+    command
+        .command("repo")
+        .description("Scaffold .propr repository setup files in the current directory")
+        .option("-f, --force", "Overwrite existing scaffold files")
+        .option("-j, --json", "Output result as JSON")
+        .action(async (options) => {
+        await runRepoScaffold(options);
+    });
+    // New control-plane stack scaffold.
+    command.addCommand(createInitStackCommand());
+    return command;
+}

package/dist/commands/initStack.js

@@ -0,0 +1,193 @@
+/**
+ * `propr init stack`
+ *
+ * Scaffolds a local control-plane stack root: copies .env from .env.example,
+ * creates data/, logs/ and repos/, detects host agent-credential directories and
+ * records them as HOST_*_DIR, and saves the stack root to the CLI config so the
+ * other control-plane commands can find it.
+ */
+import { Command } from "commander";
+import { existsSync, copyFileSync, chmodSync, mkdirSync, readFileSync, appendFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { createConfigManager } from "../config/index.js";
+/** Resolve the bundled .env.example, falling back to a repo checkout. */
+function resolveEnvExample() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // Bundled copy is renamed to avoid npm's .env* exclusion from tarballs.
+    const bundled = join(here, "..", "assets", "env.example.txt");
+    if (existsSync(bundled))
+        return bundled;
+    const bundledLegacy = join(here, "..", "assets", ".env.example");
+    if (existsSync(bundledLegacy))
+        return bundledLegacy;
+    let dir = here;
+    for (let i = 0; i < 8; i += 1) {
+        const candidate = join(dir, ".env.example");
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+/** Detect host agent-credential directories that exist on this machine. */
+function detectCredentials() {
+    const home = homedir();
+    const candidates = [
+        { envKey: "HOST_CLAUDE_DIR", path: join(home, ".claude") },
+        { envKey: "HOST_CODEX_DIR", path: join(home, ".codex") },
+        { envKey: "HOST_ANTIGRAVITY_DIR", path: join(home, ".gemini") },
+        { envKey: "HOST_OPENCODE_XDG_DIR", path: join(home, ".config", "opencode") },
+        { envKey: "HOST_OPENCODE_DATA_DIR", path: join(home, ".local", "share", "opencode") },
+        { envKey: "HOST_VIBE_DIR", path: join(home, ".vibe") },
+    ];
+    // Only keep dirs that exist and are safe as Docker bind mounts (no ':').
+    return candidates.filter((c) => existsSync(c.path) && !c.path.includes(":"));
+}
+export async function scaffoldStack(options = {}) {
+    const rootDir = resolve(options.root ?? process.cwd());
+    const envPath = join(rootDir, ".env");
+    const result = {
+        rootDir,
+        envCreated: false,
+        envSkipped: false,
+        envBackedUp: false,
+        dirsCreated: [],
+        detected: [],
+        credentialsAppended: false,
+        pendingCredentials: [],
+    };
+    mkdirSync(rootDir, { recursive: true });
+    // 1. data/logs/repos directories
+    for (const sub of ["data", "logs", "repos"]) {
+        const dir = join(rootDir, sub);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+            result.dirsCreated.push(sub);
+        }
+    }
+    // 2. .env from .env.example
+    if (existsSync(envPath) && !options.force) {
+        result.envSkipped = true;
+    }
+    else {
+        const example = resolveEnvExample();
+        if (!example) {
+            throw new Error("Could not locate .env.example. Run `npm run build` in packages/cli, or run from a ProPR source checkout.");
+        }
+        if (options.force && existsSync(envPath)) {
+            const bakPath = `${envPath}.bak`;
+            copyFileSync(envPath, bakPath);
+            try {
+                chmodSync(bakPath, 0o600);
+            }
+            catch { /* best-effort */ }
+            result.envBackedUp = true;
+        }
+        copyFileSync(example, envPath);
+        try {
+            chmodSync(envPath, 0o600);
+        }
+        catch {
+            // Best-effort — may fail on Windows or non-owned files.
+        }
+        result.envCreated = true;
+    }
+    // 3. Detect credential dirs and record any not already present in .env.
+    //    When the .env was pre-existing (not created this run) and --force was
+    //    not given, collect but do NOT write — the caller should surface the
+    //    suggestions without silently mutating a user-managed file.
+    const detected = detectCredentials();
+    const envContent = readFileSync(envPath, "utf-8");
+    const toAppend = detected.filter((c) => {
+        const re = new RegExp(`^\\s*(export\\s+)?${c.envKey}\\s*=`, "m");
+        return !re.test(envContent);
+    });
+    if (toAppend.length > 0 && !result.envSkipped) {
+        const block = "\n# --- Host agent-credential directories (detected by `propr init stack`) ---\n" +
+            toAppend.map((c) => `${c.envKey}=${c.path}`).join("\n") +
+            "\n";
+        appendFileSync(envPath, block, "utf-8");
+        result.credentialsAppended = true;
+    }
+    else {
+        result.credentialsAppended = false;
+    }
+    result.detected = detected;
+    result.pendingCredentials = toAppend;
+    // 4. Persist the stack root so other commands can find it.
+    const configManager = await createConfigManager();
+    await configManager.setStackRoot(rootDir);
+    return result;
+}
+function displayResult(result) {
+    console.log(`Initialized ProPR stack at: ${result.rootDir}`);
+    if (result.dirsCreated.length > 0) {
+        console.log(`Created directories: ${result.dirsCreated.join(", ")}`);
+    }
+    if (result.envCreated && result.envBackedUp) {
+        console.log("Overwrote .env from .env.example (previous saved to .env.bak)");
+    }
+    else if (result.envCreated) {
+        console.log("Created .env from .env.example");
+    }
+    else if (result.envSkipped) {
+        console.log("Kept existing .env (use --force to overwrite)");
+    }
+    if (result.detected.length > 0) {
+        console.log("");
+        console.log("Detected agent credentials on this host:");
+        for (const c of result.detected) {
+            console.log(`  ${c.envKey}=${c.path}`);
+        }
+        if (!result.credentialsAppended && result.pendingCredentials.length > 0) {
+            console.log("");
+            console.log("The following credentials are not in .env yet. Add them manually or re-run with --force:");
+            for (const c of result.pendingCredentials) {
+                console.log(`  ${c.envKey}=${c.path}`);
+            }
+        }
+    }
+    else {
+        console.log("");
+        console.log("No agent credential directories detected (~/.claude, ~/.codex, ~/.gemini, ~/.config/opencode, ~/.vibe).");
+        console.log("Log in with an agent CLI on this host, then re-run `propr init stack`.");
+    }
+    console.log("");
+    console.log("Next steps:");
+    console.log("  1. Review and edit .env (GitHub credentials, ports, etc.)");
+    console.log("  2. propr check          # verify the environment");
+    console.log("  3. propr start          # launch the stack");
+}
+/** Creates the `init stack` subcommand. */
+export function createInitStackCommand() {
+    return new Command("stack")
+        .description("Scaffold a local stack root (.env, data/, logs/, repos/) and detect agent credentials")
+        .option("--root <dir>", "Stack root directory (default: current directory)")
+        .option("-f, --force", "Overwrite an existing .env")
+        .option("-j, --json", "Output result as JSON")
+        .addHelpText("after", `
+Examples:
+  $ propr init stack
+  $ propr init stack --root ~/propr
+  $ propr init stack --force
+`)
+        .action(async (options) => {
+        try {
+            const result = await scaffoldStack({ root: options.root, force: options.force });
+            if (options.json) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            displayResult(result);
+        }
+        catch (error) {
+            console.error(`Error initializing stack: ${error.message}`);
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/logCommands.js

@@ -0,0 +1,170 @@
+/**
+ * LLM Log Management Commands
+ *
+ * CLI commands for viewing LLM execution logs.
+ * Provides the `log` command group with the `list` subcommand.
+ */
+import { Command } from "commander";
+import { listLlmLogs } from "../api/index.js";
+import { printOutput } from "../utils/index.js";
+/**
+ * Truncates a string to a maximum length.
+ */
+function truncate(str, maxLen) {
+    if (!str)
+        return "-";
+    if (str.length <= maxLen)
+        return str;
+    return str.substring(0, maxLen - 3) + "...";
+}
+/**
+ * Formats a number with commas for readability.
+ */
+function formatNumber(num) {
+    if (num === null || num === undefined)
+        return "-";
+    return num.toLocaleString();
+}
+/**
+ * Formats tokens count (input + output).
+ */
+function formatTokens(input, output) {
+    const inputStr = input !== null && input !== undefined ? formatNumber(input) : "-";
+    const outputStr = output !== null && output !== undefined ? formatNumber(output) : "-";
+    if (inputStr === "-" && outputStr === "-") {
+        return "-";
+    }
+    return `${inputStr}/${outputStr}`;
+}
+/**
+ * Formats cost in USD.
+ */
+function formatCost(cost) {
+    if (cost === null || cost === undefined)
+        return "-";
+    if (cost < 0.01) {
+        return `$${cost.toFixed(4)}`;
+    }
+    return `$${cost.toFixed(2)}`;
+}
+/**
+ * Displays a table of LLM logs with clean formatting.
+ */
+function displayLogsTable(logs) {
+    if (logs.length === 0) {
+        console.log("No logs found.");
+        return;
+    }
+    const typeWidth = Math.max("Type".length, ...logs.map((l) => truncate(l.executionType, 15).length));
+    const modelWidth = Math.max("Model".length, ...logs.map((l) => truncate(l.modelName, 25).length));
+    const tokensWidth = Math.max("Tokens (In/Out)".length, ...logs.map((l) => formatTokens(l.inputTokens, l.outputTokens).length));
+    const costWidth = Math.max("Cost".length, ...logs.map((l) => formatCost(l.costUsd).length));
+    const header = [
+        "Type".padEnd(typeWidth),
+        "Model".padEnd(modelWidth),
+        "Tokens (In/Out)".padEnd(tokensWidth),
+        "Cost".padEnd(costWidth),
+    ].join("  ");
+    console.log(header);
+    console.log("-".repeat(header.length));
+    for (const log of logs) {
+        const row = [
+            truncate(log.executionType, 15).padEnd(typeWidth),
+            truncate(log.modelName, 25).padEnd(modelWidth),
+            formatTokens(log.inputTokens, log.outputTokens).padEnd(tokensWidth),
+            formatCost(log.costUsd).padEnd(costWidth),
+        ].join("  ");
+        console.log(row);
+    }
+}
+/**
+ * Creates the `log` command group.
+ */
+export function createLogCommand() {
+    const log = new Command("log")
+        .description("View LLM execution logs")
+        .addHelpText("after", `
+Examples:
+  $ propr log list                      # List recent logs
+  $ propr log list -m claude-sonnet-4-20250514  # Filter by model
+  $ propr log list --failed             # Show failures only
+`);
+    // log list
+    log
+        .command("list")
+        .description("List LLM execution logs for auditing, debugging, and cost analysis")
+        .option("-l, --limit <limit>", "Maximum number of logs to show", "50")
+        .option("-m, --model <model>", "Filter by model name")
+        .option("-t, --type <type>", "Filter by execution type")
+        .option("--page <page>", "Page number for pagination", "1")
+        .option("--success", "Show only successful executions")
+        .option("--failed", "Show only failed executions")
+        .option("--agent <alias>", "Filter by agent alias")
+        .option("--draft <draftId>", "Filter by draft/plan ID")
+        .option("-j, --json", "Output as JSON for programmatic use")
+        .addHelpText("after", `
+Examples:
+  $ propr log list                            # List recent logs
+  $ propr log list -l 100 --page 2            # Paginated results
+  $ propr log list -m claude-sonnet-4-20250514            # Filter by model
+  $ propr log list --failed                   # Show failures only
+  $ propr log list --draft abc123             # Filter by plan ID
+  $ propr log list --agent my-claude          # Filter by agent
+  $ propr log list --json                     # JSON output
+`)
+        .action(async (options) => {
+        try {
+            const listOptions = {};
+            const limit = parseInt(options.limit, 10);
+            if (!isNaN(limit) && limit > 0) {
+                listOptions.limit = Math.min(limit, 100);
+            }
+            const page = parseInt(options.page, 10);
+            if (!isNaN(page) && page > 0) {
+                listOptions.page = page;
+            }
+            if (options.model) {
+                listOptions.model = options.model;
+            }
+            if (options.type) {
+                listOptions.executionType = options.type;
+            }
+            if (options.success) {
+                listOptions.success = true;
+            }
+            else if (options.failed) {
+                listOptions.success = false;
+            }
+            if (options.agent) {
+                listOptions.agentAlias = options.agent;
+            }
+            if (options.draft) {
+                listOptions.draftId = options.draft;
+            }
+            const result = await listLlmLogs(listOptions);
+            if (printOutput(result, options.json ?? false)) {
+                return;
+            }
+            console.log("Fetching LLM logs...");
+            console.log("");
+            displayLogsTable(result.logs);
+            console.log("");
+            console.log(`Showing ${result.logs.length} of ${result.pagination.total} log(s) (page ${result.pagination.page}/${result.pagination.totalPages})`);
+            if (result.pagination.hasNextPage) {
+                console.log(`Use --page ${result.pagination.page + 1} to see more results`);
+            }
+        }
+        catch (error) {
+            const errorMessage = error.message;
+            if (errorMessage.includes("401") ||
+                errorMessage.includes("unauthorized")) {
+                console.error("Error: Unauthorized. Please run 'propr login' first.");
+            }
+            else {
+                console.error(`Error listing logs: ${errorMessage}`);
+            }
+            process.exit(1);
+        }
+    });
+    return log;
+}