@getfamiliar/shared 0.1.4 → 0.1.6

package/build/markdownOutput.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Escape a single value for use as a GitHub-flavoured-markdown table cell:
+ * backslashes stay literal, `|` no longer splits the column, and any
+ * newline collapses to a space so the row stays on one line. Backticks are
+ * left untouched so inline-code spans in a cell survive. Mirrors the
+ * escaping the `tools list --raw` renderer needs; that renderer's
+ * `escapeCell` delegates here so there is a single implementation.
+ *
+ * @param text - raw cell text
+ * @returns the text safe to drop between two `|` pipes
+ */
+export declare function escapeTableCell(text: string): string;
+/**
+ * Build a GitHub-flavoured-markdown table from a header row and body rows.
+ * Every cell is run through {@link escapeTableCell}. The result is meant to
+ * be handed to {@link writeMarkdown}, which renders it (cli-table3) on a TTY
+ * or emits it verbatim when piped.
+ *
+ * @param headers - column header labels
+ * @param rows - one string tuple per row; each row should have `headers.length` cells
+ * @returns a GFM table string terminated by a single newline
+ */
+export declare function markdownTable(headers: readonly string[], rows: readonly (readonly string[])[]): string;
+/**
+ * Write a markdown string to stdout as the single human-facing CLI/plugin
+ * output sink: ANSI-styled via {@link renderMarkdown} on a TTY, or the raw
+ * markdown verbatim when stdout is piped/redirected.
+ *
+ * The TTY check lives *inside* this function on purpose — no call site
+ * should read `process.stdout.isTTY` itself. A caller can only ever *force*
+ * raw output (e.g. to honour a `--raw` flag); it can never accidentally
+ * render box-drawing tables and ANSI escapes into a pipe.
+ *
+ * @param markdown - markdown source to emit
+ * @param opts - `raw: true` forces raw output even on a TTY; omitted/false lets the TTY check decide
+ */
+export declare function writeMarkdown(markdown: string, opts?: {
+    readonly raw?: boolean;
+}): void;

package/build/markdownOutput.js

@@ -0,0 +1,50 @@
+import { renderMarkdown } from "./markdownTerminal.js";
+/**
+ * Escape a single value for use as a GitHub-flavoured-markdown table cell:
+ * backslashes stay literal, `|` no longer splits the column, and any
+ * newline collapses to a space so the row stays on one line. Backticks are
+ * left untouched so inline-code spans in a cell survive. Mirrors the
+ * escaping the `tools list --raw` renderer needs; that renderer's
+ * `escapeCell` delegates here so there is a single implementation.
+ *
+ * @param text - raw cell text
+ * @returns the text safe to drop between two `|` pipes
+ */
+export function escapeTableCell(text) {
+    return text.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+/**
+ * Build a GitHub-flavoured-markdown table from a header row and body rows.
+ * Every cell is run through {@link escapeTableCell}. The result is meant to
+ * be handed to {@link writeMarkdown}, which renders it (cli-table3) on a TTY
+ * or emits it verbatim when piped.
+ *
+ * @param headers - column header labels
+ * @param rows - one string tuple per row; each row should have `headers.length` cells
+ * @returns a GFM table string terminated by a single newline
+ */
+export function markdownTable(headers, rows) {
+    const headerLine = `| ${headers.map(escapeTableCell).join(" | ")} |`;
+    const separator = `| ${headers.map(() => "---").join(" | ")} |`;
+    const body = rows.map((row) => `| ${row.map(escapeTableCell).join(" | ")} |`).join("\n");
+    return body.length > 0
+        ? `${headerLine}\n${separator}\n${body}\n`
+        : `${headerLine}\n${separator}\n`;
+}
+/**
+ * Write a markdown string to stdout as the single human-facing CLI/plugin
+ * output sink: ANSI-styled via {@link renderMarkdown} on a TTY, or the raw
+ * markdown verbatim when stdout is piped/redirected.
+ *
+ * The TTY check lives *inside* this function on purpose — no call site
+ * should read `process.stdout.isTTY` itself. A caller can only ever *force*
+ * raw output (e.g. to honour a `--raw` flag); it can never accidentally
+ * render box-drawing tables and ANSI escapes into a pipe.
+ *
+ * @param markdown - markdown source to emit
+ * @param opts - `raw: true` forces raw output even on a TTY; omitted/false lets the TTY check decide
+ */
+export function writeMarkdown(markdown, opts) {
+    const raw = opts?.raw === true || !process.stdout.isTTY;
+    process.stdout.write(raw ? markdown : renderMarkdown(markdown));
+}

package/build/markdownTerminal.js

@@ -39,7 +39,7 @@ import wrapAnsi from "wrap-ansi";
  */
 /** Upper bound on render width; full-width prose is hard to read on ultra-wide terminals. */
 const MAX_WIDTH = 180;
-/** Fallback width when stdout is not a TTY (no `columns`). */
+/** Fallback width when stdout reports no usable `columns` (not a TTY, or a degenerate 0-width pty). */
 const FALLBACK_WIDTH = 100;
 /** Floor on the content width at deep nesting, so wrapping never degenerates. */
 const MIN_CONTENT_WIDTH = 12;
@@ -369,7 +369,12 @@ function buildRenderer(width) {
  * @returns ANSI-styled terminal output
  */
 export function renderMarkdown(input) {
-    const width = Math.min(process.stdout.columns ?? FALLBACK_WIDTH, MAX_WIDTH);
+    // `columns` is undefined when stdout is not a TTY and can be a
+    // degenerate 0 under a zero-width pty (e.g. `script`); either way fall
+    // back to a healthy default rather than rendering into no space.
+    const columns = process.stdout.columns;
+    const usableWidth = typeof columns === "number" && columns > 0 ? columns : FALLBACK_WIDTH;
+    const width = Math.min(usableWidth, MAX_WIDTH);
     const marked = new Marked();
     marked.use({ renderer: buildRenderer(width) });
     return marked.parse(input);

package/build/testing/FakeStorageProvider.d.ts

@@ -0,0 +1,133 @@
+import { type StorageCapabilities, type StorageConflict, type StorageDownloadResult, type StorageDrive, type StorageItem, type StorageItemKind, type StorageListOrder, type StoragePage, type StoragePageOptions, type StorageProvider, type StorageSearchHit, type StorageSearchQuery, type StorageUploadSource } from "../Storage.js";
+/** Which real provider the fake imitates. */
+export type FakeStorageFlavor = "onedrive" | "gdrive" | "dropbox";
+/** Google-style native doc mime types and their export mapping. */
+export declare const FAKE_NATIVE_EXPORTS: Readonly<Record<string, {
+    mime: string;
+    ext: string;
+}>>;
+/** Behaviour knobs for tests. */
+export interface FakeStorageOptions {
+    readonly pluginId?: string;
+    readonly flavor?: FakeStorageFlavor;
+    /** Accounts and their drives (selector `null` = primary). Default: one account `a@x` with a primary drive. */
+    readonly accounts?: Readonly<Record<string, readonly {
+        selector: string | null;
+        name: string;
+    }[]>>;
+    /** Accounts whose calls throw `AuthExpired`. */
+    readonly expiredAccounts?: readonly string[];
+    /** Accounts whose `listDrives` throws `ProviderUnavailable`. */
+    readonly brokenAccounts?: readonly string[];
+    /** Artificial search latency (honours the abort signal). */
+    readonly searchDelayMs?: number;
+    /** Make every search throw this error. */
+    readonly searchError?: Error;
+    /** Override `contentSearch`. */
+    readonly contentSearch?: boolean;
+    /** Override `trash`. */
+    readonly trash?: boolean;
+}
+/**
+ * In-memory {@link StorageProvider} for service, tool, CLI and contract
+ * tests. Imitates OneDrive (path addressing, unique names), Google
+ * Drive (id addressing, duplicate names, native docs) or Dropbox
+ * (path addressing, no content search). Content lives in memory;
+ * download / upload still go through real host files so the byte paths
+ * are exercised.
+ */
+export declare class FakeStorageProvider implements StorageProvider {
+    readonly pluginId: string;
+    readonly flavor: FakeStorageFlavor;
+    private readonly drives;
+    private readonly options;
+    private nextId;
+    private clock;
+    /**
+     * @param options - Behaviour knobs; see {@link FakeStorageOptions}.
+     */
+    constructor(options?: FakeStorageOptions);
+    /** @returns The capabilities of the imitated provider. */
+    capabilities(_drive: StorageDrive): StorageCapabilities;
+    /** @returns All configured accounts. */
+    listAccounts(): Promise<readonly string[]>;
+    /** @returns A fake login command. */
+    loginCommand(account: string): string;
+    /** @returns The account's drives, filtered and capped. */
+    listDrives(account: string, options: {
+        readonly limit: number;
+        readonly search?: string;
+    }): Promise<readonly StorageDrive[]>;
+    /** @returns The drive for `selector`. */
+    openDrive(account: string, selector: string | null): Promise<StorageDrive>;
+    /** @returns The root folder id. */
+    rootRealId(drive: StorageDrive): Promise<string>;
+    /** @returns The item or `null`. */
+    stat(drive: StorageDrive, realId: string): Promise<StorageItem | null>;
+    /** Native path resolution (only for path-addressed flavors). */
+    get resolvePath(): ((drive: StorageDrive, path: string) => Promise<readonly StorageItem[]>) | undefined;
+    /** @returns One page of children. */
+    list(drive: StorageDrive, folderRealId: string, options: StoragePageOptions & {
+        readonly order?: StorageListOrder;
+    }): Promise<StoragePage<StorageItem>>;
+    /** @returns One page of name / content hits. */
+    search(drive: StorageDrive, query: StorageSearchQuery, options: StoragePageOptions): Promise<StoragePage<StorageSearchHit>>;
+    /** Write the bytes (or the native export) to `destPath`. */
+    download(drive: StorageDrive, realId: string, destPath: string): Promise<StorageDownloadResult>;
+    /** Upload from a host file with conflict / revision semantics. */
+    upload(drive: StorageDrive, parentRealId: string, name: string, source: StorageUploadSource, options: {
+        readonly conflict: StorageConflict;
+        readonly replaceRealId?: string;
+        readonly ifRevision?: string;
+    }): Promise<StorageItem>;
+    /** Create a folder. */
+    createFolder(drive: StorageDrive, parentRealId: string, name: string, options: {
+        readonly conflict: "fail" | "rename" | "reuse";
+    }): Promise<StorageItem>;
+    /** Move / rename. */
+    move(drive: StorageDrive, realId: string, target: {
+        readonly parentRealId?: string;
+        readonly name?: string;
+    }, options: {
+        readonly ifRevision?: string;
+    }): Promise<StorageItem>;
+    /** Server-side copy (files only in the fake). */
+    copy(drive: StorageDrive, realId: string, target: {
+        readonly parentRealId: string;
+        readonly name?: string;
+    }, options: {
+        readonly conflict: "fail" | "rename";
+    }): Promise<StorageItem>;
+    /** Soft delete (recursive). */
+    trash(drive: StorageDrive, realId: string, options: {
+        readonly ifRevision?: string;
+    }): Promise<void>;
+    /**
+     * Seed an item under `parentPath` (folders are created as needed).
+     * Duplicates are allowed for the gdrive flavor.
+     *
+     * @returns The seeded item's realId.
+     */
+    seed(account: string, selector: string | null, path: string, options?: {
+        kind?: StorageItemKind;
+        content?: string;
+        mimeType?: string;
+    }): string;
+    /** Test helper: raw content of an item, or `null`. */
+    contentOf(account: string, selector: string | null, realId: string): string | null;
+    /** Test helper: whether an item is in the trash. */
+    isTrashed(account: string, selector: string | null, realId: string): boolean;
+    private state;
+    private assertAccount;
+    private requireNode;
+    private requireFolder;
+    private checkRevision;
+    private children;
+    private childNamed;
+    private freeName;
+    private pathOf;
+    private toItem;
+    private makeNode;
+    private newId;
+    private tick;
+}