orkestrate 0.1.14 → 0.2.0

package/src/sdk/packs/catalog.ts

@@ -0,0 +1,172 @@
+import { join } from "node:path";
+import type { Pack } from "./schema";
+import { toPack, parsePackManifest } from "./schema";
+import { listCatalogEntries, pathExists, parseManifestYaml } from "./fs";
+import { bundledCatalogDir, installPackFromDirectory, listInstalledPacks } from "./store";
+import { workspacePacksDir, globalPacksDir, PACK_MANIFEST } from "./paths";
+import { fetchRegistryPackItems, type RegistryItem } from "./registry";
+import {
+  installPackFromGitHub,
+  parseRegistryMeta,
+  resolveGitHubFromRegistryItem,
+} from "./github";
+
+export type CatalogEntry = {
+  slug: string;
+  pack: Pack;
+  installed: boolean;
+  source: "bundled" | "registry";
+  description?: string;
+  github?: string;
+};
+
+async function isPackInstalled(packId: string): Promise<boolean> {
+  if (await pathExists(join(workspacePacksDir, packId, PACK_MANIFEST))) return true;
+  if (await pathExists(join(globalPacksDir, packId, PACK_MANIFEST))) return true;
+  return false;
+}
+
+async function loadBundledEntry(slug: string, path: string): Promise<CatalogEntry> {
+  const manifestPath = join(path, PACK_MANIFEST);
+  const raw = await Bun.file(manifestPath).text();
+  const manifest = parsePackManifest(parseManifestYaml(raw));
+  const pack = toPack(manifest, path, manifestPath);
+  return {
+    slug,
+    pack,
+    installed: await isPackInstalled(pack.id),
+    source: "bundled",
+  };
+}
+
+function registryEntryToCatalog(item: RegistryItem): CatalogEntry | null {
+  const manifest = item.manifest_json;
+  if (manifest && typeof manifest === "object" && !Array.isArray(manifest)) {
+    const o = manifest as Record<string, unknown>;
+    if (typeof o.id === "string" && typeof o.harness === "string") {
+      try {
+        const parsed = parsePackManifest(manifest);
+        const pack = toPack(parsed, item.source_url, item.source_url);
+        const gh = resolveGitHubFromRegistryItem(item);
+        return {
+          slug: item.slug,
+          pack,
+          installed: false,
+          source: "registry",
+          description: item.description,
+          github: `${gh.owner}/${gh.repo}@${gh.ref}${gh.packPath ? `/${gh.packPath}` : ""}`,
+        };
+      } catch {
+        // fall through — install uses GitHub tree
+      }
+    }
+  }
+
+  const pack = toPack(
+    {
+      id: item.slug,
+      name: item.name,
+      description: item.description,
+      harness: "opencode",
+      version: item.version,
+    },
+    item.source_url,
+    item.source_url
+  );
+  const gh = resolveGitHubFromRegistryItem(item);
+  return {
+    slug: item.slug,
+    pack,
+    installed: false,
+    source: "registry",
+    description: item.description,
+    github: `${gh.owner}/${gh.repo}@${gh.ref}${gh.packPath ? `/${gh.packPath}` : ""}`,
+  };
+}
+
+export async function listBundledCatalog(): Promise<CatalogEntry[]> {
+  const entries = await listCatalogEntries(bundledCatalogDir);
+  const results: CatalogEntry[] = [];
+  for (const entry of entries) {
+    if (entry.kind !== "pack") continue;
+    results.push(await loadBundledEntry(entry.slug, entry.path));
+  }
+  return results;
+}
+
+export async function listRegistryCatalog(): Promise<CatalogEntry[]> {
+  let items: RegistryItem[];
+  try {
+    items = await fetchRegistryPackItems();
+  } catch (error) {
+    console.warn(error instanceof Error ? error.message : String(error));
+    return [];
+  }
+
+  const results: CatalogEntry[] = [];
+  for (const item of items) {
+    const entry = registryEntryToCatalog(item);
+    if (!entry) continue;
+    entry.installed = await isPackInstalled(entry.pack.id);
+    results.push(entry);
+  }
+  return results;
+}
+
+/** Bundled packs first, then registry (dedupe by pack id). */
+export async function listFullCatalog(): Promise<CatalogEntry[]> {
+  const [bundled, remote] = await Promise.all([listBundledCatalog(), listRegistryCatalog()]);
+  const seen = new Set<string>();
+  const merged: CatalogEntry[] = [];
+  for (const entry of [...bundled, ...remote]) {
+    if (seen.has(entry.pack.id)) continue;
+    seen.add(entry.pack.id);
+    merged.push(entry);
+  }
+  return merged.sort((a, b) => a.pack.id.localeCompare(b.pack.id));
+}
+
+export async function installCatalogPack(
+  slug: string,
+  options?: { target?: "workspace" | "global"; overwrite?: boolean }
+): Promise<Pack> {
+  const safeSlug = slug.replace(/[^a-z0-9-_]/gi, "");
+
+  const entries = await listCatalogEntries(bundledCatalogDir);
+  const hit = entries.find((e) => e.slug === safeSlug || e.slug === slug);
+  if (hit?.kind === "pack") {
+    return installPackFromDirectory(hit.path, {
+      target: options?.target ?? "workspace",
+      overwrite: options?.overwrite,
+    });
+  }
+
+  let items: RegistryItem[];
+  try {
+    items = await fetchRegistryPackItems();
+  } catch (error) {
+    throw new Error(
+      `Pack "${slug}" is not bundled and registry is unavailable: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+
+  const item = items.find((i) => i.slug === slug || i.slug === safeSlug);
+  if (!item) {
+    throw new Error(`Pack "${slug}" not found in bundled catalog or registry.`);
+  }
+
+  const gh = resolveGitHubFromRegistryItem(item);
+  const meta = parseRegistryMeta(item.manifest_json);
+
+  return installPackFromGitHub(item.source_url, {
+    ref: meta.ref ?? gh.ref,
+    packPath: meta.packPath ?? gh.packPath,
+    slug: item.slug,
+    target: options?.target,
+    overwrite: options?.overwrite,
+  });
+}
+
+export { listInstalledPacks, seedBundledToGlobalIfMissing } from "./store";

package/src/sdk/packs/create.ts

@@ -0,0 +1,99 @@
+import { cp, mkdir, readdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { assertPackId, type PackManifest } from "./schema";
+import { bundledCatalogDir } from "./store";
+import { pathExists } from "./fs";
+import { globalPacksDir, workspacePacksDir } from "./paths";
+
+export type CreatePackOptions = {
+  id: string;
+  description?: string;
+  template?: string;
+  target?: "workspace" | "global";
+};
+
+function yamlEscape(value: string): string {
+  if (/[:#\n]/.test(value) || value.startsWith(" ")) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  }
+  return value;
+}
+
+function manifestYaml(manifest: PackManifest): string {
+  const lines = [
+    `id: ${manifest.id}`,
+    `name: ${manifest.name}`,
+    `description: ${yamlEscape(manifest.description)}`,
+    `version: "${manifest.version ?? "0.1.0"}"`,
+    `harness: ${manifest.harness}`,
+  ];
+  return lines.join("\n") + "\n";
+}
+
+async function replaceInTree(root: string, from: string, to: string): Promise<void> {
+  const entries = await readdir(root, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = join(root, entry.name);
+    if (entry.isDirectory()) {
+      await replaceInTree(full, from, to);
+      continue;
+    }
+    const text = await readFile(full, "utf-8");
+    if (!text.includes(from)) continue;
+    await writeFile(full, text.split(from).join(to), "utf-8");
+  }
+}
+
+export async function createPackFromTemplate(options: CreatePackOptions): Promise<string> {
+  const id = assertPackId(options.id);
+  const template = assertPackId(options.template ?? "coding");
+  const templateRoot = join(bundledCatalogDir, template);
+  if (!(await pathExists(templateRoot))) {
+    throw new Error(`Template pack "${template}" not found in ${bundledCatalogDir}`);
+  }
+
+  const target = options.target ?? "workspace";
+  const destBase = target === "global" ? globalPacksDir : workspacePacksDir;
+  const dest = join(destBase, id);
+
+  if (await pathExists(dest)) {
+    throw new Error(`Pack "${id}" already exists at ${dest}`);
+  }
+
+  await mkdir(destBase, { recursive: true });
+  await cp(templateRoot, dest, { recursive: true });
+
+  const description =
+    options.description ??
+    (template === id ? `Pack ${id}` : `${template} pack customized as ${id}`);
+
+  const manifest: PackManifest = {
+    id,
+    name: id,
+    description,
+    version: "0.1.0",
+    harness: "opencode",
+  };
+  await writeFile(join(dest, "pack.yaml"), manifestYaml(manifest), "utf-8");
+
+  if (template !== id) {
+    const agentDir = join(dest, "harnesses", "opencode", "agents");
+    const oldAgent = join(agentDir, `${template}.md`);
+    const newAgent = join(agentDir, `${id}.md`);
+    if (await pathExists(oldAgent)) {
+      await rename(oldAgent, newAgent);
+    }
+    await replaceInTree(join(dest, "harnesses", "opencode"), template, id);
+  }
+
+  const infoPath = join(dest, "info.md");
+  if (!(await pathExists(infoPath))) {
+    await writeFile(
+      infoPath,
+      `# ${id}\n\n${description}\n`,
+      "utf-8"
+    );
+  }
+
+  return dest;
+}

package/src/sdk/packs/fs.ts

@@ -0,0 +1,52 @@
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { PACK_MANIFEST } from "./paths";
+
+export function parseManifestYaml(raw: string): unknown {
+  if (typeof (Bun as { YAML?: { parse: (s: string) => unknown } }).YAML?.parse === "function") {
+    return Bun.YAML.parse(raw);
+  }
+  return JSON.parse(raw);
+}
+
+export async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function findPackManifestInDir(dir: string): Promise<string | null> {
+  const direct = join(dir, PACK_MANIFEST);
+  if (await pathExists(direct)) return direct;
+  return null;
+}
+
+export type CatalogEntryKind = {
+  slug: string;
+  kind: "pack" | "legacy-profile";
+  path: string;
+};
+
+export async function listCatalogEntries(catalogDir: string): Promise<CatalogEntryKind[]> {
+  const entries: CatalogEntryKind[] = [];
+  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 findPackManifestInDir(full)) {
+          entries.push({ slug: name, kind: "pack", path: full });
+        } else if (await pathExists(join(full, "profile.json"))) {
+          entries.push({ slug: name, kind: "legacy-profile", path: full });
+        }
+      }
+    }
+  } catch {
+    return [];
+  }
+  return entries.sort((a, b) => a.slug.localeCompare(b.slug));
+}

package/src/sdk/packs/github.ts

@@ -0,0 +1,249 @@
+import { cp, mkdir, readdir, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { homedir } from "node:os";
+import { findPackManifestInDir, pathExists } from "./fs";
+import { PACK_MANIFEST } from "./paths";
+import type { Pack } from "./schema";
+
+export type GitHubSource = {
+  owner: string;
+  repo: string;
+  ref: string;
+  packPath: string;
+  webUrl: string;
+};
+
+export function packsCacheDir(): string {
+  return join(homedir(), ".orkestrate", "registry-cache");
+}
+
+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");
+  }
+
+  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}`,
+  };
+}
+
+export function parseRegistryMeta(manifest: unknown): { ref?: string; packPath?: string } {
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    return {};
+  }
+  const block = (manifest as Record<string, unknown>).orkestrate;
+  if (!block || typeof block !== "object" || Array.isArray(block)) {
+    return {};
+  }
+  const o = block as Record<string, unknown>;
+  return {
+    ref: typeof o.ref === "string" ? o.ref : undefined,
+    packPath: typeof o.packPath === "string" ? o.packPath : undefined,
+  };
+}
+
+export function resolveGitHubFromRegistryItem(item: {
+  source_url: string;
+  version?: string;
+  manifest_json?: unknown;
+  slug: string;
+}): GitHubSource {
+  const meta = parseRegistryMeta(item.manifest_json);
+  const ref = meta.ref ?? item.version ?? "main";
+  return parseGitHubSource(item.source_url, { ref, packPath: meta.packPath });
+}
+
+async function findPackRoot(cloneRoot: string, packPath: string): Promise<string> {
+  const trimmed = packPath.replace(/^\/+|\/+$/g, "");
+  if (trimmed) {
+    const candidate = join(cloneRoot, trimmed);
+    if (await findPackManifestInDir(candidate)) {
+      return candidate;
+    }
+    throw new Error(`Pack path "${packPath}" does not contain ${PACK_MANIFEST}`);
+  }
+
+  if (await findPackManifestInDir(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 findPackManifestInDir(full))) {
+      return full;
+    }
+  }
+
+  throw new Error(`Repository does not contain a pack (${PACK_MANIFEST} not found)`);
+}
+
+async function commandExists(command: string): Promise<boolean> {
+  const proc = Bun.spawnSync({
+    cmd: [command, "--version"],
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  return proc.exitCode === 0;
+}
+
+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 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 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 installPackFromGitHub(
+  sourceUrl: string,
+  options: {
+    ref?: string;
+    packPath?: string;
+    slug?: string;
+    target?: "workspace" | "global";
+    overwrite?: boolean;
+  } = {}
+): Promise<Pack> {
+  const { installPackFromDirectory } = await import("./store");
+  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 });
+
+  const packRoot = await fetchGitHubPackRoot(source);
+  const parent = join(packRoot, "..");
+  await cp(packRoot, cacheDir, { recursive: true, force: true });
+  await rm(parent, { recursive: true, force: true }).catch(() => {});
+
+  const installed = await installPackFromDirectory(cacheDir, {
+    target: options.target ?? "workspace",
+    overwrite: options.overwrite ?? false,
+  });
+
+  await writeInstallRecord(installed.packRoot, {
+    source: "registry",
+    sourceUrl,
+    ref: source.ref,
+    packPath: source.packPath,
+    slug: cacheSlug,
+    installedAt: new Date().toISOString(),
+  });
+
+  return installed;
+}
+
+async function writeInstallRecord(packDir: string, record: Record<string, unknown>): Promise<void> {
+  await Bun.write(
+    join(packDir, ".orkestrate-install.json"),
+    JSON.stringify(record, null, 2) + "\n"
+  );
+}

package/src/sdk/packs/paths.ts

@@ -0,0 +1,19 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export const PACK_MANIFEST = "pack.yaml";
+export const HARNESS_DIR = "harnesses";
+
+export const workspacePacksDir = join(process.cwd(), ".orkestrate", "packs");
+export const globalPacksDir = join(homedir(), ".orkestrate", "packs");
+export const workspaceRunsDir = join(process.cwd(), ".orkestrate", "runs");
+/** Persistent OpenCode home per pack in this workspace (sessions survive relaunches). */
+export const workspacePackHomesDir = join(process.cwd(), ".orkestrate", "pack-homes");
+
+export function packHomePath(packId: string): string {
+  return join(workspacePackHomesDir, packId, "home");
+}
+
+export function harnessSliceDir(packRoot: string, harness: string): string {
+  return join(packRoot, HARNESS_DIR, harness);
+}

package/src/sdk/packs/registry.ts

@@ -0,0 +1,40 @@
+export const REGISTRY_URL =
+  process.env.ORKESTRATE_REGISTRY_URL || "https://orkestrate.space/api/registry";
+
+export type RegistryItem = {
+  id: string;
+  slug: string;
+  kind: string;
+  name: string;
+  description: string;
+  source_url: string;
+  manifest_url: string | null;
+  version: string;
+  manifest_json: unknown;
+};
+
+const PACK_KINDS = new Set(["profile-pack", "pack", "skill-pack"]);
+
+export async function fetchRegistry(): Promise<RegistryItem[]> {
+  try {
+    const response = await fetch(REGISTRY_URL, {
+      headers: { Accept: "application/json" },
+    });
+    if (!response.ok) {
+      throw new Error(`Registry returned ${response.status} ${response.statusText}`);
+    }
+    return (await response.json()) as RegistryItem[];
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Could not reach registry at ${REGISTRY_URL}: ${message}`);
+  }
+}
+
+export function isInstallablePackKind(kind: string): boolean {
+  return PACK_KINDS.has(kind);
+}
+
+export async function fetchRegistryPackItems(): Promise<RegistryItem[]> {
+  const items = await fetchRegistry();
+  return items.filter((item) => isInstallablePackKind(item.kind) && item.source_url);
+}

package/src/sdk/packs/schema.ts

@@ -0,0 +1,51 @@
+export type PackManifest = {
+  id: string;
+  name: string;
+  description: string;
+  version?: string;
+  harness: string;
+  author?: string;
+  tags?: string[];
+};
+
+export type Pack = PackManifest & {
+  packRoot: string;
+  manifestPath: string;
+};
+
+export function assertPackId(id: string): string {
+  if (!/^[a-z0-9][a-z0-9-_]*$/.test(id)) {
+    throw new Error('Pack id must use lowercase letters, numbers, "-", or "_"');
+  }
+  return id;
+}
+
+export function parsePackManifest(value: unknown): PackManifest {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("pack.yaml must be an object");
+  }
+  const o = value as Record<string, unknown>;
+  const id = assertPackId(String(o.id ?? o.name ?? ""));
+  const name = typeof o.name === "string" && o.name.length > 0 ? o.name : id;
+  const description = typeof o.description === "string" ? o.description : "";
+  if (!description) {
+    throw new Error('pack.yaml field "description" is required');
+  }
+  const harness = typeof o.harness === "string" ? o.harness : "";
+  if (!harness || !/^[a-z0-9-]+$/.test(harness)) {
+    throw new Error('pack.yaml field "harness" must be a lowercase harness id (e.g. opencode)');
+  }
+  return {
+    id,
+    name,
+    description,
+    harness,
+    version: typeof o.version === "string" ? o.version : undefined,
+    author: typeof o.author === "string" ? o.author : undefined,
+    tags: Array.isArray(o.tags) && o.tags.every((t) => typeof t === "string") ? (o.tags as string[]) : undefined,
+  };
+}
+
+export function toPack(manifest: PackManifest, packRoot: string, manifestPath: string): Pack {
+  return { ...manifest, packRoot, manifestPath };
+}