forgeos 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/forge/workspace/git-summary.ts

@@ -0,0 +1,279 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  categorizeFiles,
+  classifyChangeType,
+  compactFiles,
+  filterVolatileForgeState,
+  type CategorizedFileSummary,
+  type ChangeClassifier,
+  type FileListSummary,
+} from "./change-summary.ts";
+
+export interface WorkspaceGitSummary {
+  available: boolean;
+  branch?: string;
+  commit?: string;
+  changed: FileListSummary;
+  staged: FileListSummary;
+  unstaged: FileListSummary;
+  untracked: FileListSummary;
+  changeSummary: {
+    changed: CategorizedFileSummary;
+    staged: CategorizedFileSummary;
+    unstaged: CategorizedFileSummary;
+    untracked: CategorizedFileSummary;
+  };
+  error?: string;
+}
+
+function emptySummary(error?: string): WorkspaceGitSummary {
+  return {
+    available: false,
+    changed: compactFiles([]),
+    staged: compactFiles([]),
+    unstaged: compactFiles([]),
+    untracked: compactFiles([]),
+    changeSummary: {
+      changed: categorizeFiles([]),
+      staged: categorizeFiles([]),
+      unstaged: categorizeFiles([]),
+      untracked: categorizeFiles([]),
+    },
+    ...(error ? { error } : {}),
+  };
+}
+
+function runGit(
+  args: string[],
+  workspaceRoot: string,
+  options: { trim?: boolean } = {},
+): { ok: boolean; stdout: string; error?: string } {
+  const result = spawnSync("git", args, {
+    cwd: workspaceRoot,
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      stdout: "",
+      error: (result.stderr || result.stdout || "git command failed").trim(),
+    };
+  }
+  return { ok: true, stdout: options.trim === false ? result.stdout : result.stdout.trim() };
+}
+
+function pathspecLiteral(file: string): string {
+  return `:(literal)${file}`;
+}
+
+function diffTouchesOnlyGeneratedMetadata(diff: string): boolean {
+  let changedLines = 0;
+  for (const line of diff.split(/\r?\n/)) {
+    if (
+      line.startsWith("diff --git ") ||
+      line.startsWith("index ") ||
+      line.startsWith("@@ ") ||
+      line.startsWith("--- ") ||
+      line.startsWith("+++ ")
+    ) {
+      continue;
+    }
+    if (!line.startsWith("+") && !line.startsWith("-")) {
+      continue;
+    }
+    changedLines += 1;
+    if (!line.slice(1).trimStart().startsWith("// @forge-generated")) {
+      return false;
+    }
+  }
+  return changedLines > 0;
+}
+
+function generatedLineSet(text: string): Set<number> {
+  const generated = new Set<number>();
+  const lines = text.split(/\r?\n/);
+  if (lines[0]?.trimStart().startsWith("// @forge-generated")) {
+    generated.add(1);
+  }
+  let inGeneratedBlock = false;
+  lines.forEach((line, index) => {
+    const lineNumber = index + 1;
+    if (line.includes("<!-- forge-generated:start -->")) {
+      inGeneratedBlock = true;
+      generated.add(lineNumber);
+      return;
+    }
+    if (inGeneratedBlock) {
+      generated.add(lineNumber);
+    }
+    if (line.includes("<!-- forge-generated:end -->")) {
+      inGeneratedBlock = false;
+    }
+  });
+  return generated;
+}
+
+function headFileText(workspaceRoot: string, file: string): string | null {
+  const result = runGit(["show", `HEAD:${file}`], workspaceRoot, { trim: false });
+  return result.ok ? result.stdout : null;
+}
+
+function worktreeFileText(workspaceRoot: string, file: string): string | null {
+  try {
+    return readFileSync(join(workspaceRoot, file), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function parseHunkStart(header: string, marker: "-" | "+"): number {
+  const pattern = marker === "-"
+    ? /^@@ -(\d+)(?:,\d+)? \+\d+(?:,\d+)? @@/
+    : /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/;
+  const match = header.match(pattern);
+  return match ? Number(match[1]) : 1;
+}
+
+function diffTouchesOnlyGeneratedRegions(diff: string, oldText: string | null, newText: string | null): boolean {
+  if (!oldText || !newText) {
+    return diffTouchesOnlyGeneratedMetadata(diff);
+  }
+  const oldGenerated = generatedLineSet(oldText);
+  const newGenerated = generatedLineSet(newText);
+  if (oldGenerated.size === 0 && newGenerated.size === 0) {
+    return diffTouchesOnlyGeneratedMetadata(diff);
+  }
+
+  let changedLines = 0;
+  let oldLine = 1;
+  let newLine = 1;
+  for (const line of diff.split(/\r?\n/)) {
+    if (line.startsWith("@@ ")) {
+      oldLine = parseHunkStart(line, "-");
+      newLine = parseHunkStart(line, "+");
+      continue;
+    }
+    if (
+      line.startsWith("diff --git ") ||
+      line.startsWith("index ") ||
+      line.startsWith("--- ") ||
+      line.startsWith("+++ ")
+    ) {
+      continue;
+    }
+    if (line.startsWith("-")) {
+      changedLines += 1;
+      if (!oldGenerated.has(oldLine) && !line.slice(1).trimStart().startsWith("// @forge-generated")) {
+        return false;
+      }
+      oldLine += 1;
+      continue;
+    }
+    if (line.startsWith("+")) {
+      changedLines += 1;
+      if (!newGenerated.has(newLine) && !line.slice(1).trimStart().startsWith("// @forge-generated")) {
+        return false;
+      }
+      newLine += 1;
+      continue;
+    }
+    if (line.startsWith(" ")) {
+      oldLine += 1;
+      newLine += 1;
+    }
+  }
+  return changedLines > 0;
+}
+
+function generatedMetadataOnlyChange(workspaceRoot: string, file: string): boolean {
+  const pathspec = pathspecLiteral(file);
+  const diffs = [
+    runGit(["diff", "--unified=0", "--", pathspec], workspaceRoot, { trim: false }),
+    runGit(["diff", "--cached", "--unified=0", "--", pathspec], workspaceRoot, { trim: false }),
+  ]
+    .filter((result) => result.ok)
+    .map((result) => result.stdout)
+    .filter((stdout) => stdout.trim().length > 0);
+  const oldText = headFileText(workspaceRoot, file);
+  const newText = worktreeFileText(workspaceRoot, file);
+  return diffs.length > 0 && diffs.every((diff) => diffTouchesOnlyGeneratedRegions(diff, oldText, newText));
+}
+
+function workspaceChangeClassifier(workspaceRoot: string): ChangeClassifier {
+  const cache = new Map<string, ReturnType<ChangeClassifier>>();
+  return (file) => {
+    const cached = cache.get(file);
+    if (cached) {
+      return cached;
+    }
+    const baseType = classifyChangeType(file);
+    const type = baseType === "docs" && generatedMetadataOnlyChange(workspaceRoot, file)
+      ? "generated"
+      : baseType;
+    cache.set(file, type);
+    return type;
+  };
+}
+
+function parseStatusPath(line: string): string {
+  const raw = line.slice(2).trimStart();
+  const renamed = raw.split(" -> ");
+  return (renamed[renamed.length - 1] ?? raw).replace(/\\/g, "/");
+}
+
+export function buildWorkspaceGitSummary(workspaceRoot: string): WorkspaceGitSummary {
+  const root = runGit(["rev-parse", "--show-toplevel"], workspaceRoot);
+  if (!root.ok) {
+    return emptySummary(root.error);
+  }
+
+  const status = runGit(["status", "--porcelain=v1", "-uall"], workspaceRoot, { trim: false });
+  const branch = runGit(["rev-parse", "--abbrev-ref", "HEAD"], workspaceRoot);
+  const commit = runGit(["rev-parse", "--short", "HEAD"], workspaceRoot);
+  const lines = status.ok ? status.stdout.split(/\r?\n/).filter(Boolean) : [];
+  const staged: string[] = [];
+  const unstaged: string[] = [];
+  const untracked: string[] = [];
+
+  for (const line of lines) {
+    const x = line[0] ?? " ";
+    const y = line[1] ?? " ";
+    const file = parseStatusPath(line);
+    if (x === "?" && y === "?") {
+      untracked.push(file);
+      continue;
+    }
+    if (x !== " ") {
+      staged.push(file);
+    }
+    if (y !== " ") {
+      unstaged.push(file);
+    }
+  }
+
+  const stagedFiles = filterVolatileForgeState([...new Set(staged)].sort());
+  const unstagedFiles = filterVolatileForgeState([...new Set(unstaged)].sort());
+  const untrackedFiles = filterVolatileForgeState([...new Set(untracked)].sort());
+  const changedFiles = [...new Set([...stagedFiles, ...unstagedFiles, ...untrackedFiles])].sort();
+  const classify = workspaceChangeClassifier(workspaceRoot);
+
+  return {
+    available: true,
+    ...(branch.ok ? { branch: branch.stdout } : {}),
+    ...(commit.ok ? { commit: commit.stdout } : {}),
+    changed: compactFiles(changedFiles),
+    staged: compactFiles(stagedFiles),
+    unstaged: compactFiles(unstagedFiles),
+    untracked: compactFiles(untrackedFiles),
+    changeSummary: {
+      changed: categorizeFiles(changedFiles, 8, classify),
+      staged: categorizeFiles(stagedFiles, 8, classify),
+      unstaged: categorizeFiles(unstagedFiles, 8, classify),
+      untracked: categorizeFiles(untrackedFiles, 8, classify),
+    },
+    ...(status.ok ? {} : { error: status.error }),
+  };
+}

package/templates/agent-workroom/AGENTS.md

@@ -0,0 +1,29 @@
+# AGENTS.md
+
+This ForgeOS app is an agent workroom. External code agents edit the app in this
+directory while ForgeOS records context, hooks, checks, generated artifacts, and
+handoff state.
+
+Before editing:
+
+```bash
+forge dev --once --json
+forge agent print-context --json
+forge check --json
+```
+
+After editing:
+
+```bash
+forge generate
+forge check
+forge verify agent
+```
+
+Do not edit:
+
+- `src/forge/_generated/**`
+- `forge.lock`
+
+Use `forge studio attach . --target codex --preview-port 5174` to connect this
+workspace to Forge Studio.

package/templates/agent-workroom/README.md

@@ -0,0 +1,34 @@
+# __FORGE_APP_TITLE__
+
+An agent-native ForgeOS workroom. It is not a chat app. Codex, Claude Code, or
+Cursor work in this directory, while the UI shows the app preview, terminal-like
+agent signals, generated freshness, diff focus, checks, and handoff evidence
+collected by ForgeOS.
+
+## Run
+
+```bash
+__PACKAGE_MANAGER__ install
+__PACKAGE_MANAGER__ run generate
+__PACKAGE_MANAGER__ run dev
+```
+
+The workroom runs on the Forge web port. The app being built should normally run
+on the next port, for example `http://127.0.0.1:5174`.
+
+## Attach to Studio
+
+```bash
+forge studio attach . --target codex --preview-port 5174
+forge agent doctor --target codex
+```
+
+Agent hooks can feed the room through ForgeOS commands or `forge agent ingest`.
+
+The browser does not chat with an AI model. It observes:
+
+- the app preview, usually on `http://127.0.0.1:5174`;
+- hook or ingest events from the external code agent;
+- authored-vs-generated diff focus;
+- generated artifact state (`fresh`, `regenerated`, or `stale-risk`);
+- verification evidence from `forge check` / `forge verify agent`.

package/templates/agent-workroom/forge.config.ts

@@ -0,0 +1,3 @@
+export default {
+  sourceRoots: ["src"],
+};

package/templates/agent-workroom/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "__FORGE_APP_NAME__",
+  "private": true,
+  "type": "module",
+  "workspaces": [
+    "web"
+  ],
+  "packageManager": "__PACKAGE_MANAGER_SPEC__",
+  "scripts": {
+    "forge": "forge",
+    "generate": "forge generate",
+    "check": "forge check",
+    "verify": "forge verify agent",
+    "dev": "forge dev",
+    "dev:api": "forge dev --api-only",
+    "dev:web": "cd web && __PACKAGE_MANAGER__ run dev",
+    "typecheck": "tsc --noEmit && cd web && __PACKAGE_MANAGER__ run typecheck"
+  },
+  "dependencies": {
+    "@electric-sql/pglite": "^0.2.17",
+    "forge": "__FORGE_PACKAGE_SPEC__"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.7.3"
+  },
+  "forge": {
+    "template": "agent-workroom",
+    "sourceRoots": [
+      "src"
+    ]
+  }
+}

package/templates/agent-workroom/src/actions/indexAgentSignal.ts

@@ -0,0 +1,10 @@
+import { action } from "forge/server";
+
+export const indexAgentSignal = action({
+  event: "agent.signal.recorded",
+  handler: async (_ctx, event) => ({
+    ok: true,
+    indexed: true,
+    event,
+  }),
+});

package/templates/agent-workroom/src/commands/openWorkroom.ts

@@ -0,0 +1,61 @@
+import { can, command } from "forge/server";
+
+function text(value: unknown, fallback: string): string {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
+}
+
+function count(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+
+export const openWorkroom = command({
+  auth: can("workroom.write"),
+  handler: async (ctx, args) => {
+    const input = args as {
+      appName?: unknown;
+      appPath?: unknown;
+      previewUrl?: unknown;
+      previewStatus?: unknown;
+      previewStatusReason?: unknown;
+      agent?: unknown;
+      objective?: unknown;
+      generatedState?: unknown;
+      generatedChangedFiles?: unknown;
+      authoredFiles?: unknown;
+      generatedFiles?: unknown;
+      authoredDiffCommand?: unknown;
+      generatedDiffCommand?: unknown;
+      terminalCommand?: unknown;
+      terminalCwd?: unknown;
+    };
+    const now = new Date().toISOString();
+    const session = await ctx.db.agentSessions.insert({
+      appName: text(input.appName, "__FORGE_APP_TITLE__"),
+      appPath: text(input.appPath, "."),
+      previewUrl: text(input.previewUrl, "http://127.0.0.1:5174"),
+      previewStatus: text(input.previewStatus, "not-checked"),
+      previewStatusReason: text(input.previewStatusReason, "Preview has not been probed yet."),
+      agent: text(input.agent, "codex"),
+      status: "observing",
+      objective: text(input.objective, "External agent development session"),
+      generatedState: text(input.generatedState, "fresh"),
+      generatedChangedFiles: count(input.generatedChangedFiles),
+      authoredFiles: count(input.authoredFiles),
+      generatedFiles: count(input.generatedFiles),
+      authoredDiffCommand: text(input.authoredDiffCommand, 'git diff -- . ":(exclude)src/forge/_generated/**" ":(exclude)forge.lock"'),
+      generatedDiffCommand: text(input.generatedDiffCommand, "git diff -- src/forge/_generated forge.lock"),
+      terminalCommand: text(input.terminalCommand, "codex"),
+      terminalCwd: text(input.terminalCwd, "."),
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    await ctx.emit("workroom.opened", {
+      sessionId: session.id,
+      appName: session.appName,
+      agent: session.agent,
+    });
+
+    return session;
+  },
+});

package/templates/agent-workroom/src/commands/recordAgentSignal.ts

@@ -0,0 +1,119 @@
+import { can, command } from "forge/server";
+
+function text(value: unknown, fallback: string): string {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
+}
+
+function optionalText(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function optionalCount(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+export const recordAgentSignal = command({
+  auth: can("workroom.write"),
+  handler: async (ctx, args) => {
+    const input = args as {
+      sessionId?: unknown;
+      source?: unknown;
+      kind?: unknown;
+      title?: unknown;
+      detail?: unknown;
+      filesChanged?: unknown;
+      status?: unknown;
+      previewStatus?: unknown;
+      previewStatusReason?: unknown;
+      generatedState?: unknown;
+      generatedChangedFiles?: unknown;
+      authoredFiles?: unknown;
+      generatedFiles?: unknown;
+      authoredDiffCommand?: unknown;
+      generatedDiffCommand?: unknown;
+      terminalCommand?: unknown;
+      terminalCwd?: unknown;
+    };
+    let session =
+      typeof input.sessionId === "string" && input.sessionId.trim().length > 0
+        ? await ctx.db.agentSessions.get(input.sessionId)
+        : null;
+    if (!session) {
+      const sessions = await ctx.db.agentSessions.all();
+      session = sessions
+        .slice()
+        .sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)))[0] ?? null;
+    }
+    if (!session) {
+      const createdAt = new Date().toISOString();
+      session = await ctx.db.agentSessions.insert({
+        appName: "__FORGE_APP_TITLE__",
+        appPath: ".",
+        previewUrl: "http://127.0.0.1:5174",
+        previewStatus: "not-checked",
+        previewStatusReason: "Preview has not been probed yet.",
+        agent: "codex",
+        status: "observing",
+        objective: "External agent development session",
+        generatedState: "fresh",
+        generatedChangedFiles: 0,
+        authoredFiles: 0,
+        generatedFiles: 0,
+        authoredDiffCommand: 'git diff -- . ":(exclude)src/forge/_generated/**" ":(exclude)forge.lock"',
+        generatedDiffCommand: "git diff -- src/forge/_generated forge.lock",
+        terminalCommand: "codex",
+        terminalCwd: ".",
+        createdAt,
+        updatedAt: createdAt,
+      });
+    }
+    if (!session) {
+      throw new Error("session not found");
+    }
+
+    const now = new Date().toISOString();
+    const signal = await ctx.db.agentSignals.insert({
+      sessionId: session.id,
+      source: text(input.source, session.agent),
+      kind: text(input.kind, "hook"),
+      title: text(input.title, "Agent activity recorded"),
+      detail: text(input.detail, "A code agent changed the workspace."),
+      filesChanged: Array.isArray(input.filesChanged)
+        ? input.filesChanged.filter((file) => typeof file === "string").join(", ")
+        : text(input.filesChanged, ""),
+      status: text(input.status, "info"),
+      createdAt: now,
+    });
+
+    const update: Record<string, unknown> = {
+      status: signal.status === "error" ? "needs-attention" : "observing",
+      updatedAt: now,
+    };
+    for (const [key, value] of Object.entries({
+      previewStatus: optionalText(input.previewStatus),
+      previewStatusReason: optionalText(input.previewStatusReason),
+      generatedState: optionalText(input.generatedState),
+      generatedChangedFiles: optionalCount(input.generatedChangedFiles),
+      authoredFiles: optionalCount(input.authoredFiles),
+      generatedFiles: optionalCount(input.generatedFiles),
+      authoredDiffCommand: optionalText(input.authoredDiffCommand),
+      generatedDiffCommand: optionalText(input.generatedDiffCommand),
+      terminalCommand: optionalText(input.terminalCommand),
+      terminalCwd: optionalText(input.terminalCwd),
+    })) {
+      if (value !== undefined) {
+        update[key] = value;
+      }
+    }
+
+    await ctx.db.agentSessions.update(session.id, update);
+    await ctx.emit("agent.signal.recorded", {
+      sessionId: session.id,
+      signalId: signal.id,
+      kind: signal.kind,
+      status: signal.status,
+    });
+
+    return signal;
+  },
+});

package/templates/agent-workroom/src/commands/recordCheckRun.ts

@@ -0,0 +1,52 @@
+import { can, command } from "forge/server";
+
+function text(value: unknown, fallback: string): string {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
+}
+
+function duration(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+
+export const recordCheckRun = command({
+  auth: can("workroom.write"),
+  handler: async (ctx, args) => {
+    const input = args as {
+      sessionId?: unknown;
+      command?: unknown;
+      status?: unknown;
+      output?: unknown;
+      durationMs?: unknown;
+    };
+    const sessionId = text(input.sessionId, "");
+    if (!sessionId) {
+      throw new Error("sessionId is required");
+    }
+    const session = await ctx.db.agentSessions.get(sessionId);
+    if (!session) {
+      throw new Error("session not found");
+    }
+
+    const now = new Date().toISOString();
+    const run = await ctx.db.checkRuns.insert({
+      sessionId,
+      command: text(input.command, "forge check"),
+      status: text(input.status, "passed"),
+      output: text(input.output, ""),
+      durationMs: duration(input.durationMs),
+      createdAt: now,
+    });
+
+    await ctx.db.agentSessions.update(sessionId, {
+      status: run.status === "failed" ? "needs-attention" : "verified",
+      updatedAt: now,
+    });
+    await ctx.emit("check.run.recorded", {
+      sessionId,
+      runId: run.id,
+      status: run.status,
+    });
+
+    return run;
+  },
+});

package/templates/agent-workroom/src/forge/schema.ts

@@ -0,0 +1,54 @@
+import { defineTable } from "forge/server";
+
+export const agentSessions = defineTable({
+  name: "agentSessions",
+  fields: {
+    id: "uuid",
+    appName: "text",
+    appPath: "text",
+    previewUrl: "text",
+    previewStatus: "text",
+    previewStatusReason: "text",
+    agent: "text",
+    status: "text",
+    objective: "text",
+    generatedState: "text",
+    generatedChangedFiles: "number",
+    authoredFiles: "number",
+    generatedFiles: "number",
+    authoredDiffCommand: "text",
+    generatedDiffCommand: "text",
+    terminalCommand: "text",
+    terminalCwd: "text",
+    createdAt: "timestamp",
+    updatedAt: "timestamp",
+  },
+});
+
+export const agentSignals = defineTable({
+  name: "agentSignals",
+  fields: {
+    id: "uuid",
+    sessionId: "uuid",
+    source: "text",
+    kind: "text",
+    title: "text",
+    detail: "text",
+    filesChanged: "text",
+    status: "text",
+    createdAt: "timestamp",
+  },
+});
+
+export const checkRuns = defineTable({
+  name: "checkRuns",
+  fields: {
+    id: "uuid",
+    sessionId: "uuid",
+    command: "text",
+    status: "text",
+    output: "text",
+    durationMs: "number",
+    createdAt: "timestamp",
+  },
+});

package/templates/agent-workroom/src/policies.ts

@@ -0,0 +1,6 @@
+import { canRole, definePolicies } from "forge/policy";
+
+export const policies = definePolicies({
+  "workroom.read": canRole("owner", "admin", "member"),
+  "workroom.write": canRole("owner", "admin", "member"),
+});