open-research-protocol 0.4.14 → 0.4.16

package/packages/lifeops-orp/src/index.d.ts

@@ -0,0 +1,106 @@
+export interface OrpCommandInput {
+  repoRoot: string;
+  args: string[];
+}
+
+export interface OrpWorkspace {
+  repoRoot: string;
+  status: Record<string, unknown>;
+  frontierState: Record<string, unknown> | null;
+  frontierRoadmap: Record<string, unknown> | null;
+  frontierChecklist: Record<string, unknown> | null;
+  about: Record<string, unknown> | null;
+  collectedAt: string;
+}
+
+export interface LifeOpsLikeItem {
+  id: string;
+  kind: "event" | "communication" | "routine" | "task" | "alert" | "document";
+  title: string;
+  summary?: string;
+  priority?: "urgent" | "high" | "normal" | "low";
+  organization?: string | null;
+  tags?: string[];
+  source?: {
+    connector?: string;
+    id?: string;
+    account?: string | null;
+  };
+  metadata?: Record<string, unknown>;
+}
+
+export interface ProjectShareInput {
+  name: string;
+  summary: string;
+  whyNow: string;
+  highlights: string[];
+  proofPoints: string[];
+  links: Array<{ label: string; url: string }>;
+  codebases: string[];
+}
+
+export declare function runOrpJson(options: {
+  repoRoot: string;
+  args: string[];
+  orpCommand?: string;
+}): Promise<Record<string, unknown>>;
+
+export declare function collectOrpWorkspace(options: {
+  repoRoot: string;
+  orpCommand?: string;
+  includeAbout?: boolean;
+  commandRunner?: (input: OrpCommandInput) => Promise<Record<string, unknown>>;
+}): Promise<OrpWorkspace>;
+
+export declare function mapOrpWorkspaceToItems(options: {
+  workspace: OrpWorkspace;
+  projectName?: string;
+  organization?: string;
+}): LifeOpsLikeItem[];
+
+export declare function createOrpProjectShareInput(options: {
+  workspace: OrpWorkspace;
+  projectName?: string;
+  summary?: string;
+  repoUrl?: string;
+  liveUrl?: string;
+  extraHighlights?: string[];
+  extraProofPoints?: string[];
+  extraCodebases?: string[];
+}): ProjectShareInput;
+
+export declare function buildOrpProjectSharePacket(options: {
+  repoRoot: string;
+  recipients: Array<Record<string, unknown>>;
+  buildProjectSharePacket: (input: Record<string, unknown>) => unknown;
+  orpCommand?: string;
+  includeAbout?: boolean;
+  commandRunner?: (input: OrpCommandInput) => Promise<Record<string, unknown>>;
+  projectName?: string;
+  summary?: string;
+  repoUrl?: string;
+  liveUrl?: string;
+  extraHighlights?: string[];
+  extraProofPoints?: string[];
+  extraCodebases?: string[];
+  senderName?: string;
+  baseTime?: string | Date | number;
+}): Promise<unknown>;
+
+export declare function createOrpConnector(options: {
+  repoRoot: string;
+  orpCommand?: string;
+  name?: string;
+  projectName?: string;
+  organization?: string;
+  includeAbout?: boolean;
+  commandRunner?: (input: OrpCommandInput) => Promise<Record<string, unknown>>;
+}): {
+  name: string;
+  pull(): Promise<{
+    items: LifeOpsLikeItem[];
+    meta: {
+      workspace: OrpWorkspace;
+    };
+  }>;
+};

package/packages/lifeops-orp/src/index.js

@@ -0,0 +1,7 @@
+export { collectOrpWorkspace, runOrpJson } from "./workspace.js";
+export {
+  buildOrpProjectSharePacket,
+  createOrpConnector,
+  createOrpProjectShareInput,
+  mapOrpWorkspaceToItems,
+} from "./mapping.js";

package/packages/lifeops-orp/src/mapping.js

@@ -0,0 +1,309 @@
+import { collectOrpWorkspace } from "./workspace.js";
+
+function slugify(value) {
+  return String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function pushItem(items, item) {
+  if (!item) {
+    return;
+  }
+  items.push(item);
+}
+
+function projectLabel(workspace, projectName) {
+  return (
+    projectName ||
+    workspace.frontierState?.label ||
+    workspace.frontierState?.program_id ||
+    workspace.status?.repo_root?.split("/").filter(Boolean).pop() ||
+    "ORP Project"
+  );
+}
+
+function readinessItem(workspace, name, organization) {
+  const readiness = workspace.status?.readiness ?? {};
+  if (!readiness.local_ready && !readiness.remote_ready) {
+    return null;
+  }
+  const scope = readiness.scope || "local_only";
+  return {
+    id: `orp-ready:${slugify(name)}`,
+    kind: "alert",
+    title: `${name} is ready to share`,
+    summary: `ORP readiness is marked true (${scope}).`,
+    priority: "high",
+    organization,
+    tags: ["orp", "readiness", "share"],
+    source: {
+      connector: "orp",
+      id: "ready",
+    },
+    metadata: {
+      readiness,
+      latestRun: workspace.status?.runtime?.last_ready ?? {},
+    },
+  };
+}
+
+function frontierItem(workspace, name, organization) {
+  const frontier = workspace.frontierState ?? {};
+  if (!frontier.active_milestone && !frontier.next_action) {
+    return null;
+  }
+  const milestone = frontier.active_milestone || frontier.active_version || "frontier";
+  const title = frontier.next_action
+    ? `ORP frontier: ${frontier.next_action}`
+    : `Advance frontier milestone ${milestone}`;
+
+  return {
+    id: `orp-frontier:${slugify(name)}:${slugify(milestone) || "state"}`,
+    kind: "task",
+    title,
+    summary: [
+      frontier.active_version ? `version ${frontier.active_version}` : "",
+      frontier.active_milestone ? `milestone ${frontier.active_milestone}` : "",
+      frontier.active_phase ? `phase ${frontier.active_phase}` : "",
+    ]
+      .filter(Boolean)
+      .join(" / "),
+    priority: "high",
+    organization,
+    tags: ["orp", "frontier"],
+    source: {
+      connector: "orp",
+      id: "frontier-state",
+    },
+    metadata: {
+      frontier,
+    },
+  };
+}
+
+function nextActionItems(workspace, name, organization) {
+  const actions = Array.isArray(workspace.status?.next_actions) ? workspace.status.next_actions : [];
+  return actions.slice(0, 5).map((action, index) => ({
+    id: `orp-next:${slugify(name)}:${index + 1}`,
+    kind: "task",
+    title: `ORP next action: ${action}`,
+    summary: `Suggested by ORP status for ${name}.`,
+    priority: index === 0 ? "high" : "normal",
+    organization,
+    tags: ["orp", "next-action"],
+    source: {
+      connector: "orp",
+      id: `next-action-${index + 1}`,
+    },
+    metadata: {
+      action,
+    },
+  }));
+}
+
+function checklistItems(workspace, name, organization) {
+  const exact = Array.isArray(workspace.frontierChecklist?.exact)
+    ? workspace.frontierChecklist.exact
+    : [];
+  return exact.slice(0, 10).map((row, index) => {
+    const milestone = row.milestone_id || row.milestone || `item-${index + 1}`;
+    const label = row.label || row.phase_label || row.next_action || milestone;
+    return {
+      id: `orp-checklist:${slugify(name)}:${slugify(milestone)}`,
+      kind: "task",
+      title: `ORP checklist: ${label}`,
+      summary: [
+        row.version_id ? `version ${row.version_id}` : "",
+        row.milestone_id ? `milestone ${row.milestone_id}` : "",
+        row.phase_id ? `phase ${row.phase_id}` : "",
+      ]
+        .filter(Boolean)
+        .join(" / "),
+      priority: "normal",
+      organization,
+      tags: ["orp", "checklist"],
+      source: {
+        connector: "orp",
+        id: `checklist-${index + 1}`,
+      },
+      metadata: {
+        checklistRow: row,
+      },
+    };
+  });
+}
+
+function validationAlert(workspace, name, organization) {
+  const latestRun = workspace.status?.runtime?.latest_run ?? {};
+  const overall = latestRun.overall || "";
+  if (!overall || overall === "PASS") {
+    return null;
+  }
+  return {
+    id: `orp-validation:${slugify(name)}`,
+    kind: "alert",
+    title: `${name} has a non-passing ORP validation state`,
+    summary: `Latest ORP run overall status: ${overall}.`,
+    priority: "urgent",
+    organization,
+    tags: ["orp", "validation"],
+    source: {
+      connector: "orp",
+      id: "validation",
+    },
+    metadata: {
+      latestRun,
+    },
+  };
+}
+
+export function mapOrpWorkspaceToItems({
+  workspace,
+  projectName,
+  organization = "ORP",
+} = {}) {
+  if (!workspace || typeof workspace !== "object") {
+    throw new Error("mapOrpWorkspaceToItems requires a workspace object.");
+  }
+
+  const name = projectLabel(workspace, projectName);
+  const items = [];
+
+  pushItem(items, readinessItem(workspace, name, organization));
+  pushItem(items, frontierItem(workspace, name, organization));
+  pushItem(items, validationAlert(workspace, name, organization));
+
+  items.push(...nextActionItems(workspace, name, organization));
+  items.push(...checklistItems(workspace, name, organization));
+
+  return items;
+}
+
+export function createOrpProjectShareInput({
+  workspace,
+  projectName,
+  summary = "",
+  repoUrl = "",
+  liveUrl = "",
+  extraHighlights = [],
+  extraProofPoints = [],
+  extraCodebases = [],
+} = {}) {
+  if (!workspace || typeof workspace !== "object") {
+    throw new Error("createOrpProjectShareInput requires a workspace object.");
+  }
+
+  const name = projectLabel(workspace, projectName);
+  const readiness = workspace.status?.readiness ?? {};
+  const frontier = workspace.frontierState ?? {};
+  const latestRun = workspace.status?.runtime?.latest_run ?? {};
+
+  const whyNow = readiness.local_ready || readiness.remote_ready
+    ? "ORP marks this repo as ready, so this is a strong moment to share it with selected collaborators."
+    : "The ORP frontier is active and concrete next actions are already defined, so this is a good moment to share progress in a structured way.";
+
+  const highlights = [
+    frontier.next_action ? `Current frontier next action: ${frontier.next_action}` : "",
+    frontier.active_milestone ? `Active frontier milestone: ${frontier.active_milestone}` : "",
+    Array.isArray(workspace.status?.next_actions) && workspace.status.next_actions[0]
+      ? `Immediate ORP next action: ${workspace.status.next_actions[0]}`
+      : "",
+    ...extraHighlights,
+  ].filter(Boolean);
+
+  const proofPoints = [
+    latestRun.overall ? `Latest ORP validation run: ${latestRun.overall}` : "",
+    readiness.local_ready ? "Local ORP readiness is marked true." : "",
+    readiness.remote_ready ? "Remote ORP readiness is marked true." : "",
+    workspace.status?.validation?.checkpoint_after_validation
+      ? "Checkpoint captured after validation."
+      : "",
+    ...extraProofPoints,
+  ].filter(Boolean);
+
+  const links = [
+    repoUrl ? { label: "Repository", url: repoUrl } : null,
+    liveUrl ? { label: "Live URL", url: liveUrl } : null,
+  ].filter(Boolean);
+
+  const codebases = [
+    "open-research-protocol",
+    ...extraCodebases,
+  ].filter(Boolean);
+
+  return {
+    name,
+    summary: summary || `An ORP-governed project with machine-readable frontier, readiness, and workflow state.`,
+    whyNow,
+    highlights,
+    proofPoints,
+    links,
+    codebases,
+  };
+}
+
+export async function buildOrpProjectSharePacket({
+  repoRoot,
+  buildProjectSharePacket,
+  recipients,
+  orpCommand = "orp",
+  includeAbout = true,
+  commandRunner,
+  ...shareOptions
+} = {}) {
+  if (typeof buildProjectSharePacket !== "function") {
+    throw new Error("buildOrpProjectSharePacket requires a buildProjectSharePacket function.");
+  }
+
+  const workspace = await collectOrpWorkspace({
+    repoRoot,
+    orpCommand,
+    includeAbout,
+    commandRunner,
+  });
+
+  return buildProjectSharePacket({
+    project: createOrpProjectShareInput({
+      workspace,
+      ...shareOptions,
+    }),
+    recipients,
+    senderName: shareOptions.senderName,
+    baseTime: shareOptions.baseTime,
+  });
+}
+
+export function createOrpConnector({
+  repoRoot,
+  orpCommand = "orp",
+  name = "orp",
+  projectName,
+  organization = "ORP",
+  includeAbout = false,
+  commandRunner,
+} = {}) {
+  return {
+    name,
+    async pull() {
+      const workspace = await collectOrpWorkspace({
+        repoRoot,
+        orpCommand,
+        includeAbout,
+        commandRunner,
+      });
+      return {
+        items: mapOrpWorkspaceToItems({
+          workspace,
+          projectName,
+          organization,
+        }),
+        meta: {
+          workspace,
+        },
+      };
+    },
+  };
+}

package/packages/lifeops-orp/src/workspace.js

@@ -0,0 +1,108 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+function withJsonFlag(args = []) {
+  return args.includes("--json") ? args : [...args, "--json"];
+}
+
+function normalizeCommandError(error) {
+  if (error instanceof Error) {
+    return error;
+  }
+  return new Error(String(error));
+}
+
+export async function runOrpJson({
+  repoRoot,
+  args = [],
+  orpCommand = "orp",
+} = {}) {
+  if (!repoRoot) {
+    throw new Error("runOrpJson requires a repoRoot.");
+  }
+
+  const result = await execFileAsync(orpCommand, withJsonFlag(args), {
+    cwd: repoRoot,
+    env: process.env,
+    maxBuffer: 8 * 1024 * 1024,
+  });
+
+  const stdout = String(result.stdout ?? "").trim();
+  if (!stdout) {
+    throw new Error(`ORP command returned no JSON output: ${args.join(" ")}`);
+  }
+
+  try {
+    return JSON.parse(stdout);
+  } catch (error) {
+    throw new Error(
+      `Failed to parse ORP JSON output for "${args.join(" ")}": ${
+        normalizeCommandError(error).message
+      }`,
+    );
+  }
+}
+
+async function tryCommand(commandRunner, input) {
+  try {
+    return await commandRunner(input);
+  } catch {
+    return null;
+  }
+}
+
+export async function collectOrpWorkspace({
+  repoRoot,
+  orpCommand = "orp",
+  includeAbout = true,
+  commandRunner,
+} = {}) {
+  if (!repoRoot) {
+    throw new Error("collectOrpWorkspace requires a repoRoot.");
+  }
+
+  const runner =
+    commandRunner ??
+    ((input) =>
+      runOrpJson({
+        repoRoot: input.repoRoot,
+        args: input.args,
+        orpCommand,
+      }));
+
+  const status = await runner({
+    repoRoot,
+    args: ["status"],
+  });
+
+  const frontierState = await tryCommand(runner, {
+    repoRoot,
+    args: ["frontier", "state"],
+  });
+  const frontierRoadmap = await tryCommand(runner, {
+    repoRoot,
+    args: ["frontier", "roadmap"],
+  });
+  const frontierChecklist = await tryCommand(runner, {
+    repoRoot,
+    args: ["frontier", "checklist"],
+  });
+  const about = includeAbout
+    ? await tryCommand(runner, {
+        repoRoot,
+        args: ["about"],
+      })
+    : null;
+
+  return {
+    repoRoot,
+    status,
+    frontierState,
+    frontierRoadmap,
+    frontierChecklist,
+    about,
+    collectedAt: new Date().toISOString(),
+  };
+}

package/packages/lifeops-orp/test/orp.test.js

@@ -0,0 +1,187 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  buildOrpProjectSharePacket,
+  collectOrpWorkspace,
+  createOrpConnector,
+  createOrpProjectShareInput,
+  mapOrpWorkspaceToItems,
+} from "../src/index.js";
+
+function createWorkspace() {
+  return {
+    repoRoot: "/tmp/demo-repo",
+    collectedAt: "2026-03-26T00:00:00.000Z",
+    status: {
+      next_actions: [
+        "orp checkpoint create -m \"capture passing validation\" --json",
+        "orp ready --json",
+      ],
+      readiness: {
+        scope: "local_only",
+        local_ready: true,
+        remote_ready: false,
+      },
+      runtime: {
+        latest_run: {
+          overall: "PASS",
+        },
+        last_ready: {
+          run_id: "run-123",
+        },
+      },
+      validation: {
+        checkpoint_after_validation: true,
+      },
+    },
+    frontierState: {
+      program_id: "lifeops",
+      label: "Life Ops",
+      active_version: "v1",
+      active_milestone: "v1.2",
+      active_phase: "395",
+      next_action: "execute phase 395",
+    },
+    frontierRoadmap: {
+      active_milestone: "v1.2",
+    },
+    frontierChecklist: {
+      exact: [
+        {
+          version_id: "v1",
+          milestone_id: "v1.2",
+          phase_id: "395",
+          label: "Execute phase 395",
+        },
+      ],
+    },
+    about: {
+      tool: {
+        name: "orp",
+      },
+    },
+  };
+}
+
+test("collectOrpWorkspace gathers core ORP json surfaces", async () => {
+  const calls = [];
+  const workspace = await collectOrpWorkspace({
+    repoRoot: "/tmp/demo-repo",
+    commandRunner: async ({ args }) => {
+      calls.push(args.join(" "));
+      const [first, second] = args;
+      if (first === "status") {
+        return createWorkspace().status;
+      }
+      if (first === "frontier" && second === "state") {
+        return createWorkspace().frontierState;
+      }
+      if (first === "frontier" && second === "roadmap") {
+        return createWorkspace().frontierRoadmap;
+      }
+      if (first === "frontier" && second === "checklist") {
+        return createWorkspace().frontierChecklist;
+      }
+      if (first === "about") {
+        return createWorkspace().about;
+      }
+      throw new Error(`unexpected args: ${args.join(" ")}`);
+    },
+  });
+
+  assert.equal(calls[0], "status");
+  assert.equal(workspace.frontierState.active_milestone, "v1.2");
+  assert.equal(workspace.about.tool.name, "orp");
+});
+
+test("mapOrpWorkspaceToItems creates readiness, frontier, and checklist items", () => {
+  const items = mapOrpWorkspaceToItems({
+    workspace: createWorkspace(),
+    projectName: "Life Ops Research",
+    organization: "ORP",
+  });
+
+  assert.ok(items.some((item) => item.title === "Life Ops Research is ready to share"));
+  assert.ok(items.some((item) => item.title.includes("ORP frontier: execute phase 395")));
+  assert.ok(items.some((item) => item.title.includes("ORP checklist: Execute phase 395")));
+});
+
+test("createOrpProjectShareInput derives share context from ORP workspace", () => {
+  const shareInput = createOrpProjectShareInput({
+    workspace: createWorkspace(),
+    projectName: "Life Ops Research",
+    repoUrl: "https://github.com/example/repo",
+  });
+
+  assert.equal(shareInput.name, "Life Ops Research");
+  assert.match(shareInput.whyNow, /ready/i);
+  assert.ok(shareInput.highlights.some((line) => line.includes("execute phase 395")));
+  assert.ok(shareInput.proofPoints.some((line) => line.includes("PASS")));
+});
+
+test("buildOrpProjectSharePacket delegates to injected Life Ops share builder", async () => {
+  let captured = null;
+  const result = await buildOrpProjectSharePacket({
+    repoRoot: "/tmp/demo-repo",
+    projectName: "Life Ops Research",
+    recipients: [{ email: "alicia@example.com" }],
+    buildProjectSharePacket(input) {
+      captured = input;
+      return { ok: true, input };
+    },
+    orpCommand: "orp",
+    includeAbout: false,
+    commandRunner: async ({ args }) => {
+      const [first, second] = args;
+      if (first === "status") {
+        return createWorkspace().status;
+      }
+      if (first === "frontier" && second === "state") {
+        return createWorkspace().frontierState;
+      }
+      if (first === "frontier" && second === "roadmap") {
+        return createWorkspace().frontierRoadmap;
+      }
+      if (first === "frontier" && second === "checklist") {
+        return createWorkspace().frontierChecklist;
+      }
+      throw new Error(`unexpected args: ${args.join(" ")}`);
+    },
+    extraHighlights: ["Agent-first workflow"],
+    extraCodebases: ["@lifeops/core"],
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(captured.project.name, "Life Ops Research");
+  assert.ok(captured.project.codebases.includes("@lifeops/core"));
+});
+
+test("createOrpConnector exposes a Life Ops-compatible pull contract", async () => {
+  const connector = createOrpConnector({
+    repoRoot: "/tmp/demo-repo",
+    projectName: "Life Ops Research",
+    includeAbout: false,
+    commandRunner: async ({ args }) => {
+      const [first, second] = args;
+      if (first === "status") {
+        return createWorkspace().status;
+      }
+      if (first === "frontier" && second === "state") {
+        return createWorkspace().frontierState;
+      }
+      if (first === "frontier" && second === "roadmap") {
+        return createWorkspace().frontierRoadmap;
+      }
+      if (first === "frontier" && second === "checklist") {
+        return createWorkspace().frontierChecklist;
+      }
+      throw new Error(`unexpected args: ${args.join(" ")}`);
+    },
+  });
+
+  const payload = await connector.pull();
+  assert.ok(Array.isArray(payload.items));
+  assert.ok(payload.items.length >= 3);
+  assert.equal(payload.meta.workspace.repoRoot, "/tmp/demo-repo");
+});