@hasna/mementos 0.14.86 → 0.14.88

package/dist/cli/global-options.d.ts

@@ -0,0 +1,27 @@
+import type { Command } from "commander";
+/**
+ * The program-level options, in one place.
+ *
+ * These are declared on the root `mementos` command, and commander resolves a
+ * short flag appearing AFTER a subcommand name to the parent's option. So any
+ * short flag listed here is claimed globally: a subcommand that declares the
+ * same short can never receive a value through it, no matter what `--help` says.
+ *
+ * That is not hypothetical. `save`/`update`/`list`/`recall`/... each declared
+ * `-s, --scope`, which `-s, --session` below shadowed. `mementos save k v -s
+ * shared` therefore wrote `session_id="shared"` and left scope at its default,
+ * while `--help` advertised `-s, --scope` — a documented flag that silently
+ * misrouted its value into a different column (HC-00149).
+ *
+ * Exported so the invariant can be enforced by a test instead of by review:
+ * see `global-options.test.ts`.
+ */
+export declare const GLOBAL_OPTIONS: ReadonlyArray<readonly [flags: string, description: string]>;
+/**
+ * Short flags no subcommand may reuse: the globals above plus commander's own
+ * built-ins (`-V` for --version, `-h` for --help).
+ */
+export declare function reservedShortFlags(): Set<string>;
+/** Apply the global options to the root program. */
+export declare function applyGlobalOptions(program: Command): Command;
+//# sourceMappingURL=global-options.d.ts.map

package/dist/cli/global-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-options.d.ts","sourceRoot":"","sources":["../../src/cli/global-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,CAMvF,CAAC;AAEF;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,GAAG,CAAC,MAAM,CAAC,CAOhD;AAED,oDAAoD;AACpD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAG5D"}

package/dist/cli/helpers.d.ts

@@ -0,0 +1,150 @@
+import type { Command } from "commander";
+import type { Memory, MemoryCategory, MemoryScope } from "../types/index.js";
+import type { Entity, EntityType } from "../types/index.js";
+export declare function getPackageVersion(): string;
+export declare function importanceColor(importance: number): (s: string) => string;
+export declare function colorScope(scope: MemoryScope): string;
+export declare function colorCategory(category: MemoryCategory): string;
+export declare function colorImportance(importance: number): string;
+export declare function colorEntityType(type: string, suffix?: string): string;
+export declare function resolveEntityArg(nameOrId: string, type?: EntityType): Entity;
+export declare function outputJson(data: unknown): void;
+export declare const DEFAULT_COMPACT_LIMIT = 20;
+export declare const DEFAULT_SEARCH_LIMIT = 10;
+export declare const DEFAULT_SNIPPET_LENGTH = 72;
+export declare function positiveIntOrDefault(value: unknown, fallback: number): number;
+export declare function cursorOrOffset(cursor: unknown, offset: unknown): number | undefined;
+export declare function truncateText(value: string | null | undefined, max?: number): string;
+export interface PagedFetchResult<T> {
+    rows: T[];
+    /**
+     * true = more rows exist; false = the end was reached; undefined = the
+     * server did not say (an older server without the pagination contract —
+     * the walk falls back to a short-page heuristic).
+     */
+    has_more: boolean | undefined;
+    next_cursor: number | null;
+}
+/**
+ * Collect rows across bounded pages (BUG 2796806b). The server caps every
+ * single response (1000 rows for list surfaces), so a request for more than
+ * one page — or for the full population — must walk pages.
+ *
+ * `target` is the number of rows the caller will display; the walk probes one
+ * row past it so `hasMore` is truthful and a "use --cursor N for more" hint is
+ * honest. With `target` undefined every matching row is collected.
+ *
+ * Guarded against cursor cycles and runaway page counts (mirrors the SDK's
+ * traversal guards). Termination: the server's `has_more: false`, or a page
+ * shorter than requested when the server carries no signal, or `target` rows
+ * collected.
+ */
+export declare function collectPagedRows<T>(fetchPage: (offset: number, limit: number) => PagedFetchResult<T>, target: number | undefined, offset: number, opts?: {
+    pageSize?: number;
+    maxPages?: number;
+}): {
+    rows: T[];
+    hasMore: boolean;
+};
+export declare function printPageHint(opts: {
+    shown: number;
+    limit: number;
+    offset?: number;
+    hasMore: boolean;
+    command: string;
+    detailHint?: string;
+}): void;
+/**
+ * Resolve output format from local command flag, global flag, or --json alias.
+ * Priority: localFmt > global --format > --json > "compact"
+ */
+export declare function getOutputFormat(program: Command, localFmt?: string): string;
+/**
+ * Simple YAML output — no library dependency.
+ * Arrays of objects: each item as `- key: value` block.
+ * Single objects: `key: value` per line.
+ */
+export declare function outputYaml(data: unknown): void;
+export declare function formatMemoryLine(m: Memory, opts?: {
+    valueLength?: number;
+    preferSummary?: boolean;
+}): string;
+export declare function formatMemoryDetail(m: Memory): string;
+export declare function makeHandleError(program: Command): (e: unknown) => never;
+export declare function resolveMemoryId(partialId: string): string;
+/**
+ * Resolve an `--agent` filter value to the agent id the store actually indexes.
+ *
+ * WHY THIS EXISTS. Every read command declared `--agent <name>` and then used
+ * the raw string as an agent ID. A registered NAME therefore matched nothing,
+ * and — because an empty list is a legal answer — the miss was reported as
+ * "No memories found." at rc=0 with empty stderr. A real name and a fabricated
+ * string produced byte-identical output, so no caller could tell an empty set
+ * from a mistyped one. The fleet's compliance check for the mementos-discipline
+ * rule is `list --agent <seat>`, which meant it reported every seat as
+ * non-compliant regardless of truth: a check that cannot pass.
+ *
+ * RESOLUTION IS DELEGATED, NOT REIMPLEMENTED. `getAgent` already does
+ * id -> case-insensitive name -> unique partial id (returning null when a
+ * partial is ambiguous), it is what the `save` path uses since #43, and it is
+ * MODE-AWARE — in API mode it resolves through `GET /agents/<value>` rather
+ * than SQL. A local-only lookup here would have worked on a developer box and
+ * failed on the fleet, which runs in API mode.
+ *
+ * ON A MISS: WARN AND PASS THE RAW VALUE THROUGH.
+ *
+ *   - WARN rather than THROW. The save path throws (#43) because there rc=0 was
+ *     illusory: the write silently landed in the unowned bucket and destroyed
+ *     what was there. A read filter destroys nothing, and callers legitimately
+ *     treat an empty list as a scriptable answer, so the sibling contract to
+ *     match is `todos list --assigned <bogus>`, which warns at rc=0. Same class,
+ *     opposite verb, deliberately different remedy.
+ *   - The warning goes to STDERR so `--format json` stays parseable on stdout.
+ *   - PASSING THE RAW VALUE THROUGH, rather than dropping the filter, is the
+ *     load-bearing half. Dropping it is what `search` and `info-stale` did, and
+ *     it WIDENS the query: an unresolvable agent then returns every agent's
+ *     rows. Zero rows is a visible failure; other agents' rows returned as
+ *     yours is an invisible one. Passing the raw value keeps the query narrow
+ *     and also cannot regress a caller whose id has no `agents` row — measured
+ *     0 such rows across 8340 memories at the time of the fix, but the store is
+ *     not frozen.
+ */
+export declare function resolveAgentFilter(nameOrId: string | undefined): string | undefined;
+/**
+ * Resolve a key-or-id argument to a Memory object.
+ * Tries key lookup first (with optional scope/agent/project filters), then partial ID.
+ */
+export declare function resolveKeyOrId(keyOrId: string, opts: {
+    scope?: string;
+    agent?: string;
+    project?: string;
+}, globalOpts: GlobalOpts): Memory | null;
+export declare function formatWatchLine(m: Memory): string;
+export declare function sendNotification(m: Memory): void;
+export interface GlobalOpts {
+    project?: string;
+    json?: boolean;
+    format?: string;
+    agent?: string;
+    session?: string;
+}
+export declare function diffLines(oldText: string, newText: string): void;
+export declare function diffMemory(memoryId: string, opts: {
+    version?: string;
+}, globalOpts: GlobalOpts): void;
+export declare const VALID_SCOPES: string[];
+export declare const VALID_CATEGORIES: string[];
+/** Navigate a nested object using dot-notation key path */
+export declare function getNestedValue(obj: Record<string, unknown>, path: string): unknown;
+/** Set a nested value using dot-notation key path */
+export declare function setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): void;
+/** Remove a nested key using dot-notation key path */
+export declare function deleteNestedKey(obj: Record<string, unknown>, path: string): void;
+/** Parse a CLI value: try JSON.parse for numbers/booleans/arrays, fall back to string */
+export declare function parseConfigValue(raw: string): unknown;
+/** Validate a config key/value pair against known constraints */
+export declare function validateConfigKeyValue(key: string, value: unknown, DEFAULT_CONFIG: unknown): string | null;
+export declare function getConfigPath(): string;
+export declare function readFileConfig(): Record<string, unknown>;
+export declare function writeFileConfig(data: Record<string, unknown>): void;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/cli/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/cli/helpers.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.tsx"],"names":[],"mappings":""}