@mytechtoday/augment-sdd 1.0.0

package/src/utils/detectCli.ts

@@ -0,0 +1,28 @@
+/**
+ * detectCli — checks whether a CLI binary is accessible on the system PATH.
+ *
+ * Uses the platform-appropriate tool (where on Windows, which on Unix) via
+ * runCli so that detection is non-interactive and consistent with all other
+ * CLI invocations in the extension.
+ */
+import { runCli } from './runCli';
+
+/**
+ * Returns `true` if `name` resolves to an executable on the system PATH,
+ * `false` otherwise.
+ *
+ * @param name  The CLI binary name to look up (e.g., "auggie", "openspec", "bd").
+ */
+export async function detectCli(name: string): Promise<boolean> {
+  // `where` (Windows) / `which` (Unix/macOS) exits 0 only when the binary is found.
+  const lookupCommand = process.platform === 'win32' ? 'where' : 'which';
+
+  try {
+    // Use the workspace root as cwd; any valid directory works for which/where.
+    await runCli(lookupCommand, [name], process.cwd(), 10_000);
+    return true;
+  } catch {
+    return false;
+  }
+}
+

package/src/utils/getConfig.ts

@@ -0,0 +1,25 @@
+/**
+ * getConfig — type-safe VS Code settings reader for the Augment SDD extension.
+ *
+ * All extension settings live under the "augmentSdd" namespace as declared in
+ * package.json `contributes.configuration`.  Callers provide a default value
+ * so they never receive `undefined` even when the setting is absent.
+ *
+ * Bead 9 wires this helper into every command; it is created here early so
+ * generateOpenSpec (Bead 5) and generateBeads (Bead 6) can use it immediately.
+ */
+import * as vscode from 'vscode';
+
+/**
+ * Read a value from the `augmentSdd` configuration scope.
+ *
+ * @param key           Setting key without the `augmentSdd.` prefix
+ *                      (e.g., `"jiraFolder"`, `"batchSize"`).
+ * @param defaultValue  Returned when the setting is absent or undefined.
+ * @returns             The configured value, or `defaultValue`.
+ */
+export function getConfig<T>(key: string, defaultValue: T): T {
+  const value = vscode.workspace.getConfiguration('augmentSdd').get<T>(key);
+  return value !== undefined ? value : defaultValue;
+}
+

package/src/utils/logger.ts

@@ -0,0 +1,42 @@
+/**
+ * logger.ts — Centralised logging for the Augment SDD extension.
+ *
+ * Separating the logger from extension.ts avoids circular-import issues when
+ * command modules import `log` / `revealOutputChannel` while extension.ts
+ * imports from those same command modules.
+ *
+ * Usage:
+ *   1. In extension.ts activate(): call initLogger(channel) immediately after
+ *      creating the OutputChannel.
+ *   2. Everywhere else: import { log, revealOutputChannel } from './logger'.
+ */
+import * as vscode from 'vscode';
+
+/** The shared OutputChannel instance, set by initLogger(). */
+let _channel: vscode.OutputChannel | undefined;
+
+/**
+ * Initialise the logger with the extension's shared OutputChannel.
+ * Must be called once in activate() before any other logging.
+ */
+export function initLogger(channel: vscode.OutputChannel): void {
+  _channel = channel;
+}
+
+/**
+ * Append a timestamped message to the Augment SDD Output Channel.
+ * Safe to call before initLogger() — the message is silently dropped.
+ */
+export function log(message: string): void {
+  const ts = new Date().toISOString();
+  _channel?.appendLine(`[${ts}] ${message}`);
+}
+
+/**
+ * Reveal the Augment SDD Output Channel in the VS Code UI and bring it
+ * into focus without stealing the editor focus.
+ */
+export function revealOutputChannel(): void {
+  _channel?.show(true);
+}
+

package/src/utils/runCli.ts

@@ -0,0 +1,102 @@
+/**
+ * runCli — reusable child_process.spawn wrapper for all augment-sdd commands.
+ *
+ * Design (D1): Uses spawn (not exec) to avoid memory caps and to enable
+ * deterministic timeout handling. execa is intentionally excluded to keep the
+ * runtime dependency footprint at zero.
+ *
+ * Design (D2): Centralises timeout, error formatting, and logging. The optional
+ * `logger` callback receives structured messages before and after each call so
+ * callers can route them to the Augment SDD Output Channel without this module
+ * depending on VS Code APIs.
+ */
+import * as cp from 'child_process';
+
+/** Maximum characters of the serialised args string written to the log. */
+const MAX_LOGGED_ARGS_CHARS = 500;
+
+/**
+ * Spawn `command` with `args` in `cwd`, collect stdout/stderr, and:
+ *  - Resolve with trimmed stdout on exit code 0.
+ *  - Reject with a descriptive Error on non-zero exit code.
+ *  - Kill the process and reject with a timeout Error when `timeoutMs` elapses.
+ *  - Reject immediately if the spawn itself emits an error (e.g., ENOENT).
+ *
+ * @param command    Executable name or path (passed to spawn with shell: true).
+ * @param args       Argument list. Prompt-like args are truncated in log output.
+ * @param cwd        Working directory for the spawned process.
+ * @param timeoutMs  Maximum allowed runtime in ms. Defaults to 120 000 ms.
+ * @param logger     Optional callback that receives structured log messages
+ *                   (pre-run, result, timeout, spawn-error). Timestamps should
+ *                   be added by the caller (e.g., the `log` helper in logger.ts).
+ */
+export function runCli(
+  command: string,
+  args: string[],
+  cwd: string,
+  timeoutMs: number = 120_000,
+  logger?: (message: string) => void
+): Promise<string> {
+  // Log the invocation with args truncated to avoid flooding the Output Channel
+  // with large Auggie prompts (spec: truncate prompt ≤ 500 chars in log entries).
+  const rawArgs = args.join(' ');
+  const displayArgs = rawArgs.length > MAX_LOGGED_ARGS_CHARS
+    ? rawArgs.slice(0, MAX_LOGGED_ARGS_CHARS) + '…'
+    : rawArgs;
+  logger?.(`Run: ${command} ${displayArgs}`);
+
+  return new Promise<string>((resolve, reject) => {
+    const proc = cp.spawn(command, args, { cwd, shell: true });
+
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+
+    /** Settle the promise at most once. */
+    function settle(action: () => void): void {
+      if (settled) { return; }
+      settled = true;
+      clearTimeout(timer);
+      action();
+    }
+
+    // Enforce a hard timeout: kill the process and reject with a clear message.
+    const timer = setTimeout(() => {
+      settle(() => {
+        proc.kill();
+        const msg = `CLI "${command} ${args.join(' ')}" timed out after ${timeoutMs} ms`;
+        logger?.(`Timeout after ${timeoutMs} ms | ${command}`);
+        reject(new Error(msg));
+      });
+    }, timeoutMs);
+
+    proc.stdout.on('data', (data: Buffer) => { stdout += data; });
+    proc.stderr.on('data', (data: Buffer) => { stderr += data; });
+
+    proc.on('close', (code: number | null) => {
+      settle(() => {
+        if (code === 0) {
+          logger?.(`Exit 0 | stdout: ${stdout.trim()}`);
+          resolve(stdout.trim());
+        } else {
+          const stderrTrimmed = stderr.trim();
+          logger?.(`Exit ${code} | stderr: ${stderrTrimmed}`);
+          reject(
+            new Error(
+              `CLI "${command} ${args.join(' ')}" failed with exit code ${code}\nStderr: ${stderrTrimmed}`
+            )
+          );
+        }
+      });
+    });
+
+    // Propagate spawn errors (e.g., ENOENT — binary not found) immediately.
+    proc.on('error', (err: Error) => {
+      settle(() => {
+        logger?.(`Spawn error: ${err.message}`);
+        reject(err);
+      });
+    });
+  });
+}
+

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "outDir": "./out",
+    "rootDir": "./src",
+    "sourceMap": true,
+    "strict": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", ".vscode-test"]
+}
+