@twinklerg/coden 0.1.0

package/src/plugins/installer.ts

@@ -0,0 +1,314 @@
+import { constants } from "node:fs";
+import { access, copyFile, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { CodeNError, type ToolDefinition } from "../core/types.js";
+import {
+  composePackageRegistry,
+  type InstalledPluginLoader,
+  type LoadedPackagePlugin,
+  type PackagePluginFailure,
+} from "./installed-loader.js";
+import {
+  type PluginManifest,
+  readPluginManifest,
+  runtimePackageJson,
+  serializePluginManifest,
+} from "./manifest.js";
+import type { PackageManager } from "./package-manager.js";
+import { readInstalledPackageMetadata } from "./package-metadata.js";
+import { type PluginPaths, type PluginScope, resolvePluginPaths } from "./paths.js";
+import { isValidNpmPackageName, parseNpmPluginSpecifier } from "./specifier.js";
+import { PluginTransaction, type PluginTransactionCandidate } from "./transaction.js";
+
+export interface PluginOperationOptions {
+  scope: PluginScope;
+  allowScripts: boolean;
+  signal?: AbortSignal;
+}
+
+export interface InstalledPluginSummary {
+  packageName: string;
+  requested: string;
+  version: string;
+  tools: string[];
+  scope: PluginScope;
+}
+
+export interface ListedPlugin extends InstalledPluginSummary {
+  shadowedByProject: boolean;
+}
+
+export class PluginInstaller {
+  constructor(
+    private readonly workspace: string,
+    private readonly dataDir: string,
+    private readonly packageManager: PackageManager,
+    private readonly loader: InstalledPluginLoader,
+    private readonly builtins: ToolDefinition[],
+  ) {}
+
+  async install(raw: string, options: PluginOperationOptions): Promise<InstalledPluginSummary> {
+    const specifier = parseNpmPluginSpecifier(raw);
+    const paths = this.paths(options.scope);
+    await new PluginTransaction(paths).recover();
+    const current = await readPluginManifest(paths.manifestPath);
+
+    if (current.plugins[specifier.packageName]?.requested === specifier.requested) {
+      const existing = await this.loader.loadScope(paths);
+      const plugin = existing.loaded.find((item) => item.packageName === specifier.packageName);
+      if (existing.failed.length === 0 && plugin)
+        return summaryFor(plugin, specifier.requested, options.scope);
+    }
+
+    const next = cloneManifest(current);
+    next.plugins[specifier.packageName] = { source: "npm", requested: specifier.requested };
+
+    let installed: LoadedPackagePlugin[] = [];
+    await new PluginTransaction(paths).run(async (candidate) => {
+      installed = await this.buildCandidate(candidate, next, paths, options, false);
+      await this.validateCandidate(paths.scope, installed);
+    });
+
+    const plugin = installed.find((item) => item.packageName === specifier.packageName);
+    if (!plugin)
+      throw packageLoadFailure([
+        {
+          packageName: specifier.packageName,
+          path: paths.runtimeDir,
+          message: "plugin did not load",
+        },
+      ]);
+    return summaryFor(plugin, specifier.requested, options.scope);
+  }
+
+  async remove(packageName: string, options: PluginOperationOptions): Promise<void> {
+    if (!isValidNpmPackageName(packageName)) throw invalidPackageName(packageName);
+    const paths = this.paths(options.scope);
+    await new PluginTransaction(paths).recover();
+    const current = await readPluginManifest(paths.manifestPath);
+    if (!current.plugins[packageName]) {
+      throw new CodeNError(
+        "plugin",
+        "plugin.install_failed",
+        `plugin.install_failed: ${packageName} is not installed in ${options.scope} scope`,
+      );
+    }
+
+    const next = cloneManifest(current);
+    delete next.plugins[packageName];
+
+    await new PluginTransaction(paths).run(async (candidate) => {
+      const installed = await this.buildCandidate(candidate, next, paths, options, false);
+      await this.validateCandidate(paths.scope, installed);
+    });
+  }
+
+  async sync(options: PluginOperationOptions): Promise<InstalledPluginSummary[]> {
+    const paths = this.paths(options.scope);
+    await new PluginTransaction(paths).recover();
+    const manifest = await readPluginManifest(paths.manifestPath);
+    if (
+      options.scope === "project" &&
+      Object.keys(manifest.plugins).length > 0 &&
+      !(await pathExists(path.join(paths.runtimeDir, "bun.lock")))
+    ) {
+      throw new CodeNError(
+        "plugin",
+        "plugin.lock_missing",
+        `plugin.lock_missing: ${options.scope} plugin sync requires ${path.join(paths.runtimeDir, "bun.lock")}`,
+      );
+    }
+
+    let installed: LoadedPackagePlugin[] = [];
+    await new PluginTransaction(paths).run(async (candidate) => {
+      installed = await this.buildCandidate(candidate, manifest, paths, options, true);
+      await this.validateCandidate(paths.scope, installed);
+    });
+
+    return installed.map((plugin) =>
+      summaryFor(
+        plugin,
+        manifest.plugins[plugin.packageName]?.requested ?? "latest",
+        options.scope,
+      ),
+    );
+  }
+
+  async list(): Promise<{ project: ListedPlugin[]; global: ListedPlugin[] }> {
+    const [project, global] = await Promise.all([
+      this.listScope(this.paths("project")),
+      this.listScope(this.paths("global")),
+    ]);
+    const projectNames = new Set(project.map((item) => item.packageName));
+    return {
+      project,
+      global: global.map((item) => ({
+        ...item,
+        shadowedByProject: projectNames.has(item.packageName),
+      })),
+    };
+  }
+
+  private paths(scope: PluginScope): PluginPaths {
+    return resolvePluginPaths(this.workspace, scope, this.dataDir);
+  }
+
+  private async buildCandidate(
+    candidate: PluginTransactionCandidate,
+    manifest: PluginManifest,
+    sourcePaths: PluginPaths,
+    options: PluginOperationOptions,
+    frozenLockfile: boolean,
+  ): Promise<LoadedPackagePlugin[]> {
+    await mkdir(candidate.runtimeDir, { recursive: true });
+    await writeFile(candidate.manifestPath, serializePluginManifest(manifest), "utf8");
+    await writeFile(
+      path.join(candidate.runtimeDir, "package.json"),
+      `${JSON.stringify(runtimePackageJson(manifest), null, 2)}\n`,
+      "utf8",
+    );
+    if (await pathExists(path.join(sourcePaths.runtimeDir, "bun.lock"))) {
+      await copyFile(
+        path.join(sourcePaths.runtimeDir, "bun.lock"),
+        path.join(candidate.runtimeDir, "bun.lock"),
+      );
+    }
+
+    try {
+      await this.packageManager.install({
+        cwd: candidate.runtimeDir,
+        frozenLockfile,
+        allowScripts: options.allowScripts,
+        ...(options.signal ? { signal: options.signal } : {}),
+      });
+    } catch (error) {
+      throw mapPackageManagerError(error, frozenLockfile);
+    }
+
+    await writeEmptyManifestLockfile(candidate.runtimeDir, manifest);
+    await writeRuntimeGitignore(candidate.runtimeDir, sourcePaths.scope);
+    const loaded = await this.loader.loadScope({
+      ...sourcePaths,
+      manifestPath: candidate.manifestPath,
+      runtimeDir: candidate.runtimeDir,
+    });
+    if (loaded.failed.length > 0) throw packageLoadFailure(loaded.failed);
+    return loaded.loaded;
+  }
+
+  private async validateCandidate(
+    scope: PluginScope,
+    staged: LoadedPackagePlugin[],
+  ): Promise<void> {
+    if (scope === "global") {
+      composePackageRegistry(this.builtins, staged, []);
+      return;
+    }
+
+    const globalPaths = this.paths("global");
+    await new PluginTransaction(globalPaths).recover();
+    const currentGlobals = await this.loadScopeOrThrow(globalPaths);
+    composePackageRegistry(this.builtins, currentGlobals, staged);
+  }
+
+  private async loadScopeOrThrow(paths: PluginPaths): Promise<LoadedPackagePlugin[]> {
+    const result = await this.loader.loadScope(paths);
+    if (result.failed.length > 0) throw packageLoadFailure(result.failed);
+    return result.loaded;
+  }
+
+  private async listScope(paths: PluginPaths): Promise<ListedPlugin[]> {
+    await new PluginTransaction(paths).recover();
+    const manifest = await readPluginManifest(paths.manifestPath);
+    const listed: ListedPlugin[] = [];
+    for (const packageName of Object.keys(manifest.plugins).sort()) {
+      const metadata = await readInstalledPackageMetadata(paths.runtimeDir, packageName);
+      listed.push({
+        packageName,
+        requested: manifest.plugins[packageName]?.requested ?? "latest",
+        version: metadata.version,
+        tools: [],
+        scope: paths.scope,
+        shadowedByProject: false,
+      });
+    }
+    return listed;
+  }
+}
+
+async function writeEmptyManifestLockfile(
+  runtimeDir: string,
+  manifest: PluginManifest,
+): Promise<void> {
+  if (Object.keys(manifest.plugins).length > 0) return;
+  await writeFile(path.join(runtimeDir, "bun.lock"), "", "utf8");
+}
+
+async function writeRuntimeGitignore(runtimeDir: string, scope: PluginScope): Promise<void> {
+  if (scope !== "project") return;
+  await writeFile(path.join(runtimeDir, ".gitignore"), "*\n!.gitignore\n!bun.lock\n", "utf8");
+}
+
+function summaryFor(
+  plugin: LoadedPackagePlugin,
+  requested: string,
+  scope: PluginScope,
+): InstalledPluginSummary {
+  return {
+    packageName: plugin.packageName,
+    requested,
+    version: plugin.version,
+    tools: plugin.tools.map((tool) => tool.name).sort(),
+    scope,
+  };
+}
+
+function cloneManifest(manifest: PluginManifest): PluginManifest {
+  return JSON.parse(serializePluginManifest(manifest)) as PluginManifest;
+}
+
+function packageLoadFailure(failures: PackagePluginFailure[]): CodeNError {
+  const message = failures
+    .map((failure) => `${failure.packageName}: ${failure.message} (${failure.path})`)
+    .join("; ");
+  return new CodeNError("plugin", "plugin.sync_failed", `plugin.sync_failed: ${message}`);
+}
+
+function invalidPackageName(packageName: string): CodeNError {
+  return new CodeNError(
+    "plugin",
+    "plugin.specifier_invalid",
+    `plugin.specifier_invalid: ${packageName}`,
+  );
+}
+
+function mapPackageManagerError(error: unknown, frozenLockfile: boolean): unknown {
+  if (frozenLockfile && isFrozenLockMismatch(error)) {
+    return new CodeNError(
+      "plugin",
+      "plugin.lock_outdated",
+      `plugin.lock_outdated: committed plugin lockfile is out of date`,
+      false,
+      undefined,
+      error instanceof Error ? { cause: error } : undefined,
+    );
+  }
+  return error;
+}
+
+function isFrozenLockMismatch(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  const text = `${error.message}\n${error instanceof CodeNError ? error.code : ""}`;
+  return /frozen-lockfile|lockfile.*out.?of.?date|lockfile.*would.*change|lockfile had changes/i.test(
+    text,
+  );
+}
+
+async function pathExists(file: string): Promise<boolean> {
+  try {
+    await access(file, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/plugins/manifest.ts

@@ -0,0 +1,89 @@
+import { readFile } from "node:fs/promises";
+import { CodeNError } from "../core/types.js";
+import { isValidNpmPackageName } from "./specifier.js";
+
+export interface PluginManifestEntry {
+  source: "npm";
+  requested: string;
+}
+
+export interface PluginManifest {
+  schemaVersion: 1;
+  plugins: Record<string, PluginManifestEntry>;
+}
+
+export const emptyPluginManifest = (): PluginManifest => ({ schemaVersion: 1, plugins: {} });
+
+export async function readPluginManifest(file: string): Promise<PluginManifest> {
+  try {
+    const raw = JSON.parse(await readFile(file, "utf8")) as unknown;
+    return normalizePluginManifest(raw);
+  } catch (error) {
+    if (isMissingFile(error)) return emptyPluginManifest();
+    if (error instanceof CodeNError) throw error;
+    throw manifestError(error, file);
+  }
+}
+
+export function serializePluginManifest(manifest: PluginManifest): string {
+  return `${JSON.stringify(normalizePluginManifest(manifest), null, 2)}\n`;
+}
+
+export function runtimePackageJson(manifest: PluginManifest): {
+  private: true;
+  dependencies: Record<string, string>;
+} {
+  const normalized = normalizePluginManifest(manifest);
+  const dependencies: Record<string, string> = {};
+  for (const [name, entry] of Object.entries(normalized.plugins))
+    dependencies[name] = entry.requested;
+  return { private: true, dependencies };
+}
+
+function normalizePluginManifest(value: unknown): PluginManifest {
+  if (!value || typeof value !== "object") throw manifestError();
+  const manifest = value as Partial<PluginManifest> & {
+    plugins?: unknown;
+    schemaVersion?: unknown;
+  };
+  if (manifest.schemaVersion !== 1) throw manifestError();
+  if (!manifest.plugins || typeof manifest.plugins !== "object" || Array.isArray(manifest.plugins))
+    throw manifestError();
+
+  const plugins: Record<string, PluginManifestEntry> = {};
+  for (const name of Object.keys(manifest.plugins).sort()) {
+    if (!isValidNpmPackageName(name)) throw manifestError();
+    const entry = (manifest.plugins as Record<string, unknown>)[name];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw manifestError();
+    const pluginEntry = entry as Partial<PluginManifestEntry>;
+    if (
+      pluginEntry.source !== "npm" ||
+      typeof pluginEntry.requested !== "string" ||
+      !pluginEntry.requested
+    )
+      throw manifestError();
+    plugins[name] = { source: "npm", requested: pluginEntry.requested };
+  }
+
+  return { schemaVersion: 1, plugins };
+}
+
+function isMissingFile(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: string }).code === "ENOENT"
+  );
+}
+
+function manifestError(cause?: unknown, file?: string): CodeNError {
+  return new CodeNError(
+    "plugin",
+    "plugin.manifest_invalid",
+    file ? `plugin.manifest_invalid: ${file}` : "plugin.manifest_invalid",
+    false,
+    undefined,
+    cause instanceof Error ? { cause } : undefined,
+  );
+}

package/src/plugins/package-manager.ts

@@ -0,0 +1,10 @@
+export interface PackageInstallRequest {
+  cwd: string;
+  frozenLockfile: boolean;
+  allowScripts: boolean;
+  signal?: AbortSignal;
+}
+
+export interface PackageManager {
+  install(request: PackageInstallRequest): Promise<void>;
+}

package/src/plugins/package-metadata.ts

@@ -0,0 +1,95 @@
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { CodeNError } from "../core/types.js";
+import { isValidNpmPackageName } from "./specifier.js";
+
+export interface InstalledPackageMetadata {
+  packageName: string;
+  version: string;
+  packageDirectory: string;
+  entryPath: string;
+  apiVersion: 1;
+}
+
+export async function readInstalledPackageMetadata(
+  runtimeDirectory: string,
+  packageName: string,
+): Promise<InstalledPackageMetadata> {
+  if (!isValidNpmPackageName(packageName)) throw metadataError();
+  const packageDirectory = path.join(runtimeDirectory, "node_modules", ...packageName.split("/"));
+  const packageJsonPath = path.join(packageDirectory, "package.json");
+  let packageJson: unknown;
+  try {
+    packageJson = JSON.parse(await readFile(packageJsonPath, "utf8")) as unknown;
+  } catch {
+    throw metadataError();
+  }
+
+  const metadata = normalizePackageJson(packageJson, packageName);
+  const packageReal = await safeRealpath(packageDirectory);
+  const entryPath = path.resolve(packageDirectory, metadata.entry);
+  const entryReal = await safeRealpath(entryPath, true);
+  if (!withinBoundary(packageReal, entryReal)) throw entryError();
+
+  return {
+    packageName,
+    version: metadata.version,
+    packageDirectory: packageReal,
+    entryPath: entryReal,
+    apiVersion: 1,
+  };
+}
+
+function normalizePackageJson(
+  packageJson: unknown,
+  packageName: string,
+): { version: string; entry: string } {
+  if (!packageJson || typeof packageJson !== "object") throw metadataError();
+  const manifest = packageJson as Record<string, unknown>;
+  if (manifest.name !== packageName || typeof manifest.version !== "string" || !manifest.version)
+    throw metadataError();
+  if (manifest.type !== "module") throw metadataError();
+  if (!manifest.coden || typeof manifest.coden !== "object" || Array.isArray(manifest.coden))
+    throw metadataError();
+  const coden = manifest.coden as Record<string, unknown>;
+  if (coden.apiVersion !== 1) throw unsupportedApiError(coden.apiVersion);
+  if (typeof coden.plugin !== "string" || !isValidEntryPath(coden.plugin)) throw entryError();
+  return { version: manifest.version, entry: coden.plugin };
+}
+
+async function safeRealpath(file: string, allowMissing = false): Promise<string> {
+  try {
+    return await realpath(file);
+  } catch {
+    if (allowMissing) throw entryError();
+    throw metadataError();
+  }
+}
+
+function withinBoundary(root: string, candidate: string): boolean {
+  return candidate === root || candidate.startsWith(`${root}${path.sep}`);
+}
+
+function isValidEntryPath(entry: string): boolean {
+  if (!entry.startsWith("./")) return false;
+  if (entry.includes("\\") || entry.includes("://") || /\s/.test(entry)) return false;
+  if (!(entry.endsWith(".js") || entry.endsWith(".mjs"))) return false;
+  if (entry.split("/").includes("..")) return false;
+  return true;
+}
+
+function metadataError(): CodeNError {
+  return new CodeNError("plugin", "plugin.metadata_missing", "plugin.metadata_missing");
+}
+
+function unsupportedApiError(apiVersion: unknown): CodeNError {
+  return new CodeNError(
+    "plugin",
+    "plugin.api_unsupported",
+    `plugin.api_unsupported: ${String(apiVersion)}`,
+  );
+}
+
+function entryError(): CodeNError {
+  return new CodeNError("plugin", "plugin.entry_invalid", "plugin.entry_invalid");
+}

package/src/plugins/paths.ts

@@ -0,0 +1,43 @@
+import path from "node:path";
+import { userDataDir } from "../config/config.js";
+
+export type PluginScope = "project" | "global";
+
+export interface PluginPaths {
+  scope: PluginScope;
+  root: string;
+  manifestPath: string;
+  runtimeDir: string;
+  lockPath: string;
+  transactionPath: string;
+}
+
+export function resolvePluginPaths(
+  workspace: string,
+  scope: PluginScope,
+  dataDir = userDataDir(),
+): PluginPaths {
+  if (scope === "project") {
+    const root = path.join(workspace, ".coden");
+    const runtimeDir = path.join(root, "plugin-runtime");
+    return {
+      scope,
+      root,
+      manifestPath: path.join(root, "plugins.json"),
+      runtimeDir,
+      lockPath: path.join(root, "plugin-lock"),
+      transactionPath: path.join(root, "plugin-transaction.json"),
+    };
+  }
+
+  const root = path.join(dataDir, "plugins");
+  const runtimeDir = path.join(root, "runtime");
+  return {
+    scope,
+    root,
+    manifestPath: path.join(root, "plugins.json"),
+    runtimeDir,
+    lockPath: path.join(root, "plugin-lock"),
+    transactionPath: path.join(root, "plugin-transaction.json"),
+  };
+}

package/src/plugins/specifier.ts

@@ -0,0 +1,63 @@
+import { CodeNError } from "../core/types.js";
+
+export interface NpmPluginSpecifier {
+  source: "npm";
+  packageName: string;
+  requested: string;
+  raw: string;
+}
+
+const PACKAGE_NAME_PATTERN =
+  /^(?:@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*|[a-z0-9][a-z0-9._-]*)$/;
+
+export function isValidNpmPackageName(name: string): boolean {
+  return PACKAGE_NAME_PATTERN.test(name) && !name.includes("..") && !name.includes("\\");
+}
+
+export function parseNpmPluginSpecifier(raw: string): NpmPluginSpecifier {
+  if (typeof raw !== "string" || !raw.startsWith("npm:")) throw invalidSpecifier(raw);
+  const body = raw.slice(4);
+  if (!body || /\s/.test(body) || body.includes("\\") || body.includes("://"))
+    throw invalidSpecifier(raw);
+
+  const { packageName, requested } = splitSpecifierBody(body);
+  if (!isValidNpmPackageName(packageName)) throw invalidSpecifier(raw);
+  if (
+    !requested ||
+    /\s/.test(requested) ||
+    requested.includes("\\") ||
+    requested.includes("/") ||
+    requested.includes(":") ||
+    requested.includes("..")
+  )
+    throw invalidSpecifier(raw);
+  return { source: "npm", packageName, requested, raw };
+}
+
+function splitSpecifierBody(body: string): { packageName: string; requested: string } {
+  if (body.startsWith("@")) {
+    const slash = body.indexOf("/");
+    if (slash < 2) throw invalidSpecifier(body);
+    const versionDelimiter = body.lastIndexOf("@");
+    if (versionDelimiter <= slash) return { packageName: body, requested: "latest" };
+    return {
+      packageName: body.slice(0, versionDelimiter),
+      requested: body.slice(versionDelimiter + 1),
+    };
+  }
+
+  const versionDelimiter = body.lastIndexOf("@");
+  if (versionDelimiter === -1) return { packageName: body, requested: "latest" };
+  return {
+    packageName: body.slice(0, versionDelimiter),
+    requested: body.slice(versionDelimiter + 1),
+  };
+}
+
+function invalidSpecifier(value: string): CodeNError {
+  return new CodeNError(
+    "plugin",
+    "plugin.specifier_invalid",
+    `plugin.specifier_invalid: ${String(value)}`,
+  );
+}