forgeos 0.1.0-alpha.21 → 0.1.0-alpha.22

package/src/forge/cli/studio.ts

@@ -139,6 +139,15 @@ export interface StudioSnapshotResult {
     commands: string[];
     diffPlan?: DevConsoleDiffPlan;
   };
+  handoff: {
+    previewUrl: string;
+    currentSession?: { id?: string; title?: string; status?: string; confidence?: number };
+    changedFiles?: number;
+    generatedState?: string;
+    deltaHealth?: string;
+    agentContextCommand: string;
+    recommendedCommands: string[];
+  };
   proofs: {
     preview: StudioAttachResult["preview"]["status"];
     generated: StudioAttachResult["posture"]["generated"];
@@ -981,6 +990,13 @@ export async function runStudioSnapshotCommand(options: StudioAttachOptions): Pr
     : undefined;
   const delta = await runDeltaStatus(appRoot);
   const contextPacket = contextPacketFor({ appRoot, posture, commands });
+  const handoff = studioHandoffFor({
+    previewUrl: preview.url,
+    posture,
+    changed: changed.data,
+    delta,
+    commands,
+  });
   const gitState = (changed.data as { git?: { available?: boolean } }).git;
   const changedReadable = changed.ok || gitState?.available === false;
   const ok = posture.state !== "needs-attention" && changedReadable &&
@@ -1006,6 +1022,7 @@ export async function runStudioSnapshotCommand(options: StudioAttachOptions): Pr
     changed: changed.data,
     commands,
     contextPacket,
+    handoff,
     proofs: {
       preview: preview.status,
       generated: posture.generated,
@@ -1019,6 +1036,43 @@ export async function runStudioSnapshotCommand(options: StudioAttachOptions): Pr
   };
 }
 
+function studioHandoffFor(input: {
+  previewUrl: string;
+  posture: StudioSnapshotResult["posture"];
+  changed: Record<string, unknown>;
+  delta: unknown;
+  commands: StudioSnapshotResult["commands"];
+}): StudioSnapshotResult["handoff"] {
+  const changedSummary = input.changed.summary as { changedFiles?: unknown } | undefined;
+  const deltaRecord = input.delta && typeof input.delta === "object" && !Array.isArray(input.delta)
+    ? input.delta as { workSession?: { id?: unknown; title?: unknown; status?: unknown; confidence?: unknown }; details?: { health?: { status?: unknown } } }
+    : undefined;
+  const workSession = deltaRecord?.workSession;
+  return {
+    previewUrl: input.previewUrl,
+    ...(workSession
+      ? {
+          currentSession: {
+            ...(typeof workSession.id === "string" ? { id: workSession.id } : {}),
+            ...(typeof workSession.title === "string" ? { title: workSession.title } : {}),
+            ...(typeof workSession.status === "string" ? { status: workSession.status } : {}),
+            ...(typeof workSession.confidence === "number" ? { confidence: workSession.confidence } : {}),
+          },
+        }
+      : {}),
+    ...(typeof changedSummary?.changedFiles === "number" ? { changedFiles: changedSummary.changedFiles } : {}),
+    generatedState: input.posture.generated?.state,
+    deltaHealth: typeof deltaRecord?.details?.health?.status === "string" ? deltaRecord.details.health.status : undefined,
+    agentContextCommand: "forge agent context --handoff --json",
+    recommendedCommands: [
+      input.commands.handoff,
+      "forge agent context --handoff --json",
+      input.commands.changed,
+      input.commands.doctor,
+    ],
+  };
+}
+
 export async function runStudioWatchCommand(options: StudioAttachOptions): Promise<StudioWatchResult> {
   const snapshot = await runStudioSnapshotCommand(options);
   const intervalMs = Math.max(1000, Math.floor(options.intervalMs ?? 5000));

package/src/forge/cli/verify.ts

@@ -695,6 +695,7 @@ const STRICT_TEST_FALLBACK_MS_BY_PATH: Array<{ pattern: RegExp; estimatedMs: num
   { pattern: /^tests\/templates\/new-b2b-support-web\.test\.ts$/, estimatedMs: 12_000 },
   { pattern: /^tests\/templates\/new-agent-workroom\.test\.ts$/, estimatedMs: 12_000 },
   { pattern: /^tests\/templates\/new-minimal-web\.test\.ts$/, estimatedMs: 12_000 },
+  { pattern: /^tests\/templates\/new-nuxt-web\.test\.ts$/, estimatedMs: 12_000 },
   { pattern: /^tests\/templates\/create-forge-app\.test\.ts$/, estimatedMs: 8_000 },
 ];
 const STRICT_ISOLATED_TEST_PATTERNS = [
@@ -730,6 +731,7 @@ const STRICT_ISOLATED_TEST_PATTERNS = [
   /^tests\/templates\/new-b2b-support-web\.test\.ts$/,
   /^tests\/templates\/new-agent-workroom\.test\.ts$/,
   /^tests\/templates\/new-minimal-web\.test\.ts$/,
+  /^tests\/templates\/new-nuxt-web\.test\.ts$/,
   /^tests\/telemetry\/telemetry-dev-server\.test\.ts$/,
 ];
 const STRICT_SERIAL_TEST_PATTERNS: RegExp[] = [];

package/src/forge/compiler/frontend-graph/build.ts

@@ -229,6 +229,58 @@ function detectRouteUses(file: string, text: string, clientManifest: ClientManif
   return uses;
 }
 
+function localComposableNames(file: string, text: string): string[] {
+  const relName = componentNameForFile(file);
+  const names = [relName.startsWith("use") ? relName : `use${relName.slice(0, 1).toUpperCase()}${relName.slice(1)}`];
+  for (const match of text.matchAll(/export\s+function\s+(use[A-Z][A-Za-z0-9_]*)\s*\(/g)) {
+    if (match[1]) {
+      names.push(match[1]);
+    }
+  }
+  return uniqueSorted(names);
+}
+
+function buildComposableUseIndex(
+  webRoot: string,
+  sourceFiles: string[],
+  clientManifest: ClientManifest,
+): Map<string, ReturnType<typeof detectUses>> {
+  const index = new Map<string, ReturnType<typeof detectUses>>();
+  for (const file of sourceFiles) {
+    const rel = toPosix(relative(webRoot, file));
+    if (!rel.startsWith("composables/") && !rel.startsWith("src/composables/")) {
+      continue;
+    }
+    if (rel.endsWith("/forge.ts") || rel === "composables/forge.ts" || rel === "src/composables/forge.ts") {
+      continue;
+    }
+    const text = nodeFileSystem.readText(file) ?? "";
+    const uses = detectUses(text, clientManifest);
+    for (const name of localComposableNames(file, text)) {
+      index.set(name, uses);
+    }
+  }
+  return index;
+}
+
+function detectLocalComposableUses(
+  text: string,
+  composableUseIndex: Map<string, ReturnType<typeof detectUses>>,
+): ReturnType<typeof detectUses> {
+  let uses: ReturnType<typeof detectUses> = {
+    usesCommands: [],
+    usesQueries: [],
+    usesLiveQueries: [],
+    rawForgeFetches: [],
+  };
+  for (const [name, composableUses] of composableUseIndex) {
+    if (new RegExp(`\\b${name}\\s*\\(`).test(text)) {
+      uses = mergeUses(uses, composableUses);
+    }
+  }
+  return uses;
+}
+
 function devCommandFor(webRoot: string, framework: FrontendGraph["framework"]): string {
   const pkg = readJson<{ scripts?: Record<string, string> }>(join(webRoot, "package.json"));
   if (pkg?.scripts?.dev) {
@@ -347,6 +399,7 @@ export function buildFrontendGraph(input: {
   const bridgeFiles: string[] = [];
   const diagnostics: FrontendGraph["diagnostics"] = [];
   const textByRel = new Map<string, string>();
+  const composableUseIndex = buildComposableUseIndex(webRoot, sourceFiles, input.clientManifest);
 
   for (const file of sourceFiles) {
     const rel = toPosix(relative(input.workspaceRoot, file));
@@ -359,7 +412,10 @@ export function buildFrontendGraph(input: {
       rel === "web/composables/forge.ts" ||
       rel === "web/plugins/forge.ts";
     textByRel.set(rel, text);
-    const uses = detectUses(text, input.clientManifest);
+    const uses = mergeUses(
+      detectUses(text, input.clientManifest),
+      detectLocalComposableUses(text, composableUseIndex),
+    );
     if (isComponentFile(webRoot, file, text)) {
       components.push({ name: componentNameForText(file, text), file: rel, ...uses });
     }
@@ -469,7 +525,7 @@ export function buildFrontendGraph(input: {
         ? "Nuxt app does not expose a Forge plugin; generated composables may not be wired"
         : "web app does not expose a ForgeProvider; generated hooks may not be wired",
       fixHint: framework === "nuxt"
-        ? "Create web/plugins/forge.ts and call provideForge with runtimeConfig.public.forgeUrl and devAuth for local development."
+        ? "Create web/plugins/forge.client.ts and web/plugins/forge.server.ts and install ForgeVuePlugin with runtimeConfig.public.forgeUrl and devAuth for local development."
         : "Mount ForgeProvider once in the web app root/provider layer and pass devAuth for local development.",
       suggestedCommands: ["forge inspect frontend --json", `forge make ui --framework ${framework === "nuxt" ? "nuxt" : "vite"} --dry-run --json`],
       docs: ["src/forge/_generated/frontendGraph.json", "AGENTS.md"],

package/src/forge/delta/index.ts

@@ -1,10 +1,22 @@
 export {
   runDeltaStatus,
   runDeltaRepair,
+  runDeltaCompact,
+  runDeltaPrune,
+  runDeltaExport,
+  runDeltaDoctor,
   formatDeltaStatusHuman,
   formatDeltaStatusJson,
   formatDeltaRepairHuman,
   formatDeltaRepairJson,
+  formatDeltaDoctorHuman,
+  formatDeltaDoctorJson,
+  formatDeltaCompactHuman,
+  formatDeltaCompactJson,
+  formatDeltaPruneHuman,
+  formatDeltaPruneJson,
+  formatDeltaExportHuman,
+  formatDeltaExportJson,
 } from "./status.ts";
 export { runDeltaTimeline, formatDeltaTimelineHuman, formatDeltaTimelineJson } from "./timeline.ts";
 export { runDeltaExplain, formatDeltaExplainHuman, formatDeltaExplainJson } from "./explain.ts";

package/src/forge/delta/recorder.ts

@@ -260,6 +260,27 @@ async function recordSpecializedCommand(
     return;
   }
 
+  if (command.kind === "cair") {
+    const cairKind = cairOperationKind(command);
+    await store.appendOperation({
+      sessionId,
+      actorId,
+      kind: cairKind,
+      summary: cairSummary(command, cairKind, exitCode),
+      data: {
+        subcommand: command.options.subcommand,
+        exitCode,
+        ...(command.options.query ? { queryVerb: compactCairVerb(command.options.query) } : {}),
+        ...(command.options.action ? { actionVerb: compactCairVerb(command.options.action) } : {}),
+        ...(command.options.inputPath ? { inputPath: command.options.inputPath } : {}),
+        dryRun: Boolean(command.options.dryRun),
+        plan: Boolean(command.options.plan),
+        allowGenerated: Boolean(command.options.allowGenerated),
+      },
+    });
+    return;
+  }
+
   if (command.kind === "check" || command.kind === "verify") {
     await store.appendOperation({
       sessionId,
@@ -276,6 +297,45 @@ async function recordSpecializedCommand(
   }
 }
 
+function cairOperationKind(command: Extract<ForgeCommand, { kind: "cair" }>): string {
+  if (command.options.subcommand === "snapshot") {
+    return "cair.snapshot.created";
+  }
+  if (command.options.subcommand === "query") {
+    return "cair.query.run";
+  }
+  const actionVerb = compactCairVerb(command.options.action ?? "");
+  if (command.options.plan) {
+    return "cair.plan.created";
+  }
+  if (actionVerb === "A APPLY") {
+    return "cair.plan.applied";
+  }
+  if (command.options.dryRun) {
+    return "cair.action.previewed";
+  }
+  return "cair.action.run";
+}
+
+function cairSummary(command: Extract<ForgeCommand, { kind: "cair" }>, kind: string, exitCode: number): string {
+  const suffix = exitCode === 0 ? "completed" : "failed";
+  if (command.options.subcommand === "query") {
+    return `CAIR query ${compactCairVerb(command.options.query ?? "")} ${suffix}`;
+  }
+  if (command.options.subcommand === "action") {
+    return `CAIR ${kind.replace(/^cair\./, "").replace(/\./g, " ")} ${compactCairVerb(command.options.action ?? "")} ${suffix}`;
+  }
+  return `CAIR snapshot ${suffix}`;
+}
+
+function compactCairVerb(input: string): string {
+  const parts = input.trim().split(/\s+/u).filter(Boolean);
+  if (parts.length === 0) {
+    return "unknown";
+  }
+  return parts.slice(0, 2).join(" ");
+}
+
 const noopRecorder: AmbientDeltaRecorder = {
   async recordRuntimeCall() {},
   async recordAgentTool() {},