AgentHub/server/openapi-extra/files.js

/**
 * @file OpenAPI fragment for the File Explorer — the same operations on a
 * workspace (`/api/lanes/{id}/fs/*`, also under /api/workspaces) and on a
 * user's home (`/api/homes/{who}/fs/*`), generated from one table so the two
 * cannot drift — plus `GET /api/homes`, Add workspace → Clone
 * (`POST /api/lanes/clone`) and the user's own git identity (`/api/me/git`).
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */

const tags = [
  {
    name: "Files",
    description:
      "The File Explorer on a workspace or a user's home: list, make, rename, move, copy, delete into a restorable trash, streamed upload, zip download. Writes run as the folder's account; a taken name is settled by `conflict`.",
  },
  {
    name: "Git identity",
    description:
      "A user's own SSH key and HTTPS logins and commit author, and cloning a repository into a new workspace with them.",
  },
];

const errorCodes =
  "400 EBADPATH/EBADNAME, 403 ESECRET/EFOREIGN/EREADONLY (another user's home)/EBADORIGIN, 404 ENOFILE/ENOHOME, 409 EEXISTS (with `error.names`)/EUPGRADE/EMEMBERGONE, 413 ETOOBIG.";

const schemas = {
  FsEntry: {
    type: "object",
    properties: {
      name: { type: "string" },
      path: { type: "string", description: "Relative to the workspace or home." },
      type: { type: "string", enum: ["dir", "file", "link", "linkdir", "other"] },
      size: { type: "integer", nullable: true },
      mtime: { type: "number", description: "Milliseconds since the epoch." },
    },
  },
  FsListing: {
    type: "object",
    properties: {
      path: { type: "string" },
      parent: { type: "string", nullable: true },
      entries: { type: "array", items: { $ref: "#/components/schemas/FsEntry" } },
      truncated: { type: "boolean" },
    },
  },
  FsConflict: {
    type: "string",
    enum: ["fail", "skip", "keep", "replace"],
    default: "fail",
    description:
      "A taken name: `fail` answers 409 EEXISTS with the names, `skip` leaves it, `keep` uses a free `name (1).ext`, `replace` sends the old one to the trash first.",
  },
};

const json = (properties, required = []) => ({
  required: true,
  content: { "application/json": { schema: { type: "object", required, properties } } },
});
const pathsArr = { type: "array", items: { type: "string" } };
const conflict = { $ref: "#/components/schemas/FsConflict" };

/** The operations, without their prefix: [method, sub, summary, extra]. */
const OPS = [
  [
    "get",
    "/list",
    "List a folder (folders first)",
    {
      parameters: [{ name: "path", in: "query", schema: { type: "string", default: "" } }],
      ok: {
        description: "The folder.",
        content: { "application/json": { schema: { $ref: "#/components/schemas/FsListing" } } },
      },
    },
  ],
  [
    "post",
    "/mkdir",
    "Make a folder",
    { body: json({ path: { type: "string" } }, ["path"]), status: 201 },
  ],
  [
    "post",
    "/newfile",
    "Make an empty file",
    { body: json({ path: { type: "string" } }, ["path"]), status: 201 },
  ],
  [
    "post",
    "/rename",
    "Rename in place",
    { body: json({ path: { type: "string" }, name: { type: "string" } }, ["path", "name"]) },
  ],
  [
    "post",
    "/move",
    "Move items into a folder",
    { body: json({ paths: pathsArr, dest: { type: "string" }, conflict }, ["paths", "dest"]) },
  ],
  [
    "post",
    "/copy",
    "Copy items into a folder — from here, another workspace (`fromLane`) or a home (`fromHome`) of the same account",
    {
      body: json(
        {
          paths: pathsArr,
          dest: { type: "string" },
          conflict,
          fromLane: { type: "integer" },
          fromHome: { type: "string" },
        },
        ["paths", "dest"]
      ),
    },
  ],
  [
    "post",
    "/delete",
    "Move items into the account's trash (restorable for 7 days)",
    { body: json({ paths: pathsArr }, ["paths"]) },
  ],
  ["get", "/trash", "The trash, newest first (entries older than 7 days are dropped)", {}],
  [
    "post",
    "/trash/restore",
    "Put a trash item back where it was",
    { body: json({ id: { type: "string" } }, ["id"]) },
  ],
  [
    "post",
    "/trash/purge",
    "Delete a trash item (or `all`) for good",
    { body: json({ id: { type: "string" } }, ["id"]) },
  ],
  [
    "post",
    "/upload",
    "Upload one file, streamed, making missing sub-folders (≤ 500 MB)",
    {
      parameters: [
        { name: "path", in: "query", required: true, schema: { type: "string" } },
        { name: "conflict", in: "query", schema: conflict },
      ],
      body: {
        required: true,
        content: { "application/octet-stream": { schema: { type: "string", format: "binary" } } },
      },
      status: 201,
    },
  ],
  [
    "get",
    "/zip",
    "Files and folders as one streamed zip (≤ 2 GB, 50,000 files)",
    {
      parameters: [
        {
          name: "p",
          in: "query",
          required: true,
          schema: { type: "array", items: { type: "string" } },
          style: "form",
          explode: true,
        },
      ],
      ok: {
        description: "application/zip",
        content: { "application/zip": { schema: { type: "string", format: "binary" } } },
      },
    },
  ],
];

function operations(prefix, idParam, opPrefix, note) {
  const out = {};
  for (const [method, sub, summary, x] of OPS) {
    const key = `${prefix}${sub}`;
    out[key] = out[key] || {};
    out[key][method] = {
      tags: ["Files"],
      summary,
      description: `${note} ${errorCodes}`,
      operationId: `${opPrefix}${sub.replace(/\/(\w)/g, (_, c) => c.toUpperCase())}`,
      parameters: [idParam, ...(x.parameters || [])],
      ...(x.body ? { requestBody: x.body } : {}),
      responses: { [x.status || 200]: x.ok || { description: "Done." } },
    };
  }
  return out;
}

const paths = {
  ...operations(
    "/api/lanes/{id}/fs",
    { name: "id", in: "path", required: true, schema: { type: "integer" } },
    "laneFs",
    "On a workspace (`?session=` / `?source=` pick the session worktree / extra folder, like the git reads)."
  ),
  ...operations(
    "/api/homes/{who}/fs",
    {
      name: "who",
      in: "path",
      required: true,
      schema: { type: "string" },
      description: "`me`, or another user's name (an admin's read-only view).",
    },
    "homeFs",
    "On a user's home. Every dot entry at the top of the home is hidden and refused."
  ),
  "/api/lanes/{id}/fs/download": undefined,
  "/api/homes/{who}/fs/download": {
    get: {
      tags: ["Files"],
      summary: "Download one file of a home",
      operationId: "homeFsDownload",
      parameters: [
        { name: "who", in: "path", required: true, schema: { type: "string" } },
        { name: "path", in: "query", required: true, schema: { type: "string" } },
      ],
      responses: { 200: { description: "The file, as a sandboxed attachment." } },
    },
  },
  "/api/homes": {
    get: {
      tags: ["Files"],
      summary: "The homes the caller may open",
      description: "`me` (their own), and for an admin every other user's — read-only.",
      operationId: "listHomes",
      responses: { 200: { description: "{homes: [{id, label, readOnly}]}" } },
    },
  },
  "/api/lanes/clone": {
    post: {
      tags: ["Git identity"],
      summary: "Clone a repository into a new folder and make it a workspace",
      description:
        "`url`: https:// (no userinfo), ssh:// or user@host:path. Runs as the folder's account with that account's own SSH key or HTTPS login. 409 ECREDENTIALS (`error.auth` names the host) asks for `credentials`; 409 ESSHAUTH: the key was refused; 409 ENOREPO: no such repository.",
      operationId: "cloneLane",
      requestBody: json(
        {
          url: { type: "string" },
          parent: { type: "string" },
          name: { type: "string" },
          title: { type: "string" },
          tool: { type: "string" },
          credentials: {
            type: "object",
            properties: {
              username: { type: "string" },
              password: { type: "string" },
              remember: { type: "boolean" },
            },
          },
        },
        ["url", "parent"]
      ),
      responses: { 201: { description: "{lane, created: true, path}" } },
    },
  },
  "/api/me/git": {
    get: {
      tags: ["Git identity"],
      summary: "The caller's own git identity",
      description: "Only the public SSH key and `hasToken` are ever returned.",
      operationId: "getGitIdentity",
      responses: {
        200: {
          description:
            "{account, writable, ssh: {type, publicKey, fingerprint, terminal} | null, https: [...], author: {name, email}}",
        },
      },
    },
  },
  "/api/me/git/ssh-key": {
    post: {
      tags: ["Git identity"],
      summary: "Make (or with `replace`, replace) the SSH key of `type`; the other type is kept",
      operationId: "generateSshKey",
      requestBody: json({
        replace: { type: "boolean" },
        type: { type: "string", enum: ["ed25519", "rsa"] },
      }),
      responses: { 201: { description: "The identity." } },
    },
    delete: {
      tags: ["Git identity"],
      summary: "Delete the SSH key of ?type=ed25519|rsa, or every key",
      operationId: "deleteSshKey",
      parameters: [
        {
          name: "type",
          in: "query",
          required: false,
          schema: { type: "string", enum: ["ed25519", "rsa"] },
        },
      ],
      responses: { 200: { description: "The identity." } },
    },
  },
  "/api/me/git/ssh-terminal": {
    put: {
      tags: ["Git identity"],
      summary: "Use the SSH key for git in the account's own terminal (core.sshCommand)",
      operationId: "setTerminalSsh",
      requestBody: json({ on: { type: "boolean" } }, ["on"]),
      responses: {
        200: { description: "The identity; `ssh.terminal` is on, off or foreign." },
        409: { description: "EFOREIGNSSH — ~/.gitconfig already sets its own core.sshCommand." },
      },
    },
  },
  "/api/me/git/https": {
    post: {
      tags: ["Git identity"],
      summary: "Save an HTTPS login (never returned)",
      operationId: "saveHttpsLogin",
      requestBody: json(
        { host: { type: "string" }, username: { type: "string" }, password: { type: "string" } },
        ["host", "username", "password"]
      ),
      responses: { 200: { description: "The identity." } },
    },
  },
  "/api/me/git/https/{host}": {
    delete: {
      tags: ["Git identity"],
      summary: "Delete an HTTPS login",
      operationId: "deleteHttpsLogin",
      parameters: [{ name: "host", in: "path", required: true, schema: { type: "string" } }],
      responses: { 200: { description: "The identity." } },
    },
  },
  "/api/me/git/author": {
    put: {
      tags: ["Git identity"],
      summary: "Set the commit author (`git config --global user.name/email`)",
      operationId: "setGitAuthor",
      requestBody: json({ name: { type: "string" }, email: { type: "string" } }, ["name", "email"]),
      responses: { 200: { description: "The identity." }, 400: { description: "EBADAUTHOR" } },
    },
  },
};
delete paths["/api/lanes/{id}/fs/download"];

module.exports = { tags, schemas, paths };