orkestrate 0.1.14 → 0.2.0

package/src/sdk/packs/store.ts

@@ -0,0 +1,172 @@
+import { cp, mkdir, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parsePackManifest, toPack, type Pack } from "./schema";
+import { findPackManifestInDir, listCatalogEntries, pathExists, parseManifestYaml } from "./fs";
+import { globalPacksDir, harnessSliceDir, PACK_MANIFEST, workspacePacksDir } from "./paths";
+
+const moduleDir = import.meta.dir ?? process.cwd();
+export const bundledCatalogDir = join(moduleDir, "..", "..", "..", "packs");
+
+export type PackLocation = {
+  pack: Pack;
+  scope: "workspace" | "global" | "bundled";
+};
+
+async function loadPackFromDir(dir: string, scope: PackLocation["scope"]): Promise<Pack | null> {
+  const manifestPath = await findPackManifestInDir(dir);
+  if (!manifestPath) return null;
+  const raw = await Bun.file(manifestPath).text();
+  const manifest = parsePackManifest(parseManifestYaml(raw));
+  return toPack(manifest, dir, manifestPath);
+}
+
+async function discoverInstalled(baseDir: string, scope: "workspace" | "global"): Promise<Pack[]> {
+  const found: Pack[] = [];
+  try {
+    const names = await readdir(baseDir);
+    for (const name of names) {
+      const full = join(baseDir, name);
+      const info = await stat(full);
+      if (!info.isDirectory()) continue;
+      const pack = await loadPackFromDir(full, scope);
+      if (pack) found.push(pack);
+    }
+  } catch {
+    return [];
+  }
+  return found;
+}
+
+export async function ensurePackStore(): Promise<void> {
+  await mkdir(globalPacksDir, { recursive: true });
+  await mkdir(workspacePacksDir, { recursive: true });
+}
+
+export async function listInstalledPacks(): Promise<PackLocation[]> {
+  await ensurePackStore();
+  await seedBundledToGlobalIfMissing();
+  const global = (await discoverInstalled(globalPacksDir, "global")).map((pack) => ({
+    pack,
+    scope: "global" as const,
+  }));
+  const workspace = (await discoverInstalled(workspacePacksDir, "workspace")).map((pack) => ({
+    pack,
+    scope: "workspace" as const,
+  }));
+  const byId = new Map<string, PackLocation>();
+  for (const loc of global) byId.set(loc.pack.id, loc);
+  for (const loc of workspace) byId.set(loc.pack.id, loc);
+  return [...byId.values()].sort((a, b) => a.pack.id.localeCompare(b.pack.id));
+}
+
+export async function resolvePack(packId: string): Promise<Pack> {
+  const locations = await listInstalledPacks();
+  const hit = locations.find((l) => l.pack.id === packId);
+  if (hit) return hit.pack;
+
+  const bundled = join(bundledCatalogDir, packId);
+  const fromBundled = await loadPackFromDir(bundled, "bundled");
+  if (fromBundled) return fromBundled;
+
+  throw new Error(`Pack "${packId}" is not installed. Run: orkestrate pack install ${packId}`);
+}
+
+export async function installPackFromDirectory(
+  sourceRoot: string,
+  options: { target?: "workspace" | "global"; overwrite?: boolean } = {}
+): Promise<Pack> {
+  const manifestPath = await findPackManifestInDir(sourceRoot);
+  if (!manifestPath) {
+    throw new Error(`Source does not contain ${PACK_MANIFEST}`);
+  }
+  const raw = await Bun.file(manifestPath).text();
+  const manifest = parsePackManifest(parseManifestYaml(raw));
+  const pack = toPack(manifest, sourceRoot, manifestPath);
+
+  const target = options.target ?? "workspace";
+  const base = target === "global" ? globalPacksDir : workspacePacksDir;
+  const dest = join(base, pack.id);
+
+  if ((await pathExists(dest)) && !options.overwrite) {
+    throw new Error(`Pack "${pack.id}" is already installed at ${dest}`);
+  }
+  if (await pathExists(dest)) {
+    await rm(dest, { recursive: true, force: true });
+  }
+  await mkdir(base, { recursive: true });
+  await cp(sourceRoot, dest, { recursive: true, force: true });
+
+  return toPack(manifest, dest, join(dest, PACK_MANIFEST));
+}
+
+export async function validatePackLayout(pack: Pack): Promise<{ errors: string[]; warnings: string[] }> {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (!(await pathExists(pack.manifestPath))) {
+    errors.push(`Missing ${PACK_MANIFEST} at pack root (${pack.packRoot})`);
+    return { errors, warnings };
+  }
+
+  const infoPath = join(pack.packRoot, "info.md");
+  if (!(await pathExists(infoPath))) {
+    warnings.push("Missing info.md (recommended pack readme for authors and agents)");
+  }
+
+  const slice = harnessSliceDir(pack.packRoot, pack.harness);
+  if (!(await pathExists(slice))) {
+    errors.push(
+      `Missing harness slice directory: ${join("harnesses", pack.harness)}/\n` +
+        `  → Add native harness config under harnesses/${pack.harness}/ (see packs/coding).`
+    );
+    return { errors, warnings };
+  }
+
+  const configPath = join(slice, "opencode.json");
+  if (!(await pathExists(configPath))) {
+    errors.push(
+      `Missing ${join("harnesses", pack.harness, "opencode.json")}\n` +
+        `  → Copy from packs/coding or run: orkestrate pack create <id> --from coding`
+    );
+  } else {
+    try {
+      const config = await Bun.file(configPath).json();
+      const agent = config.default_agent;
+      if (typeof agent !== "string" || !agent) {
+        warnings.push('opencode.json has no "default_agent" — launch will use pack id');
+      } else {
+        const agentFile = join(slice, "agents", `${agent}.md`);
+        if (!(await pathExists(agentFile))) {
+          errors.push(
+            `opencode.json default_agent "${agent}" has no agents/${agent}.md\n` +
+              `  → Create harnesses/${pack.harness}/agents/${agent}.md`
+          );
+        }
+      }
+    } catch {
+      errors.push(`Invalid JSON: ${configPath}`);
+    }
+  }
+
+  const agentsDir = join(slice, "agents");
+  if (await pathExists(agentsDir)) {
+    const agents = (await readdir(agentsDir)).filter((f) => f.endsWith(".md"));
+    if (agents.length === 0) {
+      warnings.push(`No agent prompts in harnesses/${pack.harness}/agents/*.md`);
+    }
+  } else if (pack.harness === "opencode") {
+    warnings.push(`Missing harnesses/opencode/agents/ (primary agent markdown prompts)`);
+  }
+
+  return { errors, warnings };
+}
+
+export async function seedBundledToGlobalIfMissing(): Promise<void> {
+  const entries = await listCatalogEntries(bundledCatalogDir);
+  for (const entry of entries) {
+    if (entry.kind !== "pack") continue;
+    const dest = join(globalPacksDir, entry.slug);
+    if (await pathExists(dest)) continue;
+    await installPackFromDirectory(entry.path, { target: "global", overwrite: false });
+  }
+}

package/src/sdk/profiles/catalog.ts

@@ -0,0 +1,199 @@
+import { join } from "node:path";
+import { parseProfile, type Profile } from "./schema";
+import { assertProfileName, globalProfilesDir, workspaceProfilesDir } from "./load";
+import {
+  listCatalogEntries,
+  parsePackMeta,
+  pathExists,
+  PROFILE_MANIFEST,
+} from "./pack";
+import {
+  installLegacyJsonProfile,
+  installPackFromDirectory,
+  installPackFromGitHub,
+  resolveGitHubFromRegistryItem,
+} from "./install";
+
+const profileModuleDir = import.meta.dir ?? process.cwd();
+const localCatalogDir = join(profileModuleDir, "..", "..", "..", "profiles");
+
+const REGISTRY_URL = process.env.ORKESTRATE_REGISTRY_URL || "https://orkestrate.space/api/registry";
+
+export type CatalogProfile = {
+  id: string;
+  profile: Profile;
+  sourcePath: string;
+  installed: boolean;
+  source: "bundled" | "registry";
+  github?: string;
+};
+
+export type RegistryItem = {
+  id: string;
+  slug: string;
+  kind: string;
+  name: string;
+  description: string;
+  source_url: string;
+  manifest_url: string | null;
+  version: string;
+  manifest_json: any;
+};
+
+async function isProfileInstalled(profileName: string): Promise<boolean> {
+  const ws = join(workspaceProfilesDir, profileName);
+  const gl = join(globalProfilesDir, profileName);
+  if (await pathExists(join(ws, PROFILE_MANIFEST))) return true;
+  if (await pathExists(join(gl, PROFILE_MANIFEST))) return true;
+  if (await pathExists(join(ws, `${profileName}.json`))) return true;
+  if (await pathExists(join(gl, `${profileName}.json`))) return true;
+  return false;
+}
+
+async function loadCatalogEntry(
+  slug: string,
+  kind: "pack" | "legacy-json",
+  path: string,
+  source: "bundled" | "registry"
+): Promise<CatalogProfile> {
+  let profile: Profile;
+  if (kind === "pack") {
+    const manifestPath = join(path, PROFILE_MANIFEST);
+    profile = parseProfile(await Bun.file(manifestPath).json());
+    profile.sourcePath = manifestPath;
+    profile.packRoot = path;
+  } else {
+    profile = parseProfile(await Bun.file(path).json());
+    profile.sourcePath = path;
+    profile.packRoot = join(path, "..");
+  }
+
+  return {
+    id: slug,
+    profile,
+    sourcePath: path,
+    installed: await isProfileInstalled(profile.name),
+    source,
+  };
+}
+
+async function loadLocalCatalogProfiles(): Promise<CatalogProfile[]> {
+  const entries = await listCatalogEntries(localCatalogDir);
+  const results = await Promise.allSettled(
+    entries.map((entry) => loadCatalogEntry(entry.slug, entry.kind, entry.path, "bundled"))
+  );
+  return results
+    .filter((r): r is PromiseFulfilledResult<CatalogProfile> => r.status === "fulfilled")
+    .map((r) => r.value);
+}
+
+export async function fetchRegistry(): Promise<RegistryItem[]> {
+  try {
+    const response = await fetch(REGISTRY_URL, {
+      headers: { Accept: "application/json" },
+    });
+    if (!response.ok) {
+      throw new Error(`Failed to fetch registry: ${response.status} ${response.statusText}`);
+    }
+    return (await response.json()) as RegistryItem[];
+  } catch (error) {
+    console.warn(`[registry] could not connect to ${REGISTRY_URL}`, error);
+    return [];
+  }
+}
+
+export async function listCatalogProfiles(): Promise<CatalogProfile[]> {
+  const [localProfiles, remoteItems] = await Promise.all([
+    loadLocalCatalogProfiles(),
+    fetchRegistry(),
+  ]);
+
+  const remoteProfilePacks = remoteItems.filter((item) => item.kind === "profile-pack");
+
+  const remoteResults = await Promise.allSettled(
+    remoteProfilePacks.map(async (item) => {
+      let manifest = item.manifest_json;
+      if (!manifest && item.manifest_url) {
+        const res = await fetch(item.manifest_url);
+        if (!res.ok) throw new Error(`Failed to fetch manifest for ${item.slug}`);
+        manifest = await res.json();
+      }
+      if (!manifest) {
+        throw new Error(`Profile pack "${item.slug}" has no manifest`);
+      }
+
+      const profile = parseProfile(manifest);
+      const meta = parsePackMeta(manifest);
+      const gh = parseGitHubFromRegistryItem(item);
+
+      return {
+        id: item.slug,
+        profile,
+        sourcePath: item.source_url,
+        installed: await isProfileInstalled(profile.name),
+        source: "registry" as const,
+        github: `${gh.owner}/${gh.repo}@${gh.ref}${gh.packPath ? `/${gh.packPath}` : ""}`,
+      };
+    })
+  );
+
+  const remoteProfiles: CatalogProfile[] = remoteResults
+    .filter((r) => r.status === "fulfilled")
+    .map((r) => (r as PromiseFulfilledResult<CatalogProfile>).value);
+
+  const seen = new Set<string>();
+  const merged: CatalogProfile[] = [];
+
+  for (const p of [...localProfiles, ...remoteProfiles]) {
+    if (!seen.has(p.profile.name)) {
+      seen.add(p.profile.name);
+      merged.push(p);
+    }
+  }
+
+  return merged;
+}
+
+function parseGitHubFromRegistryItem(item: RegistryItem) {
+  return resolveGitHubFromRegistryItem(item);
+}
+
+export async function installCatalogProfile(
+  slug: string,
+  options?: { target?: "workspace" | "global"; overwrite?: boolean }
+): Promise<Profile> {
+  const safeSlug = slug.replace(/[^a-z0-9-_]/gi, "");
+
+  const localEntries = await listCatalogEntries(localCatalogDir);
+  const local = localEntries.find((e) => e.slug === safeSlug || e.slug === slug);
+  const target = options?.target ?? "workspace";
+  const overwrite = options?.overwrite;
+
+  if (local) {
+    if (local.kind === "pack") {
+      return installPackFromDirectory(local.path, { target, overwrite });
+    }
+    return installLegacyJsonProfile(local.path, { target, overwrite });
+  }
+
+  const items = await fetchRegistry();
+  const item = items.find((i) => i.slug === slug || i.slug === safeSlug);
+  if (!item || item.kind !== "profile-pack") {
+    throw new Error(`Profile pack "${slug}" not found in catalog or registry.`);
+  }
+
+  if (!item.source_url) {
+    throw new Error(`Profile pack "${slug}" has no source_url`);
+  }
+
+  const gh = resolveGitHubFromRegistryItem(item);
+  const meta = parsePackMeta(item.manifest_json ?? {});
+
+  return installPackFromGitHub(item.source_url, {
+    ref: meta.ref ?? gh.ref,
+    packPath: meta.packPath ?? gh.packPath,
+    slug: item.slug,
+    target,
+    overwrite,
+  });
+}

package/src/sdk/profiles/github.ts

@@ -0,0 +1,177 @@
+import { mkdir, readdir, stat, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { copyDirectory, findProfileManifestInDir, pathExists } from "./pack";
+
+export type GitHubSource = {
+  owner: string;
+  repo: string;
+  ref: string;
+  packPath: string;
+  webUrl: string;
+};
+
+export function parseGitHubSource(
+  sourceUrl: string,
+  options?: { ref?: string; packPath?: string }
+): GitHubSource {
+  let url: URL;
+  try {
+    url = new URL(sourceUrl);
+  } catch {
+    throw new Error(`Invalid source URL: ${sourceUrl}`);
+  }
+
+  if (url.hostname !== "github.com") {
+    throw new Error("Only github.com source URLs are supported in v1");
+  }
+
+  const parts = url.pathname.split("/").filter(Boolean);
+  if (parts.length < 2) {
+    throw new Error(`Invalid GitHub URL: ${sourceUrl}`);
+  }
+
+  const owner = parts[0];
+  const repo = parts[1].replace(/\.git$/, "");
+
+  let ref = options?.ref ?? "main";
+  let packPath = options?.packPath ?? "";
+
+  if (parts[2] === "tree" || parts[2] === "blob") {
+    ref = parts[3] ?? ref;
+    packPath = parts.slice(4).join("/");
+  }
+
+  if (options?.packPath) {
+    packPath = options.packPath;
+  }
+
+  return {
+    owner,
+    repo,
+    ref,
+    packPath: packPath.replace(/^\/+|\/+$/g, ""),
+    webUrl: `https://github.com/${owner}/${repo}`,
+  };
+}
+
+async function findPackRoot(cloneRoot: string, packPath: string): Promise<string> {
+  const trimmed = packPath.replace(/^\/+|\/+$/g, "");
+  if (trimmed) {
+    const candidate = join(cloneRoot, trimmed);
+    if (await findProfileManifestInDir(candidate)) {
+      return candidate;
+    }
+    throw new Error(`Pack path "${packPath}" does not contain ${PROFILE_MANIFEST}`);
+  }
+
+  if (await findProfileManifestInDir(cloneRoot)) {
+    return cloneRoot;
+  }
+
+  const entries = await readdir(cloneRoot);
+  for (const entry of entries) {
+    const full = join(cloneRoot, entry);
+    const info = await stat(full);
+    if (info.isDirectory() && (await findProfileManifestInDir(full))) {
+      return full;
+    }
+  }
+
+  throw new Error("Repository does not contain a profile pack (profile.json not found)");
+}
+
+const PROFILE_MANIFEST = "profile.json";
+
+async function cloneWithGit(source: GitHubSource, dest: string): Promise<string> {
+  const cloneUrl = `${source.webUrl}.git`;
+  const proc = Bun.spawn(
+    ["git", "clone", "--depth", "1", "--branch", source.ref, "--single-branch", cloneUrl, dest],
+    { stdout: "pipe", stderr: "pipe" }
+  );
+  const code = await proc.exited;
+  if (code !== 0) {
+    const err = await new Response(proc.stderr).text();
+    throw new Error(`git clone failed: ${err.trim() || `exit ${code}`}`);
+  }
+  return await findPackRoot(dest, source.packPath);
+}
+
+async function downloadTarball(source: GitHubSource, dest: string): Promise<string> {
+  const apiUrl = `https://api.github.com/repos/${source.owner}/${source.repo}/tarball/${source.ref}`;
+  const response = await fetch(apiUrl, {
+    headers: { Accept: "application/vnd.github+json", "User-Agent": "orkestrate-cli" },
+    redirect: "follow",
+  });
+
+  if (!response.ok) {
+    throw new Error(`GitHub archive download failed: ${response.status} ${response.statusText}`);
+  }
+
+  const archivePath = join(dest, "archive.tar.gz");
+  await mkdir(dest, { recursive: true });
+  await Bun.write(archivePath, await response.arrayBuffer());
+
+  const extractDir = join(dest, "extract");
+  await mkdir(extractDir, { recursive: true });
+
+  const tar = Bun.spawn(["tar", "-xzf", archivePath, "-C", extractDir], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const tarCode = await tar.exited;
+  if (tarCode !== 0) {
+    const err = await new Response(tar.stderr).text();
+    throw new Error(`tar extract failed: ${err.trim() || "install git or tar"}`);
+  }
+
+  const top = await readdir(extractDir);
+  if (top.length === 0) {
+    throw new Error("GitHub archive was empty");
+  }
+  const root = join(extractDir, top[0]);
+  return await findPackRoot(root, source.packPath);
+}
+
+export async function fetchGitHubPackRoot(source: GitHubSource): Promise<string> {
+  const work = join(tmpdir(), `orkestrate-fetch-${source.owner}-${source.repo}-${Date.now()}`);
+  await mkdir(work, { recursive: true });
+
+  try {
+    if (await commandExists("git")) {
+      try {
+        return await cloneWithGit(source, join(work, "repo"));
+      } catch {
+        // fall through to tarball
+      }
+    }
+    return await downloadTarball(source, work);
+  } catch (error) {
+    await rm(work, { recursive: true, force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+export async function installGitHubPackToDirectory(
+  source: GitHubSource,
+  targetDir: string
+): Promise<string> {
+  const packRoot = await fetchGitHubPackRoot(source);
+  const parent = join(packRoot, "..");
+  await copyDirectory(packRoot, targetDir);
+  await rm(parent, { recursive: true, force: true }).catch(() => {});
+  const manifest = join(targetDir, PROFILE_MANIFEST);
+  if (!(await pathExists(manifest))) {
+    throw new Error("Installed pack is missing profile.json");
+  }
+  return manifest;
+}
+
+async function commandExists(command: string): Promise<boolean> {
+  const proc = Bun.spawnSync({
+    cmd: [command, "--version"],
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  return proc.exitCode === 0;
+}

package/src/sdk/profiles/install.ts

@@ -0,0 +1,161 @@
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { parseProfile, type Profile } from "./schema";
+import { assertProfileName, globalProfilesDir, workspaceProfilesDir } from "./load";
+import {
+  PROFILE_MANIFEST,
+  applyScaffold,
+  copyDirectory,
+  findProfileManifestInDir,
+  getPackRootFromProfilePath,
+  pathExists,
+} from "./pack";
+import { installGitHubPackToDirectory, parseGitHubSource, type GitHubSource } from "./github";
+
+export type InstallTarget = "workspace" | "global";
+
+export function packsCacheDir(): string {
+  return join(homedir(), ".orkestrate", "packs");
+}
+
+export function installedProfileDir(name: string, target: InstallTarget): string {
+  const base = target === "global" ? globalProfilesDir : workspaceProfilesDir;
+  return join(base, assertProfileName(name));
+}
+
+export async function writeInstallRecord(
+  profileDir: string,
+  record: Record<string, unknown>
+): Promise<void> {
+  await writeFile(join(profileDir, ".orkestrate-install.json"), JSON.stringify(record, null, 2) + "\n");
+}
+
+export async function installPackFromDirectory(
+  sourcePackRoot: string,
+  options: {
+    target?: InstallTarget;
+    overwrite?: boolean;
+    applyWorkspaceScaffold?: boolean;
+    installRecord?: Record<string, unknown>;
+  } = {}
+): Promise<Profile> {
+  const manifestPath = await findProfileManifestInDir(sourcePackRoot);
+  if (!manifestPath) {
+    throw new Error(`Source pack does not contain ${PROFILE_MANIFEST}`);
+  }
+
+  const raw = await Bun.file(manifestPath).json();
+  const profile = parseProfile(raw);
+  profile.sourcePath = manifestPath;
+  profile.packRoot = getPackRootFromProfilePath(manifestPath);
+
+  const target = options.target ?? "workspace";
+  const destDir = installedProfileDir(profile.name, target);
+
+  if ((await pathExists(destDir)) && !options.overwrite) {
+    throw new Error(`Profile "${profile.name}" is already installed at ${destDir}`);
+  }
+
+  if (await pathExists(destDir)) {
+    await rm(destDir, { recursive: true, force: true });
+  }
+
+  await mkdir(join(target === "global" ? globalProfilesDir : workspaceProfilesDir), {
+    recursive: true,
+  });
+  await copyDirectory(sourcePackRoot, destDir);
+
+  const installedManifest = join(destDir, PROFILE_MANIFEST);
+  profile.sourcePath = installedManifest;
+  profile.packRoot = destDir;
+
+  if (options.installRecord) {
+    await writeInstallRecord(destDir, options.installRecord);
+  }
+
+  if (options.applyWorkspaceScaffold !== false) {
+    await applyScaffold(destDir, process.cwd(), profile.name);
+  }
+
+  return profile;
+}
+
+export async function installPackFromGitHub(
+  sourceUrl: string,
+  options: {
+    ref?: string;
+    packPath?: string;
+    slug?: string;
+    target?: InstallTarget;
+    overwrite?: boolean;
+  } = {}
+): Promise<Profile> {
+  const source = parseGitHubSource(sourceUrl, {
+    ref: options.ref,
+    packPath: options.packPath,
+  });
+
+  const cacheSlug = options.slug ?? `${source.owner}-${source.repo}-${source.ref}`.replace(/[^a-z0-9-_]+/gi, "-");
+  const cacheDir = join(packsCacheDir(), cacheSlug);
+
+  if (await pathExists(cacheDir)) {
+    await rm(cacheDir, { recursive: true, force: true });
+  }
+  await mkdir(packsCacheDir(), { recursive: true });
+
+  await installGitHubPackToDirectory(source, cacheDir);
+
+  return installPackFromDirectory(cacheDir, {
+    target: options.target ?? "workspace",
+    overwrite: options.overwrite,
+    installRecord: {
+      source: "github",
+      sourceUrl,
+      ref: source.ref,
+      packPath: source.packPath,
+      slug: cacheSlug,
+      installedAt: new Date().toISOString(),
+    },
+  });
+}
+
+export async function installLegacyJsonProfile(
+  jsonPath: string,
+  options: { target?: InstallTarget; overwrite?: boolean } = {}
+): Promise<Profile> {
+  const raw = await Bun.file(jsonPath).json();
+  const profile = parseProfile(raw);
+  const target = options.target ?? "workspace";
+  const destDir = installedProfileDir(profile.name, target);
+
+  if ((await pathExists(destDir)) && !options.overwrite) {
+    throw new Error(`Profile "${profile.name}" is already installed`);
+  }
+
+  if (await pathExists(destDir)) {
+    await rm(destDir, { recursive: true, force: true });
+  }
+
+  await mkdir(destDir, { recursive: true });
+  const onlyManifest = join(destDir, PROFILE_MANIFEST);
+  await writeFile(onlyManifest, JSON.stringify(raw, null, 2) + "\n");
+
+  profile.sourcePath = onlyManifest;
+  profile.packRoot = destDir;
+  return profile;
+}
+
+export function resolveGitHubFromRegistryItem(item: {
+  source_url: string;
+  version?: string;
+  manifest_json?: any;
+  slug: string;
+}): GitHubSource & { slug: string } {
+  const manifest = item.manifest_json ?? {};
+  const meta = manifest.orkestrate ?? {};
+  const ref = typeof meta.ref === "string" ? meta.ref : item.version ?? "main";
+  const packPath = typeof meta.packPath === "string" ? meta.packPath : "";
+  const source = parseGitHubSource(item.source_url, { ref, packPath });
+  return { ...source, slug: item.slug };
+}