@contextforge/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yashwanth Krishna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,253 @@
+import { z } from 'zod';
+
+type PackageManager = "pnpm" | "npm" | "yarn" | "bun" | "unknown";
+type ProjectFramework = "next-app-router" | "next-pages-router" | "vite-react" | "unknown";
+type ProjectLanguage = "typescript" | "javascript";
+type AITool = "codex" | "claude" | "cursor" | "copilot";
+type ProjectAnalysis = {
+    root: string;
+    packageManager: PackageManager;
+    framework: ProjectFramework;
+    language: ProjectLanguage;
+    styling: {
+        tailwind: boolean;
+        shadcn: boolean;
+    };
+    database: {
+        prisma: boolean;
+        drizzle: boolean;
+    };
+    testing: {
+        vitest: boolean;
+        jest: boolean;
+        playwright: boolean;
+    };
+    aiTools: {
+        agentsMd: boolean;
+        claudeMd: boolean;
+        cursorRules: boolean;
+        copilotInstructions: boolean;
+    };
+};
+type GeneratedFile = {
+    path: string;
+    content: string;
+};
+
+declare function detectProject(root: string): Promise<ProjectAnalysis>;
+
+declare function detectPackageManager(root: string): Promise<PackageManager>;
+
+declare const PackSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
+    description: z.ZodString;
+    category: z.ZodEnum<{
+        framework: "framework";
+        database: "database";
+        testing: "testing";
+        security: "security";
+        ui: "ui";
+        workflow: "workflow";
+    }>;
+    detect: z.ZodOptional<z.ZodObject<{
+        files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    outputs: z.ZodObject<{
+        globalRules: z.ZodDefault<z.ZodBoolean>;
+        skill: z.ZodDefault<z.ZodBoolean>;
+        cursorRule: z.ZodDefault<z.ZodBoolean>;
+        copilotInstruction: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type Pack = z.infer<typeof PackSchema>;
+type LoadedPack = Pack & {
+    directory: string;
+    source: "project-cache" | "remote" | "local";
+    registryUrl?: string;
+    files: {
+        rules: string;
+        skill?: string;
+        cursor?: string;
+        copilot?: string;
+    };
+};
+declare const RemotePackFilesSchema: z.ZodObject<{
+    pack: z.ZodOptional<z.ZodString>;
+    rules: z.ZodOptional<z.ZodString>;
+    skill: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+    copilot: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const RemotePackEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    pack: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        description: z.ZodString;
+        category: z.ZodEnum<{
+            framework: "framework";
+            database: "database";
+            testing: "testing";
+            security: "security";
+            ui: "ui";
+            workflow: "workflow";
+        }>;
+        detect: z.ZodOptional<z.ZodObject<{
+            files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        outputs: z.ZodObject<{
+            globalRules: z.ZodDefault<z.ZodBoolean>;
+            skill: z.ZodDefault<z.ZodBoolean>;
+            cursorRule: z.ZodDefault<z.ZodBoolean>;
+            copilotInstruction: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    files: z.ZodOptional<z.ZodObject<{
+        pack: z.ZodOptional<z.ZodString>;
+        rules: z.ZodOptional<z.ZodString>;
+        skill: z.ZodOptional<z.ZodString>;
+        cursor: z.ZodOptional<z.ZodString>;
+        copilot: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const RemoteRegistryIndexSchema: z.ZodObject<{
+    version: z.ZodDefault<z.ZodString>;
+    packs: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+        baseUrl: z.ZodOptional<z.ZodString>;
+        pack: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            version: z.ZodOptional<z.ZodString>;
+            title: z.ZodString;
+            description: z.ZodString;
+            category: z.ZodEnum<{
+                framework: "framework";
+                database: "database";
+                testing: "testing";
+                security: "security";
+                ui: "ui";
+                workflow: "workflow";
+            }>;
+            detect: z.ZodOptional<z.ZodObject<{
+                files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>;
+            outputs: z.ZodObject<{
+                globalRules: z.ZodDefault<z.ZodBoolean>;
+                skill: z.ZodDefault<z.ZodBoolean>;
+                cursorRule: z.ZodDefault<z.ZodBoolean>;
+                copilotInstruction: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+        files: z.ZodOptional<z.ZodObject<{
+            pack: z.ZodOptional<z.ZodString>;
+            rules: z.ZodOptional<z.ZodString>;
+            skill: z.ZodOptional<z.ZodString>;
+            cursor: z.ZodOptional<z.ZodString>;
+            copilot: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type RemoteRegistryIndex = z.infer<typeof RemoteRegistryIndexSchema>;
+
+declare const OFFICIAL_REGISTRY_SOURCE = "official";
+declare const OFFICIAL_REGISTRY_URL = "https://registry.contextforge.dev/index.json";
+declare const DEFAULT_REGISTRY_SOURCES: string[];
+declare const PROJECT_PACK_CACHE = ".contextforge/packs";
+type LoadRegistryOptions = {
+    root?: string;
+    sources?: string[];
+    timeoutMs?: number;
+};
+declare function loadRegistry(input?: string | LoadRegistryOptions): Promise<LoadedPack[]>;
+
+type PackageJson = {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+    scripts?: Record<string, string>;
+};
+declare function readPackageJson(root: string): Promise<PackageJson | null>;
+declare function hasPackage(packageJson: PackageJson | null, packageName: string): boolean;
+declare function hasScript(packageJson: PackageJson | null, scriptName: string): boolean;
+
+declare function findPack(registry: LoadedPack[], packName: string): LoadedPack | undefined;
+declare function resolvePacks(packNames: string[], registry: LoadedPack[]): LoadedPack[];
+declare function recommendPacks(analysis: ProjectAnalysis, registry: LoadedPack[]): LoadedPack[];
+declare function packMatchesProject(pack: LoadedPack, root: string, packageJson: PackageJson | null): Promise<boolean>;
+declare function packageManagerLabel(packageManager: PackageManager): string;
+
+declare const ConfigSchema: z.ZodObject<{
+    version: z.ZodDefault<z.ZodString>;
+    registries: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tools: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        codex: "codex";
+        claude: "claude";
+        cursor: "cursor";
+        copilot: "copilot";
+    }>>>;
+    packs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    packageManager: z.ZodDefault<z.ZodEnum<{
+        pnpm: "pnpm";
+        npm: "npm";
+        yarn: "yarn";
+        bun: "bun";
+        unknown: "unknown";
+    }>>;
+    generatedFiles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type ContextForgeConfig = z.infer<typeof ConfigSchema>;
+
+declare const DEFAULT_TOOLS: AITool[];
+declare function createConfig(analysis: ProjectAnalysis, packs: LoadedPack[], tools?: AITool[], registries?: string[]): ContextForgeConfig;
+
+declare const CONFIG_PATH = ".contextforge/config.json";
+declare function loadConfig(root: string): Promise<ContextForgeConfig>;
+
+declare function saveConfig(root: string, config: ContextForgeConfig): Promise<void>;
+declare function addPackToConfig(config: ContextForgeConfig, packName: string): ContextForgeConfig;
+
+declare function cacheRemotePacks(root: string, packs: LoadedPack[]): Promise<void>;
+declare function saveInstalledPacks(root: string, packs: LoadedPack[]): Promise<void>;
+
+declare function compileOutputs(config: ContextForgeConfig, packs: LoadedPack[], analysis: ProjectAnalysis): GeneratedFile[];
+
+declare function writeGeneratedFiles(root: string, outputs: GeneratedFile[]): Promise<string[]>;
+
+declare function safeWriteFile(filePath: string, generatedContent: string): Promise<void>;
+
+declare const GENERATED_BLOCK_START = "<!-- contextforge:start -->";
+declare const GENERATED_BLOCK_END = "<!-- contextforge:end -->";
+declare function getGeneratedBlock(content: string): string | null;
+declare function wrapGeneratedBlock(content: string): string;
+declare function updateGeneratedBlock(existingContent: string | null, generatedContent: string): string;
+
+type SyncResult = {
+    root: string;
+    analysis: ProjectAnalysis;
+    generatedFiles: string[];
+    outputs: GeneratedFile[];
+    config: ContextForgeConfig;
+};
+declare function syncProject(root: string, providedConfig?: ContextForgeConfig): Promise<SyncResult>;
+
+type DoctorIssue = {
+    level: "error" | "warning";
+    message: string;
+};
+type DoctorReport = {
+    checks: string[];
+    issues: DoctorIssue[];
+};
+declare function doctorProject(root: string): Promise<DoctorReport>;
+
+export { type AITool, CONFIG_PATH, ConfigSchema, type ContextForgeConfig, DEFAULT_REGISTRY_SOURCES, DEFAULT_TOOLS, type DoctorIssue, type DoctorReport, GENERATED_BLOCK_END, GENERATED_BLOCK_START, type GeneratedFile, type LoadedPack, OFFICIAL_REGISTRY_SOURCE, OFFICIAL_REGISTRY_URL, PROJECT_PACK_CACHE, type Pack, PackSchema, type PackageJson, type PackageManager, type ProjectAnalysis, type ProjectFramework, type ProjectLanguage, RemotePackEntrySchema, RemotePackFilesSchema, type RemoteRegistryIndex, RemoteRegistryIndexSchema, type SyncResult, addPackToConfig, cacheRemotePacks, compileOutputs, createConfig, detectPackageManager, detectProject, doctorProject, findPack, getGeneratedBlock, hasPackage, hasScript, loadConfig, loadRegistry, packMatchesProject, packageManagerLabel, readPackageJson, recommendPacks, resolvePacks, safeWriteFile, saveConfig, saveInstalledPacks, syncProject, updateGeneratedBlock, wrapGeneratedBlock, writeGeneratedFiles };

package/dist/index.js

@@ -0,0 +1,866 @@
+// src/detect/detectProject.ts
+import path5 from "path";
+import fg4 from "fast-glob";
+import fs5 from "fs-extra";
+
+// src/detect/detectAITools.ts
+import path from "path";
+import fg from "fast-glob";
+import fs from "fs-extra";
+async function detectAITools(root) {
+  const cursorRules = await fg(".cursor/rules/**/*.{mdc,md}", {
+    cwd: root,
+    onlyFiles: true,
+    dot: true
+  });
+  const copilotInstructions = await fg(".github/instructions/*.instructions.md", {
+    cwd: root,
+    onlyFiles: true,
+    dot: true
+  });
+  return {
+    agentsMd: await fs.pathExists(path.join(root, "AGENTS.md")),
+    claudeMd: await fs.pathExists(path.join(root, "CLAUDE.md")) || await fs.pathExists(path.join(root, ".claude/CLAUDE.md")),
+    cursorRules: cursorRules.length > 0 || await fs.pathExists(path.join(root, ".cursor/rules")),
+    copilotInstructions: await fs.pathExists(path.join(root, ".github/copilot-instructions.md")) || copilotInstructions.length > 0
+  };
+}
+
+// src/detect/detectDatabase.ts
+import path2 from "path";
+import fg2 from "fast-glob";
+import fs2 from "fs-extra";
+async function detectDatabase(root) {
+  const prisma = await fs2.pathExists(path2.join(root, "prisma/schema.prisma"));
+  const drizzleConfigs = await fg2("drizzle.config.{js,ts,mjs,mts,cjs,cts}", {
+    cwd: root,
+    onlyFiles: true,
+    dot: true
+  });
+  return {
+    prisma,
+    drizzle: drizzleConfigs.length > 0
+  };
+}
+
+// src/detect/detectFramework.ts
+import path3 from "path";
+import fg3 from "fast-glob";
+import fs3 from "fs-extra";
+async function hasDirectory(root, relativePath) {
+  const statPath = path3.join(root, relativePath);
+  if (!await fs3.pathExists(statPath)) {
+    return false;
+  }
+  return (await fs3.stat(statPath)).isDirectory();
+}
+async function detectFramework(root) {
+  if (await hasDirectory(root, "src/app") || await hasDirectory(root, "app")) {
+    return "next-app-router";
+  }
+  if (await hasDirectory(root, "src/pages") || await hasDirectory(root, "pages")) {
+    return "next-pages-router";
+  }
+  const viteConfigs = await fg3("vite.config.{js,ts,mjs,mts,cjs,cts}", {
+    cwd: root,
+    onlyFiles: true,
+    dot: true
+  });
+  if (viteConfigs.length > 0) {
+    return "vite-react";
+  }
+  return "unknown";
+}
+
+// src/detect/detectPackageManager.ts
+import path4 from "path";
+import fs4 from "fs-extra";
+async function detectPackageManager(root) {
+  const checks = [
+    ["pnpm", "pnpm-lock.yaml"],
+    ["npm", "package-lock.json"],
+    ["yarn", "yarn.lock"],
+    ["bun", "bun.lockb"],
+    ["bun", "bun.lock"]
+  ];
+  for (const [manager, fileName] of checks) {
+    if (await fs4.pathExists(path4.join(root, fileName))) {
+      return manager;
+    }
+  }
+  return "unknown";
+}
+
+// src/detect/detectProject.ts
+async function hasAny(root, patterns) {
+  const matches = await fg4(patterns, {
+    cwd: root,
+    onlyFiles: true,
+    dot: true
+  });
+  return matches.length > 0;
+}
+async function detectProject(root) {
+  const resolvedRoot = path5.resolve(root);
+  const [packageManager, framework, database, aiTools] = await Promise.all([
+    detectPackageManager(resolvedRoot),
+    detectFramework(resolvedRoot),
+    detectDatabase(resolvedRoot),
+    detectAITools(resolvedRoot)
+  ]);
+  const [typescript, tailwind, shadcn, vitest, jest, playwright] = await Promise.all([
+    fs5.pathExists(path5.join(resolvedRoot, "tsconfig.json")),
+    hasAny(resolvedRoot, ["tailwind.config.{js,ts,mjs,mts,cjs,cts}"]),
+    fs5.pathExists(path5.join(resolvedRoot, "components.json")),
+    hasAny(resolvedRoot, ["vitest.config.{js,ts,mjs,mts,cjs,cts}"]),
+    hasAny(resolvedRoot, ["jest.config.{js,ts,mjs,mts,cjs,cts}", "jest.config.json"]),
+    hasAny(resolvedRoot, ["playwright.config.{js,ts,mjs,mts,cjs,cts}"])
+  ]);
+  return {
+    root: resolvedRoot,
+    packageManager,
+    framework,
+    language: typescript ? "typescript" : "javascript",
+    styling: {
+      tailwind,
+      shadcn
+    },
+    database,
+    testing: {
+      vitest,
+      jest,
+      playwright
+    },
+    aiTools
+  };
+}
+
+// src/registry/registrySchema.ts
+import { z } from "zod";
+var PackSchema = z.object({
+  name: z.string().min(1),
+  version: z.string().optional(),
+  title: z.string().min(1),
+  description: z.string().min(1),
+  category: z.enum(["framework", "database", "testing", "security", "ui", "workflow"]),
+  detect: z.object({
+    files: z.array(z.string()).optional(),
+    packages: z.array(z.string()).optional()
+  }).optional(),
+  outputs: z.object({
+    globalRules: z.boolean().default(true),
+    skill: z.boolean().default(false),
+    cursorRule: z.boolean().default(true),
+    copilotInstruction: z.boolean().default(true)
+  })
+});
+var RemotePackFilesSchema = z.object({
+  pack: z.string().optional(),
+  rules: z.string().optional(),
+  skill: z.string().optional(),
+  cursor: z.string().optional(),
+  copilot: z.string().optional()
+});
+var RemotePackEntrySchema = z.object({
+  name: z.string().min(1),
+  version: z.string().optional(),
+  baseUrl: z.string().optional(),
+  pack: PackSchema.optional(),
+  files: RemotePackFilesSchema.optional()
+}).refine((entry) => Boolean(entry.baseUrl || entry.pack || entry.files?.pack), {
+  message: "Remote pack entry must include baseUrl, inline pack metadata, or files.pack"
+});
+var RemoteRegistryIndexSchema = z.object({
+  version: z.string().default("1"),
+  packs: z.array(RemotePackEntrySchema)
+});
+
+// src/registry/loadRegistry.ts
+import path7 from "path";
+
+// src/registry/localRegistry.ts
+import path6 from "path";
+import fs6 from "fs-extra";
+async function loadLocalRegistry(registryRoot, source) {
+  if (!await fs6.pathExists(registryRoot)) {
+    return [];
+  }
+  const entries = await fs6.readdir(registryRoot, { withFileTypes: true });
+  const packs = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const directory = path6.join(registryRoot, entry.name);
+    const packPath = path6.join(directory, "pack.json");
+    if (!await fs6.pathExists(packPath)) {
+      continue;
+    }
+    const parsed = PackSchema.parse(await fs6.readJson(packPath));
+    const readOptional = async (fileName) => {
+      const filePath = path6.join(directory, fileName);
+      return await fs6.pathExists(filePath) ? fs6.readFile(filePath, "utf8") : void 0;
+    };
+    const rules = await readOptional("rules.md");
+    if (!rules) {
+      throw new Error(`Pack "${parsed.name}" is missing rules.md`);
+    }
+    packs.push({
+      ...parsed,
+      directory,
+      source,
+      files: {
+        rules,
+        skill: await readOptional("skill.md"),
+        cursor: await readOptional("cursor.mdc"),
+        copilot: await readOptional("copilot.md")
+      }
+    });
+  }
+  return packs;
+}
+
+// src/registry/remoteRegistry.ts
+var DEFAULT_TIMEOUT_MS = 1e4;
+async function fetchText(url, required, timeoutMs) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    if (!response.ok) {
+      if (!required && response.status === 404) {
+        return void 0;
+      }
+      throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+    }
+    return response.text();
+  } catch (error) {
+    if (!required) {
+      return void 0;
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function resolveUrl(value, baseUrl) {
+  return value ? new URL(value, baseUrl).toString() : void 0;
+}
+function defaultPackFile(baseUrl, fileName) {
+  return baseUrl ? new URL(fileName, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`).toString() : void 0;
+}
+async function loadRemoteRegistry(registryUrl, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const indexText = await fetchText(registryUrl, true, timeoutMs);
+  const index = RemoteRegistryIndexSchema.parse(JSON.parse(indexText ?? "{}"));
+  const packs = [];
+  for (const entry of index.packs) {
+    const baseUrl = resolveUrl(entry.baseUrl, registryUrl);
+    const packUrl = resolveUrl(entry.files?.pack, registryUrl) ?? defaultPackFile(baseUrl, "pack.json");
+    const rawPack = entry.pack ?? (packUrl ? JSON.parse(await fetchText(packUrl, true, timeoutMs) ?? "{}") : void 0);
+    const parsed = PackSchema.parse({
+      ...rawPack,
+      name: rawPack?.name ?? entry.name,
+      version: rawPack?.version ?? entry.version
+    });
+    const rulesUrl = resolveUrl(entry.files?.rules, registryUrl) ?? defaultPackFile(baseUrl, "rules.md");
+    if (!rulesUrl) {
+      throw new Error(`Remote pack "${entry.name}" is missing a rules.md URL.`);
+    }
+    packs.push({
+      ...parsed,
+      directory: baseUrl ?? registryUrl,
+      source: "remote",
+      registryUrl,
+      files: {
+        rules: await fetchText(rulesUrl, true, timeoutMs) ?? "",
+        skill: await fetchText(
+          resolveUrl(entry.files?.skill, registryUrl) ?? defaultPackFile(baseUrl, "skill.md") ?? "",
+          false,
+          timeoutMs
+        ),
+        cursor: await fetchText(
+          resolveUrl(entry.files?.cursor, registryUrl) ?? defaultPackFile(baseUrl, "cursor.mdc") ?? "",
+          false,
+          timeoutMs
+        ),
+        copilot: await fetchText(
+          resolveUrl(entry.files?.copilot, registryUrl) ?? defaultPackFile(baseUrl, "copilot.md") ?? "",
+          false,
+          timeoutMs
+        )
+      }
+    });
+  }
+  return packs;
+}
+
+// src/registry/loadRegistry.ts
+var OFFICIAL_REGISTRY_SOURCE = "official";
+var OFFICIAL_REGISTRY_URL = "https://registry.contextforge.dev/index.json";
+var DEFAULT_REGISTRY_SOURCES = [OFFICIAL_REGISTRY_SOURCE];
+var PROJECT_PACK_CACHE = ".contextforge/packs";
+function mergePacks(packs) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const pack of packs) {
+    if (!byName.has(pack.name)) {
+      byName.set(pack.name, pack);
+    }
+  }
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+async function loadRegistrySource(source, timeoutMs) {
+  if (source === OFFICIAL_REGISTRY_SOURCE) {
+    try {
+      return await loadRemoteRegistry(OFFICIAL_REGISTRY_URL, timeoutMs ?? 1500);
+    } catch {
+      return [];
+    }
+  }
+  return loadRemoteRegistry(source, timeoutMs);
+}
+async function loadRegistry(input = {}) {
+  if (typeof input === "string") {
+    return mergePacks(await loadLocalRegistry(input, "local"));
+  }
+  const sources = input.sources ?? DEFAULT_REGISTRY_SOURCES;
+  const packs = [];
+  if (input.root) {
+    packs.push(...await loadLocalRegistry(path7.join(input.root, PROJECT_PACK_CACHE), "project-cache"));
+  }
+  for (const source of sources) {
+    packs.push(...await loadRegistrySource(source, input.timeoutMs));
+  }
+  return mergePacks(packs);
+}
+
+// src/registry/resolvePack.ts
+import path9 from "path";
+import fs8 from "fs-extra";
+
+// src/project/packageJson.ts
+import path8 from "path";
+import fs7 from "fs-extra";
+async function readPackageJson(root) {
+  const packageJsonPath = path8.join(root, "package.json");
+  if (!await fs7.pathExists(packageJsonPath)) {
+    return null;
+  }
+  return fs7.readJson(packageJsonPath);
+}
+function hasPackage(packageJson, packageName) {
+  if (!packageJson) {
+    return false;
+  }
+  return Boolean(
+    packageJson.dependencies?.[packageName] || packageJson.devDependencies?.[packageName] || packageJson.peerDependencies?.[packageName] || packageJson.optionalDependencies?.[packageName]
+  );
+}
+function hasScript(packageJson, scriptName) {
+  return Boolean(packageJson?.scripts?.[scriptName]);
+}
+
+// src/registry/resolvePack.ts
+function findPack(registry, packName) {
+  return registry.find((pack) => pack.name === packName);
+}
+function resolvePacks(packNames, registry) {
+  const uniqueNames = [...new Set(packNames)];
+  return uniqueNames.map((packName) => {
+    const pack = findPack(registry, packName);
+    if (!pack) {
+      throw new Error(`Unknown ContextForge pack: ${packName}`);
+    }
+    return pack;
+  });
+}
+function recommendPacks(analysis, registry) {
+  const names = /* @__PURE__ */ new Set();
+  names.add("env-secrets");
+  if (analysis.framework === "next-app-router") {
+    names.add("next-app-router");
+  }
+  if (analysis.database.prisma) {
+    names.add("prisma-migrations");
+  }
+  if (analysis.styling.shadcn) {
+    names.add("shadcn-ui");
+  }
+  if (analysis.testing.vitest || analysis.testing.jest || analysis.testing.playwright) {
+    names.add("testing-workflow");
+  }
+  return resolvePacks(
+    [...names].filter((name) => findPack(registry, name)),
+    registry
+  );
+}
+async function packMatchesProject(pack, root, packageJson) {
+  const fileChecks = await Promise.all(
+    pack.detect?.files?.map((filePattern) => fs8.pathExists(path9.join(root, filePattern))) ?? []
+  );
+  const packageChecks = pack.detect?.packages?.map((packageName) => hasPackage(packageJson, packageName)) ?? [];
+  const checks = [...fileChecks, ...packageChecks];
+  return checks.length === 0 || checks.some(Boolean);
+}
+function packageManagerLabel(packageManager) {
+  const labels = {
+    pnpm: "pnpm",
+    npm: "npm",
+    yarn: "Yarn",
+    bun: "Bun",
+    unknown: "Unknown"
+  };
+  return labels[packageManager];
+}
+
+// src/config/configSchema.ts
+import { z as z2 } from "zod";
+var ToolSchema = z2.enum(["codex", "claude", "cursor", "copilot"]);
+var ConfigSchema = z2.object({
+  version: z2.string().default("0.1.0"),
+  registries: z2.array(z2.string()).default(DEFAULT_REGISTRY_SOURCES),
+  tools: z2.array(ToolSchema).default(["codex", "claude", "cursor", "copilot"]),
+  packs: z2.array(z2.string()).default([]),
+  packageManager: z2.enum(["pnpm", "npm", "yarn", "bun", "unknown"]).default("unknown"),
+  generatedFiles: z2.array(z2.string()).default([])
+});
+
+// src/config/defaultConfig.ts
+var DEFAULT_TOOLS = ["codex", "claude", "cursor", "copilot"];
+function createConfig(analysis, packs, tools = DEFAULT_TOOLS, registries = DEFAULT_REGISTRY_SOURCES) {
+  return {
+    version: "0.1.0",
+    registries,
+    tools,
+    packs: packs.map((pack) => pack.name),
+    packageManager: analysis.packageManager,
+    generatedFiles: []
+  };
+}
+
+// src/config/loadConfig.ts
+import path10 from "path";
+import fs9 from "fs-extra";
+var CONFIG_PATH = ".contextforge/config.json";
+async function loadConfig(root) {
+  const configPath = path10.join(root, CONFIG_PATH);
+  if (!await fs9.pathExists(configPath)) {
+    throw new Error("ContextForge config not found. Run `npx @contextforge/cli init` first.");
+  }
+  return ConfigSchema.parse(await fs9.readJson(configPath));
+}
+
+// src/config/saveConfig.ts
+import path11 from "path";
+import fs10 from "fs-extra";
+async function saveConfig(root, config) {
+  const configPath = path11.join(root, CONFIG_PATH);
+  await fs10.ensureDir(path11.dirname(configPath));
+  await fs10.writeFile(configPath, `${JSON.stringify(config, null, 2)}
+`);
+}
+function addPackToConfig(config, packName) {
+  return {
+    ...config,
+    packs: [.../* @__PURE__ */ new Set([...config.packs, packName])]
+  };
+}
+
+// src/registry/installPacks.ts
+import path12 from "path";
+import fs11 from "fs-extra";
+var INSTALLED_PACKS_PATH = ".contextforge/installed-packs.json";
+function packJson(pack) {
+  return {
+    name: pack.name,
+    version: pack.version,
+    title: pack.title,
+    description: pack.description,
+    category: pack.category,
+    detect: pack.detect,
+    outputs: pack.outputs
+  };
+}
+async function writePack(root, pack) {
+  const packRoot = path12.join(root, PROJECT_PACK_CACHE, pack.name);
+  await fs11.ensureDir(packRoot);
+  await fs11.writeFile(path12.join(packRoot, "pack.json"), `${JSON.stringify(packJson(pack), null, 2)}
+`);
+  await fs11.writeFile(path12.join(packRoot, "rules.md"), pack.files.rules);
+  const optionalFiles = [
+    ["skill.md", pack.files.skill],
+    ["cursor.mdc", pack.files.cursor],
+    ["copilot.md", pack.files.copilot]
+  ];
+  for (const [fileName, content] of optionalFiles) {
+    if (content) {
+      await fs11.writeFile(path12.join(packRoot, fileName), content);
+    }
+  }
+}
+async function cacheRemotePacks(root, packs) {
+  for (const pack of packs) {
+    if (pack.source === "remote") {
+      await writePack(root, pack);
+    }
+  }
+}
+async function saveInstalledPacks(root, packs) {
+  const metadataPath = path12.join(root, INSTALLED_PACKS_PATH);
+  const metadata = {
+    version: "1",
+    packs: packs.map((pack) => ({
+      name: pack.name,
+      version: pack.version ?? "0.0.0",
+      source: pack.source,
+      registryUrl: pack.registryUrl
+    }))
+  };
+  await fs11.ensureDir(path12.dirname(metadataPath));
+  await fs11.writeFile(metadataPath, `${JSON.stringify(metadata, null, 2)}
+`);
+}
+
+// src/compiler/compileAgentsMd.ts
+function compileAgentsMd(analysis, packs) {
+  return [
+    "# ContextForge Instructions",
+    "",
+    "Generated by ContextForge. Add project-specific guidance outside this block.",
+    "",
+    "## Detected Project",
+    `- Framework: ${analysis.framework}`,
+    `- Language: ${analysis.language}`,
+    `- Package manager: ${packageManagerLabel(analysis.packageManager)}`,
+    `- Styling: ${analysis.styling.tailwind ? "Tailwind CSS" : "not detected"}${analysis.styling.shadcn ? " + shadcn/ui" : ""}`,
+    `- Database: ${analysis.database.prisma ? "Prisma" : analysis.database.drizzle ? "Drizzle" : "not detected"}`,
+    `- Testing: ${[
+      analysis.testing.vitest && "Vitest",
+      analysis.testing.jest && "Jest",
+      analysis.testing.playwright && "Playwright"
+    ].filter(Boolean).join(", ") || "not detected"}`,
+    "",
+    "## Active Packs",
+    ...packs.flatMap((pack) => [
+      "",
+      `### ${pack.title}`,
+      "",
+      pack.description,
+      "",
+      pack.files.rules.trim()
+    ])
+  ].join("\n");
+}
+
+// src/compiler/compileClaudeMd.ts
+function compileClaudeMd(analysis, packs) {
+  return compileAgentsMd(analysis, packs).replace(
+    "# ContextForge Instructions",
+    "# ContextForge Claude Instructions"
+  );
+}
+
+// src/compiler/compileCopilotInstructions.ts
+function compileCopilotInstructions(analysis, packs) {
+  const enabledPacks = packs.filter((pack) => pack.outputs.copilotInstruction);
+  return [
+    "# ContextForge Copilot Instructions",
+    "",
+    `Project framework: ${analysis.framework}. Language: ${analysis.language}.`,
+    "",
+    ...enabledPacks.flatMap((pack) => [
+      `## ${pack.title}`,
+      "",
+      (pack.files.copilot ?? pack.files.rules).trim(),
+      ""
+    ])
+  ].join("\n");
+}
+
+// src/fs/updateGeneratedBlock.ts
+var GENERATED_BLOCK_START = "<!-- contextforge:start -->";
+var GENERATED_BLOCK_END = "<!-- contextforge:end -->";
+var blockPattern = new RegExp(
+  `${escapeRegExp(GENERATED_BLOCK_START)}[\\s\\S]*?${escapeRegExp(GENERATED_BLOCK_END)}`,
+  "m"
+);
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function getGeneratedBlock(content) {
+  return content.match(blockPattern)?.[0] ?? null;
+}
+function wrapGeneratedBlock(content) {
+  return `${GENERATED_BLOCK_START}
+${content.trim()}
+${GENERATED_BLOCK_END}`;
+}
+function updateGeneratedBlock(existingContent, generatedContent) {
+  const existing = existingContent?.replace(/\s+$/u, "") ?? "";
+  const generatedBlock = getGeneratedBlock(generatedContent) ?? wrapGeneratedBlock(generatedContent);
+  if (!existing) {
+    return `${generatedContent.includes(GENERATED_BLOCK_START) ? generatedContent.trim() : generatedBlock}
+`;
+  }
+  if (blockPattern.test(existing)) {
+    return `${existing.replace(blockPattern, generatedBlock)}
+`;
+  }
+  return `${existing}
+
+${generatedBlock}
+`;
+}
+
+// src/compiler/compileCursorRules.ts
+function withCursorFrontmatter(description, content) {
+  return [
+    "---",
+    `description: ${description}`,
+    "alwaysApply: true",
+    "---",
+    "",
+    GENERATED_BLOCK_START,
+    content.trim(),
+    GENERATED_BLOCK_END
+  ].join("\n");
+}
+function compileCursorRules(analysis, packs) {
+  const files = [
+    {
+      path: ".cursor/rules/contextforge.mdc",
+      content: withCursorFrontmatter(
+        "ContextForge generated project overview",
+        [
+          "# ContextForge Project Context",
+          "",
+          `- Framework: ${analysis.framework}`,
+          `- Language: ${analysis.language}`,
+          `- Package manager: ${analysis.packageManager}`,
+          `- Active packs: ${packs.map((pack) => pack.name).join(", ") || "none"}`
+        ].join("\n")
+      )
+    }
+  ];
+  for (const pack of packs.filter((item) => item.outputs.cursorRule)) {
+    files.push({
+      path: `.cursor/rules/${pack.name}.mdc`,
+      content: withCursorFrontmatter(
+        pack.description.replace(/:/g, "-"),
+        (pack.files.cursor ?? pack.files.rules).trim()
+      )
+    });
+  }
+  return files;
+}
+
+// src/compiler/compileSkills.ts
+function escapeYaml(value) {
+  return value.replace(/"/g, '\\"');
+}
+function compileSkills(packs) {
+  return packs.filter((pack) => pack.outputs.skill).map((pack) => ({
+    path: `.agents/skills/${pack.name}/SKILL.md`,
+    content: [
+      "---",
+      `name: ${pack.name}`,
+      `description: "${escapeYaml(pack.description)}"`,
+      "---",
+      "",
+      GENERATED_BLOCK_START,
+      (pack.files.skill ?? pack.files.rules).trim(),
+      GENERATED_BLOCK_END
+    ].join("\n")
+  }));
+}
+
+// src/compiler/compileOutputs.ts
+function compileOutputs(config, packs, analysis) {
+  const outputs = [];
+  if (config.tools.includes("codex")) {
+    outputs.push({ path: "AGENTS.md", content: compileAgentsMd(analysis, packs) });
+    outputs.push(...compileSkills(packs));
+  }
+  if (config.tools.includes("claude")) {
+    outputs.push({ path: "CLAUDE.md", content: compileClaudeMd(analysis, packs) });
+  }
+  if (config.tools.includes("cursor")) {
+    outputs.push(...compileCursorRules(analysis, packs));
+  }
+  if (config.tools.includes("copilot")) {
+    outputs.push({
+      path: ".github/copilot-instructions.md",
+      content: compileCopilotInstructions(analysis, packs)
+    });
+  }
+  return outputs;
+}
+
+// src/compiler/writeGeneratedFiles.ts
+import path14 from "path";
+
+// src/fs/safeWriteFile.ts
+import path13 from "path";
+import fs12 from "fs-extra";
+async function safeWriteFile(filePath, generatedContent) {
+  const existingContent = await fs12.pathExists(filePath) ? await fs12.readFile(filePath, "utf8") : null;
+  const nextContent = updateGeneratedBlock(existingContent, generatedContent);
+  await fs12.ensureDir(path13.dirname(filePath));
+  await fs12.writeFile(filePath, nextContent);
+}
+
+// src/compiler/writeGeneratedFiles.ts
+async function writeGeneratedFiles(root, outputs) {
+  for (const output of outputs) {
+    await safeWriteFile(path14.join(root, output.path), output.content);
+  }
+  return outputs.map((output) => output.path);
+}
+
+// src/sync.ts
+import path15 from "path";
+async function syncProject(root, providedConfig) {
+  const resolvedRoot = path15.resolve(root);
+  const analysis = await detectProject(resolvedRoot);
+  const config = providedConfig ?? await loadConfig(resolvedRoot);
+  const registry = await loadRegistry({
+    root: resolvedRoot,
+    sources: config.registries
+  });
+  const packs = resolvePacks(config.packs, registry);
+  await cacheRemotePacks(resolvedRoot, packs);
+  await saveInstalledPacks(resolvedRoot, packs);
+  const outputs = compileOutputs(config, packs, analysis);
+  const generatedFiles = await writeGeneratedFiles(resolvedRoot, outputs);
+  const nextConfig = {
+    ...config,
+    packageManager: config.packageManager === "unknown" ? analysis.packageManager : config.packageManager,
+    generatedFiles
+  };
+  await saveConfig(resolvedRoot, nextConfig);
+  return {
+    root: resolvedRoot,
+    analysis,
+    generatedFiles,
+    outputs,
+    config: nextConfig
+  };
+}
+
+// src/doctor/doctorProject.ts
+import path16 from "path";
+import fs13 from "fs-extra";
+async function fileExists(root, relativePath) {
+  return fs13.pathExists(path16.join(root, relativePath));
+}
+async function doctorProject(root) {
+  const checks = [];
+  const issues = [];
+  const resolvedRoot = path16.resolve(root);
+  if (!await fileExists(resolvedRoot, CONFIG_PATH)) {
+    return {
+      checks,
+      issues: [
+        {
+          level: "error",
+          message: "ContextForge config was not found. Run `npx @contextforge/cli init`."
+        }
+      ]
+    };
+  }
+  checks.push("Config found");
+  const config = await loadConfig(resolvedRoot);
+  const [analysis, registry, packageJson] = await Promise.all([
+    detectProject(resolvedRoot),
+    loadRegistry({ root: resolvedRoot, sources: config.registries }),
+    readPackageJson(resolvedRoot)
+  ]);
+  const packs = resolvePacks(config.packs, registry);
+  const requiredFiles = [
+    [config.tools.includes("codex"), "AGENTS.md", "Codex instructions found"],
+    [config.tools.includes("claude"), "CLAUDE.md", "Claude instructions found"],
+    [config.tools.includes("cursor"), ".cursor/rules", "Cursor rules found"],
+    [config.tools.includes("copilot"), ".github/copilot-instructions.md", "Copilot instructions found"]
+  ];
+  for (const [enabled, relativePath, okMessage] of requiredFiles) {
+    if (!enabled) {
+      continue;
+    }
+    if (await fileExists(resolvedRoot, relativePath)) {
+      checks.push(okMessage);
+    } else {
+      issues.push({
+        level: "error",
+        message: `${relativePath} is missing. Run \`npx @contextforge/cli sync\`.`
+      });
+    }
+  }
+  for (const generatedFile of config.generatedFiles) {
+    if (!await fileExists(resolvedRoot, generatedFile)) {
+      issues.push({
+        level: "warning",
+        message: `Previously generated file ${generatedFile} is missing.`
+      });
+    }
+  }
+  for (const pack of packs) {
+    if (!await packMatchesProject(pack, resolvedRoot, packageJson)) {
+      issues.push({
+        level: "warning",
+        message: `${pack.name} pack is installed, but its detection hints do not match this project.`
+      });
+    }
+  }
+  if (config.packageManager !== "unknown" && analysis.packageManager !== "unknown" && config.packageManager !== analysis.packageManager) {
+    issues.push({
+      level: "warning",
+      message: `Config says package manager is ${config.packageManager}, but ${analysis.packageManager} was detected.`
+    });
+  }
+  if (config.packs.includes("testing-workflow") && !hasScript(packageJson, "test")) {
+    issues.push({
+      level: "warning",
+      message: "testing-workflow is installed, but package.json has no test script."
+    });
+  }
+  return { checks, issues };
+}
+export {
+  CONFIG_PATH,
+  ConfigSchema,
+  DEFAULT_REGISTRY_SOURCES,
+  DEFAULT_TOOLS,
+  GENERATED_BLOCK_END,
+  GENERATED_BLOCK_START,
+  OFFICIAL_REGISTRY_SOURCE,
+  OFFICIAL_REGISTRY_URL,
+  PROJECT_PACK_CACHE,
+  PackSchema,
+  RemotePackEntrySchema,
+  RemotePackFilesSchema,
+  RemoteRegistryIndexSchema,
+  addPackToConfig,
+  cacheRemotePacks,
+  compileOutputs,
+  createConfig,
+  detectPackageManager,
+  detectProject,
+  doctorProject,
+  findPack,
+  getGeneratedBlock,
+  hasPackage,
+  hasScript,
+  loadConfig,
+  loadRegistry,
+  packMatchesProject,
+  packageManagerLabel,
+  readPackageJson,
+  recommendPacks,
+  resolvePacks,
+  safeWriteFile,
+  saveConfig,
+  saveInstalledPacks,
+  syncProject,
+  updateGeneratedBlock,
+  wrapGeneratedBlock,
+  writeGeneratedFiles
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@contextforge/core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "fast-glob": "^3.3.3",
+    "fs-extra": "^11.3.0",
+    "zod": "^4.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run"
+  }
+}