forgeos 0.1.0-alpha.0

package/src/forge/cli/index.ts

@@ -0,0 +1,25 @@
+export { CLI_VERSION } from "./version.ts";
+export { parseCli, hasUnknownOption, type ParsedCli, type ForgeCommand } from "./parse.ts";
+export { runNewCommand, type NewCommandOptions, type NewCommandResult } from "./new.ts";
+export { runSelfHostCommand, type SelfHostCommandOptions } from "./self-host.ts";
+export { runBuildCommand, type BuildCommandOptions } from "./build.ts";
+export { runServeCommand, type ServeCommandOptions } from "./serve.ts";
+export { runWorkerCommand, type WorkerCommandOptions } from "./worker.ts";
+export {
+  runAgentContractPrint,
+  type AgentContractCommandOptions,
+  type AgentContractSubcommand,
+} from "./agent-contract.ts";
+export {
+  runDoctorCommand,
+  type DoctorCheck,
+  type DoctorResult,
+} from "./doctor.ts";
+export {
+  executeCommand,
+  runGenerateCommand,
+  runAddCommand,
+  runCheckCommand,
+  runInspectCommand,
+} from "./commands.ts";
+export { main } from "./main.ts";

package/src/forge/cli/lint-forge.ts

@@ -0,0 +1,119 @@
+import { nodeFileSystem } from "../compiler/fs/index.ts";
+import { join, relative } from "node:path";
+import { createDiagnostic } from "../compiler/diagnostics/create.ts";
+import { FORGE_GUARD_VIOLATION } from "../compiler/diagnostics/codes.ts";
+import type { Diagnostic } from "../compiler/types/diagnostic.ts";
+import { GENERATED_DIR } from "../compiler/emitter/constants.ts";
+import {
+  checkSourceForgeGuards,
+  loadForgeGuardArtifacts,
+} from "../../../packages/eslint-plugin-forge/index.ts";
+import { isMainModule } from "../platform/module.ts";
+
+const SOURCE_EXTENSIONS = new Set([".ts", ".tsx"]);
+const SKIP_DIRS = new Set(["node_modules", "_generated", ".forge", "dist", "build"]);
+
+function collectSourceFiles(workspaceRoot: string, root: string): string[] {
+  const absoluteRoot = join(workspaceRoot, root);
+  if (!nodeFileSystem.exists(absoluteRoot)) {
+    return [];
+  }
+
+  const files: string[] = [];
+
+  function walk(dir: string): void {
+    for (const entry of nodeFileSystem.readDir(dir)) {
+      const absolute = join(dir, entry.name);
+      if (entry.isDirectory) {
+        if (SKIP_DIRS.has(entry.name)) {
+          continue;
+        }
+        walk(absolute);
+        continue;
+      }
+
+      if (SOURCE_EXTENSIONS.has(entry.name.slice(entry.name.lastIndexOf(".")))) {
+        files.push(relative(workspaceRoot, absolute).replace(/\\/g, "/"));
+      }
+    }
+  }
+
+  walk(absoluteRoot);
+  return files.sort();
+}
+
+export async function lintForgeGuards(workspaceRoot: string): Promise<{
+  exitCode: 0 | 1;
+  diagnostics: Diagnostic[];
+}> {
+  const importGuardsPath = join(
+    workspaceRoot,
+    GENERATED_DIR,
+    "importGuards.json",
+  );
+  const runtimeMatrixPath = join(
+    workspaceRoot,
+    GENERATED_DIR,
+    "runtimeMatrix.json",
+  );
+
+  if (!nodeFileSystem.exists(importGuardsPath) || !nodeFileSystem.exists(runtimeMatrixPath)) {
+    return {
+      exitCode: 0,
+      diagnostics: [
+        createDiagnostic({
+          severity: "warning",
+          code: "FORGE_VERIFY_LINT_SKIP",
+          message:
+            "skipping forge guard lint: run forge generate first to create importGuards.json and runtimeMatrix.json",
+        }),
+      ],
+    };
+  }
+
+  const artifacts = loadForgeGuardArtifacts(importGuardsPath, runtimeMatrixPath);
+  const diagnostics: Diagnostic[] = [];
+
+  for (const root of ["src", "tests", "examples"]) {
+    for (const file of collectSourceFiles(workspaceRoot, root)) {
+      const source = (nodeFileSystem.readText(join(workspaceRoot, file)) ?? "");
+      const violations = checkSourceForgeGuards(
+        file,
+        source,
+        artifacts.importGuards,
+        artifacts.runtimeMatrix,
+      );
+
+      for (const violation of violations) {
+        diagnostics.push(
+          createDiagnostic({
+            severity: "error",
+            code: FORGE_GUARD_VIOLATION,
+            message: `'${violation.packageName}' is not allowed in '${violation.context}' context: ${violation.rationale}`,
+            file,
+            span: {
+              start: violation.column,
+              end: violation.endColumn,
+            },
+          }),
+        );
+      }
+    }
+  }
+
+  return {
+    exitCode: diagnostics.some((item) => item.severity === "error") ? 1 : 0,
+    diagnostics,
+  };
+}
+
+if (isMainModule(import.meta)) {
+  const result = await lintForgeGuards(process.cwd());
+  for (const diagnostic of result.diagnostics) {
+    const location = diagnostic.file ? ` ${diagnostic.file}` : "";
+    console.log(
+      `${diagnostic.severity} ${diagnostic.code}:${location} ${diagnostic.message}`,
+    );
+  }
+  process.exit(result.exitCode);
+}

package/src/forge/cli/live.ts

@@ -0,0 +1,179 @@
+export type LiveSubcommand =
+  | "list"
+  | "subscribe"
+  | "status"
+  | "debug"
+  | "invalidations"
+  | "test"
+  | "load-test";
+
+export interface RunLiveCommandOptions {
+  subcommand: LiveSubcommand;
+  name?: string;
+  args?: unknown;
+  json: boolean;
+  userId?: string;
+  tenantId?: string;
+  role?: string;
+  url?: string;
+}
+
+function baseUrl(options: RunLiveCommandOptions): string {
+  return (options.url ?? process.env.FORGE_DEV_URL ?? "http://127.0.0.1:3765").replace(
+    /\/$/,
+    "",
+  );
+}
+
+function authHeaders(options: RunLiveCommandOptions): Record<string, string> {
+  return {
+    ...(options.userId ? { "x-forge-user-id": options.userId } : {}),
+    ...(options.tenantId ? { "x-forge-tenant-id": options.tenantId } : {}),
+    ...(options.role ? { "x-forge-role": options.role } : {}),
+  };
+}
+
+export async function runLiveCommand(options: RunLiveCommandOptions): Promise<number> {
+  if (options.subcommand === "list") {
+    const response = await fetch(`${baseUrl(options)}/live`);
+    const body = (await response.json().catch(() => ({}))) as {
+      liveQueries?: string[];
+    };
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(body)}\n`);
+    } else {
+      for (const name of body.liveQueries ?? []) {
+        process.stdout.write(`${name}\n`);
+      }
+    }
+    return response.ok ? 0 : 1;
+  }
+
+  if (options.subcommand === "status") {
+    const response = await fetch(`${baseUrl(options)}/live/status`);
+    const body = await response.json().catch(() => ({}));
+    process.stdout.write(options.json ? `${JSON.stringify(body)}\n` : `${JSON.stringify(body, null, 2)}\n`);
+    return response.ok ? 0 : 1;
+  }
+
+  if (options.subcommand === "invalidations") {
+    const response = await fetch(`${baseUrl(options)}/live/invalidations`);
+    const body = await response.json().catch(() => ({}));
+    process.stdout.write(options.json ? `${JSON.stringify(body)}\n` : `${JSON.stringify(body, null, 2)}\n`);
+    return response.ok ? 0 : 1;
+  }
+
+  if (options.subcommand === "debug") {
+    if (!options.name) {
+      throw new Error("forge live debug requires a subscription id");
+    }
+    const response = await fetch(
+      `${baseUrl(options)}/live/debug/${encodeURIComponent(options.name)}`,
+    );
+    const body = await response.json().catch(() => ({}));
+    process.stdout.write(options.json ? `${JSON.stringify(body)}\n` : `${JSON.stringify(body, null, 2)}\n`);
+    return response.ok ? 0 : 1;
+  }
+
+  if (options.subcommand === "test" || options.subcommand === "load-test") {
+    const response = await fetch(`${baseUrl(options)}/live/status`);
+    const body = await response.json().catch(() => ({}));
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: response.ok,
+        mode: options.subcommand,
+        status: body,
+      })}\n`,
+    );
+    return response.ok ? 0 : 1;
+  }
+
+  if (!options.name) {
+    throw new Error("forge live requires a liveQuery name");
+  }
+
+  const encodedArgs = encodeURIComponent(JSON.stringify(options.args ?? {}));
+  const response = await fetch(
+    `${baseUrl(options)}/live/${encodeURIComponent(options.name)}?args=${encodedArgs}`,
+    {
+      headers: authHeaders(options),
+    },
+  );
+
+  if (!response.ok || !response.body) {
+    process.stderr.write(`live query failed: HTTP ${response.status}\n`);
+    return 1;
+  }
+
+  if (!options.json) {
+    process.stdout.write(`[connected] ${options.name}\n`);
+  }
+
+  const decoder = new TextDecoder();
+  const reader = response.body.getReader();
+  let buffer = "";
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    buffer += decoder.decode(value, { stream: true });
+    let boundary = buffer.indexOf("\n\n");
+    while (boundary !== -1) {
+      const frame = buffer.slice(0, boundary);
+      buffer = buffer.slice(boundary + 2);
+      const event = frame
+        .split(/\r?\n/)
+        .find((line) => line.startsWith("event:"))
+        ?.slice(6)
+        .trim();
+      const data = frame
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice(5).trimStart())
+        .join("\n");
+      if (data) {
+        const payload = JSON.parse(data) as {
+          type?: string;
+          revision?: number;
+          data?: unknown;
+          error?: { code: string; message: string };
+        };
+        if (event === "snapshot" || payload.type === "snapshot") {
+          if (options.json) {
+            process.stdout.write(
+              `${JSON.stringify({
+                type: "snapshot",
+                revision: payload.revision,
+                data: payload.data,
+              })}\n`,
+            );
+          } else {
+            process.stdout.write(
+              `[revision ${payload.revision}] ${JSON.stringify(payload.data)}\n`,
+            );
+          }
+        } else if (event === "error" || payload.type === "error") {
+          if (options.json) {
+            process.stdout.write(
+              `${JSON.stringify({
+                type: "error",
+                error: payload.error,
+              })}\n`,
+            );
+          } else {
+            process.stderr.write(
+              `[error] ${payload.error?.code ?? "FORGE_LIVEQUERY_UNKNOWN"}: ${
+                payload.error?.message ?? "live query failed"
+              }\n`,
+            );
+          }
+        }
+      }
+      boundary = buffer.indexOf("\n\n");
+    }
+  }
+
+  return 0;
+}

package/src/forge/cli/main.ts

@@ -0,0 +1,92 @@
+#!/usr/bin/env bun
+import { createDiagnostic } from "../compiler/diagnostics/create.ts";
+import { isMainModule } from "../platform/module.ts";
+import { executeCommand } from "./commands.ts";
+import { hasUnknownOption, parseCli } from "./parse.ts";
+import { formatJsonResult } from "./output.ts";
+
+function formatHelp(): string {
+  return [
+    "ForgeOS",
+    "",
+    "Start with one of these:",
+    "  forge dev                 Run API, DB/worker, watch, and web app when present",
+    "  forge dev --once --json   One-shot health/diagnostic loop for agents and CI",
+    "  forge do \"fix\" --json     Ask ForgeOS for the right workflow and commands",
+    "  forge inspect all --json  Read the generated machine contract",
+    "  forge doctor windows --json  Diagnose native Windows setup and Bun shims",
+    "",
+    "Useful next commands:",
+    "  forge generate",
+    "  forge check --json",
+    "  forge verify --standard",
+    "  forge verify --strict",
+    "",
+  ].join("\n");
+}
+
+export async function main(argv: string[] = process.argv.slice(2)): Promise<number> {
+  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(formatHelp());
+    return 0;
+  }
+
+  const unknown = hasUnknownOption(argv);
+  if (unknown) {
+    const diagnostic = createDiagnostic({
+      severity: "error",
+      code: "FORGE_CLI_USAGE",
+      message: `unrecognized option '${unknown}'`,
+    });
+
+    if (argv.includes("--json")) {
+      process.stdout.write(
+        formatJsonResult({
+          errors: [diagnostic],
+          exitCode: 1,
+          failureKind: "usage",
+        }),
+      );
+    } else {
+      console.error(`error ${diagnostic.code}: ${diagnostic.message}`);
+    }
+    return 1;
+  }
+
+  const parsed = parseCli(argv);
+  if (parsed.errors.length > 0) {
+    const errors = parsed.errors.map((message) =>
+      createDiagnostic({
+        severity: "error",
+        code: "FORGE_CLI_USAGE",
+        message,
+      }),
+    );
+
+    if (argv.includes("--json")) {
+      process.stdout.write(
+        formatJsonResult({
+          errors,
+          exitCode: 1,
+          failureKind: "usage",
+        }),
+      );
+    } else {
+      for (const error of errors) {
+        console.error(`error ${error.code}: ${error.message}`);
+      }
+    }
+    return 1;
+  }
+
+  if (parsed.command === null) {
+    return 1;
+  }
+
+  return executeCommand(parsed.command);
+}
+
+if (isMainModule(import.meta)) {
+  const exitCode = await main();
+  process.exit(exitCode);
+}

package/src/forge/cli/make.ts

@@ -0,0 +1,133 @@
+import { createDiagnostic } from "../compiler/diagnostics/create.ts";
+import { run } from "../compiler/orchestrator/run.ts";
+import type { Diagnostic } from "../compiler/types/diagnostic.ts";
+import { planMakeCommand, rollbackMakePlan } from "../make/index.ts";
+import type { MakeCommandOptions, MakeResult } from "../make/types.ts";
+
+function appendDiagnostics(result: MakeResult, diagnostics: Diagnostic[]): MakeResult {
+  const all = [...result.diagnostics, ...diagnostics];
+  return {
+    ...result,
+    ok: !all.some((diagnostic) => diagnostic.severity === "error"),
+    diagnostics: all,
+    exitCode: all.some((diagnostic) => diagnostic.severity === "error") ? 1 : result.exitCode,
+  };
+}
+
+async function runPostApplyChecks(
+  options: MakeCommandOptions,
+  result: MakeResult,
+): Promise<MakeResult> {
+  if (!result.applied || !result.plan || !result.ok) {
+    return result;
+  }
+
+  let current = result;
+
+  if (!options.noGenerate) {
+    const generated = await run({
+      workspaceRoot: options.workspaceRoot,
+      check: false,
+      dryRun: false,
+      json: false,
+      concurrency: 4,
+    });
+    current = appendDiagnostics(current, [...generated.errors, ...generated.warnings]);
+  }
+
+  if (!options.noVerify && current.ok) {
+    const generatedCheck = await run({
+      workspaceRoot: options.workspaceRoot,
+      check: true,
+      dryRun: false,
+      json: false,
+      concurrency: 4,
+    });
+    const diagnostics = [...generatedCheck.errors, ...generatedCheck.warnings];
+    if (generatedCheck.exitCode !== 0) {
+      diagnostics.push(
+        createDiagnostic({
+          severity: "error",
+          code: "FORGE_MAKE_VERIFY_FAILED",
+          message: "post-apply forge generate --check failed",
+        }),
+      );
+    }
+    current = appendDiagnostics(current, diagnostics);
+  }
+
+  if (!current.ok && !options.keepFailed) {
+    const rollback = rollbackMakePlan(options.workspaceRoot, result.plan.id);
+    current = {
+      ...current,
+      applied: false,
+      explanation: `${current.explanation ?? ""}${current.explanation ? "\n" : ""}Rolled back failed make plan ${result.plan.id}.`,
+      diagnostics: [...current.diagnostics, ...rollback.diagnostics],
+    };
+  }
+
+  return current;
+}
+
+export async function runMakeCommand(options: MakeCommandOptions): Promise<MakeResult> {
+  const result = planMakeCommand(options);
+  return runPostApplyChecks(options, result);
+}
+
+export function formatMakeJson(result: MakeResult): string {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}
+
+function formatDiagnostics(diagnostics: Diagnostic[]): string {
+  if (diagnostics.length === 0) {
+    return "";
+  }
+  return `\nDiagnostics:\n${diagnostics
+    .map((diagnostic) => `- ${diagnostic.severity} ${diagnostic.code}: ${diagnostic.message}`)
+    .join("\n")}\n`;
+}
+
+export function formatMakeHuman(result: MakeResult): string {
+  if (result.primitives) {
+    return `Forge make primitives:\n${result.primitives.map((primitive) => `- ${primitive}`).join("\n")}\n`;
+  }
+
+  if (result.explanation && !result.plan) {
+    return `${result.explanation}\n${formatDiagnostics(result.diagnostics)}`;
+  }
+
+  if (!result.plan) {
+    return `Forge make ${result.ok ? "ok" : "failed"}\n${formatDiagnostics(result.diagnostics)}`;
+  }
+
+  const plan = result.plan;
+  const lines = [
+    `Forge Make ${result.applied ? "Applied" : "Plan"}`,
+    "",
+    plan.summary,
+    `Plan id: ${plan.id}`,
+    `Risk: ${plan.risk.level}`,
+    "",
+    "Files to create:",
+    ...(plan.filesToCreate.length > 0
+      ? plan.filesToCreate.map((file) => `- ${file.file}`)
+      : ["- none"]),
+    "",
+    "Files to modify:",
+    ...(plan.filesToModify.length > 0
+      ? plan.filesToModify.map((file) => `- ${file.file}`)
+      : ["- none"]),
+  ];
+
+  if (result.planPath) {
+    lines.push("", `Saved plan: ${result.planPath}`);
+  }
+  if (plan.commandsToRun.length > 0) {
+    lines.push("", "Commands:", ...plan.commandsToRun.map((command) => `- ${command}`));
+  }
+  if (result.explanation) {
+    lines.push("", result.explanation);
+  }
+
+  return `${lines.join("\n")}\n${formatDiagnostics(result.diagnostics)}`;
+}