forgeos 0.1.0-alpha.0

package/src/forge/compiler/package-graph/jsdoc.ts

@@ -0,0 +1,62 @@
+import ts from "typescript";
+import type { JsDoc } from "../types/package-graph.ts";
+
+function tagText(tag: ts.JSDocTag): string {
+  if (typeof tag.comment === "string") {
+    return tag.comment.trim();
+  }
+  if (tag.comment) {
+    return tag.comment
+      .map((part) => part.text)
+      .join("")
+      .trim();
+  }
+  return "";
+}
+
+export function extractJsDoc(
+  symbol: ts.Symbol,
+  checker: ts.TypeChecker,
+): JsDoc | null {
+  const parts = symbol.getDocumentationComment(checker);
+  const summary = ts.displayPartsToString(parts).trim();
+
+  const tags: { tag: string; text: string }[] = [];
+  for (const decl of symbol.declarations ?? []) {
+    for (const tag of ts.getJSDocTags(decl)) {
+      tags.push({
+        tag: tag.tagName.text,
+        text: tagText(tag),
+      });
+    }
+  }
+
+  if (summary.length === 0 && tags.length === 0) {
+    return null;
+  }
+
+  tags.sort((a, b) => {
+    const tagCmp = a.tag.localeCompare(b.tag);
+    if (tagCmp !== 0) return tagCmp;
+    return a.text.localeCompare(b.text);
+  });
+
+  return { summary, tags };
+}
+
+export function extractExamples(jsdoc: JsDoc | null): string[] {
+  if (jsdoc == null) {
+    return [];
+  }
+
+  const examples = jsdoc.tags
+    .filter((tag) => tag.tag.toLowerCase() === "example")
+    .map((tag) => normalizeExample(tag.text))
+    .filter((text) => text.length > 0);
+
+  return [...new Set(examples)].sort((a, b) => a.localeCompare(b));
+}
+
+function normalizeExample(text: string): string {
+  return text.replace(/\r\n/g, "\n").trim();
+}

package/src/forge/compiler/package-graph/read-file.ts

@@ -0,0 +1,21 @@
+import { readFileSync } from "node:fs";
+
+export interface ReadFileTracker {
+  recordRead(path: string): void;
+}
+
+let activeTracker: ReadFileTracker | undefined;
+
+export function setReadFileTracker(tracker: ReadFileTracker | undefined): void {
+  activeTracker = tracker;
+}
+
+export function readTextFile(path: string): string {
+  activeTracker?.recordRead(path);
+  return readFileSync(path, "utf8");
+}
+
+export function readBinaryFile(path: string): Uint8Array {
+  activeTracker?.recordRead(path);
+  return readFileSync(path);
+}

package/src/forge/compiler/package-graph/resolve.ts

@@ -0,0 +1,127 @@
+import { join } from "node:path";
+import ts from "typescript";
+import type { ResolutionMode } from "../types/runtime.ts";
+import { readTextFile } from "./read-file.ts";
+
+export interface ResolvedEntrypoint {
+  dtsPath: string | null;
+  conditions: string[];
+}
+
+export function createResolutionCompilerOptions(
+  mode: ResolutionMode,
+): ts.CompilerOptions {
+  return {
+    moduleResolution:
+      mode === "nodenext"
+        ? ts.ModuleResolutionKind.NodeNext
+        : ts.ModuleResolutionKind.Bundler,
+    resolvePackageJsonExports: true,
+    resolvePackageJsonImports: true,
+    customConditions: ["types"],
+    noEmit: true,
+    types: [],
+    skipLibCheck: true,
+  };
+}
+
+export function moduleSpecifierForSubpath(
+  packageName: string,
+  subpath: string,
+): string {
+  if (subpath === ".") {
+    return packageName;
+  }
+  const trimmed = subpath.startsWith("./") ? subpath.slice(2) : subpath;
+  return `${packageName}/${trimmed}`;
+}
+
+export function resolveEntrypointTypes(
+  installPath: string,
+  packageName: string,
+  subpath: string,
+  mode: ResolutionMode,
+): ResolvedEntrypoint {
+  const containingFile = join(installPath, "package.json");
+  const specifier = moduleSpecifierForSubpath(packageName, subpath);
+  const options = createResolutionCompilerOptions(mode);
+
+  const result = ts.resolveModuleName(
+    specifier,
+    containingFile,
+    options,
+    ts.sys,
+  );
+
+  const resolved = result.resolvedModule;
+  if (resolved == null) {
+    return { dtsPath: null, conditions: [] };
+  }
+
+  const dtsPath = pickTypesPath(resolved);
+  const conditions = extractConditions(resolved);
+
+  return { dtsPath, conditions };
+}
+
+function pickTypesPath(resolved: ts.ResolvedModuleFull): string | null {
+  if (resolved.extension === ts.Extension.Dts) {
+    return resolved.resolvedFileName;
+  }
+  if (resolved.extension === ts.Extension.Ts) {
+    return resolved.resolvedFileName;
+  }
+  if (resolved.extension === ts.Extension.Tsx) {
+    return resolved.resolvedFileName;
+  }
+  return resolved.resolvedFileName.endsWith(".d.ts")
+    ? resolved.resolvedFileName
+    : null;
+}
+
+function extractConditions(resolved: ts.ResolvedModuleFull): string[] {
+  const conditions = (resolved as { packageId?: { conditions?: string[] } })
+    .packageId?.conditions;
+  if (Array.isArray(conditions) && conditions.length > 0) {
+    return [...conditions];
+  }
+  return [];
+}
+
+export function typesPackageName(packageName: string): string {
+  if (packageName.startsWith("@")) {
+    return `@types/${packageName.slice(1).replace("/", "__")}`;
+  }
+  return `@types/${packageName}`;
+}
+
+export function resolveTypesPackage(
+  typesPackageName: string,
+  installPath: string,
+  mode: ResolutionMode,
+): string | null {
+  const typesInstallPath = join(installPath, "..", typesPackageName);
+  const packageJsonPath = join(typesInstallPath, "package.json");
+
+  try {
+    readTextFile(packageJsonPath);
+  } catch {
+    return null;
+  }
+
+  const directIndex = join(typesInstallPath, "index.d.ts");
+  try {
+    readTextFile(directIndex);
+    return directIndex;
+  } catch {
+    // fall through to module resolver
+  }
+
+  const resolved = resolveEntrypointTypes(
+    typesInstallPath,
+    typesPackageName,
+    ".",
+    mode,
+  );
+  return resolved.dtsPath;
+}

package/src/forge/compiler/package-manager/adapter.ts

@@ -0,0 +1,237 @@
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { nodeFileSystem } from "../fs/index.ts";
+import type { PackageManager } from "../types/runtime.ts";
+import type { PmAddOptions, PmAddResult } from "../types/cli.ts";
+import { buildAddCommand } from "./commands.ts";
+import {
+  detectPackageManager,
+  getLockfileCandidates,
+  getLockfileForPm,
+} from "./detect.ts";
+import {
+  defaultCommandExecutor,
+  PackageManagerCommandError,
+  type CommandExecutor,
+} from "./executor.ts";
+import { parsePackageName } from "./parse-spec.ts";
+import { readInstalledVersion } from "./version.ts";
+
+export interface PackageManagerAdapter {
+  readonly name: PackageManager;
+  readonly lockfile: string;
+  add(spec: string, opts: PmAddOptions): Promise<PmAddResult>;
+  dryRunAdd(spec: string, opts: PmAddOptions): Promise<PmAddResult>;
+  /** Install into a temp dir; caller owns cleanup unless using dryRunAdd. */
+  dryRunAddWithPath(spec: string, opts: PmAddOptions): Promise<DryRunAddResult>;
+  detectResolvedVersion(spec: string, cwd: string): Promise<string>;
+}
+
+export interface DryRunAddResult extends PmAddResult {
+  /** Absolute path to the temp install directory (for downstream analysis). */
+  installPath: string;
+}
+
+export interface CreatePackageManagerAdapterOptions {
+  executor?: CommandExecutor;
+  /** When true, retain the temp directory after dryRunAdd (for debugging). */
+  retainDryRunDir?: boolean;
+}
+
+function hashFile(path: string): string | null {
+  if (!nodeFileSystem.exists(path)) {
+    return null;
+  }
+  const content = readFileSync(path);
+  return createHash("sha256").update(content).digest("hex");
+}
+
+function hashLockfiles(cwd: string, pm: PackageManager): string | null {
+  const hashes: string[] = [];
+  for (const file of getLockfileCandidates(pm)) {
+    const h = hashFile(join(cwd, file));
+    if (h !== null) {
+      hashes.push(`${file}:${h}`);
+    }
+  }
+  return hashes.length > 0 ? hashes.join("|") : null;
+}
+
+function lockfileChanged(
+  before: string | null,
+  after: string | null,
+  pm: PackageManager,
+  cwd: string,
+): boolean {
+  if (before !== after) {
+    return true;
+  }
+  // Lockfile may be created on first install.
+  if (before === null) {
+    return getLockfileCandidates(pm).some((f) =>
+      nodeFileSystem.exists(join(cwd, f)),
+    );
+  }
+  return false;
+}
+
+async function runInstall(
+  pm: PackageManager,
+  spec: string,
+  opts: PmAddOptions,
+  executor: CommandExecutor,
+): Promise<PmAddResult> {
+  const ignoreScripts = opts.ignoreScripts ?? true;
+  const argv = buildAddCommand(pm, spec, { ignoreScripts });
+  const lockBefore = hashLockfiles(opts.cwd, pm);
+
+  const result = await executor.run(argv, { cwd: opts.cwd });
+  if (result.exitCode !== 0) {
+    throw new PackageManagerCommandError(
+      `Package manager ${pm} failed to add ${spec}: ${result.stderr || result.stdout}`,
+      argv,
+      result,
+    );
+  }
+
+  const packageName = parsePackageName(spec);
+  const resolvedVersion = readInstalledVersion(packageName, opts.cwd);
+  if (!resolvedVersion) {
+    throw new Error(
+      `Could not detect installed version for ${packageName} in ${opts.cwd}`,
+    );
+  }
+
+  const lockAfter = hashLockfiles(opts.cwd, pm);
+
+  return {
+    resolvedVersion,
+    lockfileChanged: lockfileChanged(lockBefore, lockAfter, pm, opts.cwd),
+  };
+}
+
+class PackageManagerAdapterImpl implements PackageManagerAdapter {
+  readonly name: PackageManager;
+  readonly lockfile: string;
+  private readonly executor: CommandExecutor;
+  private readonly retainDryRunDir: boolean;
+
+  constructor(
+    name: PackageManager,
+    options: CreatePackageManagerAdapterOptions = {},
+  ) {
+    this.name = name;
+    this.lockfile = getLockfileForPm(name);
+    this.executor = options.executor ?? defaultCommandExecutor;
+    this.retainDryRunDir = options.retainDryRunDir ?? false;
+  }
+
+  async add(spec: string, opts: PmAddOptions): Promise<PmAddResult> {
+    return runInstall(this.name, spec, opts, this.executor);
+  }
+
+  async dryRunAdd(spec: string, opts: PmAddOptions): Promise<PmAddResult> {
+    const result = await this.dryRunAddWithPath(spec, opts);
+    if (!this.retainDryRunDir) {
+      try {
+        nodeFileSystem.remove(result.installPath);
+      } catch {
+        // best-effort cleanup
+      }
+    }
+    return {
+      resolvedVersion: result.resolvedVersion,
+      integrity: result.integrity,
+      lockfileChanged: false,
+    };
+  }
+
+  /** Internal: dry-run install returning the temp directory path. */
+  async dryRunAddWithPath(
+    spec: string,
+    opts: PmAddOptions,
+  ): Promise<DryRunAddResult> {
+    const cacheBase = join(opts.cwd, ".forge", "cache", "dry-run");
+    nodeFileSystem.mkdirp(cacheBase);
+    const tempDir = nodeFileSystem.makeTempDir(join(cacheBase, "add-"));
+
+    const minimalPkg = {
+      name: "forge-dry-run",
+      private: true,
+      version: "0.0.0",
+    };
+    writeFileSync(
+      join(tempDir, "package.json"),
+      `${JSON.stringify(minimalPkg, null, 2)}\n`,
+      "utf8",
+    );
+
+    const installResult = await runInstall(
+      this.name,
+      spec,
+      {
+        cwd: tempDir,
+        ignoreScripts: opts.ignoreScripts ?? true,
+      },
+      this.executor,
+    );
+
+    return {
+      ...installResult,
+      lockfileChanged: false,
+      installPath: tempDir,
+    };
+  }
+
+  async detectResolvedVersion(spec: string, cwd: string): Promise<string> {
+    const version = readInstalledVersion(spec, cwd);
+    if (!version) {
+      throw new Error(
+        `Package ${parsePackageName(spec)} is not installed in ${cwd}`,
+      );
+    }
+    return version;
+  }
+}
+
+export function createPackageManagerAdapter(
+  pm: PackageManager,
+  options?: CreatePackageManagerAdapterOptions,
+): PackageManagerAdapter {
+  return new PackageManagerAdapterImpl(pm, options);
+}
+
+export function detectAndCreatePackageManagerAdapter(
+  workspaceRoot: string,
+  options?: CreatePackageManagerAdapterOptions,
+): PackageManagerAdapter {
+  const pm = detectPackageManager(workspaceRoot);
+  return createPackageManagerAdapter(pm, options);
+}
+
+/** Fallback when dry-run install is unavailable: recipe-known plan placeholder. */
+export function dryRunRecipeFallbackMessage(alias: string): string {
+  return (
+    `Dry-run for "${alias}": .d.ts analysis requires a real install. ` +
+    `Use dryRunAdd to install into a temp directory, or run forge add without --dry-run.`
+  );
+}
+
+export {
+  detectPackageManager,
+  detectPackageManagerFromLockfiles,
+  getLockfileForPm,
+  getLockfileCandidates,
+  parsePackageManagerField,
+  LOCKFILE_PM_MAP,
+} from "./detect.ts";
+export { buildAddCommand } from "./commands.ts";
+export { parsePackageName } from "./parse-spec.ts";
+export { readInstalledVersion } from "./version.ts";
+export {
+  defaultCommandExecutor,
+  PackageManagerCommandError,
+  type CommandExecutor,
+  type CommandRunResult,
+} from "./executor.ts";

package/src/forge/compiler/package-manager/bun-executable.ts

@@ -0,0 +1,92 @@
+import { homedir } from "node:os";
+import { nodeFileSystem } from "../fs/index.ts";
+import { basename, join, win32 } from "node:path";
+
+export interface BunExecutableResolutionOptions {
+  env?: Record<string, string | undefined>;
+  execPath?: string;
+  exists?: (path: string) => boolean;
+  homeDir?: string;
+  platform?: NodeJS.Platform;
+  which?: (command: string) => string | null | undefined;
+}
+
+function isBunExecutablePath(path: string, platform: NodeJS.Platform): boolean {
+  const file = (platform === "win32" ? win32.basename(path) : basename(path)).toLowerCase();
+  return platform === "win32" ? file === "bun.exe" : file === "bun";
+}
+
+function normalizeWindowsBunCandidate(
+  candidate: string | null | undefined,
+  exists: (path: string) => boolean,
+): string | null {
+  if (!candidate) {
+    return null;
+  }
+
+  const normalizedForMatch = candidate.replace(/\//g, "\\").toLowerCase();
+  if (normalizedForMatch.includes("\\kiro-cli\\")) {
+    return null;
+  }
+
+  if (candidate.toLowerCase().endsWith(".exe")) {
+    return exists(candidate) ? candidate : null;
+  }
+
+  const exeCandidate = `${candidate}.exe`;
+  return exists(exeCandidate) ? exeCandidate : null;
+}
+
+function unresolvedWindowsBunError(): Error {
+  return new Error(
+    "Unable to resolve a safe Bun executable on Windows. Install Bun at ~/.bun/bin/bun.exe or set FORGE_BUN to an existing bun.exe. Refusing to spawn bare bun.exe because Windows may open an app picker.",
+  );
+}
+
+/** Resolve the Bun executable for spawning child processes (Windows-safe). */
+export function resolveBunExecutable(options: BunExecutableResolutionOptions = {}): string {
+  const platform = options.platform ?? process.platform;
+  const exists = options.exists ?? nodeFileSystem.exists;
+  const execPath = options.execPath ?? process.execPath;
+  const configured = options.env?.FORGE_BUN ?? process.env.FORGE_BUN;
+
+  if (configured) {
+    if (platform === "win32") {
+      const normalized = normalizeWindowsBunCandidate(configured, exists);
+      if (normalized) {
+        return normalized;
+      }
+    } else if (exists(configured)) {
+      return configured;
+    }
+    throw new Error(`FORGE_BUN does not point to a safe Bun executable: ${configured}`);
+  }
+
+  if (isBunExecutablePath(execPath, platform) && exists(execPath)) {
+    return execPath;
+  }
+
+  const fromPath =
+    options.which?.("bun") ?? (typeof Bun !== "undefined" ? Bun.which("bun") : undefined);
+
+  if (platform === "win32") {
+    const normalized = normalizeWindowsBunCandidate(fromPath, exists);
+    if (normalized) {
+      return normalized;
+    }
+
+    const joinPath = platform === "win32" ? win32.join : join;
+    const homeBun = joinPath(options.homeDir ?? homedir(), ".bun", "bin", "bun.exe");
+    if (exists(homeBun)) {
+      return homeBun;
+    }
+
+    throw unresolvedWindowsBunError();
+  }
+
+  if (fromPath) {
+    return fromPath;
+  }
+
+  return "bun";
+}

package/src/forge/compiler/package-manager/commands.ts

@@ -0,0 +1,47 @@
+import type { PackageManager } from "../types/runtime.ts";
+
+export interface BuildAddCommandOptions {
+  ignoreScripts: boolean;
+}
+
+/**
+ * Build argv for adding a dependency with lifecycle scripts disabled by default.
+ */
+export function buildAddCommand(
+  pm: PackageManager,
+  spec: string,
+  options: BuildAddCommandOptions,
+): string[] {
+  const ignoreScripts = options.ignoreScripts;
+
+  switch (pm) {
+    case "bun": {
+      const args = ["bun", "add", spec];
+      if (ignoreScripts) {
+        args.push("--ignore-scripts");
+      }
+      return args;
+    }
+    case "npm": {
+      const args = ["npm", "install", spec, "--save", "--no-fund", "--no-audit"];
+      if (ignoreScripts) {
+        args.push("--ignore-scripts");
+      }
+      return args;
+    }
+    case "pnpm": {
+      const args = ["pnpm", "add", spec];
+      if (ignoreScripts) {
+        args.push("--ignore-scripts");
+      }
+      return args;
+    }
+    case "yarn": {
+      const args = ["yarn", "add", spec];
+      if (ignoreScripts) {
+        args.push("--ignore-scripts");
+      }
+      return args;
+    }
+  }
+}

package/src/forge/compiler/package-manager/detect.ts

@@ -0,0 +1,79 @@
+import { join } from "node:path";
+import { nodeFileSystem } from "../fs/index.ts";
+import type { PackageManager } from "../types/runtime.ts";
+
+/** Lockfiles checked in priority order when `packageManager` is absent. */
+export const LOCKFILE_PM_MAP: readonly { file: string; pm: PackageManager }[] = [
+  { file: "bun.lockb", pm: "bun" },
+  { file: "bun.lock", pm: "bun" },
+  { file: "pnpm-lock.yaml", pm: "pnpm" },
+  { file: "yarn.lock", pm: "yarn" },
+  { file: "package-lock.json", pm: "npm" },
+] as const;
+
+const PM_FROM_FIELD = /^(bun|npm|pnpm|yarn)(?:@|$)/;
+
+export function parsePackageManagerField(value: string): PackageManager | null {
+  const match = value.trim().match(PM_FROM_FIELD);
+  return match ? (match[1] as PackageManager) : null;
+}
+
+export function getLockfileForPm(pm: PackageManager): string {
+  switch (pm) {
+    case "bun":
+      return "bun.lock";
+    case "npm":
+      return "package-lock.json";
+    case "pnpm":
+      return "pnpm-lock.yaml";
+    case "yarn":
+      return "yarn.lock";
+  }
+}
+
+/** All lockfile names that may exist for a given package manager. */
+export function getLockfileCandidates(pm: PackageManager): readonly string[] {
+  if (pm === "bun") {
+    return ["bun.lock", "bun.lockb"];
+  }
+  return [getLockfileForPm(pm)];
+}
+
+export function detectPackageManagerFromLockfiles(
+  workspaceRoot: string,
+): PackageManager | null {
+  for (const { file, pm } of LOCKFILE_PM_MAP) {
+    if (nodeFileSystem.exists(join(workspaceRoot, file))) {
+      return pm;
+    }
+  }
+  return null;
+}
+
+/**
+ * Detect the active package manager via `package.json#packageManager` or lockfile presence.
+ * Defaults to `npm` when the project has not declared a package manager.
+ * Bun remains first-class when selected via `packageManager`, `bun.lock`, or
+ * `bun.lockb`; the neutral fallback avoids surprising Windows app-picker
+ * launches from ambiguous `bun` associations.
+ */
+export function detectPackageManager(workspaceRoot: string): PackageManager {
+  const pkgPath = join(workspaceRoot, "package.json");
+  if (nodeFileSystem.exists(pkgPath)) {
+    try {
+      const pkg = JSON.parse((nodeFileSystem.readText(pkgPath) ?? "")) as {
+        packageManager?: string;
+      };
+      if (pkg.packageManager) {
+        const fromField = parsePackageManagerField(pkg.packageManager);
+        if (fromField) {
+          return fromField;
+        }
+      }
+    } catch {
+      // fall through to lockfile detection
+    }
+  }
+
+  return detectPackageManagerFromLockfiles(workspaceRoot) ?? "npm";
+}