@ggui-ai/cli 0.1.0-rc.1

package/dist/paths.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Return the OSS CLI config directory.
+ *
+ * Resolution order:
+ *   1. `GGUI_CONFIG_DIR` env (if set + non-empty) — tests + clean-room.
+ *   2. `~/.ggui` (`os.homedir() + DIRNAME`) — operator default.
+ */
+export declare function getConfigDir(): string;
+/**
+ * Path to the BYOK credentials file. Written + read by the
+ * `PlaintextFileProviderKeyStore` from `@ggui-ai/mcp-server-core/plaintext`
+ * at the global app-scope (single-user personal-mode default).
+ *
+ * On-disk shape is `PlaintextFileProviderKeyStore`'s v1 document. Mode
+ * 0o600 is enforced by the store on every write.
+ */
+export declare function getCredentialsFile(): string;
+/**
+ * Path to the CLI auth-session file. Written by `ggui login` after a
+ * successful device-flow exchange against `api.ggui.ai`; read by every
+ * authenticated command (`whoami`, `keys *`).
+ *
+ * On-disk shape is `AuthSessionDocument` from `./lib/auth-store.ts`.
+ * Mode 0o600 is enforced by the store on every write — the access +
+ * refresh tokens are bearer secrets equivalent to a short-lived
+ * password.
+ */
+export declare function getAuthFile(): string;
+/**
+ * Path to the local-embedding model cache. Resolution order matches
+ * the OSS full-generation port plan (§2.B + §7.2):
+ *
+ *   1. `GGUI_EMBEDDING_CACHE_DIR` env — operator override (CI, custom
+ *      mounts, shared NFS).
+ *   2. `~/.ggui/models` — first-run default. Owned by ggui to avoid
+ *      polluting the operator's `~/.cache/huggingface` cache.
+ *
+ * Returned even when the directory does not exist on disk — the
+ * embedding bootstrap creates it on first warmup.
+ */
+export declare function getEmbeddingCacheDir(): string;
+/**
+ * Path to the content-addressable componentCode cache. Used by
+ * `FileSystemCodeStore` when wired as the OSS dev default.
+ *
+ * Resolution order:
+ *   1. `GGUI_CODE_CACHE_DIR` env — operator override.
+ *   2. `~/.ggui/code-cache` — first-run default.
+ *
+ * The store creates the directory lazily on first put; the path is
+ * safe to return even when nothing has been written yet. Operators
+ * who want to reset the cache can `rm -rf` this directory at any
+ * time — every entry is content-addressable + immutable, so a
+ * re-fetch repopulates from upstream code on next push.
+ */
+export declare function getCodeCacheDir(): string;
+/**
+ * Directory backing the `--persistent` bundle (sessions.sqlite,
+ * short-codes.sqlite, bootstrap-secret.hex, render-signer-secret.hex,
+ * keys.json …). Survives `ggui serve` restarts so claude.ai chat-history
+ * revisits can rehydrate the iframe instead of seeing four cascading
+ * failures (HMAC + shortCode + session + pairing).
+ *
+ * Resolution order:
+ *   1. `GGUI_PERSISTENT_DIR` env — operator override (tests, clean-room,
+ *      shared mount).
+ *   2. `<projectRoot>/.ggui/persistent` — when the CLI resolved a
+ *      ggui.json. Per-project isolation; different projects get
+ *      separate sessions even on the same machine.
+ *   3. `~/.ggui/persistent` — fallback when there's no manifest
+ *      (`ggui serve` from a bare directory).
+ *
+ * Returned even when the directory doesn't exist on disk — the
+ * persistence wiring creates parents on first write.
+ */
+export declare function getPersistentDir(projectRoot?: string | null): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAkBA;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAIrC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAI7C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAIxC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAOpE"}

package/dist/paths.js

@@ -0,0 +1,119 @@
+/**
+ * Centralized path helpers for the open `@ggui-ai/cli` (`ggui`).
+ *
+ * The OSS dirstub lives at `~/.ggui/`. All CLI-managed state
+ * (credentials, embedding cache, code cache, persistent bundle) is
+ * rooted under this single directory.
+ *
+ * Override the dir via `GGUI_CONFIG_DIR` env so tests + clean-room
+ * harnesses can scope the store to a temp dir without touching the
+ * operator's HOME. The override is read on every call (no module-level
+ * cache) so process-level env mutations between calls take effect —
+ * matters for vitest suites that mutate `process.env` per test.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const DIRNAME = '.ggui';
+/**
+ * Return the OSS CLI config directory.
+ *
+ * Resolution order:
+ *   1. `GGUI_CONFIG_DIR` env (if set + non-empty) — tests + clean-room.
+ *   2. `~/.ggui` (`os.homedir() + DIRNAME`) — operator default.
+ */
+export function getConfigDir() {
+    const override = process.env['GGUI_CONFIG_DIR'];
+    if (override && override.length > 0)
+        return override;
+    return join(homedir(), DIRNAME);
+}
+/**
+ * Path to the BYOK credentials file. Written + read by the
+ * `PlaintextFileProviderKeyStore` from `@ggui-ai/mcp-server-core/plaintext`
+ * at the global app-scope (single-user personal-mode default).
+ *
+ * On-disk shape is `PlaintextFileProviderKeyStore`'s v1 document. Mode
+ * 0o600 is enforced by the store on every write.
+ */
+export function getCredentialsFile() {
+    return join(getConfigDir(), 'credentials.json');
+}
+/**
+ * Path to the CLI auth-session file. Written by `ggui login` after a
+ * successful device-flow exchange against `api.ggui.ai`; read by every
+ * authenticated command (`whoami`, `keys *`).
+ *
+ * On-disk shape is `AuthSessionDocument` from `./lib/auth-store.ts`.
+ * Mode 0o600 is enforced by the store on every write — the access +
+ * refresh tokens are bearer secrets equivalent to a short-lived
+ * password.
+ */
+export function getAuthFile() {
+    return join(getConfigDir(), 'auth.json');
+}
+/**
+ * Path to the local-embedding model cache. Resolution order matches
+ * the OSS full-generation port plan (§2.B + §7.2):
+ *
+ *   1. `GGUI_EMBEDDING_CACHE_DIR` env — operator override (CI, custom
+ *      mounts, shared NFS).
+ *   2. `~/.ggui/models` — first-run default. Owned by ggui to avoid
+ *      polluting the operator's `~/.cache/huggingface` cache.
+ *
+ * Returned even when the directory does not exist on disk — the
+ * embedding bootstrap creates it on first warmup.
+ */
+export function getEmbeddingCacheDir() {
+    const override = process.env['GGUI_EMBEDDING_CACHE_DIR'];
+    if (override && override.length > 0)
+        return override;
+    return join(getConfigDir(), 'models');
+}
+/**
+ * Path to the content-addressable componentCode cache. Used by
+ * `FileSystemCodeStore` when wired as the OSS dev default.
+ *
+ * Resolution order:
+ *   1. `GGUI_CODE_CACHE_DIR` env — operator override.
+ *   2. `~/.ggui/code-cache` — first-run default.
+ *
+ * The store creates the directory lazily on first put; the path is
+ * safe to return even when nothing has been written yet. Operators
+ * who want to reset the cache can `rm -rf` this directory at any
+ * time — every entry is content-addressable + immutable, so a
+ * re-fetch repopulates from upstream code on next push.
+ */
+export function getCodeCacheDir() {
+    const override = process.env['GGUI_CODE_CACHE_DIR'];
+    if (override && override.length > 0)
+        return override;
+    return join(getConfigDir(), 'code-cache');
+}
+/**
+ * Directory backing the `--persistent` bundle (sessions.sqlite,
+ * short-codes.sqlite, bootstrap-secret.hex, render-signer-secret.hex,
+ * keys.json …). Survives `ggui serve` restarts so claude.ai chat-history
+ * revisits can rehydrate the iframe instead of seeing four cascading
+ * failures (HMAC + shortCode + session + pairing).
+ *
+ * Resolution order:
+ *   1. `GGUI_PERSISTENT_DIR` env — operator override (tests, clean-room,
+ *      shared mount).
+ *   2. `<projectRoot>/.ggui/persistent` — when the CLI resolved a
+ *      ggui.json. Per-project isolation; different projects get
+ *      separate sessions even on the same machine.
+ *   3. `~/.ggui/persistent` — fallback when there's no manifest
+ *      (`ggui serve` from a bare directory).
+ *
+ * Returned even when the directory doesn't exist on disk — the
+ * persistence wiring creates parents on first write.
+ */
+export function getPersistentDir(projectRoot) {
+    const override = process.env['GGUI_PERSISTENT_DIR'];
+    if (override && override.length > 0)
+        return override;
+    if (projectRoot && projectRoot.length > 0) {
+        return join(projectRoot, DIRNAME, 'persistent');
+    }
+    return join(getConfigDir(), 'persistent');
+}

package/dist/persistent-secrets.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Read a hex-encoded HMAC secret from `filename`. If the file doesn't
+ * exist (ENOENT), mint a fresh 32-byte secret, write it with mode 0600,
+ * and return the hex string.
+ *
+ * Concurrency: the write is atomic — a fresh secret is written to a
+ * sibling temp file with `O_CREAT | O_WRONLY` and then `rename(2)`'d
+ * into place. POSIX guarantees `rename` is atomic on the same
+ * filesystem, so two `ggui serve` processes racing on the same
+ * persistent dir can't tear the file at a byte boundary; the loser's
+ * rename overwrites the winner's. Both processes then re-read the
+ * same surviving value on next boot — last-writer-wins on the secret
+ * itself, never partial-write corruption. (Two processes simultaneously
+ * minting fresh secrets is already a degenerate case for a per-user
+ * persistent dir.)
+ *
+ * Throws on:
+ *   - read errors other than ENOENT (permission denied, EISDIR, etc.)
+ *   - write errors (mkdir / writeFile / rename)
+ *   - on-disk content that isn't a 64-char hex string (corrupt secret)
+ *
+ * The throw-on-corrupt branch is deliberate: silently re-minting would
+ * invalidate every outstanding token without telling the operator.
+ * Better to fail loud so the operator can diagnose (manual edit?) and
+ * decide whether to delete and accept the cost.
+ */
+export declare function readOrMintHexSecret(filename: string): string;
+//# sourceMappingURL=persistent-secrets.d.ts.map

package/dist/persistent-secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistent-secrets.d.ts","sourceRoot":"","sources":["../src/persistent-secrets.ts"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA4B5D"}

package/dist/persistent-secrets.js

@@ -0,0 +1,94 @@
+/**
+ * Read-or-mint helpers for HMAC secrets that MUST survive a `ggui serve`
+ * restart.
+ *
+ * Background: `createGguiServer` mints two HMAC secrets at boot when the
+ * caller doesn't pass them — `bootstrapSecret` (signs MCP Apps `_meta.
+ * ggui.bootstrap.token` so iframes can subscribe to the live-channel WS)
+ * and the render-URL signer secret (signs `/r/<code>?sig=&exp=`). Both
+ * are process-local `randomBytes(32)` by default — fine for a single
+ * process lifetime, fatal for "revisit a claude.ai chat history after a
+ * restart": the cached bootstrap token + cached render URL fail HMAC
+ * verify against the freshly-minted secret.
+ *
+ * Persisting the secrets to a 0600-mode file makes those tokens valid
+ * across restarts, which is the precondition for any rehydrate path
+ * working at all. The file format is intentionally tiny: 64 chars of
+ * lowercase hex (32 bytes), no trailing newline, no JSON wrapper. Easy
+ * to inspect, easy to rotate (delete the file, restart, fresh secret).
+ *
+ * Security posture: these secrets are a session-token signing key, NOT
+ * a long-lived credential like an OAuth client secret. Losing them
+ * means an attacker can mint MCP Apps bootstrap tokens for arbitrary
+ * `(sessionId, appId)` pairs — same blast radius as before, just
+ * surviving restart. Mode 0600 on the file matches `~/.ggui/credentials
+ * .json` (BYOK keys) which has the same threat model.
+ *
+ * Caller composes the path; this module is pure I/O over a given
+ * filename so tests can scope to a tmpdir.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { dirname, join } from 'node:path';
+/**
+ * Read a hex-encoded HMAC secret from `filename`. If the file doesn't
+ * exist (ENOENT), mint a fresh 32-byte secret, write it with mode 0600,
+ * and return the hex string.
+ *
+ * Concurrency: the write is atomic — a fresh secret is written to a
+ * sibling temp file with `O_CREAT | O_WRONLY` and then `rename(2)`'d
+ * into place. POSIX guarantees `rename` is atomic on the same
+ * filesystem, so two `ggui serve` processes racing on the same
+ * persistent dir can't tear the file at a byte boundary; the loser's
+ * rename overwrites the winner's. Both processes then re-read the
+ * same surviving value on next boot — last-writer-wins on the secret
+ * itself, never partial-write corruption. (Two processes simultaneously
+ * minting fresh secrets is already a degenerate case for a per-user
+ * persistent dir.)
+ *
+ * Throws on:
+ *   - read errors other than ENOENT (permission denied, EISDIR, etc.)
+ *   - write errors (mkdir / writeFile / rename)
+ *   - on-disk content that isn't a 64-char hex string (corrupt secret)
+ *
+ * The throw-on-corrupt branch is deliberate: silently re-minting would
+ * invalidate every outstanding token without telling the operator.
+ * Better to fail loud so the operator can diagnose (manual edit?) and
+ * decide whether to delete and accept the cost.
+ */
+export function readOrMintHexSecret(filename) {
+    let existing = null;
+    try {
+        existing = readFileSync(filename, 'utf8').trim();
+    }
+    catch (err) {
+        if (!isEnoent(err))
+            throw err;
+    }
+    if (existing !== null) {
+        if (!HEX_64.test(existing)) {
+            throw new Error(`[ggui-cli] persistent secret at ${filename} is corrupt — expected ` +
+                `64 lowercase hex chars (32 bytes), got ${existing.length} chars. ` +
+                `Delete the file to re-mint a fresh secret (this will invalidate ` +
+                `every outstanding token).`);
+        }
+        return existing;
+    }
+    const minted = randomBytes(32).toString('hex');
+    const parent = dirname(filename);
+    mkdirSync(parent, { recursive: true });
+    // Atomic write: pid-suffixed temp file in the same dir, then rename
+    // into place. Same-filesystem rename is atomic on POSIX, so a racing
+    // boot from another process can't observe a half-written secret.
+    const tmp = join(parent, `${filename.split('/').pop()}.tmp-${process.pid}`);
+    writeFileSync(tmp, minted, { mode: 0o600, encoding: 'utf8' });
+    renameSync(tmp, filename);
+    return minted;
+}
+const HEX_64 = /^[0-9a-f]{64}$/;
+function isEnoent(err) {
+    return (typeof err === 'object'
+        && err !== null
+        && 'code' in err
+        && err.code === 'ENOENT');
+}

package/dist/persistent-short-code-index.d.ts

@@ -0,0 +1,14 @@
+import type { ShortCodeIndex } from '@ggui-ai/mcp-server-core';
+/**
+ * Construct the persistent ShortCodeIndex backed by `<persistentDir>/
+ * short-codes.sqlite`. Creates the parent dir if missing (the persistent
+ * dir always exists by the time this is called — the secrets helper
+ * already mkdir'd it — but mkdir is idempotent and cheap).
+ *
+ * Throws if `better-sqlite3` can't be loaded (e.g. native binding
+ * missing for the current platform). The CLI surfaces this as a fatal
+ * boot error so the operator can either install the binding or pass
+ * `--ephemeral`.
+ */
+export declare function createPersistentShortCodeIndex(persistentDir: string): Promise<ShortCodeIndex>;
+//# sourceMappingURL=persistent-short-code-index.d.ts.map

package/dist/persistent-short-code-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistent-short-code-index.d.ts","sourceRoot":"","sources":["../src/persistent-short-code-index.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,wBAAsB,8BAA8B,CAClD,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,cAAc,CAAC,CAQzB"}

package/dist/persistent-short-code-index.js

@@ -0,0 +1,39 @@
+/**
+ * Resolve a persistent `ShortCodeIndex` for `ggui serve`.
+ *
+ * The OSS default for `shortCodeIndex` is `InMemoryShortCodeIndex` —
+ * the mapping lives in process memory and a restart drops every
+ * binding, so `/r/<code>` + `/api/bootstrap/<code>` 404 on the cached
+ * envelopes claude.ai stored before the restart.
+ *
+ * When the CLI is running in persistent mode (no `--ephemeral`), this
+ * helper constructs a `SqliteShortCodeIndex` against
+ * `<persistentDir>/short-codes.sqlite` so the same lookups survive
+ * restart. better-sqlite3 is dynamic-imported (same pattern as
+ * `@ggui-ai/mcp-server::resolveStorageFromConfig`) so consumers that
+ * stay ephemeral don't pay the N-API binding load on boot.
+ *
+ * Caller composes the path; this module is pure construction over a
+ * given dir + better-sqlite3 dynamic-import, so tests can scope to a
+ * tmpdir.
+ */
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Construct the persistent ShortCodeIndex backed by `<persistentDir>/
+ * short-codes.sqlite`. Creates the parent dir if missing (the persistent
+ * dir always exists by the time this is called — the secrets helper
+ * already mkdir'd it — but mkdir is idempotent and cheap).
+ *
+ * Throws if `better-sqlite3` can't be loaded (e.g. native binding
+ * missing for the current platform). The CLI surfaces this as a fatal
+ * boot error so the operator can either install the binding or pass
+ * `--ephemeral`.
+ */
+export async function createPersistentShortCodeIndex(persistentDir) {
+    mkdirSync(persistentDir, { recursive: true });
+    const { SqliteShortCodeIndex } = await import('@ggui-ai/mcp-server-core/sqlite');
+    return new SqliteShortCodeIndex({
+        filename: join(persistentDir, 'short-codes.sqlite'),
+    });
+}

package/dist/persistent-stores.d.ts

@@ -0,0 +1,12 @@
+import type { SessionStore, VectorStore } from '@ggui-ai/mcp-server-core';
+export declare function createPersistentSessionStore(persistentDir: string): Promise<SessionStore>;
+export declare function createPersistentVectorStore(persistentDir: string): Promise<VectorStore>;
+/**
+ * Compute the auto-default `keysFile` path. Returns `undefined` when
+ * the caller wants ephemeral pairing (the operator already passed
+ * `--keys-file` explicitly, or `--ephemeral` is on). The CLI uses
+ * this to honour explicit operator paths while still providing a
+ * survives-restart default in the common case.
+ */
+export declare function defaultKeysFile(persistentDir: string): string;
+//# sourceMappingURL=persistent-stores.d.ts.map

package/dist/persistent-stores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistent-stores.d.ts","sourceRoot":"","sources":["../src/persistent-stores.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAElC,wBAAsB,4BAA4B,CAChD,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,YAAY,CAAC,CAQvB;AAED,wBAAsB,2BAA2B,CAC/C,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,CAAC,CAQtB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE7D"}

package/dist/persistent-stores.js

@@ -0,0 +1,42 @@
+/**
+ * Default-on persistent stores under `<persistentDir>/`. Used when the
+ * operator hasn't declared `storage.sessions` / `storage.vectors` in
+ * `ggui.json` AND hasn't passed `--ephemeral`. Closes the SessionStore
+ * leg of the rehydrate problem: without this, a restart drops every
+ * session row even though the HMAC secret + ShortCodeIndex now persist.
+ *
+ * Override precedence (caller enforces):
+ *   1. Explicit `ggui.json#storage.sessions` / `.vectors`   (user wins)
+ *   2. These defaults                                       (operator-friendly)
+ *   3. In-memory (`createGguiServer`'s internal fallback)   (last resort)
+ *
+ * `better-sqlite3` is dynamic-imported (same pattern as the storage
+ * resolver in `@ggui-ai/mcp-server`) so `--ephemeral` runs don't pay
+ * the N-API binding load.
+ */
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+export async function createPersistentSessionStore(persistentDir) {
+    mkdirSync(persistentDir, { recursive: true });
+    const { SqliteSessionStore } = await import('@ggui-ai/mcp-server-core/sqlite');
+    return new SqliteSessionStore({
+        filename: join(persistentDir, 'sessions.sqlite'),
+    });
+}
+export async function createPersistentVectorStore(persistentDir) {
+    mkdirSync(persistentDir, { recursive: true });
+    const { SqliteVectorStore } = await import('@ggui-ai/mcp-server-core/sqlite');
+    return new SqliteVectorStore({
+        filename: join(persistentDir, 'vectors.sqlite'),
+    });
+}
+/**
+ * Compute the auto-default `keysFile` path. Returns `undefined` when
+ * the caller wants ephemeral pairing (the operator already passed
+ * `--keys-file` explicitly, or `--ephemeral` is on). The CLI uses
+ * this to honour explicit operator paths while still providing a
+ * survives-restart default in the common case.
+ */
+export function defaultKeysFile(persistentDir) {
+    return join(persistentDir, 'keys.json');
+}