@openparachute/vault 0.4.9-rc.7 → 0.4.9-rc.8

package/src/mirror-routes.test.ts

@@ -26,9 +26,20 @@ import {
   handleAuthGithubRepos,
   handleAuthPat,
   handleMirrorGet,
+  handleMirrorImport,
   handleMirrorPut,
   handleMirrorRunNow,
 } from "./mirror-routes.ts";
+import {
+  _resetImportInFlightForTest,
+  type GitSpawn,
+} from "./mirror-import.ts";
+import { writeVaultConfig } from "./config.ts";
+import { clearVaultStoreCache } from "./vault-store.ts";
+import { exportVaultToDir } from "../core/src/portable-md.ts";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "../core/src/store.ts";
+import { cpSync, writeFileSync as nodeWriteFileSync } from "node:fs";
 import {
   mirrorCredentialsPath,
   readCredentials,
@@ -848,3 +859,310 @@ describe("auth credential routes — github repos / create-repo", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// POST /.parachute/mirror/import — clone-and-import HTTP route (vault#391).
+// ---------------------------------------------------------------------------
+
+/**
+ * Bootstrap a real vault config + db file so getVaultStore('default')
+ * succeeds inside the handler. Returns the home dir for cleanup.
+ */
+async function bootstrapVault(home: string): Promise<void> {
+  process.env.PARACHUTE_HOME = home;
+  process.env.HOME = home;
+  // The minimal layout vault needs to spin up its store: a per-vault
+  // dir at $PARACHUTE_HOME/vault/data/<name> + a `vault.yaml` config.
+  // writeVaultConfig creates these for us.
+  fs.mkdirSync(path.join(home, "vault", "data", "default"), { recursive: true });
+  writeVaultConfig({
+    name: "default",
+    description: "import-test vault",
+    created_at: "2026-05-28T00:00:00.000Z",
+    api_keys: [],
+  });
+  clearVaultStoreCache();
+}
+
+/**
+ * Build a real portable-md vault export, return the path. The clone
+ * spawn-mock copies this into the tempdir to simulate a successful
+ * `git clone`.
+ */
+async function buildExportFixture(): Promise<string> {
+  const fixture = tmp("import-route-fixture-");
+  const exportStore = new SqliteStore(new Database(":memory:"));
+  await exportStore.createNote("alpha body", { id: "n-alpha", path: "alpha", tags: ["t1"] });
+  await exportStore.createNote("beta body", { id: "n-beta", path: "beta" });
+  await exportVaultToDir(exportStore, {
+    outDir: fixture,
+    vaultName: "source",
+    exportedAt: "2026-05-28T00:00:00.000Z",
+  });
+  return fixture;
+}
+
+const spawnCloneSuccess = (fixture: string): GitSpawn => async (argv) => {
+  const destDir = argv[argv.length - 1]!;
+  cpSync(fixture, destDir, { recursive: true });
+  return { exitCode: 0, stderr: "", timedOut: false };
+};
+
+const spawnCloneFail: GitSpawn = async () => ({
+  exitCode: 128,
+  stderr: "fatal: repository not found",
+  timedOut: false,
+});
+
+describe("handleMirrorImport", () => {
+  let home: string;
+  let fixture: string;
+
+  afterEach(() => {
+    if (home) fs.rmSync(home, { recursive: true, force: true });
+    if (fixture) fs.rmSync(fixture, { recursive: true, force: true });
+    _resetImportInFlightForTest();
+    clearVaultStoreCache();
+  });
+
+  test("rejects invalid JSON body with 400", async () => {
+    home = tmp("import-route-badjson-");
+    await bootstrapVault(home);
+    const req = new Request("http://x/import", {
+      method: "POST",
+      body: "{not-json",
+    });
+    const res = await handleMirrorImport(req, "default");
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error_type: string };
+    expect(body.error_type).toBe("invalid_json");
+  });
+
+  test("rejects missing remote_url with 400", async () => {
+    home = tmp("import-route-no-url-");
+    await bootstrapVault(home);
+    const req = new Request("http://x/import", {
+      method: "POST",
+      body: JSON.stringify({ mode: "merge" }),
+    });
+    const res = await handleMirrorImport(req, "default");
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { field: string };
+    expect(body.field).toBe("remote_url");
+  });
+
+  test("rejects invalid mode with 400", async () => {
+    home = tmp("import-route-bad-mode-");
+    await bootstrapVault(home);
+    const req = new Request("http://x/import", {
+      method: "POST",
+      body: JSON.stringify({ remote_url: "https://github.com/a/b.git", mode: "wipe" }),
+    });
+    const res = await handleMirrorImport(req, "default");
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { field: string };
+    expect(body.field).toBe("mode");
+  });
+
+  test("rejects per-call PAT without token", async () => {
+    home = tmp("import-route-pat-missing-token-");
+    await bootstrapVault(home);
+    const req = new Request("http://x/import", {
+      method: "POST",
+      body: JSON.stringify({
+        remote_url: "https://github.com/a/b.git",
+        mode: "merge",
+        credentials: { kind: "pat", token: "" },
+      }),
+    });
+    const res = await handleMirrorImport(req, "default");
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { field: string };
+    expect(body.field).toBe("credentials.token");
+  });
+
+  test("rejects unknown credentials.kind", async () => {
+    home = tmp("import-route-bad-kind-");
+    await bootstrapVault(home);
+    const req = new Request("http://x/import", {
+      method: "POST",
+      body: JSON.stringify({
+        remote_url: "https://github.com/a/b.git",
+        mode: "merge",
+        credentials: { kind: "magic" },
+      }),
+    });
+    const res = await handleMirrorImport(req, "default");
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { field: string };
+    expect(body.field).toBe("credentials.kind");
+  });
+
+  test("success path — merge mode imports notes into target vault", async () => {
+    home = tmp("import-route-success-");
+    await bootstrapVault(home);
+    fixture = await buildExportFixture();
+    const req = new Request("http://x/import", {
+      method: "POST",
+      body: JSON.stringify({
+        remote_url: "https://github.com/a/b.git",
+        mode: "merge",
+        credentials: { kind: "none" },
+      }),
+    });
+    const res = await handleMirrorImport(req, "default", spawnCloneSuccess(fixture));
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      notes_imported: number;
+      tags_imported: number;
+      attachments_imported: number;
+      warnings: string[];
+      notes_deleted?: number;
+    };
+    expect(body.notes_imported).toBe(2);
+    expect(body.warnings).toEqual([]);
+    expect(body.notes_deleted).toBeUndefined();
+  });
+
+  test("replace mode sets notes_deleted in response", async () => {
+    home = tmp("import-route-replace-");
+    await bootstrapVault(home);
+    fixture = await buildExportFixture();
+    // Seed the target vault with a local-only note that gets wiped.
+    const { getVaultStore } = await import("./vault-store.ts");
+    const store = getVaultStore("default");
+    await store.createNote("local", { id: "n-local", path: "local" });
+
+    const req = new Request("http://x/import", {
+      method: "POST",
+      body: JSON.stringify({
+        remote_url: "https://github.com/a/b.git",
+        mode: "replace",
+        credentials: { kind: "none" },
+      }),
+    });
+    const res = await handleMirrorImport(req, "default", spawnCloneSuccess(fixture));
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      notes_imported: number;
+      notes_deleted: number;
+    };
+    expect(body.notes_imported).toBe(2);
+    expect(body.notes_deleted).toBe(1);
+  });
+
+  test("clone failure returns 502 with redacted message", async () => {
+    home = tmp("import-route-clone-fail-");
+    await bootstrapVault(home);
+    const req = new Request("http://x/import", {
+      method: "POST",
+      body: JSON.stringify({
+        remote_url: "https://github.com/a/b.git",
+        mode: "merge",
+        credentials: { kind: "pat", token: "ghp_secret_xyz" },
+      }),
+    });
+    const res = await handleMirrorImport(req, "default", spawnCloneFail);
+    expect(res.status).toBe(502);
+    const text = await res.text();
+    expect(text).not.toContain("ghp_secret_xyz");
+    const body = JSON.parse(text) as { error_type: string };
+    expect(body.error_type).toBe("clone_failed");
+  });
+
+  test("not-a-vault-export returns 400 with actionable message", async () => {
+    home = tmp("import-route-not-vault-");
+    await bootstrapVault(home);
+    const notAnExport = tmp("import-route-notvault-fixture-");
+    nodeWriteFileSync(path.join(notAnExport, "README.md"), "hello");
+    fixture = notAnExport;
+    const req = new Request("http://x/import", {
+      method: "POST",
+      body: JSON.stringify({
+        remote_url: "https://github.com/a/b.git",
+        mode: "merge",
+        credentials: { kind: "none" },
+      }),
+    });
+    const res = await handleMirrorImport(req, "default", spawnCloneSuccess(notAnExport));
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error_type: string; message: string };
+    expect(body.error_type).toBe("not_a_vault_export");
+    expect(body.message).toContain("vault.yaml");
+  });
+
+  test("uses stored credentials when credentials: null (credentialsFile path)", async () => {
+    home = tmp("import-route-stored-creds-");
+    await bootstrapVault(home);
+    fixture = await buildExportFixture();
+    // Write a stored PAT credential matching github.com.
+    writeCredentials({
+      active_method: "pat",
+      github_oauth: null,
+      pat: {
+        token: "ghp_stored_token_xyz",
+        remote_url: "https://x-access-token:ghp_stored_token_xyz@github.com/a/b.git",
+        label: "stored",
+      },
+    });
+    // Assert the spawn argv carries the stored token (proves the
+    // credentialsFile path resolved).
+    let observedArgv: string[] | null = null;
+    const fakeSpawn: GitSpawn = async (argv) => {
+      observedArgv = argv;
+      const destDir = argv[argv.length - 1]!;
+      cpSync(fixture, destDir, { recursive: true });
+      return { exitCode: 0, stderr: "", timedOut: false };
+    };
+    const req = new Request("http://x/import", {
+      method: "POST",
+      body: JSON.stringify({
+        remote_url: "https://github.com/a/b.git",
+        mode: "merge",
+        credentials: null,
+      }),
+    });
+    const res = await handleMirrorImport(req, "default", fakeSpawn);
+    expect(res.status).toBe(200);
+    // The clone URL should have the stored token embedded.
+    expect(observedArgv).not.toBeNull();
+    expect(observedArgv!.some((arg) => arg.includes("ghp_stored_token_xyz"))).toBe(true);
+  });
+
+  test("per-call PAT override is used when supplied", async () => {
+    home = tmp("import-route-per-call-pat-");
+    await bootstrapVault(home);
+    fixture = await buildExportFixture();
+    // Stored credentials should be IGNORED when per-call PAT is supplied.
+    writeCredentials({
+      active_method: "pat",
+      github_oauth: null,
+      pat: {
+        token: "ghp_stored_xyz",
+        remote_url: "https://x-access-token:ghp_stored_xyz@github.com/a/b.git",
+        label: "stored",
+      },
+    });
+    let observedArgv: string[] | null = null;
+    const fakeSpawn: GitSpawn = async (argv) => {
+      observedArgv = argv;
+      const destDir = argv[argv.length - 1]!;
+      cpSync(fixture, destDir, { recursive: true });
+      return { exitCode: 0, stderr: "", timedOut: false };
+    };
+    const req = new Request("http://x/import", {
+      method: "POST",
+      body: JSON.stringify({
+        remote_url: "https://github.com/a/b.git",
+        mode: "merge",
+        credentials: { kind: "pat", token: "ghp_per_call_only" },
+      }),
+    });
+    const res = await handleMirrorImport(req, "default", fakeSpawn);
+    expect(res.status).toBe(200);
+    expect(observedArgv).not.toBeNull();
+    const joined = observedArgv!.join(" ");
+    expect(joined).toContain("ghp_per_call_only");
+    expect(joined).not.toContain("ghp_stored_xyz");
+  });
+});
+

package/src/mirror-routes.ts

@@ -52,6 +52,17 @@ import {
   type FetchLike,
   type GitHubRepoInfo,
 } from "./github-device-flow.ts";
+import {
+  CloneFailedError,
+  ImportConflictError,
+  NotAVaultExportError,
+  cloneAndImport,
+  type GitSpawn,
+  type ImportAuth,
+  type ImportResult,
+} from "./mirror-import.ts";
+import { getVaultStore } from "./vault-store.ts";
+import { assetsDir } from "./routes.ts";
 
 /**
  * `GET /vault/<name>/.parachute/mirror` — return the persisted config +
@@ -874,3 +885,207 @@ export async function applyCredentialsToMirror(
   // until a repo is selected. Caller is responsible for invoking
   // select-repo separately.
 }
+
+// ---------------------------------------------------------------------------
+// Import-from-git route — symmetric counterpart to the mirror export work.
+//
+// `POST /vault/<name>/.parachute/mirror/import` — clone a vault export from
+// a git remote and import it into the named vault.
+//
+// Request body:
+//   {
+//     "remote_url": "https://github.com/aaron/my-vault.git",
+//     "mode": "merge" | "replace",
+//     "credentials": null
+//       | { "kind": "pat", "token": "ghp_..." }
+//       | { "kind": "none" }
+//   }
+//
+// `credentials: null` means "use the stored mirror credentials." Passing
+// `{kind: "pat", token}` is the one-shot path — token doesn't get persisted.
+//
+// Response:
+//   200 { notes_imported, tags_imported, attachments_imported,
+//         notes_deleted?, warnings }
+//   400 { error, error_type, message }  — validation / not-a-vault-export
+//   409 { error, error_type, message }  — concurrent import for this vault
+//   502 { error, message }              — clone failed (auth, network, …)
+//
+// Admin-gated upstream in routing.ts.
+// ---------------------------------------------------------------------------
+
+/**
+ * `POST /vault/<name>/.parachute/mirror/import`. See block comment above.
+ *
+ * Synchronous response: imports complete in <30s for typical vaults
+ * (a 1k-note vault clones+imports in well under that bound on Aaron's hardware).
+ * If/when bigger vaults arrive we promote to async polling — for now the
+ * synchronous path keeps the UI flow simple.
+ *
+ * `spawnOverride` is a test seam: lets the test inject a fake git binary.
+ * Production callers omit it; `cloneAndImport` falls back to `defaultGitSpawn`.
+ */
+export async function handleMirrorImport(
+  req: Request,
+  vaultName: string,
+  spawnOverride?: GitSpawn,
+): Promise<Response> {
+  let body: {
+    remote_url?: unknown;
+    mode?: unknown;
+    credentials?: unknown;
+  };
+  try {
+    body = (await req.json()) as Record<string, unknown>;
+  } catch (err) {
+    return Response.json(
+      {
+        error: "Invalid JSON body",
+        error_type: "invalid_json",
+        message: (err as Error).message ?? String(err),
+      },
+      { status: 400 },
+    );
+  }
+
+  const remote_url =
+    typeof body.remote_url === "string" ? body.remote_url.trim() : "";
+  if (remote_url.length === 0) {
+    return Response.json(
+      {
+        error: "remote_url required",
+        error_type: "validation",
+        field: "remote_url",
+        message: "Provide an HTTPS or SSH clone URL.",
+      },
+      { status: 400 },
+    );
+  }
+  const mode = body.mode;
+  if (mode !== "merge" && mode !== "replace") {
+    return Response.json(
+      {
+        error: "mode invalid",
+        error_type: "validation",
+        field: "mode",
+        message: 'mode must be "merge" or "replace".',
+      },
+      { status: 400 },
+    );
+  }
+
+  // Resolve auth shape. The wire format mirrors the internal ImportAuth
+  // type, but tightened: only `kind` and `token` cross the wire. `none`
+  // and `null` both fall through to "use stored credentials" because the
+  // common case is "I configured mirror creds; use them" — and the
+  // shorthand keeps the SPA from having to track which kind to send.
+  let auth: ImportAuth;
+  const creds = body.credentials;
+  if (creds === null || creds === undefined) {
+    auth = { kind: "credentialsFile" };
+  } else if (typeof creds === "object") {
+    const credsObj = creds as Record<string, unknown>;
+    if (credsObj.kind === "pat") {
+      const token = typeof credsObj.token === "string" ? credsObj.token.trim() : "";
+      if (token.length === 0) {
+        return Response.json(
+          {
+            error: "credentials.token required",
+            error_type: "validation",
+            field: "credentials.token",
+            message: 'When credentials.kind is "pat", credentials.token must be a non-empty string.',
+          },
+          { status: 400 },
+        );
+      }
+      auth = { kind: "pat", token };
+    } else if (credsObj.kind === "none") {
+      auth = { kind: "none" };
+    } else if (credsObj.kind === "credentialsFile") {
+      auth = { kind: "credentialsFile" };
+    } else {
+      return Response.json(
+        {
+          error: "credentials.kind invalid",
+          error_type: "validation",
+          field: "credentials.kind",
+          message: 'credentials.kind must be "pat", "credentialsFile", or "none". Or pass credentials: null.',
+        },
+        { status: 400 },
+      );
+    }
+  } else {
+    return Response.json(
+      {
+        error: "credentials invalid",
+        error_type: "validation",
+        field: "credentials",
+        message: "credentials must be an object or null.",
+      },
+      { status: 400 },
+    );
+  }
+
+  // Resolve the target vault's store + assets dir. The route is gated on
+  // `vault:<name>:admin`, so we trust vaultName is real by the time we
+  // reach this code path; defensively re-resolve in case the vault was
+  // deleted between auth and now.
+  const store = getVaultStore(vaultName);
+  const assets = assetsDir(vaultName);
+
+  let result: ImportResult;
+  try {
+    result = await cloneAndImport({
+      vaultName,
+      remoteUrl: remote_url,
+      auth,
+      mode,
+      store,
+      assetsDir: assets,
+      spawn: spawnOverride,
+    });
+  } catch (err) {
+    if (err instanceof ImportConflictError) {
+      return Response.json(
+        {
+          error: "Import already running",
+          error_type: "concurrent_import",
+          message: err.message,
+        },
+        { status: 409 },
+      );
+    }
+    if (err instanceof NotAVaultExportError) {
+      return Response.json(
+        {
+          error: "Not a vault export",
+          error_type: "not_a_vault_export",
+          message: err.message,
+        },
+        { status: 400 },
+      );
+    }
+    if (err instanceof CloneFailedError) {
+      return Response.json(
+        {
+          error: "Clone failed",
+          error_type: "clone_failed",
+          message: err.message,
+        },
+        { status: 502 },
+      );
+    }
+    return Response.json(
+      {
+        error: "Import failed",
+        error_type: "internal",
+        message: (err as Error).message ?? String(err),
+      },
+      { status: 500 },
+    );
+  }
+
+  return Response.json(result, {
+    headers: { "Access-Control-Allow-Origin": "*" },
+  });
+}

package/src/routing.ts

@@ -82,6 +82,7 @@ import {
   handleAuthGithubSelectRepo,
   handleAuthPat,
   handleMirrorGet,
+  handleMirrorImport,
   handleMirrorPut,
   handleMirrorRunNow,
 } from "./mirror-routes.ts";
@@ -556,6 +557,30 @@ export async function route(
     return Response.json({ error: "Method not allowed" }, { status: 405 });
   }
 
+  // /.parachute/mirror/import — clone a vault export from git + import.
+  // Admin-gated. POST-only. Synchronous (imports finish in <30s for
+  // typical vaults). See mirror-routes.ts:handleMirrorImport for the
+  // request/response shape + error map. Symmetric counterpart to the
+  // export-to-git flow vault#382 + vault#384 shipped.
+  if (subpath === "/.parachute/mirror/import") {
+    if (!hasScopeForVault(auth.scopes, vaultName, "admin")) {
+      return Response.json(
+        {
+          error: "Forbidden",
+          error_type: "insufficient_scope",
+          message: `This endpoint requires the '${SCOPE_ADMIN}' scope (or '${SCOPE_ADMIN.replace("vault:", `vault:${vaultName}:`)}').`,
+          required_scope: SCOPE_ADMIN,
+          granted_scopes: auth.scopes,
+        },
+        { status: 403 },
+      );
+    }
+    if (req.method !== "POST") {
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    return handleMirrorImport(req, vaultName);
+  }
+
   // /.parachute/mirror/auth/* — UI-configurable git push credentials.
   // GitHub OAuth Device Flow + PAT fallback. All admin-gated; the
   // routes themselves don't carry secrets in their responses