@jxsuite/protocol 6.2.1 → 6.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/protocol",
-  "version": "6.2.1",
+  "version": "6.2.3",
   "description": "The Studio Backend Protocol — wire types and the canonical route table every Jx Studio backend implements",
   "license": "MIT",
   "repository": {
@@ -14,6 +14,7 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
+    "./git-scope": "./src/git-scope.ts",
     "./problem": "./src/problem.ts",
     "./problems": "./src/problems.ts",
     "./routes": "./src/routes.ts",
@@ -27,6 +28,6 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/schema": "^5.1.0"
+    "@jxsuite/schema": "^5.3.0"
   }
 }

package/src/git-scope.ts

@@ -0,0 +1,92 @@
+/**
+ * What a project nested inside a larger repository sees of it.
+ *
+ * Git answers in two coordinate systems. `status` and `diff --name-only` print paths from the
+ * REPOSITORY ROOT whatever the cwd is (porcelain ignores `status.relativePaths`), while `add`,
+ * `restore`, `checkout` and the `readFile` Studio pairs them with read paths from the PROJECT ROOT.
+ * Handed straight across, a site at `Sites/acme/` asked git to stage
+ * `Sites/acme/Sites/acme/pages/index.md`.
+ *
+ * So every path a backend gives Studio is project-relative, and a project's status and commit cover
+ * that project (`desktop.md` §5.1, `studio.md` §22.8). Both backends run these same rules so they
+ * cannot disagree about one working tree. At a repository's root the prefix is empty and each of
+ * them is the identity.
+ *
+ * @module
+ * @docs extending/embedding/platform-adapter
+ */
+
+/** Runs one git command in the project root, resolving stdout and rejecting on a non-zero exit. */
+export type GitRunner = (args: string[]) => Promise<string>;
+
+/** `git rev-parse --show-prefix`: the project's folder within its repository, `""` at the root. */
+export async function readGitPrefix(run: GitRunner): Promise<string> {
+  const out = await run(["rev-parse", "--show-prefix"]);
+  // A prefix is empty or ends in `/`, so this can only remove the newline git adds.
+  return out.trimEnd();
+}
+
+/**
+ * A root-relative path git printed, as the project-relative path every other verb reads.
+ *
+ * A path outside the project stays as git printed it: it has no project-relative spelling the file
+ * routes would accept, and a `conflicts` list still has to name it.
+ *
+ * @param {string} prefix - From {@link readGitPrefix}
+ * @param {string} path - Relative to the repository root
+ * @returns {string}
+ */
+export function projectRelativePath(prefix: string, path: string): string {
+  return path.startsWith(prefix) ? path.slice(prefix.length) : path;
+}
+
+/**
+ * The `git commit` that publishes THIS project's staged changes and nothing else.
+ *
+ * Review changes lists only the project, and a commit made from a subfolder still takes the whole
+ * index. In a repository of several sites, where each one's changes are staged the first time its
+ * Review changes shows them, a plain commit would carry another site's changes under this site's
+ * summary. So those stay staged, for the project they belong to:
+ *
+ * - **At the root**, everything is the project: the index, or every tracked change when nothing is
+ *   staged (the route's "staged, else all dirty").
+ * - **During a merge** the commit is the merge, which git refuses to split, and which is the
+ *   repository's rather than the project's.
+ * - **Nothing of the project's staged**: its own tracked changes, never `-a`, which reaches past it.
+ * - **Only the project's staged**: the index, exactly.
+ * - **Others staged too**: `--only` the project's paths. Those paths are committed from the working
+ *   tree rather than the index, so this is reserved for the case that needs it.
+ *
+ * `--no-renames` because a staged rename's old path has to be committed too, or `--only` would keep
+ * it in the tree and turn the rename into a copy; `--no-relative` because `diff.relative` would
+ * otherwise hide exactly the paths this is looking for.
+ *
+ * @param {GitRunner} run - Runs git in the project root
+ * @param {string} message - The commit message
+ * @returns {Promise<string[]>} The argv to hand git
+ */
+export async function projectCommitArgs(run: GitRunner, message: string): Promise<string[]> {
+  const [prefix, stagedOut, merging] = await Promise.all([
+    readGitPrefix(run),
+    run(["diff", "--cached", "--name-only", "--no-renames", "--no-relative", "-z"]),
+    run(["rev-parse", "--quiet", "--verify", "MERGE_HEAD"]).then(
+      () => true,
+      () => false,
+    ),
+  ]);
+  const commit = ["commit", "-m", message];
+  const staged = stagedOut.split("\0").filter(Boolean);
+  if (prefix === "") {
+    return staged.length > 0 ? commit : [...commit, "-a"];
+  }
+  if (merging) {
+    return commit;
+  }
+  const own = staged
+    .filter((path) => path.startsWith(prefix))
+    .map((path) => path.slice(prefix.length));
+  if (own.length === 0) {
+    return [...commit, "--", "."];
+  }
+  return own.length === staged.length ? commit : [...commit, "--only", "--", ...own];
+}

package/src/index.ts

@@ -5,6 +5,7 @@
  * @license MIT
  */
 
+export * from "./git-scope";
 export * from "./problem";
 export * from "./problems";
 export * from "./routes";

package/src/routes.ts

@@ -371,12 +371,20 @@ export const STUDIO_ROUTES = {
   ),
 
   // ─── Git ──────────────────────────────────────────────────────────────────
-  gitStatus: route("GET", "/__studio/git/status", "Working-tree status (GitStatusResult)"),
+  gitStatus: route(
+    "GET",
+    "/__studio/git/status",
+    "The project's working-tree status (GitStatusResult), project-relative",
+  ),
   gitBranches: route("GET", "/__studio/git/branches", "Branch list (GitBranchesResult)"),
   gitLog: route("GET", "/__studio/git/log", "Recent commits (GitLogEntry[])"),
   gitStage: route("POST", "/__studio/git/stage", "Stage files"),
   gitUnstage: route("POST", "/__studio/git/unstage", "Unstage files"),
-  gitCommit: route("POST", "/__studio/git/commit", "Commit staged (else all dirty) files"),
+  gitCommit: route(
+    "POST",
+    "/__studio/git/commit",
+    "Commit the project's staged (else all its dirty) files",
+  ),
   gitPush: route("POST", "/__studio/git/push", "Push (cloud: sync check — commits land on push)"),
   gitPull: route("POST", "/__studio/git/pull", "Pull/fast-forward; 409 {conflicts} on overlap"),
   gitFetch: route("POST", "/__studio/git/fetch", "Refresh remote tracking state"),

package/src/types.ts

@@ -206,6 +206,10 @@ export interface GitFileStatus {
    * code.
    */
   status: string;
+  /**
+   * Relative to the PROJECT root, never the repository's: the path every other git verb and file
+   * route reads. A project nested in a larger repository lists only its own changes.
+   */
   path: string;
   /** Whether this change is in the index. Absent reads as unstaged. */
   staged?: boolean;