forgeos 0.1.0-alpha.0

package/packages/eslint-plugin-forge/src/check-source.ts

@@ -0,0 +1,95 @@
+import { lookupMatrixEntry } from "../../../src/forge/compiler/classifier/runtime-matrix.ts";
+import type { ImportGuardsArtifact } from "../../../src/forge/compiler/types/import-guards.ts";
+import type { RuntimeContext } from "../../../src/forge/compiler/types/runtime.ts";
+import type { RuntimeMatrix } from "../../../src/forge/compiler/types/runtime-matrix.ts";
+import { parsePackageSpecifier } from "../../../src/forge/compiler/app-graph/module-graph.ts";
+
+export interface ForgeGuardSourceViolation {
+  packageName: string;
+  context: RuntimeContext;
+  rationale: string;
+  line: number;
+  column: number;
+  endColumn: number;
+}
+
+const IMPORT_PATTERN =
+  /(?:import\s+(?:type\s+)?(?:[\w*{}\s,]+from\s+)?|export\s+(?:type\s+)?(?:[\w*{}\s,]+from\s+)?)['"]([^'"]+)['"]|require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+function lineColumnAtOffset(
+  source: string,
+  offset: number,
+): { line: number; column: number } {
+  const before = source.slice(0, offset);
+  const lines = before.split("\n");
+  return {
+    line: lines.length,
+    column: (lines.at(-1)?.length ?? 0) + 1,
+  };
+}
+
+function effectiveContextsForFile(
+  file: string,
+  guards: ImportGuardsArtifact,
+): RuntimeContext[] {
+  const normalized = file.replace(/\\/g, "/");
+  const entry = guards.moduleContexts.find(
+    (module) =>
+      module.file === normalized ||
+      normalized.endsWith(`/${module.file}`) ||
+      module.file.endsWith(normalized),
+  );
+  return entry?.effectiveContexts ?? [];
+}
+
+export function checkSourceForgeGuards(
+  filePath: string,
+  source: string,
+  importGuards: ImportGuardsArtifact,
+  runtimeMatrix: RuntimeMatrix,
+): ForgeGuardSourceViolation[] {
+  const effectiveContexts = effectiveContextsForFile(filePath, importGuards);
+  if (effectiveContexts.length === 0) {
+    return [];
+  }
+
+  const violations: ForgeGuardSourceViolation[] = [];
+
+  for (const match of source.matchAll(IMPORT_PATTERN)) {
+    const specifier = match[1] ?? match[2];
+    if (!specifier) {
+      continue;
+    }
+
+    const parsed = parsePackageSpecifier(specifier);
+    if (!parsed) {
+      continue;
+    }
+
+    const matrixEntry = lookupMatrixEntry(runtimeMatrix, parsed.packageName);
+    if (matrixEntry == null) {
+      continue;
+    }
+
+    const offset = match.index ?? 0;
+    const start = lineColumnAtOffset(source, offset);
+    const endColumn = start.column + match[0].length;
+
+    for (const context of effectiveContexts) {
+      if (!matrixEntry.compatible.includes(context)) {
+        violations.push({
+          packageName: parsed.packageName,
+          context,
+          rationale:
+            matrixEntry.rationale[context] ??
+            "package is incompatible with this runtime context",
+          line: start.line,
+          column: start.column,
+          endColumn,
+        });
+      }
+    }
+  }
+
+  return violations;
+}

package/packages/eslint-plugin-forge/src/load-artifacts.ts

@@ -0,0 +1,24 @@
+import { readFileSync } from "node:fs";
+import { stripDeterministicHeader } from "../../../src/forge/compiler/primitives/header.ts";
+import type { ImportGuardsArtifact } from "../../../src/forge/compiler/types/import-guards.ts";
+import type { RuntimeMatrix } from "../../../src/forge/compiler/types/runtime-matrix.ts";
+
+export interface ForgeGuardArtifacts {
+  importGuards: ImportGuardsArtifact;
+  runtimeMatrix: RuntimeMatrix;
+}
+
+function parseGeneratedJson<T>(path: string): T {
+  const raw = stripDeterministicHeader(readFileSync(path, "utf8"));
+  return JSON.parse(raw) as T;
+}
+
+export function loadForgeGuardArtifacts(
+  importGuardsPath: string,
+  runtimeMatrixPath: string,
+): ForgeGuardArtifacts {
+  const importGuards = parseGeneratedJson<ImportGuardsArtifact>(importGuardsPath);
+  const runtimeMatrix = parseGeneratedJson<RuntimeMatrix>(runtimeMatrixPath);
+
+  return { importGuards, runtimeMatrix };
+}

package/packages/eslint-plugin-forge/src/rule-no-forge-guard-violation.ts

@@ -0,0 +1,93 @@
+import type { ForgeGuardArtifacts } from "./load-artifacts.ts";
+import { loadForgeGuardArtifacts } from "./load-artifacts.ts";
+import {
+  checkSourceForgeGuards,
+  type ForgeGuardSourceViolation,
+} from "./check-source.ts";
+
+export interface ForgeEslintSettings {
+  importGuardsPath?: string;
+  runtimeMatrixPath?: string;
+}
+
+export interface ForgeEslintContext {
+  filename: string;
+  sourceCode: string;
+  settings?: { forge?: ForgeEslintSettings };
+  report: (descriptor: {
+    message: string;
+    line: number;
+    column: number;
+    endColumn: number;
+  }) => void;
+}
+
+let cachedArtifacts: ForgeGuardArtifacts | null = null;
+let cachedKey = "";
+
+function resolveArtifacts(context: ForgeEslintContext): ForgeGuardArtifacts | null {
+  const forgeSettings = context.settings?.forge;
+  const importGuardsPath = forgeSettings?.importGuardsPath;
+  const runtimeMatrixPath = forgeSettings?.runtimeMatrixPath;
+
+  if (!importGuardsPath || !runtimeMatrixPath) {
+    return null;
+  }
+
+  const key = `${importGuardsPath}|${runtimeMatrixPath}`;
+  if (cachedArtifacts && cachedKey === key) {
+    return cachedArtifacts;
+  }
+
+  cachedArtifacts = loadForgeGuardArtifacts(importGuardsPath, runtimeMatrixPath);
+  cachedKey = key;
+  return cachedArtifacts;
+}
+
+export function runForgeGuardRule(context: ForgeEslintContext): void {
+  const artifacts = resolveArtifacts(context);
+  if (!artifacts) {
+    return;
+  }
+
+  const violations = checkSourceForgeGuards(
+    context.filename,
+    context.sourceCode,
+    artifacts.importGuards,
+    artifacts.runtimeMatrix,
+  );
+
+  for (const violation of violations) {
+    context.report({
+      message: `'${violation.packageName}' is not allowed in '${violation.context}' context: ${violation.rationale}`,
+      line: violation.line,
+      column: violation.column,
+      endColumn: violation.endColumn,
+    });
+  }
+}
+
+export function formatViolationMessage(violation: ForgeGuardSourceViolation): string {
+  return `'${violation.packageName}' is not allowed in '${violation.context}' context: ${violation.rationale}`;
+}
+
+export const forgeGuardRuleDefinition = {
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        "Disallow package imports incompatible with Forge effective runtime contexts",
+    },
+    schema: [],
+    messages: {
+      violation: "{{message}}",
+    },
+  },
+  create(context: ForgeEslintContext) {
+    return {
+      Program() {
+        runForgeGuardRule(context);
+      },
+    };
+  },
+};

package/src/forge/_generated/actionSubscriptions.json

@@ -0,0 +1,2 @@
+// @forge-generated generator=0.0.0 input=eb8d78e749f083957f69f7f316aa4efc3faf5ccd81ff63e3cf32bf7fb7f705ac content=8b0157f6f5ada213d0614d45aea3535d310f4aa74afce62dd6144a50d90375b2
+{"analyzerVersion":"0.1.0","byEvent":{},"diagnostics":[],"generatorVersion":"0.0.0","inputHash":"dd356f5b886d56bc39e3633c018d348746ab64c4d5e7778b0ba47687e421f568","schemaVersion":"0.1.0","subscriptions":[]}

package/src/forge/_generated/actionSubscriptions.ts

@@ -0,0 +1,10 @@
+// @forge-generated generator=0.0.0 input=eb8d78e749f083957f69f7f316aa4efc3faf5ccd81ff63e3cf32bf7fb7f705ac content=3651d5984e70296e09aab8a2ece35bceb207fecb9548fc9ac3067c091188f098
+export const actionSubscriptions = {
+  "analyzerVersion": "0.1.0",
+  "byEvent": {},
+  "diagnostics": [],
+  "generatorVersion": "0.0.0",
+  "inputHash": "dd356f5b886d56bc39e3633c018d348746ab64c4d5e7778b0ba47687e421f568",
+  "schemaVersion": "0.1.0",
+  "subscriptions": []
+} as const;

package/src/forge/_generated/agentAdapterManifest.json

@@ -0,0 +1,2 @@
+// @forge-generated generator=0.0.0 input=6b855b87f2f57fce3e0939076b81cc0263cccfeae7bb969d2662613867b1c8ee content=31b6d77c832d71d7b897e35d7bd415732db0f5d1ddb9168abf92938beb22deb4
+{"generatorVersion":"0.0.0","schemaVersion":"0.1.0","sourceHash":"sha256:837cea11273ca7d9149ffc0f3e6f52b1f754f498b6ab4604e8090b8ed59ade89","targets":[{"adapterVersion":"agent-adapter-0.1.0","default":true,"files":["AGENTS.md",".forge/agent/context.json",".forge/agent/commands.json",".forge/agent/done-criteria.json",".forge/agent/playbooks/add-command.md",".forge/agent/playbooks/add-query.md",".forge/agent/playbooks/add-livequery.md",".forge/agent/playbooks/add-resource.md",".forge/agent/playbooks/refactor-field.md",".forge/agent/playbooks/fix-policy-denied.md",".forge/agent/playbooks/fix-guard-violation.md",".forge/agent/playbooks/upgrade-package.md",".forge/agent/playbooks/debug-trace.md",".forge/agent/playbooks/frontend-change.md",".forge/agent/playbooks/self-host-check.md"],"formatVersion":"2026-06","name":"generic"},{"adapterVersion":"agent-adapter-0.1.0","files":[".codex/skills/forge-add-command/SKILL.md",".codex/skills/forge-add-resource/SKILL.md",".codex/skills/forge-fix-guard-violation/SKILL.md",".codex/skills/forge-fix-policy-denied/SKILL.md",".codex/skills/forge-upgrade-package/SKILL.md",".codex/skills/forge-debug-trace/SKILL.md",".codex/agents/forge-explorer.toml",".codex/agents/forge-worker.toml",".codex/agents/forge-reviewer.toml",".codex/agents/forge-security.toml"],"formatVersion":"2026-06","name":"codex","optional":true},{"adapterVersion":"agent-adapter-0.1.0","files":[".cursor/rules/forge-runtime.mdc",".cursor/rules/forge-frontend.mdc",".cursor/rules/forge-security.mdc",".cursor/rules/forge-workflow.mdc"],"formatVersion":"2026-06","name":"cursor","optional":true},{"adapterVersion":"agent-adapter-0.1.0","files":["CLAUDE.md",".claude/forge-runtime.md",".claude/forge-playbooks.md",".claude/forge-security.md"],"formatVersion":"2026-06","name":"claude","optional":true}]}

package/src/forge/_generated/agentAdapterManifest.ts

@@ -0,0 +1,73 @@
+// @forge-generated generator=0.0.0 input=6b855b87f2f57fce3e0939076b81cc0263cccfeae7bb969d2662613867b1c8ee content=f171fc557de10137021c564e631f2cd7e3a38bf599bd6f9a884ac1091559a1b5
+export const agentAdapterManifest = {
+  "generatorVersion": "0.0.0",
+  "schemaVersion": "0.1.0",
+  "sourceHash": "sha256:837cea11273ca7d9149ffc0f3e6f52b1f754f498b6ab4604e8090b8ed59ade89",
+  "targets": [
+    {
+      "adapterVersion": "agent-adapter-0.1.0",
+      "default": true,
+      "files": [
+        "AGENTS.md",
+        ".forge/agent/context.json",
+        ".forge/agent/commands.json",
+        ".forge/agent/done-criteria.json",
+        ".forge/agent/playbooks/add-command.md",
+        ".forge/agent/playbooks/add-query.md",
+        ".forge/agent/playbooks/add-livequery.md",
+        ".forge/agent/playbooks/add-resource.md",
+        ".forge/agent/playbooks/refactor-field.md",
+        ".forge/agent/playbooks/fix-policy-denied.md",
+        ".forge/agent/playbooks/fix-guard-violation.md",
+        ".forge/agent/playbooks/upgrade-package.md",
+        ".forge/agent/playbooks/debug-trace.md",
+        ".forge/agent/playbooks/frontend-change.md",
+        ".forge/agent/playbooks/self-host-check.md"
+      ],
+      "formatVersion": "2026-06",
+      "name": "generic"
+    },
+    {
+      "adapterVersion": "agent-adapter-0.1.0",
+      "files": [
+        ".codex/skills/forge-add-command/SKILL.md",
+        ".codex/skills/forge-add-resource/SKILL.md",
+        ".codex/skills/forge-fix-guard-violation/SKILL.md",
+        ".codex/skills/forge-fix-policy-denied/SKILL.md",
+        ".codex/skills/forge-upgrade-package/SKILL.md",
+        ".codex/skills/forge-debug-trace/SKILL.md",
+        ".codex/agents/forge-explorer.toml",
+        ".codex/agents/forge-worker.toml",
+        ".codex/agents/forge-reviewer.toml",
+        ".codex/agents/forge-security.toml"
+      ],
+      "formatVersion": "2026-06",
+      "name": "codex",
+      "optional": true
+    },
+    {
+      "adapterVersion": "agent-adapter-0.1.0",
+      "files": [
+        ".cursor/rules/forge-runtime.mdc",
+        ".cursor/rules/forge-frontend.mdc",
+        ".cursor/rules/forge-security.mdc",
+        ".cursor/rules/forge-workflow.mdc"
+      ],
+      "formatVersion": "2026-06",
+      "name": "cursor",
+      "optional": true
+    },
+    {
+      "adapterVersion": "agent-adapter-0.1.0",
+      "files": [
+        "CLAUDE.md",
+        ".claude/forge-runtime.md",
+        ".claude/forge-playbooks.md",
+        ".claude/forge-security.md"
+      ],
+      "formatVersion": "2026-06",
+      "name": "claude",
+      "optional": true
+    }
+  ]
+} as const;

package/src/forge/_generated/agentContract.json

@@ -0,0 +1,2 @@
+// @forge-generated generator=0.0.0 input=6b855b87f2f57fce3e0939076b81cc0263cccfeae7bb969d2662613867b1c8ee content=837cea11273ca7d9149ffc0f3e6f52b1f754f498b6ab4604e8090b8ed59ade89
+{"actions":[],"ai":{"generations":[],"providers":["anthropic","gateway","openai"]},"auth":{"bearerTokenHeader":"Authorization","claims":{"email":"email","name":"name","permissions":"permissions","role":"role","roles":"roles","tenantId":"tenant_id","userId":"sub"},"defaultMode":"dev-headers","env":{"algorithms":"FORGE_AUTH_ALGORITHMS","audience":"FORGE_AUTH_AUDIENCE","issuer":"FORGE_AUTH_ISSUER","jwksUri":"FORGE_AUTH_JWKS_URI","mode":"FORGE_AUTH_MODE"},"modes":["dev-headers","jwt","oidc","disabled"],"productionDefaultAllowed":false,"requiresTenant":false},"client":{"commands":[],"liveQueries":[],"queries":[],"reactHooks":["ForgeProvider","useForgeClient","useAuth","useQuery","useCommand","useLiveQuery"],"transport":{"commands":"POST /commands/:name","liveQueries":"GET /live/:name","queries":"POST /queries/:name"}},"commands":[],"commandsToRun":{"afterEditing":["forge generate","forge check","forge verify --standard","forge verify --strict"],"beforeEditing":["forge do inspect --json","forge dev --once --json","forge inspect all --json","forge check --json"],"dev":["forge dev","forge dev --once --json","forge do fix --json","forge do verify --json","forge dev --api-only","forge dev --web-only"]},"data":{"tables":[]},"deploy":{"files":["deploy/docker-compose.yml","deploy/.env.example","deploy/deployManifest.json"],"selfHost":true},"frontend":{"bridgeFiles":[],"clientBindings":[],"componentBindings":[],"components":[],"diagnostics":[],"framework":"none","present":false,"providers":[],"routeBindings":[],"routes":[],"runtimeEndpoints":[],"webManifest":{"bridge":{"files":[],"valid":false},"env":{"apiUrl":"NEXT_PUBLIC_FORGE_URL"},"framework":"none","present":false,"scripts":{},"urls":{"api":"http://127.0.0.1:3765"}}},"generatorVersion":"0.0.0","integrations":[{"alias":"ai-gateway","allowedContexts":["server","action","workflow","endpoint","test","build"],"deniedContexts":["shared","client","query","liveQuery","command","edge"],"packages":["ai"],"secrets":["AI_GATEWAY_API_KEY"]},{"alias":"ai-provider-anthropic","allowedContexts":["server","action","workflow","endpoint","test","build"],"deniedContexts":["shared","client","query","liveQuery","command","edge"],"packages":["@ai-sdk/anthropic"],"secrets":["ANTHROPIC_API_KEY"]},{"alias":"ai-provider-openai","allowedContexts":["server","action","workflow","endpoint","test","build"],"deniedContexts":["shared","client","query","liveQuery","command","edge"],"packages":["@ai-sdk/openai"],"secrets":["OPENAI_API_KEY"]},{"alias":"zod","allowedContexts":["shared","client","server","query","liveQuery","command","action","workflow","endpoint","edge","test","build"],"deniedContexts":[],"packages":["zod"],"secrets":[]}],"liveQueries":[],"packages":[{"allowedContexts":["server","action","workflow","endpoint","test","build"],"deniedContexts":["shared","client","query","liveQuery","command","edge"],"name":"@ai-sdk/anthropic","version":"2.0.81"},{"allowedContexts":["server","action","workflow","endpoint","test","build"],"deniedContexts":["shared","client","query","liveQuery","command","edge"],"name":"@ai-sdk/openai","version":"2.0.106"},{"allowedContexts":["server","action","workflow","endpoint","edge","test","build"],"deniedContexts":["shared","client","query","liveQuery","command"],"name":"@changesets/changelog-github","version":"0.7.0"},{"allowedContexts":["server","action","workflow","endpoint","edge","test","build"],"deniedContexts":["shared","client","query","liveQuery","command"],"name":"@changesets/cli","version":"2.31.0"},{"allowedContexts":["server","action","workflow","endpoint","edge","test","build"],"deniedContexts":["shared","client","query","liveQuery","command"],"name":"@electric-sql/pglite","version":"0.2.17"},{"allowedContexts":["server","action","workflow","endpoint","edge","test","build"],"deniedContexts":["shared","client","query","liveQuery","command"],"name":"@types/bun","version":"1.3.14"},{"allowedContexts":["server","action","workflow","endpoint","edge","test","build"],"deniedContexts":["shared","client","query","liveQuery","command"],"name":"@types/react","version":"19.2.17"},{"allowedContexts":["server","action","workflow","endpoint","edge","test","build"],"deniedContexts":["shared","client","query","liveQuery","command"],"name":"@types/react-test-renderer","version":"19.1.0"},{"allowedContexts":["server","action","workflow","endpoint","test","build"],"deniedContexts":["shared","client","query","liveQuery","command","edge"],"name":"ai","version":"5.0.197"},{"allowedContexts":["server","action","workflow","endpoint","edge","test","build"],"deniedContexts":["shared","client","query","liveQuery","command"],"name":"fast-check","version":"3.23.2"},{"allowedContexts":["client","server","action","workflow","endpoint","edge","test","build"],"deniedContexts":["shared","query","liveQuery","command"],"name":"jose","version":"6.2.3"},{"allowedContexts":["server","action","workflow","endpoint","edge","test","build"],"deniedContexts":["shared","client","query","liveQuery","command"],"name":"postgres","version":"3.4.9"},{"allowedContexts":["server","action","workflow","endpoint","edge","test","build"],"deniedContexts":["shared","client","query","liveQuery","command"],"name":"react","version":"19.2.7"},{"allowedContexts":["server","action","workflow","endpoint","edge","test","build"],"deniedContexts":["shared","client","query","liveQuery","command"],"name":"react-test-renderer","version":"19.2.7"},{"allowedContexts":["server","action","workflow","endpoint","edge","test","build"],"deniedContexts":["shared","client","query","liveQuery","command"],"name":"tree-sitter","version":"0.22.4"},{"allowedContexts":["server","action","workflow","endpoint","edge","test","build"],"deniedContexts":["shared","client","query","liveQuery","command"],"name":"tree-sitter-typescript","version":"0.23.2"},{"allowedContexts":["server","action","workflow","endpoint","edge","test","build"],"deniedContexts":["shared","client","query","liveQuery","command"],"name":"tsx","version":"4.22.4"},{"allowedContexts":["server","action","workflow","endpoint","edge","test","build"],"deniedContexts":["shared","client","query","liveQuery","command"],"name":"typescript","version":"5.9.3"},{"allowedContexts":["shared","client","server","query","liveQuery","command","action","workflow","endpoint","edge","test","build"],"deniedContexts":[],"name":"zod","version":"3.25.76"}],"playbooks":[{"steps":["Run forge do \"<objective>\" --json when the next command is not obvious.","Use forge do fix --json for failures, forge do verify --json before handoff, and forge do connect-ui --json for frontend wiring.","Follow the returned plan, filesToInspect, risks, and nextAction before using lower-level commands directly."],"title":"Choose the right workflow"},{"steps":["Add a file under src/commands.","Declare auth with can(\"policy.name\") unless intentionally public/system.","Use ctx.db for transactional writes.","Use ctx.emit for side effects.","Run forge generate.","Run forge verify --strict."],"title":"Add a command"},{"steps":["Add a file under src/queries.","Keep it read-only.","Declare auth explicitly.","Run forge generate.","Run forge check."],"title":"Add a query"},{"steps":["Add a liveQuery under src/queries.","Keep it read-only and tenant-scoped when reading tenant tables.","Run forge generate.","Use forge inspect client --json to confirm client exposure."],"title":"Add a liveQuery"},{"steps":["Run forge live status --json.","Run forge live invalidations list --json and confirm the table and tenant changed.","Run forge live debug <subscriptionId> --json when a subscription id is available.","Check that _forge_live_invalidations has revisions newer than the last sent snapshot.","Reconnect with Last-Event-ID or ?lastRevision=<revision> to verify resume behavior."],"title":"Debug a stale liveQuery"},{"steps":["Edit src/forge/schema.ts.","Include tenantId for tenant-scoped data.","Run forge generate.","Run forge db diff.","Run forge verify --strict."],"title":"Add a table"},{"steps":["Run forge make resource <name> --fields name:type,status:enum(open,closed) --dry-run --json.","Review the plan and diagnostics.","Run forge make resource <name> --fields name:type --with-ui --yes when the resource should be visible in the web app.","Run forge generate.","Run forge verify --strict."],"title":"Scaffold a resource"},{"steps":["Write a JSON blueprint under .forge/blueprints.","Run forge feature validate <blueprint> --json.","Run forge feature plan <blueprint>.","Review the plan, impact, and risk.","Run forge feature apply <blueprint> --yes.","Run forge verify --strict."],"title":"Apply a feature blueprint"},{"steps":["Run forge refactor rename field <table.field> <table.field> --dry-run --json.","Rename codemods are AST-aware for extract-action, rename field, and rename table.","Field renames are scoped to the target table, so tickets.priority only rewrites references linked to tickets.","Review filesToModify, migrationPlan, diagnostics, and risk.","Use --allow-high-risk only for intentional high-risk refactors.","Apply with forge refactor rename field <table.field> <table.field> --yes.","Run forge generate.","Run forge verify --strict."],"title":"Safely refactor a feature"},{"steps":["Run forge impact --changed --json.","Run forge test plan --changed --json.","Run forge test run --changed --timeout-ms 120000 --json for targeted checks.","Use forge verify --changed for the fast impact gate.","Run forge verify --strict before final handoff."],"title":"Plan impact-based tests"},{"steps":["Run forge test run --changed --json.","Run forge repair diagnose --from-last-test-run --json.","Review the failureKind, likelyCause, suggestedRepairs, and confidence.","Apply only high-confidence repairs automatically.","Run forge verify --changed.","Run forge verify --strict before final handoff."],"title":"Repair a failing check"},{"steps":["Use forge add <alias>.","Do not install packages manually unless the architecture exception is intentional.","Run forge generate.","Run forge check."],"title":"Add a package"},{"steps":["Run forge deps upgrade-plan <package> --to latest.","Read .forge/upgrades/.../plan.md.","If risk is high, inspect affected files and generated adapters before applying.","Apply with forge deps upgrade-apply <plan>.","Finish with forge verify --strict."],"title":"Upgrade a package"},{"steps":["Capture the traceId from the response or frontend.","Run forge telemetry inspect <traceId>.","Run forge policy simulate <policy> --role <role>."],"title":"Debug a policy error"},{"steps":["Run forge dev for the full local loop: generated checks, API runtime, web app, DB, worker, watch, and startup URLs.","Run forge dev --once --json for a one-shot diagnostic cycle.","Use --api-only, --web-only, --no-watch, or --no-worker only when narrowing the loop intentionally.","When a web app exists, forge dev starts the API runtime and the web dev server together and prints both URLs.","Use generated client and React hooks through web/lib/forge.ts."],"title":"Run dev"},{"steps":["Run forge make ui --framework vite --dry-run --json when the app does not have a web root.","Use web/lib/forge.ts as the generated client bridge.","Mount ForgeProvider once in the web app provider/layout layer; use devAuth for local development.","Use useQuery, useCommand, and useLiveQuery instead of raw /commands or /queries fetches.","Run forge generate so frontendGraph and agentContract include routes and bindings.","Run forge inspect capabilities --json to confirm UI actions map to runtime capabilities.","Run forge dev --once --json and forge doctor --json."],"title":"Add or update frontend"},{"steps":["Run forge self-host compose.","Review deploy/.env.example.","Run forge self-host check."],"title":"Self-host"},{"steps":["Run forge release inspect <releaseId> --json.","Run forge release sourcemaps symbolicate --input stacktrace.json --json.","Open the original source file and line from the symbolicated frame.","Use forge telemetry inspect <traceId> --with-release --json when a trace id is available."],"title":"Debug a production stack trace"}],"policies":[],"project":{"name":"forgeos","type":"forgeos-app"},"queries":[],"rules":[{"allowed":["ctx.db writes","ctx.emit","ctx.telemetry buffered events"],"context":"command","forbidden":["network packages","ctx.secrets","ctx.ai","process.env","filesystem access"]},{"allowed":["ctx.db reads","ctx.telemetry buffered events"],"context":"query","forbidden":["insert/update/delete","ctx.emit","ctx.secrets","ctx.ai","network integrations"]},{"allowed":["ctx.db reads","tenant-scoped subscriptions"],"context":"liveQuery","forbidden":["insert/update/delete","ctx.emit","ctx.secrets","ctx.ai","network integrations"]},{"allowed":["ctx.secrets","integrations","ctx.ai","ctx.db reads/writes","network packages"],"context":"action","forbidden":["uncommitted transactional side effects"]},{"allowed":["durable steps","ctx.secrets","integrations","ctx.ai","retries"],"context":"workflow","forbidden":["non-idempotent step behavior without guards"]}],"schemaVersion":"0.1.0","secrets":[{"allowedContexts":["server","action","workflow","endpoint","test","build"],"integration":"ai-gateway","name":"AI_GATEWAY_API_KEY","public":false,"required":true},{"allowedContexts":["server","action","workflow","endpoint","test","build"],"integration":"ai-provider-anthropic","name":"ANTHROPIC_API_KEY","public":false,"required":true},{"allowedContexts":["server","action","workflow","endpoint","test","build"],"integration":"ai-provider-openai","name":"OPENAI_API_KEY","public":false,"required":true}],"telemetry":{"events":[],"sinks":["local"]},"workflows":[]}