@batadata/cli 0.1.7 → 0.1.9

package/dist/link.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Project linking — Vercel/Neon-style. A linked directory carries its project
+ * (and optionally its branch) in `.batadata/project.json`, so an agent no longer
+ * has to thread `--project <id>` through every invocation.
+ *
+ * ── Resolution precedence (the ONE rule, used everywhere) ─────────────────
+ *   1. an explicit `--project` / `--branch` flag        (per-invocation intent)
+ *   2. `.batadata/project.json`, discovered by walking UP from CWD like git    (per-directory intent)
+ *   3. `defaultProject` in `~/.batarc`                  (per-machine fallback)
+ *
+ * Flags always win, so linking never silently overrides an explicit request.
+ * The precedence itself lives in the pure `pickProjectId` / `pickBranchId`
+ * helpers (unit-testable without fs), and `resolveProjectId` / `resolveBranchId`
+ * compose them with the on-disk sources.
+ */
+export declare const LINK_DIR = ".batadata";
+export declare const LINK_FILE = "project.json";
+export interface LinkFile {
+    projectId: string;
+    /** Optional pinned branch (set by `bata db branch checkout`). */
+    branchId?: string | null;
+}
+export type ProjectSource = "flag" | "link" | "config" | "none";
+export type BranchSource = "flag" | "link" | "none";
+/**
+ * The ordered list of directories to search for a link file, from `startDir`
+ * up to (and including) the ceiling — the user's HOME dir or the filesystem
+ * root, whichever comes first. Exactly how git bounds its repo discovery.
+ *
+ * Pure: no fs, no env — just path math — so the walk-up order is unit-testable
+ * without ever writing to a real HOME.
+ */
+export declare function linkSearchDirs(startDir: string, homeDir: string): string[];
+/**
+ * Absolute path to the nearest `.batadata/project.json` at or above `startDir`,
+ * or null if none exists within the ceiling. Walks up like git.
+ */
+export declare function findLinkFile(startDir?: string, homeDir?: string): string | null;
+/**
+ * Read and parse the nearest link file. Returns its absolute path alongside the
+ * parsed contents, or null if there's no (valid) link file. A malformed file is
+ * treated as absent rather than throwing, so a stray/corrupt file can't wedge
+ * every command.
+ */
+export declare function readLinkFile(startDir?: string, homeDir?: string): {
+    path: string;
+    link: LinkFile;
+} | null;
+/**
+ * Write `.batadata/project.json` inside `dir` (creating `.batadata/` if needed)
+ * and return the absolute path written. `branchId` is normalized to null when
+ * absent so the file shape is stable.
+ */
+export declare function writeLinkFile(dir: string, link: LinkFile): string;
+/**
+ * Delete the nearest link file (and its now-empty `.batadata/` dir, if empty).
+ * Returns the path removed, or null if there was nothing to remove. Idempotent.
+ */
+export declare function removeLinkFile(startDir?: string, homeDir?: string): string | null;
+/**
+ * Pure precedence policy for the project id: flag > linked > config > none.
+ * No fs/env access, so the ordering is unit-testable in isolation (mirrors the
+ * `pickTeamId` pattern in api.ts).
+ */
+export declare function pickProjectId(params: {
+    flag?: string;
+    linked?: string | null;
+    config?: string;
+}): {
+    projectId?: string;
+    source: ProjectSource;
+};
+/**
+ * Pure precedence policy for the branch id: flag > linked > none. There is no
+ * config-level default branch, so config isn't a source here.
+ */
+export declare function pickBranchId(params: {
+    flag?: string;
+    linked?: string | null;
+}): {
+    branchId?: string;
+    source: BranchSource;
+};
+/**
+ * Resolve the active project id from all sources in precedence order. `explicit`
+ * is an already-parsed `--project` value (or a positional id) — pass it through
+ * so a flag always wins over a link file or config default.
+ */
+export declare function resolveProjectId(explicit?: string, opts?: {
+    startDir?: string;
+    homeDir?: string;
+}): {
+    projectId?: string;
+    source: ProjectSource;
+};
+/**
+ * Resolve the active branch id from all sources in precedence order. `explicit`
+ * is an already-parsed `--branch` value (id or name); the link file's pinned
+ * branch is the fallback.
+ */
+export declare function resolveBranchId(explicit?: string, opts?: {
+    startDir?: string;
+    homeDir?: string;
+}): {
+    branchId?: string;
+    source: BranchSource;
+};

package/dist/link.js

@@ -0,0 +1,170 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { loadConfig } from "./config.js";
+/**
+ * Project linking — Vercel/Neon-style. A linked directory carries its project
+ * (and optionally its branch) in `.batadata/project.json`, so an agent no longer
+ * has to thread `--project <id>` through every invocation.
+ *
+ * ── Resolution precedence (the ONE rule, used everywhere) ─────────────────
+ *   1. an explicit `--project` / `--branch` flag        (per-invocation intent)
+ *   2. `.batadata/project.json`, discovered by walking UP from CWD like git    (per-directory intent)
+ *   3. `defaultProject` in `~/.batarc`                  (per-machine fallback)
+ *
+ * Flags always win, so linking never silently overrides an explicit request.
+ * The precedence itself lives in the pure `pickProjectId` / `pickBranchId`
+ * helpers (unit-testable without fs), and `resolveProjectId` / `resolveBranchId`
+ * compose them with the on-disk sources.
+ */
+export const LINK_DIR = ".batadata";
+export const LINK_FILE = "project.json";
+/** Resolve HOME at call time (env-first) so a redirected HOME — every test does
+ *  this to avoid touching the developer's real home — is honored. Mirrors the
+ *  same rule in config.ts. */
+function defaultHome() {
+    return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+/**
+ * The ordered list of directories to search for a link file, from `startDir`
+ * up to (and including) the ceiling — the user's HOME dir or the filesystem
+ * root, whichever comes first. Exactly how git bounds its repo discovery.
+ *
+ * Pure: no fs, no env — just path math — so the walk-up order is unit-testable
+ * without ever writing to a real HOME.
+ */
+export function linkSearchDirs(startDir, homeDir) {
+    const dirs = [];
+    let dir = path.resolve(startDir);
+    const home = path.resolve(homeDir);
+    // Guard against a pathological loop; the parent === dir root check is the
+    // real terminator.
+    for (let i = 0; i < 4096; i++) {
+        dirs.push(dir);
+        if (dir === home)
+            break; // don't search above HOME
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // filesystem root
+        dir = parent;
+    }
+    return dirs;
+}
+/**
+ * Absolute path to the nearest `.batadata/project.json` at or above `startDir`,
+ * or null if none exists within the ceiling. Walks up like git.
+ */
+export function findLinkFile(startDir = process.cwd(), homeDir = defaultHome()) {
+    for (const dir of linkSearchDirs(startDir, homeDir)) {
+        const candidate = path.join(dir, LINK_DIR, LINK_FILE);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Read and parse the nearest link file. Returns its absolute path alongside the
+ * parsed contents, or null if there's no (valid) link file. A malformed file is
+ * treated as absent rather than throwing, so a stray/corrupt file can't wedge
+ * every command.
+ */
+export function readLinkFile(startDir = process.cwd(), homeDir = defaultHome()) {
+    const filePath = findLinkFile(startDir, homeDir);
+    if (!filePath)
+        return null;
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed.projectId !== "string" || !parsed.projectId) {
+            return null;
+        }
+        return { path: filePath, link: parsed };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write `.batadata/project.json` inside `dir` (creating `.batadata/` if needed)
+ * and return the absolute path written. `branchId` is normalized to null when
+ * absent so the file shape is stable.
+ */
+export function writeLinkFile(dir, link) {
+    const linkDir = path.join(path.resolve(dir), LINK_DIR);
+    fs.mkdirSync(linkDir, { recursive: true });
+    const filePath = path.join(linkDir, LINK_FILE);
+    const body = {
+        projectId: link.projectId,
+        branchId: link.branchId ?? null,
+    };
+    fs.writeFileSync(filePath, JSON.stringify(body, null, 2) + "\n", "utf-8");
+    return filePath;
+}
+/**
+ * Delete the nearest link file (and its now-empty `.batadata/` dir, if empty).
+ * Returns the path removed, or null if there was nothing to remove. Idempotent.
+ */
+export function removeLinkFile(startDir = process.cwd(), homeDir = defaultHome()) {
+    const filePath = findLinkFile(startDir, homeDir);
+    if (!filePath)
+        return null;
+    try {
+        fs.unlinkSync(filePath);
+        // Best-effort cleanup of an empty .batadata dir.
+        const linkDir = path.dirname(filePath);
+        if (path.basename(linkDir) === LINK_DIR && fs.readdirSync(linkDir).length === 0) {
+            fs.rmdirSync(linkDir);
+        }
+    }
+    catch {
+        // Already gone / racing removal — unlink is best-effort.
+    }
+    return filePath;
+}
+/**
+ * Pure precedence policy for the project id: flag > linked > config > none.
+ * No fs/env access, so the ordering is unit-testable in isolation (mirrors the
+ * `pickTeamId` pattern in api.ts).
+ */
+export function pickProjectId(params) {
+    if (params.flag)
+        return { projectId: params.flag, source: "flag" };
+    if (params.linked)
+        return { projectId: params.linked, source: "link" };
+    if (params.config)
+        return { projectId: params.config, source: "config" };
+    return { source: "none" };
+}
+/**
+ * Pure precedence policy for the branch id: flag > linked > none. There is no
+ * config-level default branch, so config isn't a source here.
+ */
+export function pickBranchId(params) {
+    if (params.flag)
+        return { branchId: params.flag, source: "flag" };
+    if (params.linked)
+        return { branchId: params.linked, source: "link" };
+    return { source: "none" };
+}
+/**
+ * Resolve the active project id from all sources in precedence order. `explicit`
+ * is an already-parsed `--project` value (or a positional id) — pass it through
+ * so a flag always wins over a link file or config default.
+ */
+export function resolveProjectId(explicit, opts = {}) {
+    const linked = readLinkFile(opts.startDir, opts.homeDir)?.link.projectId ?? null;
+    return pickProjectId({
+        flag: explicit,
+        linked,
+        config: loadConfig().defaultProject,
+    });
+}
+/**
+ * Resolve the active branch id from all sources in precedence order. `explicit`
+ * is an already-parsed `--branch` value (id or name); the link file's pinned
+ * branch is the fallback.
+ */
+export function resolveBranchId(explicit, opts = {}) {
+    const linked = readLinkFile(opts.startDir, opts.homeDir)?.link.branchId ?? null;
+    return pickBranchId({ flag: explicit, linked });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@batadata/cli",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "CLI for BataDB — serverless Postgres platform",
   "bin": {
     "bata": "./dist/index.js"