forgeos 0.1.0-alpha.0 → 0.1.0-alpha.2

package/src/forge/cli/deps.ts

@@ -6,7 +6,18 @@ import { GENERATED_DIR } from "../compiler/emitter/constants.ts";
 import type { Diagnostic } from "../compiler/types/diagnostic.ts";
 import type { PackageGraph } from "../compiler/types/package-graph.ts";
 import type { ForgeLock } from "../compiler/types/lock.ts";
+import { createDiagnostic } from "../compiler/diagnostics/create.ts";
+import {
+  FORGE_DEPS_RUNTIME_TYPE_MISMATCH,
+  FORGE_DEPS_UNKNOWN_EXPORT,
+} from "../compiler/diagnostics/codes.ts";
 import { resolveByPackageName } from "../compiler/recipes/registry.ts";
+import {
+  defaultPackageMetadata,
+  defaultRuntimeCompatibility,
+  summarizeDependencyApi,
+  traceForPackage,
+} from "../compiler/package-graph/oracle.ts";
 import {
   createUpgradePlan,
   listOutdatedFromFixture,
@@ -20,6 +31,9 @@ import {
 export type DepsSubcommand =
   | "outdated"
   | "inspect"
+  | "api"
+  | "trace"
+  | "runtime-compat"
   | "diff"
   | "upgrade-plan"
   | "upgrade-apply"
@@ -30,6 +44,7 @@ export type DepsSubcommand =
 export interface DepsCommandOptions {
   subcommand: DepsSubcommand;
   packageName?: string;
+  symbolName?: string;
   planPath?: string;
   target?: string;
   json: boolean;
@@ -68,38 +83,68 @@ function planPathFor(workspaceRoot: string, planIdOrPath: string): string {
   return join(workspaceRoot, ".forge", "upgrades", planIdOrPath, "plan.json");
 }
 
-function inspectPackage(workspaceRoot: string, packageName: string): DepsCommandResult {
+function findPackage(workspaceRoot: string, packageName: string): {
+  graph: PackageGraph | null;
+  pkg: PackageGraph["packages"][number] | undefined;
+  lock: ForgeLock | null;
+} {
   const graph = readGeneratedJson<PackageGraph>(workspaceRoot, `${GENERATED_DIR}/packageGraph.json`);
   const lock = nodeFileSystem.exists(join(workspaceRoot, "forge.lock"))
     ? (JSON.parse((nodeFileSystem.readText(join(workspaceRoot, "forge.lock")) ?? "")) as ForgeLock)
     : null;
   const pkg = graph?.packages.find((candidate) => candidate.name === packageName);
+  return { graph, pkg, lock };
+}
+
+function packageMissing(packageName: string): DepsCommandResult {
+  return {
+    ok: false,
+    diagnostics: [{
+      severity: "error",
+      code: "FORGE_DEPS_PACKAGE_NOT_INSTALLED",
+      message: `package '${packageName}' is not present in generated packageGraph`,
+      fixHint: "Run forge generate, then retry the deps command.",
+      suggestedCommands: ["forge generate", `forge deps inspect ${packageName} --json`],
+    }],
+    exitCode: 1,
+  };
+}
+
+function inspectPackage(workspaceRoot: string, packageName: string): DepsCommandResult {
+  const { pkg, lock } = findPackage(workspaceRoot, packageName);
   const lockEntry = lock?.packages.find((candidate) => candidate.name === packageName);
   const recipe = resolveByPackageName(packageName);
 
   if (!pkg) {
-    return {
-      ok: false,
-      diagnostics: [{
-        severity: "error",
-        code: "FORGE_DEPS_PACKAGE_NOT_INSTALLED",
-        message: `package '${packageName}' is not present in generated packageGraph`,
-      }],
-      exitCode: 1,
-    };
+    return packageMissing(packageName);
   }
 
+  const runtimeMismatchDiagnostics = (pkg.runtimeTypeMismatches ?? []).map((mismatch) =>
+    createDiagnostic({
+      severity: "warning",
+      code: FORGE_DEPS_RUNTIME_TYPE_MISMATCH,
+      message: `${packageName} ${mismatch.entrypoint} export '${mismatch.exportName}' is ${mismatch.kind}`,
+      fixHint: "Run forge deps api/trace and check package runtime inspection before relying on this export.",
+      suggestedCommands: [
+        `forge deps api ${packageName} ${mismatch.exportName} --json`,
+        `forge deps trace ${packageName} --json`,
+      ],
+    }),
+  );
+
   return {
-    ok: true,
+    ok: runtimeMismatchDiagnostics.every((diagnostic) => diagnostic.severity !== "error"),
     data: {
       package: packageName,
       version: pkg.version,
+      source: pkg.source,
       integrationAlias: recipe?.alias,
       recipeVersion: recipe?.recipeVersion,
       runtimeContexts: {
         allowed: lockEntry?.runtimeContexts ?? [],
         denied: recipe?.contexts.denied ?? [],
       },
+      oracle: summarizeDependencyApi(pkg),
       usedBy: {
         generatedAdapters: (recipe?.adapters ?? []).map(
           (adapter) => `src/forge/_generated/packages/${adapter}`,
@@ -107,6 +152,90 @@ function inspectPackage(workspaceRoot: string, packageName: string): DepsCommand
       },
       secrets: (recipe?.secrets ?? []).map((secret) => secret.envVar),
     },
+    diagnostics: runtimeMismatchDiagnostics,
+    exitCode: 0,
+  };
+}
+
+function inspectPackageApi(workspaceRoot: string, packageName: string, symbolName: string | undefined): DepsCommandResult {
+  const { pkg } = findPackage(workspaceRoot, packageName);
+  if (!pkg) {
+    return packageMissing(packageName);
+  }
+  if (!symbolName) {
+    return {
+      ok: false,
+      diagnostics: [{
+        severity: "error",
+        code: FORGE_DEPS_UNKNOWN_EXPORT,
+        message: "symbol name is required",
+        fixHint: `Use: forge deps api ${packageName} <symbol> --json`,
+      }],
+      exitCode: 1,
+    };
+  }
+  const summary = summarizeDependencyApi(pkg, symbolName);
+  if (summary.symbols.length === 0) {
+    return {
+      ok: false,
+      data: summary,
+      diagnostics: [
+        createDiagnostic({
+          severity: "error",
+          code: FORGE_DEPS_UNKNOWN_EXPORT,
+          message: `${packageName} does not expose '${symbolName}' in generated packageGraph`,
+          fixHint: "Run forge deps inspect to list exports, or run forge generate if node_modules changed.",
+          suggestedCommands: [`forge deps inspect ${packageName} --json`, "forge generate"],
+        }),
+      ],
+      exitCode: 1,
+    };
+  }
+  return {
+    ok: true,
+    data: summary,
+    diagnostics: [],
+    exitCode: 0,
+  };
+}
+
+function tracePackage(workspaceRoot: string, packageName: string): DepsCommandResult {
+  const { pkg } = findPackage(workspaceRoot, packageName);
+  if (!pkg) {
+    return packageMissing(packageName);
+  }
+  return {
+    ok: true,
+    data: {
+      package: packageName,
+      version: pkg.version,
+      source: pkg.source,
+      resolutionMode: pkg.resolutionMode,
+      traces: traceForPackage(pkg),
+      runtimeShapeAvailable: Boolean(pkg.runtimeShape),
+      runtimeTypeMismatches: pkg.runtimeTypeMismatches ?? [],
+    },
+    diagnostics: [],
+    exitCode: 0,
+  };
+}
+
+function runtimeCompatPackage(workspaceRoot: string, packageName: string): DepsCommandResult {
+  const { pkg } = findPackage(workspaceRoot, packageName);
+  if (!pkg) {
+    return packageMissing(packageName);
+  }
+  return {
+    ok: true,
+    data: {
+      package: packageName,
+      version: pkg.version,
+      runtimeCompatibility: pkg.runtimeCompatibility ?? defaultRuntimeCompatibility(),
+      metadata: pkg.metadata ?? defaultPackageMetadata(pkg.entrypoints.length),
+      runtimeContexts: pkg.entrypoints.flatMap((entrypoint) =>
+        entrypoint.exports.flatMap((exported) => exported.classification.compatible),
+      ).filter((value, index, array) => array.indexOf(value) === index).sort(),
+    },
     diagnostics: [],
     exitCode: 0,
   };
@@ -129,6 +258,27 @@ export async function runDepsCommand(options: DepsCommandOptions): Promise<DepsC
     return inspectPackage(options.workspaceRoot, options.packageName);
   }
 
+  if (options.subcommand === "api") {
+    if (!options.packageName) {
+      return missingPackage();
+    }
+    return inspectPackageApi(options.workspaceRoot, options.packageName, options.symbolName);
+  }
+
+  if (options.subcommand === "trace") {
+    if (!options.packageName) {
+      return missingPackage();
+    }
+    return tracePackage(options.workspaceRoot, options.packageName);
+  }
+
+  if (options.subcommand === "runtime-compat") {
+    if (!options.packageName) {
+      return missingPackage();
+    }
+    return runtimeCompatPackage(options.workspaceRoot, options.packageName);
+  }
+
   if (options.subcommand === "diff" || options.subcommand === "upgrade-plan" || options.subcommand === "risk") {
     if (!options.packageName) {
       return missingPackage();
@@ -273,5 +423,22 @@ export function formatDepsHuman(subcommand: DepsSubcommand, result: DepsCommandR
     const data = result.data as { planDir?: string; plan?: { risk?: { level?: string } } } | undefined;
     return `upgrade plan written: ${data?.planDir ?? "not written"}\nrisk: ${data?.plan?.risk?.level ?? "unknown"}\n`;
   }
+  if (subcommand === "api") {
+    const data = result.data as { package?: string; version?: string; symbols?: Array<{ entrypoint: string; name: string; signature: string }> } | undefined;
+    const symbols = data?.symbols ?? [];
+    return `deps api ${data?.package ?? ""}@${data?.version ?? ""}\n${symbols.map((symbol) => `${symbol.entrypoint} ${symbol.name}: ${symbol.signature}`).join("\n")}\n`;
+  }
+  if (subcommand === "trace") {
+    const data = result.data as { package?: string; version?: string; traces?: Array<{ entrypoint: string; trace: Array<{ step: string; status: string; detail: string }> }> } | undefined;
+    const lines = (data?.traces ?? []).flatMap((entry) => [
+      `${entry.entrypoint}:`,
+      ...entry.trace.map((step) => `  ${step.status} ${step.step}: ${step.detail}`),
+    ]);
+    return `deps trace ${data?.package ?? ""}@${data?.version ?? ""}\n${lines.join("\n")}\n`;
+  }
+  if (subcommand === "runtime-compat") {
+    const data = result.data as { package?: string; version?: string; runtimeCompatibility?: Record<string, unknown> } | undefined;
+    return `deps runtime-compat ${data?.package ?? ""}@${data?.version ?? ""}\n${JSON.stringify(data?.runtimeCompatibility ?? {}, null, 2)}\n`;
+  }
   return `deps ${subcommand} ok${diagnostics ? `\n${diagnostics}` : ""}\n`;
 }

package/src/forge/cli/dev.ts

@@ -147,6 +147,30 @@ function hasWebApp(workspaceRoot: string): boolean {
   );
 }
 
+function sanitizeProcessEnv(
+  env: NodeJS.ProcessEnv,
+  extra: Record<string, string>,
+): Record<string, string> {
+  const sanitized: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (typeof value === "string") {
+      sanitized[key] = value;
+    }
+  }
+  return {
+    ...sanitized,
+    ...extra,
+  };
+}
+
+function wrapWindowsShellCommand(command: string[]): string[] {
+  const executable = command[0];
+  if (process.platform !== "win32" || !executable || !/\.(cmd|bat)$/i.test(executable)) {
+    return command;
+  }
+  return [process.env.ComSpec ?? "cmd.exe", "/d", "/c", ...command];
+}
+
 function startWebDevServer(input: {
   workspaceRoot: string;
   host: string;
@@ -161,24 +185,27 @@ function startWebDevServer(input: {
 
   const pkg = readPackageJson(input.workspaceRoot);
   const packageManager = detectPackageManager(input.workspaceRoot);
-  const env = {
-    ...process.env,
+  const env = sanitizeProcessEnv(process.env, {
     PORT: String(input.port),
     NEXT_PUBLIC_FORGE_URL: input.apiUrl,
     VITE_FORGE_URL: input.apiUrl,
-  };
+  });
   const rawCommand =
     pkg?.scripts?.dev
       ? [packageManager, "run", "dev", "--", ...webDevArgsForPackage(pkg, input)]
       : ["node", "--import", "tsx", "server.ts"];
-  const command = resolvePackageManagerArgv(rawCommand);
+  const command = wrapWindowsShellCommand(resolvePackageManagerArgv(rawCommand));
   const cwd = pkg?.scripts?.dev ? webRoot : webRoot;
   const child = spawn(command[0]!, command.slice(1), {
     cwd,
-    stdio: ["ignore", input.json ? "pipe" : "inherit", input.json ? "pipe" : "inherit"],
+    stdio: ["ignore", "pipe", "pipe"],
     env,
     windowsHide: true,
   });
+  if (!input.json) {
+    child.stdout?.on("data", (chunk: Buffer) => process.stdout.write(chunk));
+    child.stderr?.on("data", (chunk: Buffer) => process.stderr.write(chunk));
+  }
   return {
     url: `http://${input.host}:${input.port}`,
     port: input.port,

package/src/forge/cli/index.ts

@@ -1,4 +1,4 @@
-export { CLI_VERSION } from "./version.ts";
+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";
@@ -17,9 +17,9 @@ export {
 } from "./doctor.ts";
 export {
   executeCommand,
-  runGenerateCommand,
-  runAddCommand,
-  runCheckCommand,
-  runInspectCommand,
-} from "./commands.ts";
-export { main } from "./main.ts";
+  runGenerateCommand,
+  runAddCommand,
+  runCheckCommand,
+  runInspectCommand,
+} from "./commands.ts";
+export { main } from "./main.ts";

package/src/forge/cli/main.ts

@@ -32,60 +32,60 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
   }
 
   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 (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/new.ts

@@ -57,6 +57,8 @@ const REQUIRED_GITIGNORE_PATHS = [
   ".forge/agent-adapters/",
 ] as const;
 
+const DEFAULT_FORGE_PACKAGE_SPEC = "npm:forgeos@alpha";
+
 const TEXT_EXTENSIONS = new Set([
   "",
   ".css",
@@ -135,7 +137,10 @@ function forgePackageSpec(targetDir: string, options: Pick<NewCommandOptions, "f
   if (options.forgePackageSpec && !options.localForge) {
     return normalizeForgePackageSpec(options.forgePackageSpec);
   }
-  return localForgePackageSpec(targetDir);
+  if (options.localForge) {
+    return localForgePackageSpec(targetDir);
+  }
+  return DEFAULT_FORGE_PACKAGE_SPEC;
 }
 
 function packageManagerSpec(packageManager: string): string {
@@ -207,6 +212,28 @@ function analyzeGitHygiene(targetDir: string): NewCommandResult["gitHygiene"] {
   };
 }
 
+function ensureGitignore(targetDir: string): void {
+  const gitignorePath = join(targetDir, ".gitignore");
+  const existing = nodeFileSystem.exists(gitignorePath)
+    ? (nodeFileSystem.readText(gitignorePath) ?? "")
+    : "";
+  const normalized = existing.replace(/\r\n/g, "\n");
+  const missingPaths = REQUIRED_GITIGNORE_PATHS.filter(
+    (path) => !normalized.includes(path),
+  );
+  if (normalized.trim().length > 0 && missingPaths.length === 0) {
+    return;
+  }
+
+  const sections = [
+    normalized.trimEnd(),
+    normalized.trim().length > 0 ? "" : "node_modules/\ndist/\n.env\n.env.local",
+    "# ForgeOS generated and local runtime artifacts",
+    ...missingPaths,
+  ].filter(Boolean);
+  nodeFileSystem.writeText(gitignorePath, `${sections.join("\n")}\n`);
+}
+
 async function spawnCommand(
   command: string,
   args: string[],
@@ -393,6 +420,7 @@ export async function runNewCommand(options: NewCommandOptions): Promise<NewComm
 
   nodeFileSystem.mkdirp(targetDir);
   cpSync(source, targetDir, { recursive: true, force: true });
+  ensureGitignore(targetDir);
   replaceTokens(
     targetDir,
     options.name,