npm - symphifo - Versions diffs - 0.1.0 - Mend

symphifo 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (28) hide show

package/LICENSE +201 -0
package/NOTICE +13 -0
package/README.md +394 -0
package/SYMPHIFO.md +171 -0
package/WORKFLOW.md +39 -0
package/bin/symphifo.js +37 -0
package/package.json +46 -0
package/src/cli.ts +213 -0
package/src/dashboard/app.js +1390 -0
package/src/dashboard/index.html +139 -0
package/src/dashboard/styles.css +1528 -0
package/src/fixtures/local-issues.json +13 -0
package/src/integrations/catalog.ts +151 -0
package/src/mcp/server.ts +1237 -0
package/src/routing/capability-resolver.ts +390 -0
package/src/runtime/agent.ts +1050 -0
package/src/runtime/api-server.ts +306 -0
package/src/runtime/constants.ts +102 -0
package/src/runtime/helpers.ts +134 -0
package/src/runtime/issues.ts +456 -0
package/src/runtime/logger.ts +59 -0
package/src/runtime/providers.ts +310 -0
package/src/runtime/run-local.ts +146 -0
package/src/runtime/scheduler.ts +214 -0
package/src/runtime/skills.ts +55 -0
package/src/runtime/store.ts +313 -0
package/src/runtime/types.ts +274 -0
package/src/runtime/workflow.ts +185 -0

package/src/runtime/api-server.ts ADDED Viewed

@@ -0,0 +1,306 @@
+import type {
+  IssueEntry,
+  JsonRecord,
+  RuntimeEvent,
+  RuntimeState,
+  WorkflowDefinition,
+} from "./types.ts";
+import {
+  FRONTEND_INDEX,
+  FRONTEND_APP_JS,
+  FRONTEND_STYLES_CSS,
+  S3DB_RUNTIME_RESOURCE,
+  S3DB_ISSUE_RESOURCE,
+  S3DB_EVENT_RESOURCE,
+  S3DB_AGENT_SESSION_RESOURCE,
+  S3DB_AGENT_PIPELINE_RESOURCE,
+  TERMINAL_STATES,
+  ALLOWED_STATES,
+} from "./constants.ts";
+import { now, toStringValue, normalizeState, readTextOrNull, clamp } from "./helpers.ts";
+import { logger } from "./logger.ts";
+import {
+  loadS3dbModule,
+  getStateDb,
+  getIssueStateResource,
+  getEventStateResource,
+  setActiveApiPlugin,
+  persistState,
+} from "./store.ts";
+import {
+  addEvent,
+  createIssueFromPayload,
+  computeCapabilityCounts,
+  handleStatePatch,
+  transition,
+} from "./issues.ts";
+import {
+  getEffectiveAgentProviders,
+  detectAvailableProviders,
+} from "./providers.ts";
+import {
+  loadAgentPipelineSnapshotForIssue,
+  loadAgentSessionSnapshotsForIssue,
+} from "./agent.ts";
+import { analyzeParallelizability } from "./scheduler.ts";
+export async function startApiServer(
+  state: RuntimeState,
+  port: number,
+  workflowDefinition: WorkflowDefinition | null,
+): Promise<void> {
+  const stateDb = getStateDb();
+  if (!stateDb) {
+    throw new Error("Cannot start API plugin before the database is initialized.");
+  }
+  const { ApiPlugin } = await loadS3dbModule();
+  const indexHtml = readTextOrNull(FRONTEND_INDEX) ?? "";
+  const appJs = readTextOrNull(FRONTEND_APP_JS) ?? "";
+  const stylesCss = readTextOrNull(FRONTEND_STYLES_CSS) ?? "";
+  const fallback = `<!doctype html><html><body><pre>Unable to load Symphifo dashboard assets.</pre></body></html>`;
+  const findIssue = (issueId: string) =>
+    state.issues.find((c) => c.id === issueId || c.identifier === issueId);
+  const issueResource = getIssueStateResource();
+  const eventResource = getEventStateResource();
+  const listIssues = async (filters: { state?: string; capabilityCategory?: string } = {}): Promise<IssueEntry[]> => {
+    const { state: issueState, capabilityCategory } = filters;
+    if (issueResource?.list) {
+      const partition = issueState && capabilityCategory
+        ? "byStateAndCapability"
+        : issueState ? "byState"
+        : capabilityCategory ? "byCapabilityCategory"
+        : null;
+      const partitionValues = issueState && capabilityCategory
+        ? { state: issueState, capabilityCategory }
+        : issueState ? { state: issueState }
+        : capabilityCategory ? { capabilityCategory }
+        : {};
+      const records = await issueResource.list({ partition, partitionValues, limit: 500 });
+      return records.map((record) => record as IssueEntry);
+    }
+    return state.issues.filter((issue) => {
+      if (issueState && issue.state !== issueState) return false;
+      if (capabilityCategory && issue.capabilityCategory !== capabilityCategory) return false;
+      return true;
+    });
+  };
+  const listEvents = async (filters: { issueId?: string; kind?: string; since?: string } = {}): Promise<RuntimeEvent[]> => {
+    const { issueId, kind, since } = filters;
+    let events: RuntimeEvent[];
+    if (eventResource?.list) {
+      const partition = issueId && kind ? "byIssueIdAndKind"
+        : issueId ? "byIssueId"
+        : kind ? "byKind"
+        : null;
+      const partitionValues = issueId && kind ? { issueId, kind }
+        : issueId ? { issueId }
+        : kind ? { kind }
+        : {};
+      events = (await eventResource.list({ partition, partitionValues, limit: 200 }))
+        .map((record) => record as RuntimeEvent);
+    } else {
+      events = state.events.filter((event) => {
+        if (issueId && event.issueId !== issueId) return false;
+        if (kind && event.kind !== kind) return false;
+        return true;
+      });
+    }
+    return typeof since === "string" && since
+      ? events.filter((entry) => entry.at > since)
+      : events;
+  };
+  const apiPlugin = new ApiPlugin({
+    port,
+    host: "0.0.0.0",
+    versionPrefix: false,
+    docs: { enabled: true, title: "Symphifo API", version: "1.0.0", description: "Local orchestration API for Symphifo" },
+    cors: { enabled: true, origin: "*" },
+    logging: { enabled: true, excludePaths: ["/health", "/api/health"] },
+    compression: { enabled: true, threshold: 1024 },
+    health: { enabled: true },
+    resources: {
+      [S3DB_RUNTIME_RESOURCE]: { auth: false, methods: ["GET", "HEAD", "OPTIONS"] },
+      [S3DB_ISSUE_RESOURCE]: { auth: false, methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"] },
+      [S3DB_EVENT_RESOURCE]: { auth: false, methods: ["GET", "HEAD", "OPTIONS"] },
+      [S3DB_AGENT_SESSION_RESOURCE]: { auth: false, methods: ["GET", "HEAD", "OPTIONS"] },
+      [S3DB_AGENT_PIPELINE_RESOURCE]: { auth: false, methods: ["GET", "HEAD", "OPTIONS"] },
+    },
+    routes: {
+      "GET /api/state": async () => ({
+        ...state,
+        capabilities: computeCapabilityCounts(state.issues),
+      }),
+      "GET /api/health": async () => ({
+        status: "ok",
+        updatedAt: state.updatedAt,
+        config: state.config,
+        trackerKind: state.trackerKind,
+      }),
+      "GET /api/providers": async () => {
+        const providers = detectAvailableProviders();
+        return { providers };
+      },
+      "GET /api/parallelism": async () => {
+        return analyzeParallelizability(state.issues);
+      },
+      "GET /api/issues": async (c: any) => {
+        const issueState = c.req.query("state");
+        const capabilityCategory = c.req.query("capabilityCategory") ?? c.req.query("category");
+        const issues = await listIssues({
+          state: typeof issueState === "string" && issueState ? issueState : undefined,
+          capabilityCategory: typeof capabilityCategory === "string" && capabilityCategory ? capabilityCategory : undefined,
+        });
+        return { issues };
+      },
+      "POST /api/issues": async (c: any) => {
+        const payload = await c.req.json() as JsonRecord;
+        const issue = createIssueFromPayload(payload, state.issues, workflowDefinition);
+        const duplicate = state.issues.find((candidate) => candidate.id === issue.id || candidate.identifier === issue.identifier);
+        if (duplicate) {
+          return c.json({ ok: false, error: "Issue id or identifier already exists", issue: duplicate }, 409);
+        }
+        state.issues.push(issue);
+        state.updatedAt = now();
+        addEvent(state, issue.id, "manual", `Issue ${issue.identifier} created via API.`);
+        await persistState(state);
+        return c.json({ ok: true, issue }, 201);
+      },
+      "PUT /api/issues/:id": async (c: any) => {
+        const issue = findIssue(c.req.param("id"));
+        if (!issue) return c.json({ ok: false, error: "Issue not found" }, 404);
+        const payload = await c.req.json() as JsonRecord;
+        if (typeof payload.title === "string") issue.title = payload.title;
+        if (typeof payload.description === "string") issue.description = payload.description;
+        if (typeof payload.priority === "number") issue.priority = clamp(payload.priority, 1, 10);
+        if (Array.isArray(payload.labels)) issue.labels = payload.labels.filter((l: unknown): l is string => typeof l === "string");
+        if (Array.isArray(payload.paths)) issue.paths = payload.paths.filter((p: unknown): p is string => typeof p === "string");
+        if (Array.isArray(payload.blockedBy)) issue.blockedBy = payload.blockedBy.filter((b: unknown): b is string => typeof b === "string");
+        issue.updatedAt = now();
+        addEvent(state, issue.id, "manual", `Issue ${issue.identifier} updated via API.`);
+        await persistState(state);
+        return { ok: true, issue };
+      },
+      "DELETE /api/issues/:id": async (c: any) => {
+        const issueId = c.req.param("id");
+        const index = state.issues.findIndex((i) => i.id === issueId || i.identifier === issueId);
+        if (index === -1) return c.json({ ok: false, error: "Issue not found" }, 404);
+        const removed = state.issues.splice(index, 1)[0];
+        state.updatedAt = now();
+        addEvent(state, removed.id, "manual", `Issue ${removed.identifier} deleted via API.`);
+        await persistState(state);
+        return { ok: true, deleted: removed.identifier };
+      },
+      "POST /api/config/concurrency": async (c: any) => {
+        const payload = await c.req.json() as JsonRecord;
+        const value = typeof payload.concurrency === "number" ? payload.concurrency : undefined;
+        if (!value || value < 1 || value > 16) {
+          return c.json({ ok: false, error: "concurrency must be between 1 and 16" }, 400);
+        }
+        state.config.workerConcurrency = clamp(Math.round(value), 1, 16);
+        state.updatedAt = now();
+        addEvent(state, undefined, "manual", `Worker concurrency updated to ${state.config.workerConcurrency}.`);
+        await persistState(state);
+        return { ok: true, workerConcurrency: state.config.workerConcurrency };
+      },
+      "GET /api/events": async (c: any) => {
+        const since = c.req.query("since");
+        const issueId = c.req.query("issueId");
+        const kind = c.req.query("kind");
+        const events = await listEvents({
+          since: typeof since === "string" ? since : undefined,
+          issueId: typeof issueId === "string" && issueId ? issueId : undefined,
+          kind: typeof kind === "string" && kind ? kind : undefined,
+        });
+        return { events: events.slice(0, 200) };
+      },
+      "GET /api/issue/:id/pipeline": async (c: any) => {
+        const issue = findIssue(c.req.param("id"));
+        if (!issue) return c.json({ ok: false, error: "Issue not found" }, 404);
+        const providers = getEffectiveAgentProviders(state, issue, workflowDefinition);
+        const pipeline = await loadAgentPipelineSnapshotForIssue(issue, providers);
+        return { ok: true, issueId: issue.id, pipeline };
+      },
+      "GET /api/issue/:id/sessions": async (c: any) => {
+        const issue = findIssue(c.req.param("id"));
+        if (!issue) return c.json({ ok: false, error: "Issue not found" }, 404);
+        const providers = getEffectiveAgentProviders(state, issue, workflowDefinition);
+        const pipeline = await loadAgentPipelineSnapshotForIssue(issue, providers);
+        const sessions = await loadAgentSessionSnapshotsForIssue(issue, providers, pipeline, workflowDefinition);
+        return { ok: true, issueId: issue.id, pipeline, sessions };
+      },
+      "POST /api/issue/:id/state": async (c: any) => {
+        const issue = findIssue(c.req.param("id"));
+        if (!issue) return c.json({ ok: false, error: "Issue not found" }, 404);
+        const payload = await c.req.json() as JsonRecord;
+        try {
+          handleStatePatch(state, issue, payload);
+          await persistState(state);
+          return { ok: true, issue };
+        } catch (error) {
+          return c.json({ ok: false, error: String(error) }, 400);
+        }
+      },
+      "POST /api/issue/:id/retry": async (c: any) => {
+        const issue = findIssue(c.req.param("id"));
+        if (!issue) return c.json({ ok: false, error: "Issue not found" }, 404);
+        if (TERMINAL_STATES.has(issue.state)) {
+          issue.state = "Todo";
+          issue.attempts = Math.max(0, issue.attempts - 1);
+          issue.lastError = undefined;
+          issue.nextRetryAt = undefined;
+          transition(issue, "Todo", "Manual retry requested.");
+        } else {
+          issue.nextRetryAt = undefined;
+          issue.lastError = undefined;
+        }
+        addEvent(state, issue.id, "manual", `Manual retry requested for ${issue.id}.`);
+        await persistState(state);
+        return { ok: true, issue };
+      },
+      "POST /api/issue/:id/cancel": async (c: any) => {
+        const issue = findIssue(c.req.param("id"));
+        if (!issue) return c.json({ ok: false, error: "Issue not found" }, 404);
+        transition(issue, "Cancelled", "Manual cancel requested.");
+        addEvent(state, issue.id, "manual", `Manual cancel requested for ${issue.id}.`);
+        await persistState(state);
+        return { ok: true, issue };
+      },
+      "GET /state": async (c: any) => c.redirect("/api/state"),
+      "GET /": async (c: any) => c.html(indexHtml || fallback),
+      "GET /index.html": async (c: any) => c.html(indexHtml || fallback),
+      "GET /assets/app.js": async (c: any) => c.body(appJs || "console.log('Dashboard script not found.');", 200, {
+        "content-type": "application/javascript; charset=utf-8",
+      }),
+      "GET /assets/styles.css": async (c: any) => c.body(stylesCss || "", 200, {
+        "content-type": "text/css; charset=utf-8",
+      }),
+    },
+  });
+  const plugin = await stateDb.usePlugin(apiPlugin, "api") as { stop?: () => Promise<void> };
+  setActiveApiPlugin(plugin);
+  logger.info(`Local dashboard available at http://localhost:${port}`);
+  logger.info(`State API: http://localhost:${port}/api/state`);
+  logger.info(`OpenAPI docs available at http://localhost:${port}/docs`);
+}

package/src/runtime/constants.ts ADDED Viewed

@@ -0,0 +1,102 @@
+import { existsSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { env, argv, cwd as getCwd } from "node:process";
+import { homedir } from "node:os";
+import type { IssueState } from "./types.ts";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export const PACKAGE_ROOT = resolve(__dirname, "../..");
+export const CLI_ARGS = argv.slice(2);
+export function readArgValue(args: string[], flag: string): string | undefined {
+  const index = args.indexOf(flag);
+  if (index === -1) return undefined;
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) return undefined;
+  return value;
+}
+export function resolveInputPath(value: string): string {
+  if (value.startsWith("~/")) {
+    return resolve(homedir(), value.slice(2));
+  }
+  return resolve(value);
+}
+export function resolvePersistenceRoot(value: string): string {
+  const resolved = value.startsWith("file://")
+    ? fileURLToPath(value)
+    : resolveInputPath(value);
+  return basename(resolved) === ".symphifo"
+    ? resolved
+    : join(resolved, ".symphifo");
+}
+const CLI_WORKSPACE_ROOT = readArgValue(CLI_ARGS, "--workspace");
+const CLI_PERSISTENCE = readArgValue(CLI_ARGS, "--persistence");
+export const TARGET_ROOT = resolveInputPath(
+  env.SYMPHIFO_WORKSPACE_ROOT ?? CLI_WORKSPACE_ROOT ?? getCwd(),
+);
+export const TRACKER_KIND = env.SYMPHIFO_TRACKER_KIND ?? "filesystem";
+export const STATE_ROOT = resolvePersistenceRoot(
+  env.SYMPHIFO_PERSISTENCE
+    ?? CLI_PERSISTENCE
+    ?? env.SYMPHIFO_BOOTSTRAP_ROOT
+    ?? TARGET_ROOT,
+);
+export const SOURCE_ROOT = `${STATE_ROOT}/source`;
+export const WORKSPACE_ROOT = `${STATE_ROOT}/workspaces`;
+export const SOURCE_MARKER = `${SOURCE_ROOT}/.symphifo-local-source-ready`;
+export const WORKFLOW_TEMPLATE = existsSync(join(TARGET_ROOT, "WORKFLOW.md"))
+  ? join(TARGET_ROOT, "WORKFLOW.md")
+  : existsSync(join(PACKAGE_ROOT, "WORKFLOW.md"))
+    ? join(PACKAGE_ROOT, "WORKFLOW.md")
+    : "";
+export const WORKFLOW_RENDERED = `${STATE_ROOT}/WORKFLOW.local.md`;
+export const S3DB_DATABASE_PATH = `${STATE_ROOT}/s3db`;
+export const S3DB_BUCKET = env.SYMPHIFO_STORAGE_BUCKET ?? "symphifo";
+export const S3DB_KEY_PREFIX = env.SYMPHIFO_STORAGE_KEY_PREFIX ?? "state";
+export const S3DB_RUNTIME_RESOURCE = "symphifo_runtime_state";
+export const S3DB_ISSUE_RESOURCE = "symphifo_issues";
+export const S3DB_EVENT_RESOURCE = "symphifo_events";
+export const S3DB_AGENT_SESSION_RESOURCE = "symphifo_agent_sessions";
+export const S3DB_AGENT_PIPELINE_RESOURCE = "symphifo_agent_pipelines";
+export const S3DB_RUNTIME_RECORD_ID = "current";
+export const S3DB_RUNTIME_SCHEMA_VERSION = 1;
+export const DEFAULT_ISSUES_TEMPLATE = `${PACKAGE_ROOT}/src/fixtures/local-issues.json`;
+export const LOCAL_ISSUES_FILE = resolveInputPath(
+  env.SYMPHIFO_ISSUES_FILE ?? join(STATE_ROOT, "issues.json"),
+);
+export const FRONTEND_DIR = `${PACKAGE_ROOT}/src/dashboard`;
+export const FRONTEND_INDEX = `${FRONTEND_DIR}/index.html`;
+export const FRONTEND_APP_JS = `${FRONTEND_DIR}/app.js`;
+export const FRONTEND_STYLES_CSS = `${FRONTEND_DIR}/styles.css`;
+export const DEBUG_BOOT = env.SYMPHIFO_DEBUG_BOOT === "1";
+export const ALLOWED_STATES: IssueState[] = [
+  "Todo",
+  "In Progress",
+  "In Review",
+  "Blocked",
+  "Done",
+  "Cancelled",
+];
+export const TERMINAL_STATES = new Set<IssueState>(["Done", "Cancelled"]);
+export const EXECUTING_STATES = new Set<IssueState>(["In Progress", "In Review"]);
+export const PERSIST_EVENTS_MAX = 500;

package/src/runtime/helpers.ts ADDED Viewed

@@ -0,0 +1,134 @@
+import { appendFileSync, readFileSync } from "node:fs";
+import { env } from "node:process";
+import { parse as parseYaml } from "yaml";
+import type { IssueState, JsonRecord } from "./types.ts";
+import { ALLOWED_STATES, DEBUG_BOOT } from "./constants.ts";
+export function now(): string {
+  return new Date().toISOString();
+}
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function toStringValue(value: unknown, fallback = ""): string {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
+}
+export function toNumberValue(value: unknown, fallback = 1): number {
+  const parsed =
+    typeof value === "number"
+      ? value
+      : typeof value === "string"
+        ? Number.parseInt(value, 10)
+        : Number.NaN;
+  return Number.isFinite(parsed) && parsed > 0 ? Math.round(parsed) : fallback;
+}
+export function toBooleanValue(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+export function toStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)
+    .map((entry) => entry.trim());
+}
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+export function normalizeState(value: unknown): IssueState {
+  const raw = typeof value === "string" ? value.trim() : "";
+  if ((ALLOWED_STATES as readonly string[]).includes(raw)) {
+    return raw as IssueState;
+  }
+  return "Todo";
+}
+export function parseEnvNumber(name: string, fallback: number): number {
+  return toNumberValue(env[name], fallback);
+}
+export function parseIntArg(value: string, fallback: number): number {
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+export function parsePositiveIntEnv(name: string, fallback: number): number {
+  const source = env[name];
+  if (!source) return fallback;
+  return parseIntArg(source, fallback);
+}
+export function withRetryBackoff(attempt: number, baseDelayMs: number): number {
+  return Math.min(baseDelayMs * 2 ** attempt, 5 * 60 * 1000);
+}
+export function idToSafePath(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9._-]/g, "-");
+}
+export function appendFileTail(target: string, text: string, maxLength: number): string {
+  const merged = `${target}\n${text}`;
+  if (merged.length <= maxLength) return merged;
+  return `…${merged.slice(-(maxLength - 1))}`;
+}
+export function readTextOrNull(path: string): string | null {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+export function parseFrontMatter(source: string): { config: JsonRecord; body: string } {
+  const match = source.match(/^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/);
+  if (!match) {
+    return { config: {}, body: source.trim() };
+  }
+  const rawConfig = parseYaml(match[1]) as unknown;
+  const config = rawConfig && typeof rawConfig === "object" && !Array.isArray(rawConfig)
+    ? rawConfig as JsonRecord
+    : {};
+  return { config, body: match[2].trim() };
+}
+export function getNestedRecord(source: unknown, key: string): JsonRecord {
+  if (!source || typeof source !== "object" || Array.isArray(source)) return {};
+  const value = (source as JsonRecord)[key];
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as JsonRecord
+    : {};
+}
+export function getNestedString(source: unknown, key: string, fallback = ""): string {
+  if (!source || typeof source !== "object" || Array.isArray(source)) return fallback;
+  return toStringValue((source as JsonRecord)[key], fallback);
+}
+export function getNestedNumber(source: unknown, key: string, fallback: number): number {
+  if (!source || typeof source !== "object" || Array.isArray(source)) return fallback;
+  return toNumberValue((source as JsonRecord)[key], fallback);
+}
+export function appendLog(logPath: string, entry: string): void {
+  appendFileSync(logPath, `${now()} [symphifo-local-ts] ${entry}\n`, "utf8");
+}
+export function debugBoot(message: string): void {
+  if (!DEBUG_BOOT) return;
+  console.error(`[SYMPHIFO_DEBUG_BOOT] ${message}`);
+}
+export function fail(message: string): never {
+  console.error(message);
+  process.exit(1);
+}