@almightygpt/core 0.2.0

package/src/runs/types.ts

@@ -0,0 +1,98 @@
+/**
+ * Types for run metadata persisted in .almightygpt/runs/<id>/run.json.
+ *
+ * The run folder is the machine-readable side of the dual artifact strategy.
+ * It is gitignored by default — git holds the human review files only.
+ *
+ * run.json must contain enough information to:
+ *   - reproduce or re-render the run,
+ *   - audit what was sent to which provider,
+ *   - drive the future VS Code / dashboard / CLI history views.
+ */
+
+export type RunType =
+  | "review-diff"
+  | "review-path"
+  | "review-requirement"
+  | "review-worker-reviewer";
+
+export type RunStatus = "running" | "completed" | "failed" | "aborted_budget";
+
+export interface AgentMetrics {
+  agent: string;
+  role: "worker" | "reviewer" | "judge";
+  provider: string;
+  model: string;
+  tokensIn: number;
+  tokensOut: number;
+  costUsd: number;
+  latencyMs: number;
+}
+
+export interface RunMetadata {
+  /** Folder name: <YYYY-MM-DD-HHmmss>-<topic>-<random>. */
+  id: string;
+  /** Kind of run. */
+  type: RunType;
+  /** ISO timestamp when the run started. */
+  createdAt: string;
+  /** ISO timestamp when the run completed (or failed). */
+  finishedAt?: string;
+  /** Repo root absolute path. */
+  workspacePath: string;
+  /** Topic slug. */
+  topic: string;
+  /** Optional git context. */
+  git?: {
+    branch?: string;
+    commit?: string;
+    dirty: boolean;
+  };
+  /** What kicked off the run. */
+  input: {
+    source: "diff" | "diff-range" | "path" | "requirement-file" | "ask";
+    range?: string;
+    path?: string;
+  };
+  /** Agents that participated, with config snapshot. */
+  agents: { name: string; role: string; provider: string; enabled: boolean }[];
+  /** Adapter package versions. */
+  adapterVersions: { adapter: string; version: string }[];
+  /** Final status. */
+  status: RunStatus;
+  /** Per-agent metrics. */
+  metrics: AgentMetrics[];
+  /** Aggregate totals. */
+  totals: {
+    tokensIn: number;
+    tokensOut: number;
+    costUsd: number;
+    latencyMs: number;
+  };
+  /** Where the human-facing review file lives (relative to workspacePath). */
+  reviewPath?: string;
+  /** Where the context manifest lives (relative to the run folder). */
+  contextManifestPath?: string;
+  /** Optional error info if status is failed. */
+  error?: { name: string; message: string };
+  /** Budget caps that were in effect. */
+  budget: {
+    maxCostPerRunUsd: number;
+    maxTokensPerRun: number;
+  };
+  /** Human decision recorded via `almightygpt decide`. */
+  decision?: HumanDecision;
+}
+
+export type DecisionStatus =
+  | "approved"
+  | "needs_changes"
+  | "rejected"
+  | "deferred";
+
+export interface HumanDecision {
+  status: DecisionStatus;
+  note?: string;
+  decidedBy?: string;
+  decidedAt: string;
+}

package/src/templates/install.ts

@@ -0,0 +1,198 @@
+/**
+ * Convention Pack template installer.
+ *
+ * Given a target repo and a stack name, copy the template files from
+ * @almightygpt/templates into the target. Each file is checked against
+ * git status before being written; existing files are skipped unless
+ * `force` is set.
+ *
+ * Behavior intentionally narrow for MVP 1:
+ *   - One stack supported: "node-ts".
+ *   - No prompts, no diffing — caller decides force vs skip.
+ *   - Non-existent target files are written unconditionally.
+ *   - Existing tracked files are protected by `assertSafeToWrite`.
+ *   - Existing untracked files are surfaced as dirty too (intentional).
+ */
+
+import { mkdir, readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { assertSafeToWrite } from "../git/status.js";
+
+export interface InstallOptions {
+  /** Target repo root where the convention should be installed. */
+  targetDir: string;
+  /** Stack template name. MVP 1 only supports "node-ts". */
+  stack: string;
+  /** Overwrite without git-status safety check. Default false. */
+  force?: boolean;
+  /**
+   * For each existing file, rename it to `<file>.almighty-bak` and write the
+   * new template. Safer than --force when upgrading an existing install.
+   * If a `.almighty-bak` already exists, the second backup is suffixed with
+   * a counter (e.g. `.almighty-bak.2`). Default false.
+   */
+  backup?: boolean;
+  /** Plan only — log what would happen, write nothing. Default false. */
+  dryRun?: boolean;
+}
+
+export interface InstallResult {
+  written: string[];
+  skipped: { path: string; reason: string }[];
+  /** Files that were backed up before being overwritten. */
+  backedUp: { from: string; to: string }[];
+}
+
+const __filename = fileURLToPath(import.meta.url);
+// In dev (ts-node-esm) and in built form, the templates package lives at the
+// same monorepo root. Find it by walking up until we hit packages/templates.
+function findTemplatesRoot(stack: string): string {
+  // From packages/core/dist/templates/install.js → up to monorepo root.
+  let cur = dirname(__filename);
+  for (let i = 0; i < 8; i++) {
+    const candidate = join(cur, "..", "templates");
+    if (existsSync(join(candidate, "package.json"))) {
+      const distRoot = join(candidate, "dist", stack);
+      const srcRoot = join(candidate, "src", stack);
+      if (existsSync(distRoot)) return distRoot;
+      if (existsSync(srcRoot)) return srcRoot;
+    }
+    cur = join(cur, "..");
+  }
+  throw new Error(
+    `Could not locate @almightygpt/templates for stack "${stack}". ` +
+      `Searched relative to ${__filename}. Did you forget to run \`npm run build\`?`,
+  );
+}
+
+/**
+ * Recursively walk a directory and return relative paths of every file.
+ */
+async function walk(root: string, prefix = ""): Promise<string[]> {
+  const entries = await readdir(root, { withFileTypes: true });
+  const out: string[] = [];
+  for (const entry of entries) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    const abs = join(root, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...(await walk(abs, rel)));
+    } else if (entry.isFile()) {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+export async function installTemplate(
+  options: InstallOptions,
+): Promise<InstallResult> {
+  const {
+    targetDir,
+    stack,
+    force = false,
+    backup = false,
+    dryRun = false,
+  } = options;
+
+  const sourceRoot = findTemplatesRoot(stack);
+  const files = await walk(sourceRoot);
+
+  const written: string[] = [];
+  const skipped: { path: string; reason: string }[] = [];
+  const backedUp: { from: string; to: string }[] = [];
+
+  for (const rel of files) {
+    // Some template paths use a sentinel "almightygpt" folder because dotfile
+    // folders can be awkward to author. Translate it to ".almightygpt" at
+    // install time.
+    const destRel = rel.replace(/(^|\/)almightygpt(\/|$)/, "$1.almightygpt$2");
+    const srcAbs = join(sourceRoot, rel);
+    const destAbs = join(targetDir, destRel);
+
+    // Decision tree for existing destination files:
+    //   --backup: rename existing → <file>.almighty-bak, then write new
+    //   --force:  overwrite (still respects dirty check unless force=true)
+    //   default:  skip with reason "already exists" — safest behavior
+    if (existsSync(destAbs)) {
+      if (backup) {
+        // Backup mode: even if the file is dirty, preserve it via rename.
+        // No git-status check needed because we're not destroying anything.
+        if (dryRun) {
+          written.push(destRel);
+          continue;
+        }
+        const backupRel = await pickBackupPath(destRel, targetDir);
+        const backupAbs = join(targetDir, backupRel);
+        await rename(destAbs, backupAbs);
+        backedUp.push({ from: destRel, to: backupRel });
+        // Fall through to write the new version below.
+      } else {
+        try {
+          await assertSafeToWrite(targetDir, destRel, force);
+          // Tracked and clean (or --force without --backup): skip by default.
+          // --force is required to actually overwrite a clean file.
+          if (!force) {
+            skipped.push({
+              path: destRel,
+              reason: "already exists (use --backup or --force to update)",
+            });
+            continue;
+          }
+        } catch (err) {
+          skipped.push({
+            path: destRel,
+            reason:
+              err instanceof Error ? err.message.split("\n")[0]! : String(err),
+          });
+          continue;
+        }
+      }
+    }
+
+    if (dryRun) {
+      written.push(destRel);
+      continue;
+    }
+
+    const content = await readFile(srcAbs);
+    await mkdir(dirname(destAbs), { recursive: true });
+    await writeFile(destAbs, content);
+    written.push(destRel);
+  }
+
+  return { written, skipped, backedUp };
+}
+
+/**
+ * Find a free `<file>.almighty-bak[.N]` slot for an existing file.
+ * Avoids overwriting a previous backup if the user runs --backup twice.
+ */
+async function pickBackupPath(
+  destRel: string,
+  targetDir: string,
+): Promise<string> {
+  const base = `${destRel}.almighty-bak`;
+  if (!existsSync(join(targetDir, base))) return base;
+  for (let i = 2; i < 1000; i++) {
+    const candidate = `${base}.${i}`;
+    if (!existsSync(join(targetDir, candidate))) return candidate;
+  }
+  throw new Error(`Could not find a free backup slot for ${destRel}.`);
+}
+
+export function relativeFromCwd(targetDir: string, absPath: string): string {
+  const rel = relative(targetDir, absPath);
+  return rel.startsWith("..") ? absPath : rel;
+}
+
+/** Stat helper used by callers that want to detect an existing install. */
+export async function hasExistingConfig(targetDir: string): Promise<boolean> {
+  try {
+    await stat(join(targetDir, ".almightygpt", "config.yaml"));
+    return true;
+  } catch {
+    return false;
+  }
+}