backpack-ontology 0.2.1 → 0.2.3

package/README.md

@@ -1,198 +1,137 @@
-# Backpack Ontology
+# Backpack
 
-A persistent knowledge graph engine for Claude Code, delivered as an MCP server. Backpack gives AI agents structured, searchable memory that persists across sessions.
+**Give your AI a memory it can actually use.** Backpack lets Claude remember what matters — your clients, your processes, your decisions — across every conversation.
 
-## Installation
+## What it does
 
-```bash
-npm install -g backpack-ontology
-```
-
-## Setup
-
-Add Backpack to your Claude Code project (`.mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "backpack": {
-      "command": "npx",
-      "args": ["backpack-ontology"]
-    }
-  }
-}
-```
-
-Or register it globally:
+When you're working with Claude and something worth remembering comes up — a relationship, a project decision, a workflow, a domain concept — Backpack saves it as a structured knowledge graph. Next time you ask, Claude already knows.
 
-```bash
-claude mcp add backpack -- npx backpack-ontology
 ```
+You: "We just signed Acme Corp, they're on the Enterprise tier, main contact is Sarah Chen"
 
-Restart Claude Code to activate.
+Claude: [saves to backpack → clients ontology]
 
-## Usage
+--- weeks later, different conversation ---
 
-Backpack organizes knowledge as typed graphs — nodes (entities) connected by edges (relationships). There are no enforced schemas. The LLM decides what structure fits the domain.
+You: "What do we know about Acme Corp?"
 
+Claude: "Acme Corp is on the Enterprise tier, main contact is Sarah Chen..."
 ```
-[Ingredient: garlic] --USED_IN--> [Recipe: Aglio e Olio]
-[Module: auth]       --DEPENDS_ON--> [Module: database]
-```
-
-Tell Claude what to store:
 
-> "Create an ontology about our codebase architecture"
+No copy-pasting. No re-explaining. Your knowledge carries forward.
 
-> "Search the backpack for anything related to authentication"
+## Get started
 
-> "Add the deployment pipeline to the infrastructure ontology"
+Tell Claude to set up Backpack:
 
-### Progressive Discovery
+> "Add backpack to this project"
 
-Tools are organized in layers so the context window stays clean. Claude starts broad and drills down — only pulling in what it needs.
+Claude will configure the MCP server for you. Restart Claude Code and you're ready.
 
-| Layer | Tools | Returns |
-|-------|-------|---------|
-| **Discover** | `backpack_list`, `backpack_create`, `backpack_describe` | Ontology names, descriptions, type counts |
-| **Browse** | `backpack_list_nodes`, `backpack_node_types`, `backpack_search` | Paginated node summaries (id, type, label) |
-| **Inspect** | `backpack_get_node`, `backpack_get_neighbors` | Full node data, graph traversal |
-| **Mutate** | `backpack_add_node`, `backpack_update_node`, `backpack_add_edge`, ... | Create and modify data |
+Or set it up yourself — pick local or cloud:
 
-## Tools Reference
+| Mode | Setup command |
+|---|---|
+| **Local** (free, private, on your machine) | `claude mcp add backpack -- npx backpack-ontology` |
+| **Backpack App** (free account, cloud sync) | `claude mcp add backpack-app -- npx backpack-app` |
 
-### Discovery
+Backpack App syncs your knowledge across devices and gives you access to the web-based graph visualizer at [app.backpackontology.com](https://app.backpackontology.com). On first run, a browser window opens for sign-in — after that, it's automatic.
 
-| Tool | Description |
-|------|-------------|
-| `backpack_list` | List all ontologies with names, descriptions, and summary counts |
-| `backpack_create` | Create a new empty ontology |
-| `backpack_delete` | Permanently delete an ontology and all its data |
-| `backpack_describe` | Inspect ontology structure: node types, edge types, counts |
+## What to say to Claude
 
-### Browsing
+You don't need to learn commands or tools. Just talk to Claude naturally. Here's what you can do:
 
-| Tool | Description |
-|------|-------------|
-| `backpack_node_types` | List distinct node types with counts |
-| `backpack_list_nodes` | Paginated node summaries, optionally filtered by type |
-| `backpack_search` | Case-insensitive text search across all node properties |
+### Remember something
 
-### Inspection
+> "Remember that Acme Corp is on the Enterprise tier, main contact is Sarah Chen"
 
-| Tool | Description |
-|------|-------------|
-| `backpack_get_node` | Full node with all properties and connected edge summaries |
-| `backpack_get_neighbors` | BFS graph traversal from a node (max depth 3) |
+> "Add our new vendor agreement details to backpack"
 
-### Mutation
+> "Start an ontology for our hiring process"
 
-| Tool | Description |
-|------|-------------|
-| `backpack_add_node` | Add a node with a freeform type and properties |
-| `backpack_update_node` | Merge new properties into an existing node |
-| `backpack_remove_node` | Remove a node and cascade-delete its edges |
-| `backpack_add_edge` | Create a typed relationship between two nodes |
-| `backpack_remove_edge` | Remove a relationship |
-| `backpack_import_nodes` | Bulk-add multiple nodes in a single operation |
+### Find something
 
-## Programmatic API
+> "What's in my backpack about Acme Corp?"
 
-The core engine has no MCP dependency and can be used as a library:
+> "Search backpack for anything related to compliance"
 
-```typescript
-import { Backpack, JsonFileBackend } from "backpack-ontology";
+> "What do we know about the deployment process?"
 
-const backpack = new Backpack(new JsonFileBackend());
-await backpack.initialize();
+### See the big picture
 
-await backpack.createOntology("my-graph", "A knowledge graph");
-const node = await backpack.addNode("my-graph", "Person", { name: "Alice" });
-await backpack.addEdge("my-graph", "KNOWS", node.id, otherNodeId);
+> "Show me my knowledge graph"
 
-// Search across all node properties (case-insensitive)
-const results = await backpack.searchNodes("my-graph", "alice");
+> "What's in my backpack?"
 
-// BFS traversal from a node (depth 1–3)
-const neighbors = await backpack.getNeighbors("my-graph", node.id, undefined, "both", 2);
-```
+> "Describe the clients ontology"
 
-### Pluggable Storage
+Claude will open the graph visualizer so you can explore your knowledge visually.
 
-The `StorageBackend` interface allows custom persistence implementations:
+### Move to the cloud
 
-```typescript
-import { Backpack, StorageBackend } from "backpack-ontology";
+> "Sync my backpack to the cloud"
 
-class SqliteBackend implements StorageBackend {
-  // initialize, listOntologies, loadOntology, saveOntology,
-  // createOntology, deleteOntology, ontologyExists
-}
+> "Upload my local ontologies to Backpack App"
 
-const backpack = new Backpack(new SqliteBackend());
-```
+Claude will migrate your local knowledge to Backpack App so you can access it from any device.
 
-## Data Storage
+## What people use it for
 
-Backpack follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/):
+- **Client management** — keep track of accounts, contacts, contract details, and conversations across sessions
+- **Process documentation** — capture how things are done so Claude can help consistently
+- **Project knowledge** — architecture decisions, vendor relationships, compliance requirements
+- **Domain expertise** — industry terminology, regulatory frameworks, best practices
+- **Team onboarding** — new team members get Claude with your organization's context already loaded
 
-```
-~/.local/share/backpack/ontologies/
-├── cooking/
-│   └── ontology.json
-└── codebase-arch/
-    └── ontology.json
-```
+## How it works
 
-Ontology files are human-readable JSON. They can be inspected, edited, backed up, or version-controlled directly.
+You have one backpack — it goes everywhere with you. Inside it, you organize knowledge into **ontologies**, each one covering a different topic (clients, processes, compliance, etc.). Within each ontology, information is stored as things connected by relationships. You don't need to think about the structure. Claude handles it automatically based on what you're discussing.
 
-| Variable | Effect |
-|----------|--------|
-| `XDG_DATA_HOME` | Override data location (default: `~/.local/share`) |
-| `XDG_CONFIG_HOME` | Override config location (default: `~/.config`) |
-| `BACKPACK_DIR` | Override both — config at `$BACKPACK_DIR/config`, data at `$BACKPACK_DIR/data` |
+## Data and privacy
 
-## Telemetry
+**Local mode**: Your data is stored as readable JSON files on your computer at `~/.local/share/backpack/ontologies/`. You can inspect, edit, back up, or version-control these files directly.
 
-Backpack collects anonymous usage telemetry to improve the product. No personal data, ontology content, or tool arguments are ever collected.
+**Backpack App**: Your data is stored securely in our cloud infrastructure. See our [privacy policy](https://backpackontology.com/privacy) for details.
 
-**What is collected:**
-- Tool call counts (which tools are used, not what data is passed)
-- Session duration
-- Aggregate ontology statistics (total node/edge counts, not names or content)
-- Runtime environment (Node.js version, OS, platform)
+**Telemetry**: Backpack collects anonymous usage statistics (which tools are used, session duration) to improve the product. No content, names, or personal data is ever collected. Opt out with `DO_NOT_TRACK=1`.
 
-**What is never collected:**
-- Ontology names, descriptions, or content
-- Node or edge properties
-- File paths or user identifiers
-- Tool arguments or query strings
+## Reference
 
-**To opt out**, use any of the following:
+### CLI commands
 
-```bash
-# Environment variable (standard)
-export DO_NOT_TRACK=1
+| Command | What it does |
+|---|---|
+| `npx backpack-ontology` | Start the local MCP server |
+| `npx backpack-app` | Start the Backpack App MCP server (cloud) |
+| `npx backpack-sync` | Upload local ontologies to Backpack App |
+| `npx backpack-viewer` | Open the graph visualizer (http://localhost:5173) |
+| `npx backpack-init` | Reinstall auto-capture hooks if removed |
 
-# Backpack-specific environment variable
-export BACKPACK_TELEMETRY_DISABLED=1
-```
+### Tools
 
-Or add to `~/.config/backpack/config.json`:
+Claude uses these automatically — you don't need to call them directly.
 
-```json
-{
-  "telemetry": false
-}
-```
+| What Claude does | How |
+|---|---|
+| See what's in the backpack | `backpack_list`, `backpack_describe` |
+| Add a new ontology to the backpack | `backpack_create` |
+| Find something in the backpack | `backpack_search`, `backpack_list_nodes` |
+| Get full details on an item | `backpack_get_node`, `backpack_get_neighbors` |
+| Add or update knowledge | `backpack_add_node`, `backpack_update_node`, `backpack_add_edge` |
+| Bulk import | `backpack_import_nodes` |
+| Clean up | `backpack_remove_node`, `backpack_remove_edge`, `backpack_delete` |
 
-## Visualization
+### Advanced configuration
 
-Use [backpack-viewer](https://www.npmjs.com/package/backpack-viewer) to visualize ontologies in a web-based graph explorer with force-directed layout and live reload.
+| Variable | Effect |
+|---|---|
+| `XDG_DATA_HOME` | Change local data location (default: `~/.local/share`) |
+| `BACKPACK_DIR` | Override all Backpack directories |
+| `DO_NOT_TRACK` | Disable anonymous telemetry |
 
 ## Support
 
-For questions, feedback, or sponsorship inquiries: **support@backpackontology.com**
+Questions, feedback, or partnership inquiries: **support@backpackontology.com**
 
 ## License
 

package/dist/auth/oauth.d.ts

@@ -0,0 +1,32 @@
+/**
+ * OAuth2 authorization code flow with PKCE for CLI/MCP clients.
+ *
+ * On first run: opens the browser → user signs in via Entra → callback
+ * captures the code → exchanges for tokens → caches to disk.
+ *
+ * On subsequent runs: uses cached token, refreshes if expired.
+ */
+export declare class OAuthClient {
+    private clientId;
+    private issuerUrl;
+    private tokenCachePath;
+    private cachedToken;
+    private endpoints;
+    constructor(clientId: string, issuerUrl: string, cacheKey: string);
+    /** Returns a valid token for Bearer auth, refreshing or re-authenticating as needed. */
+    getAccessToken(): Promise<string>;
+    /**
+     * Prefer id_token for Bearer auth. Entra CIAM access tokens have
+     * Microsoft Graph as the audience, which oauth2-proxy won't accept.
+     * The id_token has the correct issuer and audience (our client ID).
+     */
+    private getBearerToken;
+    private discoverEndpoints;
+    private authorize;
+    private refreshToken;
+    private startCallbackServer;
+    private openBrowser;
+    private loadCachedToken;
+    private saveToken;
+}
+//# sourceMappingURL=oauth.d.ts.map

package/dist/auth/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/auth/oauth.ts"],"names":[],"mappings":"AAmBA;;;;;;;GAOG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,WAAW,CAA0B;IAC7C,OAAO,CAAC,SAAS,CAA8B;gBAEnC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAMjE,wFAAwF;IAClF,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IA0BvC;;;;OAIG;IACH,OAAO,CAAC,cAAc;YAIR,iBAAiB;YAQjB,SAAS;YA4DT,YAAY;IAyB1B,OAAO,CAAC,mBAAmB;IAqD3B,OAAO,CAAC,WAAW;YAiBL,eAAe;YASf,SAAS;CAQxB"}

package/dist/auth/oauth.js

@@ -0,0 +1,208 @@
+import * as crypto from "node:crypto";
+import * as http from "node:http";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { exec } from "node:child_process";
+import { configDir } from "../core/paths.js";
+/**
+ * OAuth2 authorization code flow with PKCE for CLI/MCP clients.
+ *
+ * On first run: opens the browser → user signs in via Entra → callback
+ * captures the code → exchanges for tokens → caches to disk.
+ *
+ * On subsequent runs: uses cached token, refreshes if expired.
+ */
+export class OAuthClient {
+    clientId;
+    issuerUrl;
+    tokenCachePath;
+    cachedToken = null;
+    endpoints = null;
+    constructor(clientId, issuerUrl, cacheKey) {
+        this.clientId = clientId;
+        this.issuerUrl = issuerUrl.replace(/\/+$/, "");
+        this.tokenCachePath = path.join(configDir(), "app-tokens", `${cacheKey}.json`);
+    }
+    /** Returns a valid token for Bearer auth, refreshing or re-authenticating as needed. */
+    async getAccessToken() {
+        if (!this.cachedToken) {
+            this.cachedToken = await this.loadCachedToken();
+        }
+        if (this.cachedToken) {
+            // Still valid (with 60s buffer)
+            if (this.cachedToken.expires_at > Date.now() / 1000 + 60) {
+                return this.getBearerToken();
+            }
+            // Try refresh
+            if (this.cachedToken.refresh_token) {
+                try {
+                    await this.refreshToken(this.cachedToken.refresh_token);
+                    return this.getBearerToken();
+                }
+                catch {
+                    console.error("Token refresh failed, re-authenticating...");
+                }
+            }
+        }
+        // Full browser-based authorization
+        await this.authorize();
+        return this.getBearerToken();
+    }
+    /**
+     * Prefer id_token for Bearer auth. Entra CIAM access tokens have
+     * Microsoft Graph as the audience, which oauth2-proxy won't accept.
+     * The id_token has the correct issuer and audience (our client ID).
+     */
+    getBearerToken() {
+        return this.cachedToken.id_token ?? this.cachedToken.access_token;
+    }
+    async discoverEndpoints() {
+        if (this.endpoints)
+            return this.endpoints;
+        const res = await fetch(`${this.issuerUrl}/.well-known/openid-configuration`);
+        if (!res.ok)
+            throw new Error(`OIDC discovery failed: ${res.status}`);
+        this.endpoints = (await res.json());
+        return this.endpoints;
+    }
+    async authorize() {
+        const endpoints = await this.discoverEndpoints();
+        // PKCE
+        const codeVerifier = crypto.randomBytes(32).toString("base64url");
+        const codeChallenge = crypto
+            .createHash("sha256")
+            .update(codeVerifier)
+            .digest("base64url");
+        // Start a temporary callback server on a random port
+        const { port, codePromise } = await this.startCallbackServer();
+        const redirectUri = `http://localhost:${port}`;
+        const params = new URLSearchParams({
+            client_id: this.clientId,
+            response_type: "code",
+            redirect_uri: redirectUri,
+            scope: "openid email profile offline_access",
+            code_challenge: codeChallenge,
+            code_challenge_method: "S256",
+        });
+        const authUrl = `${endpoints.authorization_endpoint}?${params}`;
+        console.error("Opening browser for sign-in...");
+        await this.openBrowser(authUrl);
+        // Block until the user completes sign-in (or 120s timeout)
+        const code = await codePromise;
+        // Exchange authorization code for tokens
+        const tokenRes = await fetch(endpoints.token_endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                client_id: this.clientId,
+                grant_type: "authorization_code",
+                code,
+                redirect_uri: redirectUri,
+                code_verifier: codeVerifier,
+            }),
+        });
+        if (!tokenRes.ok) {
+            const body = await tokenRes.text();
+            throw new Error(`Token exchange failed (${tokenRes.status}): ${body}`);
+        }
+        const data = (await tokenRes.json());
+        this.cachedToken = {
+            access_token: data.access_token,
+            refresh_token: data.refresh_token,
+            expires_at: Date.now() / 1000 + (data.expires_in ?? 3600),
+            id_token: data.id_token,
+        };
+        await this.saveToken(this.cachedToken);
+        console.error("Authenticated successfully.");
+    }
+    async refreshToken(refreshToken) {
+        const endpoints = await this.discoverEndpoints();
+        const res = await fetch(endpoints.token_endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                client_id: this.clientId,
+                grant_type: "refresh_token",
+                refresh_token: refreshToken,
+            }),
+        });
+        if (!res.ok)
+            throw new Error(`Refresh failed: ${res.status}`);
+        const data = (await res.json());
+        this.cachedToken = {
+            access_token: data.access_token,
+            refresh_token: data.refresh_token ?? refreshToken,
+            expires_at: Date.now() / 1000 + (data.expires_in ?? 3600),
+            id_token: data.id_token,
+        };
+        await this.saveToken(this.cachedToken);
+    }
+    startCallbackServer() {
+        return new Promise((resolve) => {
+            const server = http.createServer();
+            const codePromise = new Promise((resolveCode, rejectCode) => {
+                const timeout = setTimeout(() => {
+                    server.close();
+                    rejectCode(new Error("Authentication timed out (120s)"));
+                }, 120_000);
+                server.on("request", (req, res) => {
+                    const url = new URL(req.url, "http://localhost");
+                    const code = url.searchParams.get("code");
+                    const error = url.searchParams.get("error");
+                    const errorDesc = url.searchParams.get("error_description");
+                    if (error) {
+                        res.writeHead(200, { "Content-Type": "text/html" });
+                        res.end("<html><body><h1>Authentication failed</h1><p>You can close this tab.</p></body></html>");
+                        clearTimeout(timeout);
+                        server.close();
+                        rejectCode(new Error(`OAuth error: ${error} — ${errorDesc}`));
+                        return;
+                    }
+                    if (code) {
+                        res.writeHead(200, { "Content-Type": "text/html" });
+                        res.end("<html><body><h1>Signed in to Backpack</h1><p>You can close this tab.</p></body></html>");
+                        clearTimeout(timeout);
+                        server.close();
+                        resolveCode(code);
+                        return;
+                    }
+                    res.writeHead(400);
+                    res.end();
+                });
+            });
+            server.listen(0, "127.0.0.1", () => {
+                const addr = server.address();
+                resolve({ port: addr.port, codePromise });
+            });
+        });
+    }
+    openBrowser(url) {
+        const cmd = process.platform === "darwin"
+            ? "open"
+            : process.platform === "win32"
+                ? "start"
+                : "xdg-open";
+        return new Promise((resolve) => {
+            exec(`${cmd} "${url}"`, (err) => {
+                if (err) {
+                    console.error(`Could not open browser. Please visit:\n${url}`);
+                }
+                resolve();
+            });
+        });
+    }
+    async loadCachedToken() {
+        try {
+            const raw = await fs.readFile(this.tokenCachePath, "utf-8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    async saveToken(token) {
+        await fs.mkdir(path.dirname(this.tokenCachePath), { recursive: true });
+        await fs.writeFile(this.tokenCachePath, JSON.stringify(token, null, 2), "utf-8");
+    }
+}
+//# sourceMappingURL=oauth.js.map

package/dist/auth/oauth.js.map

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

package/dist/bin/backpack-app.js

@@ -1,15 +1,25 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createMcpServer } from "../mcp/server.js";
+import { ensureHooksInstalled } from "../core/hooks.js";
 import { shutdown as shutdownTelemetry } from "../core/telemetry.js";
+// Production defaults — users never need to configure these.
+// Env vars override for development/testing only.
+const DEFAULTS = {
+    url: "https://app.backpackontology.com",
+    clientId: "YOUR_ENTRA_CLIENT_ID_HERE",
+    issuerUrl: "https://YOUR_TENANT.ciamlogin.com/YOUR_TENANT_ID/v2.0",
+};
 async function main() {
-    const apiUrl = process.env.BACKPACK_APP_URL;
-    const apiToken = process.env.BACKPACK_APP_TOKEN;
-    if (!apiUrl || !apiToken) {
-        console.error("Required env vars: BACKPACK_APP_URL, BACKPACK_APP_TOKEN");
-        process.exit(1);
-    }
-    const server = await createMcpServer({ mode: "app", url: apiUrl, token: apiToken });
+    // Install hooks on first run (silent, non-blocking)
+    ensureHooksInstalled().catch(() => { });
+    const apiUrl = process.env.BACKPACK_APP_URL || DEFAULTS.url;
+    const clientId = process.env.BACKPACK_APP_CLIENT_ID || DEFAULTS.clientId;
+    const issuerUrl = process.env.BACKPACK_APP_ISSUER_URL || DEFAULTS.issuerUrl;
+    const staticToken = process.env.BACKPACK_APP_TOKEN;
+    const server = await createMcpServer(staticToken
+        ? { mode: "app", url: apiUrl, token: staticToken }
+        : { mode: "app", url: apiUrl, clientId, issuerUrl });
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error(`Backpack App MCP server running on stdio (${apiUrl})`);

package/dist/bin/backpack-app.js.map

@@ -1 +1 @@
-{"version":3,"file":"backpack-app.js","sourceRoot":"","sources":["../../src/bin/backpack-app.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,QAAQ,IAAI,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAErE,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IAC5C,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAEhD,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QACzB,OAAO,CAAC,KAAK,CAAC,yDAAyD,CAAC,CAAC;QACzE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IACpF,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,OAAO,CAAC,KAAK,CAAC,6CAA6C,MAAM,GAAG,CAAC,CAAC;AACxE,CAAC;AAED,KAAK,UAAU,gBAAgB;IAC7B,MAAM,iBAAiB,EAAE,CAAC;IAC1B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;AACvC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,gBAAgB,CAAC,CAAC;AAExC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"backpack-app.js","sourceRoot":"","sources":["../../src/bin/backpack-app.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,QAAQ,IAAI,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAErE,6DAA6D;AAC7D,kDAAkD;AAClD,MAAM,QAAQ,GAAG;IACf,GAAG,EAAE,kCAAkC;IACvC,QAAQ,EAAE,2BAA2B;IACrC,SAAS,EAAE,uDAAuD;CACnE,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,oDAAoD;IACpD,oBAAoB,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAEvC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,QAAQ,CAAC,GAAG,CAAC;IAC5D,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,QAAQ,CAAC,QAAQ,CAAC;IACzE,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,QAAQ,CAAC,SAAS,CAAC;IAC5E,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAEnD,MAAM,MAAM,GAAG,MAAM,eAAe,CAClC,WAAW;QACT,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE;QAClD,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,CACtD,CAAC;IAEF,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,OAAO,CAAC,KAAK,CAAC,6CAA6C,MAAM,GAAG,CAAC,CAAC;AACxE,CAAC;AAED,KAAK,UAAU,gBAAgB;IAC7B,MAAM,iBAAiB,EAAE,CAAC;IAC1B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;AACvC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,gBAAgB,CAAC,CAAC;AAExC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/bin/backpack-sync.d.ts

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

package/dist/bin/backpack-sync.d.ts.map

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