orkestrate 0.1.14 → 0.2.0

package/src/sdk/profiles/load.ts

@@ -0,0 +1,209 @@
+import { copyFile, mkdir, readdir, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseProfile, type Profile } from "./schema";
+import { homedir } from "node:os";
+import {
+  PROFILE_MANIFEST,
+  findProfileManifestInDir,
+  getPackRootFromProfilePath,
+  listCatalogEntries,
+  pathExists,
+} from "./pack";
+
+const profileModuleDir = import.meta.dir ?? process.cwd();
+const seedProfilesDir = join(profileModuleDir, "..", "..", "..", "profiles");
+export const workspaceProfilesDir = join(process.cwd(), ".orkestrate", "profiles");
+export const globalProfilesDir = join(homedir(), ".orkestrate", "profiles");
+
+export type ProfileLocation = {
+  name: string;
+  manifestPath: string;
+  packRoot: string;
+  scope: "workspace" | "global";
+};
+
+async function discoverInStore(baseDir: string, scope: "workspace" | "global"): Promise<ProfileLocation[]> {
+  const found: ProfileLocation[] = [];
+  try {
+    const entries = await readdir(baseDir);
+    for (const entry of entries) {
+      const full = join(baseDir, entry);
+      const info = await stat(full);
+
+      if (info.isDirectory()) {
+        const manifest = await findProfileManifestInDir(full);
+        if (manifest) {
+          found.push({
+            name: entry,
+            manifestPath: manifest,
+            packRoot: full,
+            scope,
+          });
+        }
+        continue;
+      }
+
+      if (entry.endsWith(".json")) {
+        const name = entry.slice(0, -".json".length);
+        found.push({
+          name,
+          manifestPath: full,
+          packRoot: getPackRootFromProfilePath(full),
+          scope,
+        });
+      }
+    }
+  } catch {
+    return [];
+  }
+  return preferPackDirsOverLegacyJson(found);
+}
+
+/** When both `name/` and `name.json` exist, keep the directory pack. */
+function preferPackDirsOverLegacyJson(locations: ProfileLocation[]): ProfileLocation[] {
+  const byName = new Map<string, ProfileLocation>();
+  for (const loc of locations) {
+    const existing = byName.get(loc.name);
+    if (!existing) {
+      byName.set(loc.name, loc);
+      continue;
+    }
+    const existingIsDir = existing.manifestPath.endsWith(`${PROFILE_MANIFEST}`);
+    const nextIsDir = loc.manifestPath.endsWith(`${PROFILE_MANIFEST}`);
+    if (!existingIsDir && nextIsDir) {
+      byName.set(loc.name, loc);
+    }
+  }
+  return [...byName.values()];
+}
+
+export function assertProfileName(name: string): string {
+  if (!/^[a-z0-9][a-z0-9-_]*$/.test(name)) {
+    throw new Error('Profile name must use lowercase letters, numbers, "-", or "_"');
+  }
+  return name;
+}
+
+export async function ensureProfileStore(): Promise<void> {
+  await mkdir(globalProfilesDir, { recursive: true });
+  await mkdir(workspaceProfilesDir, { recursive: true });
+
+  const catalogEntries = await listCatalogEntries(seedProfilesDir);
+  for (const entry of catalogEntries) {
+    const installedDir = join(globalProfilesDir, entry.slug);
+    if (await pathExists(installedDir)) continue;
+
+    if (entry.kind === "pack") {
+      const { copyDirectory } = await import("./pack");
+      await copyDirectory(entry.path, installedDir);
+    } else {
+      await mkdir(installedDir, { recursive: true });
+      const raw = await Bun.file(entry.path).json();
+      await writeFile(join(installedDir, PROFILE_MANIFEST), JSON.stringify(raw, null, 2) + "\n");
+    }
+  }
+}
+
+export async function resolveProfileLocations(name: string): Promise<ProfileLocation[]> {
+  await ensureProfileStore();
+  const safe = assertProfileName(name);
+  const workspace = await discoverInStore(workspaceProfilesDir, "workspace");
+  const global = await discoverInStore(globalProfilesDir, "global");
+  return [...workspace, ...global].filter((loc) => {
+    const manifestName = loc.name;
+    try {
+      return manifestName === safe;
+    } catch {
+      return false;
+    }
+  });
+}
+
+export async function resolveProfileFilePath(name: string): Promise<string> {
+  const locations = await resolveProfileLocations(name);
+  if (locations.length === 0) {
+    await mkdir(workspaceProfilesDir, { recursive: true });
+    return join(workspaceProfilesDir, assertProfileName(name), PROFILE_MANIFEST);
+  }
+  const workspace = locations.find((l) => l.scope === "workspace");
+  return (workspace ?? locations[0]).manifestPath;
+}
+
+export async function loadProfile(name: string): Promise<Profile> {
+  const manifestPath = await resolveProfileFilePath(name);
+  if (!(await pathExists(manifestPath))) {
+    throw new Error(`Profile "${name}" was not found locally or globally.`);
+  }
+
+  const profile = parseProfile(await Bun.file(manifestPath).json(), (warning) => {
+    console.warn(`profile "${name}": ${warning.field} - ${warning.message}`);
+  });
+  profile.sourcePath = manifestPath;
+  profile.packRoot = getPackRootFromProfilePath(manifestPath);
+  return profile;
+}
+
+export async function listProfiles(options?: { warn?: boolean }): Promise<Profile[]> {
+  await ensureProfileStore();
+
+  const workspace = await discoverInStore(workspaceProfilesDir, "workspace");
+  const global = await discoverInStore(globalProfilesDir, "global");
+
+  const byName = new Map<string, ProfileLocation>();
+  for (const loc of preferPackDirsOverLegacyJson([...global, ...workspace])) {
+    const existing = byName.get(loc.name);
+    if (!existing) {
+      byName.set(loc.name, loc);
+      continue;
+    }
+    // Workspace wins over global when both are packs
+    if (loc.scope === "workspace") {
+      byName.set(loc.name, loc);
+    }
+  }
+
+  const validProfiles: Profile[] = [];
+  for (const loc of byName.values()) {
+    try {
+      const profile = parseProfile(await Bun.file(loc.manifestPath).json());
+      profile.sourcePath = loc.manifestPath;
+      profile.packRoot = loc.packRoot;
+      validProfiles.push(profile);
+    } catch (error) {
+      if (options?.warn) {
+        console.warn(`Skipped corrupted profile "${loc.name}":`, error);
+      }
+    }
+  }
+
+  return validProfiles.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export async function saveProfile(
+  profile: Profile,
+  options?: { overwrite?: boolean; isGlobal?: boolean }
+): Promise<void> {
+  await ensureProfileStore();
+  assertProfileName(profile.name);
+
+  const base = options?.isGlobal ? globalProfilesDir : workspaceProfilesDir;
+  const dir = join(base, profile.name);
+  const manifestPath = join(dir, PROFILE_MANIFEST);
+
+  await mkdir(base, { recursive: true });
+
+  if (!options?.overwrite && (await pathExists(manifestPath))) {
+    throw new Error(`Profile "${profile.name}" already exists`);
+  }
+
+  await mkdir(dir, { recursive: true });
+  await writeFile(manifestPath, JSON.stringify(profile, null, 2) + "\n", "utf-8");
+  profile.sourcePath = manifestPath;
+  profile.packRoot = dir;
+}
+
+/** @deprecated use seed dir layout; kept for re-exports */
+export async function jsonProfileNames(dir: string): Promise<string[]> {
+  const locs = await discoverInStore(dir, "global");
+  return locs.map((l) => l.name);
+}

package/src/sdk/profiles/materialize.ts

@@ -0,0 +1,85 @@
+import { cp, mkdir, readdir, stat } from "node:fs/promises";
+import { join, basename } from "node:path";
+import type { Profile } from "./schema";
+import { pathExists } from "./pack";
+
+const profileModuleDir = import.meta.dir ?? process.cwd();
+const bundledSkillsDir = join(profileModuleDir, "..", "..", "..", "skills");
+
+async function copySkillDir(skillDir: string, targetSkillsRoot: string, skillName: string): Promise<void> {
+  const dest = join(targetSkillsRoot, skillName);
+  await mkdir(dest, { recursive: true });
+  await cp(skillDir, dest, { recursive: true, force: true });
+}
+
+async function resolveSkillSource(skillId: string, packRoot: string, cwd: string): Promise<string | null> {
+  const packSkill = join(packRoot, "skills", skillId);
+  if (await pathExists(join(packSkill, "SKILL.md"))) {
+    return packSkill;
+  }
+
+  const bundled = join(bundledSkillsDir, skillId);
+  if (await pathExists(join(bundled, "SKILL.md"))) {
+    return bundled;
+  }
+
+  const candidates = [
+    join(cwd, ".opencode", "skills", skillId),
+    join(cwd, ".agents", "skills", skillId),
+    join(cwd, ".claude", "skills", skillId),
+  ];
+
+  for (const candidate of candidates) {
+    if (await pathExists(join(candidate, "SKILL.md"))) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+export async function materializePackToOpenCodeHome(
+  profile: Profile,
+  opencodeConfigDir: string,
+  cwd: string
+): Promise<{ skillNames: string[]; pluginPaths: string[] }> {
+  const packRoot = profile.packRoot ?? join(profile.sourcePath ?? cwd, "..");
+  const skillsOut = join(opencodeConfigDir, "skills");
+  const pluginsOut = join(opencodeConfigDir, "plugins");
+  await mkdir(skillsOut, { recursive: true });
+  await mkdir(pluginsOut, { recursive: true });
+
+  const resources = profile.config?.resources || profile.resources;
+  const requestedSkills = new Set<string>([...(resources?.skills ?? []), "orkestrate"]);
+  const installedSkills: string[] = [];
+
+  for (const skillId of requestedSkills) {
+    const source = await resolveSkillSource(skillId, packRoot, cwd);
+    if (!source) continue;
+    await copySkillDir(source, skillsOut, basename(source) === skillId ? skillId : basename(source));
+    installedSkills.push(skillId);
+  }
+
+  const pluginsDir = join(packRoot, "plugins");
+  const pluginPaths: string[] = [];
+  if (await pathExists(pluginsDir)) {
+    const entries = await readdir(pluginsDir);
+    for (const entry of entries) {
+      if (!/\.(ts|js|mjs|cjs)$/.test(entry)) continue;
+      const src = join(pluginsDir, entry);
+      const dest = join(pluginsOut, entry);
+      await cp(src, dest, { force: true });
+      pluginPaths.push(dest);
+    }
+  }
+
+  return { skillNames: installedSkills, pluginPaths };
+}
+
+export function buildSkillAllowPermission(skillNames: string[]): Record<string, "allow"> {
+  const permission: Record<string, "allow"> = {};
+  for (const name of skillNames) {
+    permission[name] = "allow";
+  }
+  return permission;
+}

package/src/sdk/profiles/pack.ts

@@ -0,0 +1,128 @@
+import { cp, mkdir, readdir, stat } from "node:fs/promises";
+import { join, basename } from "node:path";
+
+export const PROFILE_MANIFEST = "profile.json";
+
+export type PackMeta = {
+  slug?: string;
+  ref?: string;
+  packPath?: string;
+  sourceUrl?: string;
+};
+
+export function getPackRootFromProfilePath(profileJsonPath: string): string {
+  return join(profileJsonPath, "..");
+}
+
+export async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function copyDirectory(src: string, dest: string): Promise<void> {
+  await mkdir(dest, { recursive: true });
+  await cp(src, dest, { recursive: true, force: true });
+}
+
+export async function findProfileManifestInDir(dir: string): Promise<string | null> {
+  const direct = join(dir, PROFILE_MANIFEST);
+  if (await pathExists(direct)) return direct;
+  return null;
+}
+
+/** List installable catalog slugs: `name/` packs and legacy `name.json` files. */
+export async function listCatalogEntries(catalogDir: string): Promise<
+  { slug: string; kind: "pack" | "legacy-json"; path: string }[]
+> {
+  const entries: { slug: string; kind: "pack" | "legacy-json"; path: string }[] = [];
+  try {
+    const names = await readdir(catalogDir);
+    for (const name of names) {
+      const full = join(catalogDir, name);
+      const info = await stat(full);
+      if (info.isDirectory()) {
+        if (await findProfileManifestInDir(full)) {
+          entries.push({ slug: name, kind: "pack", path: full });
+        }
+      } else if (name.endsWith(".json")) {
+        entries.push({ slug: name.slice(0, -".json".length), kind: "legacy-json", path: full });
+      }
+    }
+  } catch {
+    return [];
+  }
+  return entries.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+export function parsePackMeta(manifest: Record<string, unknown>): PackMeta {
+  const block = manifest.orkestrate;
+  if (!block || typeof block !== "object" || Array.isArray(block)) {
+    return {};
+  }
+  const o = block as Record<string, unknown>;
+  return {
+    slug: typeof o.slug === "string" ? o.slug : undefined,
+    ref: typeof o.ref === "string" ? o.ref : undefined,
+    packPath: typeof o.packPath === "string" ? o.packPath : undefined,
+    sourceUrl: typeof o.sourceUrl === "string" ? o.sourceUrl : undefined,
+  };
+}
+
+export async function validatePackBundle(
+  profile: { packRoot?: string; sourcePath?: string; config?: Record<string, any>; resources?: { skills?: string[] } },
+  options?: { bundledSkillsDir?: string; cwd?: string }
+): Promise<{ errors: string[]; warnings: string[] }> {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const packRoot = profile.packRoot ?? join(profile.sourcePath ?? ".", "..");
+  const cwd = options?.cwd ?? process.cwd();
+  const resources = profile.config?.resources ?? profile.resources;
+  const skills = resources?.skills ?? [];
+
+  for (const skillId of skills) {
+    const packSkill = join(packRoot, "skills", skillId, "SKILL.md");
+    if (await pathExists(packSkill)) continue;
+
+    if (options?.bundledSkillsDir) {
+      const bundled = join(options.bundledSkillsDir, skillId, "SKILL.md");
+      if (await pathExists(bundled)) continue;
+    }
+
+    const workspaceCandidates = [
+      join(cwd, ".opencode", "skills", skillId, "SKILL.md"),
+      join(cwd, ".agents", "skills", skillId, "SKILL.md"),
+    ];
+    const found = await Promise.all(workspaceCandidates.map(pathExists));
+    if (found.some(Boolean)) continue;
+
+    errors.push(`Skill "${skillId}" not found in pack, bundled skills, or workspace`);
+  }
+
+  const pluginsDir = join(packRoot, "plugins");
+  if (await pathExists(pluginsDir)) {
+    const entries = await readdir(pluginsDir);
+    const pluginFiles = entries.filter((e) => /\.(ts|js|mjs|cjs)$/.test(e));
+    if (entries.length > 0 && pluginFiles.length === 0) {
+      warnings.push("plugins/ exists but contains no .ts/.js plugin files");
+    }
+  }
+
+  return { errors, warnings };
+}
+
+export async function applyScaffold(
+  packRoot: string,
+  workspaceCwd: string,
+  profileName: string
+): Promise<void> {
+  const scaffoldDir = join(packRoot, "scaffold");
+  if (!(await pathExists(scaffoldDir))) return;
+
+  const target = join(workspaceCwd, ".orkestrate", "packs", profileName);
+  await mkdir(target, { recursive: true });
+  await copyDirectory(scaffoldDir, target);
+}

package/src/sdk/profiles/schema.ts

@@ -0,0 +1,201 @@
+export type McpServerConfig = {
+  id: string;
+  command: string;
+  args: string[];
+  env?: Record<string, string>;
+};
+
+export type Profile = {
+  name: string;
+  description: string;
+  harness: string;
+  author?: string;
+  tags?: string[];
+  version?: string;
+  sourcePath?: string;
+  /** Directory containing profile.json and bundled skills/plugins/scaffold */
+  packRoot?: string;
+  info: string;
+  config: Record<string, any>;
+
+  // Optional fields for backward compatibility / type convenience in CLI / adapters
+  workspace?: {
+    root: string;
+    policy: "current-directory" | "custom";
+  };
+  model?: {
+    provider: string;
+    id: string;
+    thinking?: string;
+    cycle?: string[];
+  };
+  prompt?: string;
+  resources?: {
+    skills?: string[];
+    prompts?: string[];
+    extensions?: string[];
+    mcpServers?: McpServerConfig[];
+  };
+  tools?: {
+    allow?: string[];
+    deny?: string[];
+  };
+  session?: {
+    dir: string;
+  };
+  env?: Record<string, string>;
+  harnessConfig?: Record<string, any>;
+};
+
+export type ProfileParseWarning = {
+  field: string;
+  message: string;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function assertString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Profile field "${field}" must be a non-empty string`);
+  }
+  return value;
+}
+
+function assertStringArray(value: unknown, field: string): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+    throw new Error(`Profile field "${field}" must be an array of strings`);
+  }
+  return value;
+}
+
+function assertWorkspacePolicy(value: unknown, field: string): "current-directory" | "custom" {
+  if (value === "current-directory" || value === "custom") {
+    return value;
+  }
+  throw new Error(`Profile field "${field}" must be "current-directory" or "custom"`);
+}
+
+function assertHarnessName(value: unknown, field: string): string {
+  const raw = isRecord(value) && typeof value.adapter === "string" ? value.adapter : value;
+  const str = assertString(raw, field);
+  if (!/^[a-z0-9-]+$/.test(str)) {
+    throw new Error(`Profile field "${field}" must contain only lowercase letters, numbers, and dashes`);
+  }
+  return str;
+}
+
+function assertProfileNameValue(value: unknown, field: string): string {
+  const str = assertString(value, field);
+  if (!/^[a-z0-9][a-z0-9-_]*$/.test(str)) {
+    throw new Error('Profile name must use lowercase letters, numbers, "-", or "_"');
+  }
+  return str;
+}
+
+export function parseProfile(value: unknown, warn?: (warning: ProfileParseWarning) => void): Profile {
+  if (!isRecord(value)) {
+    throw new Error("Profile must be an object");
+  }
+
+  const name = assertProfileNameValue(value.name, "name");
+  const description = assertString(value.description, "description");
+  const harness = assertHarnessName(value.harness, "harness");
+  const info = assertString(value.info, "info");
+
+  const author = typeof value.author === "string" ? value.author : undefined;
+  const version = typeof value.version === "string" ? value.version : undefined;
+  const tags = Array.isArray(value.tags) && value.tags.every((t) => typeof t === "string")
+    ? (value.tags as string[])
+    : undefined;
+
+  let config: Record<string, any> = {};
+  if (isRecord(value.config)) {
+    config = value.config;
+  }
+
+  // Populate config from legacy top-level fields if config is empty
+  if (Object.keys(config).length === 0) {
+    const legacyKeys = ["workspace", "model", "prompt", "resources", "tools", "session", "env", "harnessConfig"];
+    for (const key of legacyKeys) {
+      if (key in value) {
+        config[key] = value[key];
+      }
+    }
+  }
+
+  const profile: Profile = {
+    name,
+    description,
+    harness,
+    info,
+    author,
+    tags,
+    version,
+    config,
+  };
+
+  // Optional typing fields mapping for convenience/backward compatibility
+  const configWorkspace = config.workspace || value.workspace;
+  if (isRecord(configWorkspace)) {
+    profile.workspace = {
+      root: typeof configWorkspace.root === "string" ? configWorkspace.root : ".",
+      policy: assertWorkspacePolicy(configWorkspace.policy || "current-directory", "workspace.policy"),
+    };
+  }
+
+  const configModel = config.model || value.model;
+  if (isRecord(configModel)) {
+    profile.model = {
+      provider: typeof configModel.provider === "string" ? configModel.provider : "default",
+      id: typeof configModel.id === "string" ? configModel.id : "default",
+      thinking: typeof configModel.thinking === "string" ? configModel.thinking : undefined,
+      cycle: Array.isArray(configModel.cycle) ? assertStringArray(configModel.cycle, "model.cycle") : undefined,
+    };
+  }
+
+  const configPrompt = config.prompt || value.prompt;
+  if (typeof configPrompt === "string") {
+    profile.prompt = configPrompt;
+  }
+
+  const configResources = config.resources || value.resources;
+  if (isRecord(configResources)) {
+    profile.resources = {
+      skills: assertStringArray(configResources.skills, "resources.skills"),
+      prompts: assertStringArray(configResources.prompts, "resources.prompts"),
+      extensions: assertStringArray(configResources.extensions, "resources.extensions"),
+      mcpServers: (configResources.mcpServers as McpServerConfig[]) || [],
+    };
+  }
+
+  const configTools = config.tools || value.tools;
+  if (isRecord(configTools)) {
+    profile.tools = {
+      allow: assertStringArray(configTools.allow, "tools.allow"),
+      deny: assertStringArray(configTools.deny, "tools.deny"),
+    };
+  }
+
+  const configSession = config.session || value.session;
+  if (isRecord(configSession)) {
+    profile.session = {
+      dir: typeof configSession.dir === "string" ? configSession.dir : "",
+    };
+  }
+
+  const configEnv = config.env || value.env;
+  if (isRecord(configEnv)) {
+    profile.env = configEnv as Record<string, string>;
+  }
+
+  const configHarnessConfig = config.harnessConfig || value.harnessConfig;
+  if (isRecord(configHarnessConfig)) {
+    profile.harnessConfig = configHarnessConfig;
+  }
+
+  return profile;
+}
+

package/src/sdk/registry.ts

@@ -0,0 +1,19 @@
+import type { HarnessDriver } from "./types";
+
+class ExtensionRegistry {
+  private adapters = new Map<string, HarnessDriver>();
+
+  registerAdapter(harness: string, adapter: HarnessDriver): void {
+    this.adapters.set(harness, adapter);
+  }
+
+  getAdapter(harness: string): HarnessDriver | undefined {
+    return this.adapters.get(harness);
+  }
+
+}
+
+export const registry = new ExtensionRegistry();
+
+// Convenience alias for direct use outside extensions
+export const getAdapter = registry.getAdapter.bind(registry);