syndai 0.1.1 → 0.4.0

package/src/openapi.js

@@ -0,0 +1,145 @@
+// The live API description behind `syndai api <operationId>`. The server's public
+// `/openapi.json` is the one source, so a new route is callable the day it deploys. It is
+// cached per host for 24 hours ($XDG_CACHE_HOME/syndai/openapi-<host>.json) and fetched again
+// once when an operationId is not in the cached copy. The server sends no ETag, and a ~27 KB
+// gzipped fetch a day does not justify one.
+
+import path from "node:path";
+import { CliError, EXIT } from "./errors.js";
+import { readJson, writeFileAtomic } from "./store.js";
+import { hostOf } from "./ui.js";
+
+const TTL_MS = 24 * 60 * 60 * 1000;
+export const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+const EXT_PREFIX = /^\/api\/v1\/(external\/coding\/)?/;
+
+function cacheFile(ctx) {
+  const host = (hostOf(ctx.baseUrl) ?? "api").replace(/[^\w.-]/g, "_");
+  return path.join(ctx.paths.cache, `openapi-${host}.json`);
+}
+
+/** The operations, from the cache when it is fresh (or `refresh` is false and it exists). */
+export async function loadOperations(ctx, { refresh = false } = {}) {
+  const file = cacheFile(ctx);
+  let cached = null;
+  try {
+    cached = readJson(file, null);
+  } catch {
+    // A corrupt cache is refetched, never an error.
+  }
+  if (!refresh && cached?.spec && ctx.io.now() - cached.fetched_at < TTL_MS) {
+    return { operations: index(cached.spec), fresh: false };
+  }
+  const spec = await ctx.client.send("GET", "/openapi.json", { auth: false });
+  writeFileAtomic(file, JSON.stringify({ fetched_at: ctx.io.now(), spec }), 0o644);
+  return { operations: index(spec), fresh: true };
+}
+
+/** One operation by id (exact, or ignoring case, `-` and `_`); refetches once when unknown. */
+export async function findOperation(ctx, id) {
+  let { operations, fresh } = await loadOperations(ctx);
+  let op = lookup(operations, id);
+  if (!op && !fresh) {
+    ({ operations } = await loadOperations(ctx, { refresh: true }));
+    op = lookup(operations, id);
+  }
+  if (op) return op;
+  const near = closest(operations, id);
+  throw new CliError(EXIT.USAGE, `No API operation is called "${id}".`, {
+    next: near.length ? `did you mean: ${near.join(", ")}? (syndai api lists them all)` : "syndai api",
+  });
+}
+
+/** The operation a concrete METHOD + path calls, or null. */
+export function matchPath(operations, method, concretePath) {
+  return (
+    operations.find(
+      (op) =>
+        op.method === method &&
+        new RegExp(`^${op.path.replace(/[.*+?^$()|[\]\\]/g, "\\$&").replace(/\\?\{[^}]+\\?\}/g, "[^/]+")}$`).test(
+          concretePath,
+        ),
+    ) ?? null
+  );
+}
+
+const norm = (name) => name.toLowerCase().replace(/[-_]/g, "");
+
+function lookup(operations, id) {
+  return operations.find((op) => op.id === id) ?? operations.find((op) => norm(op.id) === norm(id)) ?? null;
+}
+
+function closest(operations, id, count = 3) {
+  const wanted = norm(id);
+  return operations
+    .map((op) => [distance(norm(op.id), wanted), op.id])
+    .sort((a, b) => a[0] - b[0] || a[1].localeCompare(b[1]))
+    .slice(0, count)
+    .map(([, name]) => name);
+}
+
+function distance(a, b) {
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i];
+    for (let j = 1; j <= b.length; j++) {
+      row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    prev = row;
+  }
+  return prev[b.length];
+}
+
+/** Flatten an OpenAPI document to `[{id, method, path, group, summary, params, body}]`. */
+export function index(spec) {
+  const resolve = (schema) => {
+    const ref = schema?.$ref;
+    return ref ? (spec.components?.schemas?.[ref.split("/").pop()] ?? {}) : (schema ?? {});
+  };
+  const operations = [];
+  for (const [opPath, item] of Object.entries(spec.paths ?? {})) {
+    for (const method of HTTP_METHODS) {
+      const op = item[method.toLowerCase()];
+      if (!op?.operationId) continue;
+      const params = [...(item.parameters ?? []), ...(op.parameters ?? [])].map((p) => ({
+        name: p.name,
+        in: p.in,
+        required: Boolean(p.required),
+      }));
+      const schemaRef = op.requestBody?.content?.["application/json"]?.schema;
+      const schema = resolve(schemaRef);
+      const required = new Set(schema.required ?? []);
+      const body = schemaRef
+        ? {
+            schema: schemaRef.$ref?.split("/").pop() ?? null,
+            fields: Object.entries(schema.properties ?? {}).map(([name, prop]) => ({
+              name,
+              type: typeName(prop),
+              required: required.has(name),
+            })),
+          }
+        : null;
+      operations.push({
+        id: op.operationId,
+        method,
+        path: opPath,
+        group: opPath.replace(EXT_PREFIX, "").split("/")[0] || "other",
+        summary: op.summary ?? "",
+        params,
+        body,
+      });
+    }
+  }
+  return operations;
+}
+
+function typeName(schema) {
+  const options = schema.oneOf ?? schema.anyOf;
+  if (options) return options.map((o) => o.type ?? o.$ref?.split("/").pop() ?? "object").join(" | ");
+  return schema.type ?? schema.$ref?.split("/").pop() ?? "object";
+}
+
+/** `/api/v1/external/coding/runs` -> `/runs`, for compact listings. */
+export function shortPath(opPath) {
+  return opPath.startsWith("/api/v1/external/coding/") ? opPath.slice("/api/v1/external/coding".length) : opPath;
+}

package/src/projects.js

@@ -0,0 +1,168 @@
+// Which project a command acts on. Order (docs: syndai.ai/docs/cli, "Choosing the project"):
+// --app, SYNDAI_APP, the link for this directory or a parent, a git remote that matches a
+// connected repo, the only project, a picker on a terminal. Otherwise exit 2 with the list.
+//
+// A project is a connected repository, joined with its app (live URL, slug) when it has one.
+
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { CliError, EXIT } from "./errors.js";
+import { findLink, saveLink } from "./store.js";
+import { ask, hostOf } from "./ui.js";
+
+export async function listProjects(ctx) {
+  const customerId = await ctx.customerId();
+  const [{ repos }, { items }] = await Promise.all([
+    ctx.client.call("listRepos"),
+    ctx.client.call("listApps", { params: { customer_id: customerId } }),
+  ]);
+  const appByRepo = new Map(items.map((app) => [app.repository_id, app]));
+  return repos.map((repo) => {
+    const app = appByRepo.get(repo.id);
+    return {
+      id: repo.id,
+      name: repo.display_name || app?.repository_name || repo.full_name,
+      full_name: repo.full_name,
+      live_url: app?.url ?? null,
+      slug: app?.publication?.slug ?? null,
+      repo_urls: [repo.repo_url, repo.clone_url, repo.html_url].filter(Boolean),
+      protected_paths: repo.protected_paths ?? [],
+      customer_id: customerId,
+    };
+  });
+}
+
+export function projectLabel(project) {
+  const host = project.live_url ? hostOf(project.live_url) : null;
+  return host && host !== project.name ? `${project.name} (${host})` : project.name;
+}
+
+/** The project's live host for "Changing <host>", or its name before it is live. */
+export function projectHost(project) {
+  return (project.live_url && hostOf(project.live_url)) || project.name;
+}
+
+/** Projects matching a ref: id, slug, live host, name or repo name (case-insensitive). */
+export function matchRef(projects, ref) {
+  const wanted = ref.trim().toLowerCase();
+  const wantedHost = hostOf(wanted.includes("://") ? wanted : `https://${wanted}`);
+  return projects.filter((p) => {
+    const names = [p.id, p.slug, p.name, p.full_name, p.full_name.split("/").pop()];
+    if (names.some((n) => n?.toLowerCase() === wanted)) return true;
+    return Boolean(p.live_url && wantedHost && hostOf(p.live_url)?.toLowerCase() === wantedHost);
+  });
+}
+
+/**
+ * @param {object} ctx
+ * @param {{app?: string, required?: boolean, picker?: boolean, useLink?: boolean}} options
+ */
+export async function resolveProject(ctx, { app, required = true, picker = true, useLink = true } = {}) {
+  const { io, ui, paths } = ctx;
+  const projects = await listProjects(ctx);
+  const pick = (ref, source) => {
+    const hits = matchRef(projects, ref);
+    if (hits.length === 1) return hits[0];
+    throw noProject(
+      projects,
+      hits.length
+        ? `"${ref}" (${source}) matches ${hits.length} projects; use the id.`
+        : `No project matches "${ref}" (${source}).`,
+    );
+  };
+  if (app) return pick(app, "--app");
+  if (io.env.SYNDAI_APP) return pick(io.env.SYNDAI_APP, "SYNDAI_APP");
+  if (useLink) {
+    const link = findLink(paths, io.cwd);
+    if (link) {
+      const linked = projects.find((p) => p.id === link.project_id);
+      if (linked) return linked;
+      throw noProject(projects, `The project linked to ${link.dir} is no longer in this workspace.`);
+    }
+  }
+  const remotes = gitRemotes(io.cwd);
+  const byRemote = projects.filter((p) => p.repo_urls.some((u) => remotes.has(normalizeRemote(u))));
+  if (byRemote.length === 1) return byRemote[0];
+  if (projects.length === 1) return projects[0];
+  if (picker && ui.interactive && projects.length > 1) return pickInteractively(ctx, projects);
+  if (!required) return null;
+  throw noProject(
+    projects,
+    projects.length
+      ? "Which project? Pass --app or link this directory."
+      : "This workspace has no projects yet.",
+  );
+}
+
+function noProject(projects, message) {
+  const human = projects.length
+    ? ["Projects:", ...projects.map((p) => `  ${projectLabel(p)}  ${p.id}`)].join("\n")
+    : "Start one at https://app.syndai.ai";
+  return new CliError(EXIT.USAGE, message, {
+    next: projects.length ? "syndai link <project>" : null,
+    result: {
+      data: { projects: projects.map(({ id, name, live_url }) => ({ id, name, live_url })) },
+      human,
+    },
+  });
+}
+
+async function pickInteractively(ctx, projects) {
+  for (const [i, p] of projects.entries()) ctx.ui.progress(`  ${i + 1}. ${projectLabel(p)}`);
+  for (;;) {
+    const answer = await ask(ctx.io, `Which project? [1-${projects.length}] `);
+    const index = Number(answer) - 1;
+    if (Number.isInteger(index) && projects[index]) return projects[index];
+  }
+}
+
+/** Normalised remotes of the git checkout at `cwd` (empty outside one). */
+export function gitRemotes(cwd) {
+  let out = "";
+  try {
+    out = execFileSync("git", ["remote", "-v"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 3000,
+    });
+  } catch {
+    return new Set();
+  }
+  return new Set(
+    out
+      .split("\n")
+      .map((line) => line.split(/\s+/)[1])
+      .filter(Boolean)
+      .map(normalizeRemote),
+  );
+}
+
+/** `git@host:o/r.git`, `ssh://git@host:22/o/r`, `https://tok@host/o/r.git` -> `host/o/r`. */
+export function normalizeRemote(url) {
+  const text = url.trim().toLowerCase();
+  const scp = /^(?:[\w.-]+@)?([\w.-]+):(?!\/\/)(.+)$/.exec(text);
+  let normal = text;
+  if (scp && !text.includes("://")) {
+    normal = `${scp[1]}/${scp[2]}`;
+  } else {
+    try {
+      const parsed = new URL(text);
+      normal = parsed.hostname + parsed.pathname;
+    } catch {
+      // Not a URL: compare as typed.
+    }
+  }
+  return normal.replace(/\.git$/, "").replace(/\/+$/, "");
+}
+
+export async function link(ctx, ref) {
+  const project = await resolveProject(ctx, { app: ref ?? ctx.flags.app, useLink: false });
+  const dir = path.resolve(ctx.io.cwd);
+  saveLink(ctx.paths, dir, { project_id: project.id, name: project.name, customer_id: project.customer_id });
+  ctx.ui.result(
+    { dir, project_id: project.id, name: project.name },
+    `Linked ${dir} to ${projectLabel(project)}.`,
+  );
+  return EXIT.OK;
+}

package/src/routes.js

@@ -0,0 +1,65 @@
+// Every REST route the CLI calls, in one table. Code builds paths only through `path()`,
+// so `test/contract.test.js` can prove each one exists, with the same method, in the
+// published OpenAPI (`docs/api/external-coding-v1.openapi.json`). `syndai api` is the one
+// command that bypasses this table: it reads the live OpenAPI instead (openapi.js).
+
+const EXT = "/api/v1/external/coding";
+
+export const ROUTES = Object.freeze({
+  deviceStart: ["POST", "/api/v1/cli/device"],
+  deviceToken: ["POST", "/api/v1/cli/device/token"],
+  me: ["GET", `${EXT}/me`],
+  revokeMe: ["DELETE", `${EXT}/me`],
+  listRepos: ["GET", `${EXT}/repos`],
+  updateRepo: ["PATCH", `${EXT}/repos/{coding_repository_id}`],
+  textEdit: ["POST", `${EXT}/repos/{coding_repository_id}/text-edits`],
+  undoTextEdit: ["POST", `${EXT}/repos/{coding_repository_id}/text-edits/{sha}/undo`],
+  listApps: ["GET", `${EXT}/customers/{customer_id}/apps`],
+  getPublication: ["GET", `${EXT}/customers/{customer_id}/repositories/{coding_repository_id}/publication`],
+  updatePublication: [
+    "PATCH",
+    `${EXT}/customers/{customer_id}/repositories/{coding_repository_id}/publication`,
+  ],
+  getBugScan: ["GET", `${EXT}/repositories/{repository_id}/bug-scan`],
+  setBugScan: ["PUT", `${EXT}/repositories/{repository_id}/bug-scan`],
+  getPolicy: ["GET", `${EXT}/policy/defaults`],
+  putPolicy: ["PUT", `${EXT}/policy/defaults`],
+  imageIngest: ["POST", `${EXT}/runs/image-ingest`],
+  createRun: ["POST", `${EXT}/runs`],
+  listRuns: ["GET", `${EXT}/runs`],
+  getRun: ["GET", `${EXT}/runs/{coding_run_id}`],
+  changeState: ["GET", `${EXT}/runs/{run_id}/change`],
+  runEvents: ["GET", `${EXT}/runs/{run_id}/events`],
+  respond: ["POST", `${EXT}/runs/{run_id}/responses`],
+  cancel: ["POST", `${EXT}/runs/{run_id}/cancel`],
+  revert: ["POST", `${EXT}/runs/{run_id}/revert`],
+  landRetry: ["POST", `${EXT}/runs/{run_id}/land/retry`],
+  landClose: ["POST", `${EXT}/runs/{run_id}/land/close`],
+  goLive: ["POST", `${EXT}/runs/{run_id}/land/go-live`],
+  heldDiff: ["GET", `${EXT}/runs/{run_id}/land/held-diff`],
+  listSchedules: ["GET", `${EXT}/schedules`],
+  createSchedule: ["POST", `${EXT}/schedules`],
+  getSchedule: ["GET", `${EXT}/schedules/{schedule_id}`],
+  updateSchedule: ["PATCH", `${EXT}/schedules/{schedule_id}`],
+  deleteSchedule: ["DELETE", `${EXT}/schedules/{schedule_id}`],
+  pauseSchedule: ["POST", `${EXT}/schedules/{schedule_id}/pause`],
+  resumeSchedule: ["POST", `${EXT}/schedules/{schedule_id}/resume`],
+  runScheduleNow: ["POST", `${EXT}/schedules/{schedule_id}/run-now`],
+});
+
+/** The MCP endpoint `syndai mcp install` points clients at (JSON-RPC, not REST). */
+export const MCP_PATH = "/api/v1/coding/mcp";
+
+/** `[method, path]` for a route, with `{name}` placeholders filled and URL-encoded. */
+export function route(name, params = {}) {
+  const entry = ROUTES[name];
+  if (!entry) throw new Error(`unknown route ${name}`);
+  const [method, template] = entry;
+  const path = template.replace(/\{(\w+)\}/g, (_, key) => {
+    if (params[key] === undefined || params[key] === null) {
+      throw new Error(`route ${name} needs ${key}`);
+    }
+    return encodeURIComponent(String(params[key]));
+  });
+  return [method, path];
+}