@productbrain/cli 0.1.0-beta.29 → 0.1.0-beta.32

package/README.md

@@ -1,230 +1,114 @@
 # Product Brain CLI (`pb`)
 
-CLI for Chain knowledge: read, search, gather context, and **write back**. Uses your Product Brain API key (same as MCP). Write commands require a readwrite key.
+Chain knowledge + write-back in the terminal. Read, search, capture, and update your product knowledge graph.
 
-**Requirements:** Node 18+, API key from Product Brain → Settings → API Keys (`pb_sk_*`).
-
----
+**Requirements:** Node 18+, API key from Product Brain Settings (`pb_sk_*`).
 
 ## Install
 
-### From npm (beta)
-
 ```bash
 npm install -g @productbrain/cli@beta
 ```
 
-**IDE MCP (Cursor, Claude Desktop, VS Code):** `npx @productbrain/mcp@beta setup` — [Install — MCP and CLI](../../docs/surfaces/INSTALL.md).
-
-Updates require a new publish to npm (and, if you use 2FA, a one-time password). Use this when you want a stable beta from the registry.
-
-### From main (no publish needed)
-
-If you have the repo and want **latest from `main`** without publishing to npm:
+From source (latest main):
 
 ```bash
 git clone https://github.com/synergyai-os/Product-OS.git
-cd Product-OS
-npm ci
+cd Product-OS && npm ci
 cd packages/cli && npm run build && npm install -g .
 ```
 
-After that, `pb` runs from your global path. Pull and re-run the last two commands to update:
+## Login
 
 ```bash
-cd Product-OS && git pull && cd packages/cli && npm run build && npm install -g .
+pb login
 ```
 
-See [Deployment strategy — CLI vs MCP](../../docs/deployment-strategy.md#cli-vs-mcp-distribution) for why this avoids `cli:publish` / OTP.
-
----
-
-## First run
+Paste your API key (`pb_sk_...`). Saved to `~/.config/productbrain/.env`.
 
-- **No key yet:** Run any command (e.g. `pb orient -b`). You’ll get a short guided flow: “Do you have an API key? (y/n)” → paste key → saved to `~/.config/productbrain/.env`. Your command then runs.
-- **Or:** Run `pb login` to paste and save your key once. Get a key: Product Brain app → Settings → API Keys.
+Or run any command without a key and follow the guided flow.
 
-Config is read from (in order): env vars → `~/.config/productbrain/.env` → `.env.mcp` in the current directory.
+## Quick Start
 
-## Terminal-native contract
-
-Use `pb` with two explicit modes:
-
-- **Read mode** for `orient`, `get`, `search`, `context`, and repo grounding
-- **Write mode** for `capture`, `relate`, `update`, and other Chain writes
+```bash
+# 1. Check your setup
+pb doctor
 
-The Chain is the live source of truth. Generated files such as `AGENTS.md`, `.productbrain/context.md`, `.productbrain/briefing.md`, and `.codex/skills/*` are local projections for grounding, not the authoring source.
+# 2. Orient — see where things stand
+pb orient -b
 
-In non-TTY usage, `pb` defaults to machine-readable JSON. Use `--json` to force JSON and `--pretty` to force human formatting.
+# 3. Read an entry
+pb get BET-123
 
-Recommended default loop:
+# 4. Search the Chain
+pb search "onboarding flow"
 
-```bash
-pb orient -b
-pb get <ID>
-# read projected repo context as needed
-pb session start   # only when entering write-heavy work
-pb capture "INS: ..."
+# 5. Start a write session and capture knowledge
+pb session start
+pb capture "DEC: chose X because Y"
+pb capture "TEN: blocked by missing API"
 pb session close
 ```
 
-Projected files such as `AGENTS.md`, `.productbrain/context.md`, and `.productbrain/briefing.md` are startup aids and mirrors. Use live `pb` reads when you need current truth from the Chain.
-
-### Recommended terminal-native startup loop
-
-1. `pb orient -b`
-2. `pb get <ID>` before bet-, decision-, or standard-scoped implementation
-3. read projected repo context (`AGENTS.md`, `.productbrain/context.md`, `.productbrain/briefing.md`)
-4. stay in read mode while exploring
-5. `pb session start` only when you are entering write-heavy work
-6. `pb capture ...`
-7. `pb session close`
-
----
+Running `pb` with no arguments shows contextual guidance based on your setup state.
 
 ## Commands
 
 ### Read (no session required)
 
 | Command | Description |
-|--------|-------------|
-| `pb orient` | Workspace stage, bets, governance, tensions. Use `-b` for a brief view. |
-| `pb search <query>` | Full-text search across the Chain. |
-| `pb get <entry-id>` | Full entry (data, relations, last 10 history events). |
-| `pb context <entry-id>` | Constellation context (pipe-friendly markdown when not a TTY). |
-| `pb handshake` | Generate context files for AI developer tools. See below. |
-| `pb login` | Save your API key to `~/.config/productbrain/.env`. |
-
-Read mode is the default for grounding, repo tracing, and spec lookup. Do not start a write session until you actually intend to write back to the Chain.
-
-**Internal (Product-OS repo only):** `pb brand-pack` forwards to `scripts/brand-pack.mjs` — structured community marketing JSON via **OpenRouter** (`OPENROUTER_API_KEY`, not the Product Brain API key). Use `npm run brand-pack -- --help` from repo root for script options. Not published behavior for global npm installs unless built from this monorepo.
-
-### Write (session required — DEC-9)
+|---------|-------------|
+| `pb orient [-b]` | Workspace overview. `-b` for brief, `--task` for task-grounded context. |
+| `pb get <id>` | Full entry: data, relations, history. |
+| `pb search <query>` | Full-text search across all collections. |
+| `pb context <id>` | Constellation context for an entry. |
+| `pb fields <collection>` | Field definitions for a collection. |
+| `pb constellation <id>` | Entry + all related entries grouped by relation type. |
+| `pb collections list` | All collections with field counts. |
+| `pb glossary` | Key Product Brain CLI terms. |
+| `pb doctor` | Check configuration and connectivity. |
+
+### Write (session required)
 
 | Command | Description |
-|--------|-------------|
-| `pb session start` | Open a tracked write session. Refreshes context files. |
-| `pb capture "<text>"` | Capture a decision, tension, insight, or any knowledge to the Chain. Auto-classifies. |
-| `pb session close` | Close the session. Shows captured entries, runs wrapup, refreshes context. |
-
-`pb --help` for options.
-
-### Mixed-surface switching
-
-If you use Codex, Cursor, or Claude on the same stretch of work:
-
-1. let one surface own writes at a time
-2. let other surfaces read freely
-3. close the current write stretch before a different surface becomes the writer
-
-Do not treat force-close or overlapping write sessions as normal workflow. The goal is clear attribution, not concurrent write ownership.
-
-### Delivery + Chain (when you ship code in Product-OS)
-
-Progressive delivery and deploy ordering are documented in the monorepo — not inside the `pb` binary:
+|---------|-------------|
+| `pb session start` | Open a tracked write session. |
+| `pb capture "<text>"` | Capture knowledge. Auto-classifies to the right collection. |
+| `pb update <id>` | Update fields on an existing entry. |
+| `pb relate <from> <type> <to>` | Add a typed relation between entries. |
+| `pb promote <id>` | Promote entry from draft to active. |
+| `pb session close` | Close session, show summary. |
 
-| SSOT | Purpose |
-|------|---------|
-| [`docs/system/design/progressive-delivery-thesis.md`](../../docs/system/design/progressive-delivery-thesis.md) | Ladder (dark launch → GA), rollback (**STA-10**), flags, edge/Cloudflare notes |
-| **MAP-13** on the Chain | Map entry pointing at the thesis — `pb get MAP-13` / `pb context MAP-13` |
-| [`docs/deployment-strategy.md`](../../docs/deployment-strategy.md) | CI target, Convex vs Railway, CLI vs MCP distribution |
+### Profile Management
 
-**BR-157:** If your push includes changes under `convex/`, run **`npx convex deploy`** (correct deployment) **before** `git push origin main` so Railway never serves a frontend that calls missing Convex functions.
-
-**Typical ship loop with `pb`:**
+Config is read from (in order): environment variables, `~/.config/productbrain/.env`, `.env.mcp` in the current directory.
 
 ```bash
-pb session start
-# … commit, merge, push per .productbrain/skills/commit-to-main …
-pb capture "DEC: Shipped <short>. Rollback: <flag OFF | Railway revert | …>. Convex deploy before push: <yes | N/A>."
-pb session close
-# If you changed .productbrain rules or skills:
-cd ../.. && pb handshake   # from repo root
+pb login          # Save API key
+pb doctor         # Verify configuration
+pb setup          # Guided first-time setup
 ```
 
----
-
-## `pb handshake` — AI Developer Onboarding
-
-One command generates context files for every major AI coding tool:
-
-```bash
-pb handshake
-```
-
-**What it generates:**
-
-| File | Purpose |
-|------|---------|
-| `AGENTS.md` | Adapter for Codex / terminal-native agents |
-| `.codex/skills/*.md` | Product Brain skill projections for Codex |
-| `.productbrain/context.md` | Workspace briefing — stage, bets, governance, architecture, tensions |
-| `.productbrain/briefing.md` | Chain entries matched to this specific repo |
-| `CLAUDE.md` | Adapter for Claude Code |
-| `.cursor/rules/chain.mdc` | Adapter for Cursor |
-| `.github/copilot-instructions.md` | Adapter for GitHub Copilot |
-
-**Options:**
-
-- `--force` — Overwrite adapter files even if they have custom content
-- `--dry-run` — Preview what would be generated without writing files
-
-**Safety:** Adapter files are marked with `auto-generated by pb handshake`. If you customize one and remove the marker, future runs skip it (unless `--force`). The `.productbrain/` directory contains workspace-specific context and should be in `.gitignore`.
-
-**Governance:** Context export surface per DEC-161 and GLO-63. Architecture: ARCH-63 (surfaces are peers consuming the kernel).
-
-Projected files are adapters and mirrors, not the authoring source of truth. Use live `pb` reads when you need current Chain truth or are verifying governed product behavior.
-
----
-
-## `pb session` + `pb capture` — Close the Loop
-
-The Chain compounds from every AI coding session. Instead of knowledge dying in chat transcripts (TEN-27), capture it as you work.
-
-### Flow
+### AI Developer Onboarding
 
 ```bash
-# Start of session
-pb session start          # opens session, refreshes context
-
-# During work — capture what you learn
-pb capture "TEN: topology query returns stale containers when initiatives are archived"
-pb capture "DEC: excluded archived initiatives at the query level, not the UI filter"
-pb capture "INS: learned that the containerIds array references soft-deleted entries"
-
-# End of session
-pb session close          # shows summary, runs wrapup, refreshes context
+pb handshake      # Generate context files for Codex, Cursor, Claude, Copilot
 ```
 
-### How capture works
-
-1. Text is sent to the Chain's classification pipeline — auto-assigns collection
-2. Entry is created as a **draft** (nothing auto-commits)
-3. Receipt shows: entry ID, collection, confidence, reasoning, alternatives
-4. You review and commit drafts in Product Brain Studio
-
-### Options
-
-- `pb capture --collection tensions "text"` — skip auto-classification, use explicit collection
-- `pb capture --name "Short title" --description "Full explanation"` — separate name and description
-- `pb session close --force` — clear local session state even if server close fails
-
-### Governance
-
-- Write access requires a tracked session (DEC-9, BR-8)
-- Session attribution via API key; `clientKind: 'cli'` discriminator per DEC-184 (pending schema extension)
-- All captures are drafts — human reviews and commits (TEN-374)
-- Solves TEN-264 (CLI write access session attribution) with explicit session token in `.productbrain/session.json`
-- Addresses TEN-27 (strategic conversations generate decisions that never reach the Chain)
-- Implements INS-80 (proactive capture during coding)
+Generates `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/chain.mdc`, `.productbrain/context.md`, and more.
 
-## JSON output contract
+## Output Modes
 
-`pb` treats output mode as part of the terminal-native surface contract:
+| Context | Output |
+|---------|--------|
+| TTY (terminal) | Human-readable formatting |
+| Piped / non-TTY | JSON |
+| `--json` | Force JSON |
+| `--pretty` | Force human-readable |
 
-- non-TTY output defaults to JSON
-- TTY output defaults to human-readable formatting
-- `--json` forces machine-readable JSON
-- `--pretty` forces human-readable output even when piped
+## Reference
 
-For automation, prefer calling `pb` directly instead of wrappers that add extra stdout noise. Changes to output shape should be treated as compatibility-sensitive for machine consumers.
+- `pb --help` for full command list
+- `pb <command> --help` for command-specific options
+- `pb glossary` for key terms
+- Chain: WP-302 (CLI Maturity)

package/dist/__tests__/constants.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=constants.test.d.ts.map

package/dist/__tests__/constants.test.d.ts.map

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

package/dist/__tests__/constants.test.js

@@ -0,0 +1,94 @@
+/**
+ * constants — unit tests.
+ * WP-301 Slice 0: Verify DEFAULT_SITE_URL, resolveSiteUrl(), resolveAppUrl(), isDevMode().
+ */
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { DEFAULT_SITE_URL, resolveSiteUrl, resolveAppUrl, isDevMode } from '../lib/constants.js';
+describe('DEFAULT_SITE_URL', () => {
+    it('is the production Convex site URL', () => {
+        expect(DEFAULT_SITE_URL).toBe('https://gateway.productbrain.io');
+    });
+});
+describe('resolveSiteUrl', () => {
+    let originalPbEnv;
+    beforeEach(() => {
+        originalPbEnv = process.env.PB_ENV;
+    });
+    afterEach(() => {
+        if (originalPbEnv === undefined) {
+            delete process.env.PB_ENV;
+        }
+        else {
+            process.env.PB_ENV = originalPbEnv;
+        }
+    });
+    it('returns localhost URL when PB_ENV=dev', () => {
+        process.env.PB_ENV = 'dev';
+        expect(resolveSiteUrl()).toBe('http://localhost:5176');
+    });
+    it('returns production URL when PB_ENV=production', () => {
+        process.env.PB_ENV = 'production';
+        expect(resolveSiteUrl()).toBe(DEFAULT_SITE_URL);
+    });
+    it('returns production URL when PB_ENV is unset', () => {
+        delete process.env.PB_ENV;
+        expect(resolveSiteUrl()).toBe(DEFAULT_SITE_URL);
+    });
+    it('is case-insensitive for dev', () => {
+        process.env.PB_ENV = 'DEV';
+        expect(resolveSiteUrl()).toBe('http://localhost:5176');
+    });
+});
+describe('resolveAppUrl', () => {
+    let originalPbEnv;
+    beforeEach(() => {
+        originalPbEnv = process.env.PB_ENV;
+    });
+    afterEach(() => {
+        if (originalPbEnv === undefined) {
+            delete process.env.PB_ENV;
+        }
+        else {
+            process.env.PB_ENV = originalPbEnv;
+        }
+    });
+    it('returns localhost URL when PB_ENV=dev', () => {
+        process.env.PB_ENV = 'dev';
+        expect(resolveAppUrl()).toBe('http://localhost:5173');
+    });
+    it('returns production URL when PB_ENV=production', () => {
+        process.env.PB_ENV = 'production';
+        expect(resolveAppUrl()).toBe('https://work.productbrain.io');
+    });
+    it('returns production URL when PB_ENV is unset', () => {
+        delete process.env.PB_ENV;
+        expect(resolveAppUrl()).toBe('https://work.productbrain.io');
+    });
+});
+describe('isDevMode', () => {
+    let originalPbEnv;
+    beforeEach(() => {
+        originalPbEnv = process.env.PB_ENV;
+    });
+    afterEach(() => {
+        if (originalPbEnv === undefined) {
+            delete process.env.PB_ENV;
+        }
+        else {
+            process.env.PB_ENV = originalPbEnv;
+        }
+    });
+    it('returns true when PB_ENV=dev', () => {
+        process.env.PB_ENV = 'dev';
+        expect(isDevMode()).toBe(true);
+    });
+    it('returns false when PB_ENV=production', () => {
+        process.env.PB_ENV = 'production';
+        expect(isDevMode()).toBe(false);
+    });
+    it('returns false when PB_ENV is unset', () => {
+        delete process.env.PB_ENV;
+        expect(isDevMode()).toBe(false);
+    });
+});
+//# sourceMappingURL=constants.test.js.map

package/dist/__tests__/constants.test.js.map

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

package/dist/__tests__/errors.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=errors.test.d.ts.map

package/dist/__tests__/errors.test.d.ts.map

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

package/dist/__tests__/errors.test.js

@@ -0,0 +1,117 @@
+/**
+ * CLIError + McpError — unit tests.
+ * WP-302 Slice 0: Error Taxonomy + Commander Migration.
+ *
+ * Verifies:
+ * - CLIError serializes correctly with code, category, guidance
+ * - CLIError works with just a message (optional fields default)
+ * - McpError extends CLIError and retains backward compat
+ * - McpError maps server codes to categories
+ */
+import { describe, expect, it } from 'vitest';
+import { CLIError, ErrorCode } from '../lib/errors.js';
+import { McpError } from '../lib/client.js';
+describe('CLIError', () => {
+    it('serializes all fields to JSON', () => {
+        const err = new CLIError('No API key configured', {
+            code: ErrorCode.AUTH_MISSING,
+            category: 'auth',
+            guidance: 'Run `pb login` to configure your API key.',
+        });
+        expect(err.message).toBe('No API key configured');
+        expect(err.code).toBe('AUTH_MISSING');
+        expect(err.category).toBe('auth');
+        expect(err.guidance).toBe('Run `pb login` to configure your API key.');
+        const json = err.toJSON();
+        expect(json).toEqual({
+            error: 'No API key configured',
+            code: 'AUTH_MISSING',
+            category: 'auth',
+            guidance: 'Run `pb login` to configure your API key.',
+        });
+    });
+    it('defaults to INTERNAL code and internal category when no options given', () => {
+        const err = new CLIError('Something broke');
+        expect(err.code).toBe('INTERNAL');
+        expect(err.category).toBe('internal');
+        expect(err.guidance).toBeUndefined();
+        const json = err.toJSON();
+        expect(json).toEqual({
+            error: 'Something broke',
+            code: 'INTERNAL',
+            category: 'internal',
+        });
+        // guidance should NOT appear in JSON when undefined
+        expect(json).not.toHaveProperty('guidance');
+    });
+    it('is an instance of Error', () => {
+        const err = new CLIError('test');
+        expect(err).toBeInstanceOf(Error);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.name).toBe('CLIError');
+    });
+    it('supports all defined error codes', () => {
+        // Verify the ErrorCode object has all expected keys
+        expect(ErrorCode.AUTH_MISSING).toBe('AUTH_MISSING');
+        expect(ErrorCode.AUTH_INVALID).toBe('AUTH_INVALID');
+        expect(ErrorCode.AUTH_DENIED).toBe('AUTH_DENIED');
+        expect(ErrorCode.NETWORK_UNREACHABLE).toBe('NETWORK_UNREACHABLE');
+        expect(ErrorCode.NETWORK_TIMEOUT).toBe('NETWORK_TIMEOUT');
+        expect(ErrorCode.CONFIG_MISSING).toBe('CONFIG_MISSING');
+        expect(ErrorCode.CONFIG_INVALID).toBe('CONFIG_INVALID');
+        expect(ErrorCode.SESSION_REQUIRED).toBe('SESSION_REQUIRED');
+        expect(ErrorCode.VALIDATION_FAILED).toBe('VALIDATION_FAILED');
+        expect(ErrorCode.INTERNAL).toBe('INTERNAL');
+    });
+});
+describe('McpError', () => {
+    it('extends CLIError', () => {
+        const err = new McpError('Server error');
+        expect(err).toBeInstanceOf(Error);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err).toBeInstanceOf(McpError);
+        expect(err.name).toBe('McpError');
+    });
+    it('preserves backward-compatible interface (message, code, details)', () => {
+        const details = [
+            {
+                fieldKey: 'status',
+                fieldLabel: 'Status',
+                invalidValue: 'bogus',
+                validOptions: ['draft', 'active'],
+                errorType: 'invalid_option',
+                message: 'Invalid status value',
+            },
+        ];
+        const err = new McpError('Validation failed', 'VALIDATION_FAILED', details);
+        expect(err.message).toBe('Validation failed');
+        expect(err.code).toBe('VALIDATION_FAILED');
+        expect(err.details).toEqual(details);
+        expect(err.category).toBe('validation');
+    });
+    it('maps AUTH codes to auth category', () => {
+        const err = new McpError('Unauthorized', 'AUTH_DENIED');
+        expect(err.category).toBe('auth');
+    });
+    it('maps UNAUTHORIZED to auth category', () => {
+        const err = new McpError('Unauthorized', 'UNAUTHORIZED');
+        expect(err.category).toBe('auth');
+    });
+    it('maps SESSION_REQUIRED to session category', () => {
+        const err = new McpError('No session', 'SESSION_REQUIRED');
+        expect(err.category).toBe('session');
+    });
+    it('defaults to INTERNAL code and internal category when no code given', () => {
+        const err = new McpError('Unknown error');
+        expect(err.code).toBe('INTERNAL');
+        expect(err.category).toBe('internal');
+    });
+    it('serializes via toJSON from CLIError', () => {
+        const err = new McpError('Bad request', 'VALIDATION_FAILED');
+        const json = err.toJSON();
+        expect(json.error).toBe('Bad request');
+        expect(json.code).toBe('VALIDATION_FAILED');
+        expect(json.category).toBe('validation');
+    });
+});
+//# sourceMappingURL=errors.test.js.map

package/dist/__tests__/errors.test.js.map

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

package/dist/__tests__/glossary.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=glossary.test.d.ts.map

package/dist/__tests__/glossary.test.d.ts.map

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

package/dist/__tests__/glossary.test.js

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest';
+import { GLOSSARY, formatGlossary } from '../lib/glossary.js';
+describe('glossary', () => {
+    it('has non-empty entries', () => {
+        expect(GLOSSARY.length).toBeGreaterThan(0);
+        for (const entry of GLOSSARY) {
+            expect(entry.term.length).toBeGreaterThan(0);
+            expect(entry.definition.length).toBeGreaterThan(0);
+        }
+    });
+    const requiredTerms = ['workspace', 'entry', 'collection', 'relation', 'session', 'capture', 'profile'];
+    it.each(requiredTerms)('includes required term: %s', (term) => {
+        const found = GLOSSARY.find((g) => g.term === term);
+        expect(found).toBeDefined();
+        expect(found.definition.length).toBeGreaterThan(0);
+    });
+    it('formatGlossary produces formatted multi-line output', () => {
+        const output = formatGlossary();
+        expect(output).toContain('workspace');
+        expect(output).toContain('entry');
+        expect(output).toContain('collection');
+        // Should have multiple lines (one per term)
+        const lines = output.split('\n');
+        expect(lines.length).toBe(GLOSSARY.length);
+    });
+    it('all terms are unique', () => {
+        const terms = GLOSSARY.map((g) => g.term);
+        const unique = new Set(terms);
+        expect(unique.size).toBe(terms.length);
+    });
+});
+//# sourceMappingURL=glossary.test.js.map

package/dist/__tests__/glossary.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glossary.test.js","sourceRoot":"","sources":["../../src/__tests__/glossary.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE9D,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE;IACxB,EAAE,CAAC,uBAAuB,EAAE,GAAG,EAAE;QAC/B,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;QAC3C,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC7B,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;YAC7C,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;QACrD,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,aAAa,GAAG,CAAC,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IAExG,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,4BAA4B,EAAE,CAAC,IAAI,EAAE,EAAE;QAC5D,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;QACpD,MAAM,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;QAC5B,MAAM,CAAC,KAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC7D,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC;QAChC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;QACtC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAClC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;QACvC,4CAA4C;QAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sBAAsB,EAAE,GAAG,EAAE;QAC9B,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC9B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/login.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=login.test.d.ts.map

package/dist/__tests__/login.test.d.ts.map

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