forgeos 0.1.0-alpha.0

package/src/forge/ui/types.ts

@@ -0,0 +1,191 @@
+import type { Diagnostic } from "../compiler/types/diagnostic.ts";
+import type { TestCost } from "../compiler/types/test-graph.ts";
+
+export type UiSubcommand =
+  | "smoke"
+  | "test"
+  | "scenario"
+  | "route"
+  | "snapshot"
+  | "report"
+  | "doctor"
+  | "list";
+
+export type UiBrowserName = "chromium" | "firefox" | "webkit";
+export type UiTraceMode = "on" | "off" | "retain-on-failure";
+export type UiScreenshotMode = "on" | "off" | "only-on-failure";
+export type UiVideoMode = "on" | "off" | "retain-on-failure";
+
+export interface UiCommandOptions {
+  subcommand: UiSubcommand;
+  workspaceRoot: string;
+  json: boolean;
+  headed: boolean;
+  browser: UiBrowserName;
+  trace: UiTraceMode;
+  screenshot: UiScreenshotMode;
+  video: UiVideoMode;
+  baseUrl: string;
+  runtimeUrl: string;
+  reuseServers: boolean;
+  startServers: boolean;
+  scenarioName?: string;
+  routePath?: string;
+  snapshotName?: string;
+  reportId?: string;
+  all: boolean;
+  changed: boolean;
+  ci: boolean;
+  timeoutMs: number;
+  authToken?: string;
+}
+
+export type UiScenarioStep =
+  | { kind: "goto"; path: string }
+  | { kind: "click"; selector: string }
+  | { kind: "fill"; selector: string; value: string }
+  | { kind: "expectText"; selector: string; text: string; timeoutMs?: number }
+  | { kind: "expectVisible"; selector: string; timeoutMs?: number }
+  | { kind: "expectNotVisible"; selector: string; timeoutMs?: number }
+  | { kind: "waitForLiveRevision"; minRevision: number; timeoutMs?: number }
+  | { kind: "captureScreenshot"; name: string }
+  | { kind: "runForgeCommand"; command: string };
+
+export interface UiScenarioRequires {
+  commands: string[];
+  queries: string[];
+  liveQueries: string[];
+  policies: string[];
+  components: string[];
+  workflows: string[];
+}
+
+export interface UiScenario {
+  name: string;
+  description: string;
+  route: string;
+  cost: TestCost;
+  steps: UiScenarioStep[];
+  requires: UiScenarioRequires;
+}
+
+export interface UiRoute {
+  path: string;
+  name: string;
+  uses: {
+    commands: string[];
+    queries: string[];
+    liveQueries: string[];
+    components: string[];
+  };
+}
+
+export interface UiTestManifest {
+  schemaVersion: "0.1.0";
+  generatorVersion: string;
+  framework: "next" | "react" | "unknown";
+  webRoot: string;
+  defaultBaseUrl: string;
+  runtimeUrl: string;
+  routes: UiRoute[];
+  scenarios: string[];
+  selectors: string[];
+}
+
+export interface UiScenariosArtifact {
+  schemaVersion: "0.1.0";
+  scenarios: UiScenario[];
+}
+
+export interface UiRoutesArtifact {
+  schemaVersion: "0.1.0";
+  routes: UiRoute[];
+}
+
+export type UiFailureKind =
+  | "route-load-failed"
+  | "selector-not-found"
+  | "expected-text-missing"
+  | "command-failed"
+  | "live-query-no-update"
+  | "policy-denied-unexpected"
+  | "browser-console-error"
+  | "network-error"
+  | "timeout"
+  | "playwright-missing";
+
+export interface UiStepResult {
+  kind: UiScenarioStep["kind"];
+  ok: boolean;
+  durationMs: number;
+  message?: string;
+  selector?: string;
+}
+
+export interface UiScenarioResult {
+  name: string;
+  ok: boolean;
+  route?: string;
+  durationMs: number;
+  steps: UiStepResult[];
+  traceId?: string;
+  failure?: {
+    kind: UiFailureKind;
+    message: string;
+    screenshot?: string;
+    trace?: string;
+    video?: string;
+    suggestedCommands: string[];
+  };
+}
+
+export interface UiRunReport {
+  schemaVersion: "0.1.0";
+  uiRunVersion: string;
+  id: string;
+  startedAt?: string;
+  completedAt?: string;
+  config: {
+    baseUrl: string;
+    runtimeUrl: string;
+    browser: UiBrowserName;
+    headed: boolean;
+    trace: UiTraceMode;
+    screenshot: UiScreenshotMode;
+    video: UiVideoMode;
+  };
+  scenarios: UiScenarioResult[];
+  summary: {
+    ok: boolean;
+    passed: number;
+    failed: number;
+    skipped: number;
+    durationMs: number;
+  };
+  artifacts: {
+    screenshots: string[];
+    traces: string[];
+    videos: string[];
+    logs: string[];
+    console: string;
+    network: string;
+  };
+  suggestedCommands: string[];
+  diagnostics: Diagnostic[];
+}
+
+export interface UiCommandResult {
+  ok: boolean;
+  report?: UiRunReport;
+  reports?: Array<{ id: string; path: string }>;
+  manifest?: UiTestManifest;
+  scenarios?: UiScenario[];
+  diagnostics: Diagnostic[];
+  exitCode: 0 | 1;
+}
+
+export interface UiGeneratedArtifacts {
+  manifest: UiTestManifest;
+  scenarios: UiScenariosArtifact;
+  routes: UiRoutesArtifact;
+}

package/templates/b2b-support-web/.env.example

@@ -0,0 +1,22 @@
+# Forge runtime
+FORGE_ENV=development
+NEXT_PUBLIC_FORGE_URL=http://127.0.0.1:3765
+
+# PostHog
+POSTHOG_KEY=
+POSTHOG_HOST=
+
+# Sentry
+SENTRY_DSN=
+SENTRY_AUTH_TOKEN=
+SENTRY_ORG=
+SENTRY_PROJECT=
+
+# Stripe
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+
+# AI
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+AI_GATEWAY_API_KEY=

package/templates/b2b-support-web/.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+  "files.exclude": {
+    "**/.forge": true,
+    "**/node_modules": true,
+    "**/src/forge/_generated": true,
+    "**/forge.lock": true
+  },
+  "search.exclude": {
+    "**/.forge": true,
+    "**/node_modules": true,
+    "**/src/forge/_generated": true,
+    "**/forge.lock": true
+  }
+}

package/templates/b2b-support-web/AGENTS.md

@@ -0,0 +1,108 @@
+// @forge-generated generator=0.0.0 input=219ea7f374e4f290890f7b468c21647187b05b8d10e11eb30d0b5207309cc615 content=4f2136319a711c1c6cfd5bb0d2dc610055ea6da11eebc5c1cc923b22adbbbe4b
+# AGENTS.md
+
+<!-- forge-generated:start -->
+
+## Project
+
+This is a ForgeOS application named `__FORGE_APP_NAME__`.
+
+## Required workflow
+
+Before editing:
+
+```bash
+forge inspect all --json
+forge check --json
+```
+
+After editing:
+
+```bash
+forge generate
+forge check
+forge verify --strict
+```
+
+## Do not edit
+
+Do not:
+
+- `src/forge/_generated/**`
+- `forge.lock`
+- `deploy/docker-compose.yml`, unless changing deployment config intentionally
+
+## Runtime model
+
+- Commands are transactional writes.
+- Queries and liveQueries are read-only.
+- Actions perform side effects after commit.
+- Workflows orchestrate durable steps.
+- AI is only allowed in actions, workflows, endpoints, and server code.
+- Secrets are accessed through `ctx.secrets`.
+
+## Runtime rules
+
+- Do not import network packages inside `command`, `query`, or `liveQuery`.
+- Do not use `process.env` directly.
+- Do not access cross-tenant data.
+- Commands must use `ctx.emit` for side effects.
+- Actions and workflows handle side effects after commit.
+
+## Useful commands
+
+```bash
+forge inspect app --json
+forge inspect all --json
+forge inspect runtime-matrix --json
+forge inspect policies --json
+forge inspect client --json
+forge doctor
+forge verify --strict
+```
+
+## Data
+
+Tenant-scoped tables:
+
+- tickets via tenant_id
+- users via tenant_id
+
+## Policies
+
+- billing.manage: owner
+- tickets.close: admin, owner
+- tickets.create: admin, member, owner
+- tickets.read: admin, member, owner
+- tickets.update: admin, owner
+
+## Secrets
+
+- none
+
+## Common tasks
+
+### Add a command
+
+1. Add file in `src/commands`.
+2. Declare `auth: can("...")`.
+3. Run `forge generate`.
+4. Run `forge verify --strict`.
+
+### Add a package
+
+Use:
+
+```bash
+forge add <alias>
+```
+
+Do not install packages manually unless intentional.
+
+<!-- forge-generated:end -->
+
+<!-- user-notes:start -->
+
+Project-specific notes can go here.
+
+<!-- user-notes:end -->

package/templates/b2b-support-web/README.md

@@ -0,0 +1,48 @@
+# ForgeOS B2B Support Web Template
+
+## Quick Start
+
+```bash
+__PACKAGE_MANAGER__ install
+__PACKAGE_MANAGER__ run generate
+__PACKAGE_MANAGER__ run dev
+```
+
+`forge dev` starts the API runtime, database, worker, watcher, and web app together.
+
+Open:
+
+- API: http://127.0.0.1:3765/health
+- Web: http://127.0.0.1:3000
+
+For one-shot agent/CI diagnostics:
+
+```bash
+__PACKAGE_MANAGER__ run forge -- dev --once --json
+__PACKAGE_MANAGER__ run forge -- inspect all --json
+__PACKAGE_MANAGER__ run verify
+```
+
+## What This Template Demonstrates
+
+- DataGraph schema
+- policy-gated commands and queries
+- tenant isolation
+- liveQuery reactivity
+- outbox actions
+- lightweight workflows
+- AI workflow step in mock mode
+- telemetry trace IDs
+- React hooks
+
+## Useful Commands
+
+```bash
+forge inspect app --json
+forge inspect data --json
+forge inspect policies --json
+forge inspect client --json
+forge verify --strict
+```
+
+Generated files, local runtime state, and dependencies are gitignored and hidden from editor search by default. Recreate generated files with `forge generate`.

package/templates/b2b-support-web/forge.config.ts

@@ -0,0 +1,3 @@
+export default {
+  app: "__FORGE_APP_NAME__",
+};

package/templates/b2b-support-web/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "__FORGE_APP_NAME__",
+  "private": true,
+  "type": "module",
+  "workspaces": [
+    "web"
+  ],
+  "packageManager": "__PACKAGE_MANAGER_SPEC__",
+  "scripts": {
+    "forge": "forge",
+    "generate": "forge generate",
+    "verify": "forge verify --strict",
+    "self-host:compose": "forge self-host compose",
+    "self-host:check": "forge self-host check",
+    "dev:api": "forge dev --api-only",
+    "dev:web": "cd web && __PACKAGE_MANAGER__ run dev",
+    "dev": "forge dev",
+    "test": "node -e \"console.log('No tests configured')\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@electric-sql/pglite": "^0.2.17",
+    "forge": "__FORGE_PACKAGE_SPEC__",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3"
+  },
+  "forge": {
+    "sourceRoots": [
+      "src"
+    ]
+  }
+}

package/templates/b2b-support-web/src/actions/captureTicketCreated.ts

@@ -0,0 +1,14 @@
+import { action } from "forge/server";
+
+export const captureTicketCreated = action({
+  event: "ticket.created",
+  handler: async (ctx, event: { ticketId: string }) => {
+    await ctx.telemetry.capture("ticket_created_action_processed", {
+      ticketId: event.ticketId,
+    });
+
+    return {
+      captured: true,
+    };
+  },
+});

package/templates/b2b-support-web/src/commands/closeTicket.ts

@@ -0,0 +1,20 @@
+import { can, command } from "forge/server";
+
+export const closeTicket = command({
+  auth: can("tickets.close"),
+  handler: async (ctx, input: { ticketId: string }) => {
+    const ticket = await ctx.db.tickets.update(input.ticketId, {
+      status: "closed",
+      updatedAt: new Date(),
+    });
+    if (!ticket) {
+      throw new Error("ticket not found");
+    }
+
+    await ctx.emit("ticket.closed", {
+      ticketId: ticket.id,
+    });
+
+    return ticket;
+  },
+});

package/templates/b2b-support-web/src/commands/createTicket.ts

@@ -0,0 +1,47 @@
+import { can, command } from "forge/server";
+
+async function ensureTenant(ctx: {
+  auth?: { tenantId?: string | null };
+  db: Record<
+    string,
+    {
+      get(id: string): Promise<Record<string, unknown> | null>;
+      insert(value: Record<string, unknown>): Promise<Record<string, unknown>>;
+    }
+  >;
+}) {
+  if (!ctx.auth?.tenantId) {
+    throw new Error("tenant auth is required");
+  }
+
+  const existing = await ctx.db.tenants.get(ctx.auth.tenantId);
+  if (!existing) {
+    await ctx.db.tenants.insert({
+      id: ctx.auth.tenantId,
+    });
+  }
+}
+
+export const createTicket = command({
+  auth: can("tickets.create"),
+  handler: async (ctx, input: { title: string }) => {
+    await ensureTenant(ctx);
+
+    const ticket = await ctx.db.tickets.insert({
+      title: input.title,
+      status: "open",
+      severity: "medium",
+      triageSummary: "Waiting for workflow triage.",
+    });
+
+    await ctx.emit("ticket.created", {
+      ticketId: ticket.id,
+    });
+
+    await ctx.telemetry.capture("ticket_created", {
+      ticketId: ticket.id,
+    });
+
+    return ticket;
+  },
+});

package/templates/b2b-support-web/src/commands/manageBilling.ts

@@ -0,0 +1,9 @@
+import { can, command } from "forge/server";
+
+export const manageBilling = command({
+  auth: can("billing.manage"),
+  handler: async () => ({
+    ok: true,
+    message: "Only owners can manage billing.",
+  }),
+});

package/templates/b2b-support-web/src/forge/schema.ts

@@ -0,0 +1,35 @@
+import { defineTable } from "forge/server";
+
+export const tenants = defineTable({
+  name: "tenants",
+  fields: {
+    id: "uuid",
+    name: "text",
+    createdAt: "timestamp",
+  },
+});
+
+export const users = defineTable({
+  name: "users",
+  fields: {
+    id: "uuid",
+    tenantId: "ref:tenants",
+    email: "text",
+    role: "text",
+    createdAt: "timestamp",
+  },
+});
+
+export const tickets = defineTable({
+  name: "tickets",
+  fields: {
+    id: "uuid",
+    tenantId: "ref:tenants",
+    title: "text",
+    status: "text",
+    severity: "text",
+    triageSummary: "text",
+    createdAt: "timestamp",
+    updatedAt: "timestamp",
+  },
+});

package/templates/b2b-support-web/src/policies.ts

@@ -0,0 +1,9 @@
+import { canRole, definePolicies } from "forge/policy";
+
+export const policies = definePolicies({
+  "tickets.read": canRole("owner", "admin", "member"),
+  "tickets.create": canRole("owner", "admin", "member"),
+  "tickets.update": canRole("owner", "admin"),
+  "tickets.close": canRole("owner", "admin"),
+  "billing.manage": canRole("owner"),
+});

package/templates/b2b-support-web/src/queries/getTicket.ts

@@ -0,0 +1,6 @@
+import { can, query } from "forge/server";
+
+export const getTicket = query({
+  auth: can("tickets.read"),
+  handler: async (ctx, input: { ticketId: string }) => ctx.db.tickets.get(input.ticketId),
+});

package/templates/b2b-support-web/src/queries/listTickets.ts

@@ -0,0 +1,6 @@
+import { can, query } from "forge/server";
+
+export const listTickets = query({
+  auth: can("tickets.read"),
+  handler: async (ctx) => ctx.db.tickets.all(),
+});

package/templates/b2b-support-web/src/queries/liveTickets.ts

@@ -0,0 +1,9 @@
+import { can, liveQuery } from "forge/server";
+
+export const liveTickets = liveQuery({
+  auth: can("tickets.read"),
+  handler: async (ctx) =>
+    ctx.db.tickets.where({
+      status: "open",
+    }),
+});

package/templates/b2b-support-web/src/workflows/triageTicketWorkflow.ts

@@ -0,0 +1,64 @@
+import { event, step, workflow } from "forge/server";
+
+export const triageTicketWorkflow = workflow({
+  trigger: event("ticket.created"),
+  steps: [
+    step("loadTicket", async (ctx) => {
+      const input = ctx.input as { ticketId: string };
+      const ticket = await ctx.db.tickets.get(input.ticketId);
+
+      return {
+        ticket,
+      };
+    }),
+
+    step("triageWithAI", async (ctx) => {
+      const loaded = ctx.steps.loadTicket?.output as
+        | { ticket?: { title?: string } }
+        | undefined;
+      const title = loaded?.ticket?.title ?? "Untitled support ticket";
+
+      const result = await ctx.ai.generateText({
+        provider: "openai",
+        model: "mock",
+        prompt: `Classify this support ticket: ${title}`,
+        purpose: "ticket_triage",
+      });
+
+      return {
+        triage: result.text,
+        usage: result.usage,
+      };
+    }),
+
+    step("saveTriage", async (ctx) => {
+      const input = ctx.input as { ticketId: string };
+      const triage = (ctx.steps.triageWithAI?.output as { triage?: string } | undefined)
+        ?.triage;
+
+      const updated = await ctx.db.tickets.update(input.ticketId, {
+        triageSummary: triage ?? "Mock AI triage complete.",
+        severity: "medium",
+        updatedAt: new Date(),
+      });
+      if (!updated) {
+        throw new Error("ticket not found");
+      }
+
+      return {
+        ticketId: updated.id,
+      };
+    }),
+
+    step("captureTriageTelemetry", async (ctx) => {
+      const input = ctx.input as { ticketId: string };
+      await ctx.telemetry.capture("ticket_triaged", {
+        ticketId: input.ticketId,
+      });
+
+      return {
+        captured: true,
+      };
+    }),
+  ],
+});

package/templates/b2b-support-web/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}