@supportpages.io/wtfm 0.0.0-stage → 0.3.0

package/dist/hosted-operations.js

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import { randomUUID, createHash } from 'node:crypto';
+import { parse } from './artifacts.js';
+import { resolveAction, requireExecution } from './actions.js';
+import { fail } from './errors.js';
+import { preferences } from './settings.js';
+import { remoteId } from './schema.js';
+import { secondsSince, track } from './telemetry.js';
+export const operationSchema = z.object({ id: remoteId, project_id: remoteId, action: z.string(), execution: z.literal('hosted'),
+    attempt: z.number().int().positive(), status: z.enum(['queued', 'running', 'succeeded', 'failed']), article_id: remoteId.nullable(), walkthrough_id: remoteId.nullable().optional(),
+    result: z.record(z.string(), z.unknown()), error: z.object({ code: z.string(), message: z.string().max(500) }).nullable(),
+    review_url: z.url().nullable(), created_at: z.iso.datetime(), started_at: z.iso.datetime().nullable(), finished_at: z.iso.datetime().nullable() });
+/** Durable request identity is written before any submission. Status can recover
+ * a lost response by key without creating another job, even after a restart. */
+export class HostedOperations {
+    bridge;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    path(project) { return `${this.bridge.stateRoot}/operations/${project}`; }
+    check(raw, project, id, action) {
+        const operation = parse(operationSchema, raw, 'invalid_response');
+        if (operation.project_id !== project || id && operation.id !== id || action && operation.action !== action)
+            fail('invalid_response', 'The server returned a different operation.');
+        if (operation.review_url) {
+            const url = new URL(operation.review_url), origin = new URL(this.bridge.api.origin);
+            if (url.username || url.password || url.origin !== origin.origin && !(this.bridge.api.dev && url.hostname === origin.hostname && url.protocol === 'https:'))
+                fail('invalid_response', 'Invalid operation review link.');
+        }
+        return operation;
+    }
+    async submit(action, input, options = {}) {
+        requireExecution(options.decision ?? await resolveAction(this.bridge, action, typeof input.article_id === 'string' ? input.article_id : undefined), 'hosted');
+        const settings = await preferences(this.bridge.api);
+        const prefs = { prefer_background: options.prefer_background ?? settings.prefer_background, open_when_ready: options.open_when_ready ?? settings.open_when_ready };
+        let operation = await this.bridge.lock(async () => {
+            const binding = await this.bridge.binding();
+            const canonical = (value) => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, canonical(v)])) : value;
+            const digest = createHash('sha256').update(JSON.stringify(canonical({ action, input, request_id: options.request_id }))).digest('hex');
+            const filename = `${this.path(binding.project_id)}/requests/${digest}.json`;
+            const previous = await this.bridge.ws.exists(filename) ? await this.bridge.ws.json(filename) : undefined;
+            const key = previous?.key ?? options.request_id ?? randomUUID();
+            if (!z.uuid().safeParse(key).success)
+                fail('invalid_request', 'Use a UUID request_id.');
+            const journal = { key, action, input, preferences: prefs };
+            await this.bridge.ws.writeJson(filename, journal);
+            await this.bridge.ws.writeJson(`${this.path(binding.project_id)}/latest.json`, journal);
+            const value = this.check(await this.bridge.api.request('POST', `/projects/${binding.project_id}/writer_operations`, { action_name: action, input }, key), binding.project_id, undefined, action);
+            await this.bridge.ws.writeJson(`${this.path(binding.project_id)}/latest.json`, { ...journal, operation_id: value.id });
+            await this.bridge.ws.writeJson(`${this.path(binding.project_id)}/${value.id}.json`, { preferences: prefs });
+            return value;
+        });
+        // Hosted work always runs in SupportPages, where the user can watch it.
+        // Holding the call adds latency and teaches the agent to wait; the link does not.
+        return this.present(operation);
+    }
+    async get(id, waitMs = 0, allowOpen = true) {
+        const binding = await this.bridge.binding();
+        if (id)
+            parse(remoteId, id);
+        if (!id) {
+            const latest = `${this.path(binding.project_id)}/latest.json`;
+            if (!await this.bridge.ws.exists(latest))
+                return undefined;
+            const journal = await this.bridge.ws.json(latest);
+            if (!journal.operation_id) {
+                const value = this.check(await this.bridge.api.request('GET', `/projects/${binding.project_id}/writer_operations?idempotency_key=${encodeURIComponent(journal.key)}`), binding.project_id, undefined, journal.action);
+                await this.bridge.ws.writeJson(latest, { ...journal, operation_id: value.id });
+                await this.bridge.ws.writeJson(`${this.path(binding.project_id)}/${value.id}.json`, { preferences: journal.preferences });
+                return this.present(value, allowOpen);
+            }
+            id = journal.operation_id;
+        }
+        return this.present(await this.poll(id, waitMs), allowOpen);
+    }
+    async poll(id, waitMs) {
+        const binding = await this.bridge.binding();
+        const deadline = Date.now() + Math.max(0, Math.min(waitMs, 20_000));
+        while (true) {
+            const result = this.check(await this.bridge.api.request('GET', `/projects/${binding.project_id}/writer_operations/${id}`), binding.project_id, id);
+            if (!['queued', 'running'].includes(result.status) || Date.now() >= deadline)
+                return result;
+            await new Promise(resolve => setTimeout(resolve, Math.min(3000, deadline - Date.now())));
+        }
+    }
+    async retry(id, attempt) {
+        parse(remoteId, id);
+        const binding = await this.bridge.binding();
+        return this.present(this.check(await this.bridge.api.request('POST', `/projects/${binding.project_id}/writer_operations/${id}/retry_operation`, { expected_attempt: attempt }), binding.project_id, id));
+    }
+    async present(operation, allowOpen = true) {
+        const open = await this.bridge.lock(async () => {
+            const file = `${this.path(operation.project_id)}/${operation.id}.json`;
+            const saved = await this.bridge.ws.exists(file) ? await this.bridge.ws.json(file) : {};
+            const open = allowOpen && operation.status === 'succeeded' && !!saved.preferences?.open_when_ready && !saved.opened;
+            // Counted once per operation, however often it is presented.
+            const counted = !saved.counted && ['succeeded', 'failed'].includes(operation.status) && ['create_article', 'create_video_walkthrough'].includes(operation.action);
+            if (open || counted)
+                await this.bridge.ws.writeJson(file, { ...saved, ...(open ? { opened: true } : {}), ...(counted ? { counted: true } : {}) });
+            if (counted)
+                track(operation.action === 'create_article' ? 'article_completed' : 'walkthrough_completed', {
+                    ...(operation.action === 'create_article' ? { location: 'hosted' } : {}), outcome: operation.status, error_code: operation.error?.code,
+                    duration_s: operation.started_at ? secondsSince(operation.started_at, operation.finished_at ? Date.parse(operation.finished_at) : Date.now()) : undefined
+                });
+            return open;
+        });
+        const completed = operation.action === 'create_video_walkthrough'
+            ? 'The video is ready for private review and playback. Show the review link. Do not publish or share it automatically.'
+            : ['suggest_sections', 'recommend_articles', 'find_article_gaps'].includes(operation.action)
+                ? `Read the results with ${operation.action === 'suggest_sections' ? 'list_sections' : 'list_recommendations'} and review selected IDs. Do not automatically accept suggestions, advance onboarding or generate articles. Zero new results is a successful analysis.`
+                : 'Show the result and review link. Creation remains a draft unless publication was explicitly requested; edits preserve publication state. Do not publish or share automatically.';
+        return { ...operation, operation_id: operation.id, open_when_ready: open && operation.status === 'succeeded',
+            instructions: operation.status === 'failed' && operation.error?.code === 'revision_conflict' ? 'The target changed. Read it again and submit a new request with its current revision and a new request_id if the editing instructions still apply. Retrying the old operation cannot overwrite a changed article.'
+                : operation.status === 'failed' ? 'Show the safe error and review link. Read the current article before retrying a revision conflict. Explicit retries use retry_operation with the current attempt; never start a local writer.'
+                    : operation.status === 'succeeded' ? completed
+                        : operation.review_url ? `SupportPages is writing this now, and the page fills in as it is written. Show ${operation.review_url} as the place to watch it, then finish your turn. Do not poll: call get_operation only when the user asks how it is going, or with this operation_id after a client restart — never resubmit, and never launch a local writer.`
+                            : 'SupportPages is working on this now. Tell the user it is running and finish your turn. Do not poll: call get_operation only when the user asks for progress, or with this operation_id after a client restart — never resubmit, and never launch a local writer.' };
+    }
+}
+//# sourceMappingURL=hosted-operations.js.map

package/dist/hosted-operations.js.map

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

package/dist/hosting-benefits.d.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+export declare const hostingInvitationSchema: z.ZodObject<{
+    id: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type HostingInvitation = z.infer<typeof hostingInvitationSchema>;
+/** Why an anonymous local folder would want a SupportPages.io account. Every
+ * message must hold on the free plan a new account lands on. */
+export declare const hostingBenefits: readonly [{
+    readonly id: "public_url";
+    readonly category: "reach";
+    readonly short: "a public URL to share with customers";
+    readonly message: "Give this article a public URL on your own SupportPages.io help centre, ready to share with customers.";
+}, {
+    readonly id: "editor_review";
+    readonly category: "editing";
+    readonly short: "an editor to polish drafts before anyone sees them";
+    readonly message: "Review and polish drafts in the SupportPages.io editor, with your screenshots already in place, before anyone else sees them.";
+}, {
+    readonly id: "ai_answers";
+    readonly category: "reach";
+    readonly short: "AI answers for the questions customers ask";
+    readonly message: "Let customers ask questions on your help centre and get AI answers grounded in your articles.";
+}, {
+    readonly id: "agent_publishing";
+    readonly category: "editing";
+    readonly message: "Publish, unpublish and update hosted articles straight from your coding agent, with revision-safe saves that never overwrite browser edits.";
+}, {
+    readonly id: "free_account";
+    readonly category: "usage";
+    readonly short: "hosts up to 10 articles and leaves your local files exactly where they are";
+    readonly message: "A free SupportPages.io account hosts up to 10 articles, and your local files stay exactly where they are.";
+}, {
+    readonly id: "one_help_centre";
+    readonly category: "organisation";
+    readonly message: "Keep every article together in one help centre organised into sections, instead of scattered Markdown files.";
+}, {
+    readonly id: "next_step_repository";
+    readonly category: "hosted";
+    readonly message: "Once hosted, connect your repository and let SupportPages.io suggest, generate and maintain articles in the background.";
+}];
+export declare const setupInvitation: () => string[];
+/** The exact paragraph the agent shows after a saved local article: the benefit, then the offer. */
+export declare const hostingShowText: (invitation: HostingInvitation) => string;
+/** Anonymous users have no context yet: every one of the first three local
+ * completions carries a benefit, then every third completion after that. */
+export declare const hostingReminderDue: (count: number) => boolean;
+/** Device-local preference and deduplication for a whole API origin: an anonymous
+ * folder has no help centre to key on, so every local folder on this computer shares it. */
+export declare class HostingReminders {
+    private journal;
+    constructor(configDir?: string);
+    private transaction;
+    preference(origin: string, enabled?: boolean): Promise<{
+        enabled: boolean;
+        api_origin: string;
+        scope: string;
+    }>;
+    complete(input: {
+        origin: string;
+        articleId: string;
+    }): Promise<{
+        id: "public_url" | "editor_review" | "ai_answers" | "agent_publishing" | "free_account" | "one_help_centre" | "next_step_repository";
+        message: "Give this article a public URL on your own SupportPages.io help centre, ready to share with customers." | "Review and polish drafts in the SupportPages.io editor, with your screenshots already in place, before anyone else sees them." | "Let customers ask questions on your help centre and get AI answers grounded in your articles." | "Publish, unpublish and update hosted articles straight from your coding agent, with revision-safe saves that never overwrite browser edits." | "A free SupportPages.io account hosts up to 10 articles, and your local files stay exactly where they are." | "Keep every article together in one help centre organised into sections, instead of scattered Markdown files." | "Once hosted, connect your repository and let SupportPages.io suggest, generate and maintain articles in the background.";
+    } | undefined>;
+}

package/dist/hosting-benefits.js

@@ -0,0 +1,67 @@
+import path from 'node:path';
+import { z } from 'zod';
+import { ReminderJournal, claimDelivery, defaultConfigDir, reminderStateSchema, selectBenefit } from './reminders.js';
+export const hostingInvitationSchema = z.object({ id: z.string(), message: z.string() });
+/** Why an anonymous local folder would want a SupportPages.io account. Every
+ * message must hold on the free plan a new account lands on. */
+export const hostingBenefits = [
+    { id: 'public_url', category: 'reach', short: 'a public URL to share with customers', message: 'Give this article a public URL on your own SupportPages.io help centre, ready to share with customers.' },
+    { id: 'editor_review', category: 'editing', short: 'an editor to polish drafts before anyone sees them', message: 'Review and polish drafts in the SupportPages.io editor, with your screenshots already in place, before anyone else sees them.' },
+    { id: 'ai_answers', category: 'reach', short: 'AI answers for the questions customers ask', message: 'Let customers ask questions on your help centre and get AI answers grounded in your articles.' },
+    { id: 'agent_publishing', category: 'editing', message: 'Publish, unpublish and update hosted articles straight from your coding agent, with revision-safe saves that never overwrite browser edits.' },
+    { id: 'free_account', category: 'usage', short: 'hosts up to 10 articles and leaves your local files exactly where they are', message: 'A free SupportPages.io account hosts up to 10 articles, and your local files stay exactly where they are.' },
+    { id: 'one_help_centre', category: 'organisation', message: 'Keep every article together in one help centre organised into sections, instead of scattered Markdown files.' },
+    { id: 'next_step_repository', category: 'hosted', message: 'Once hosted, connect your repository and let SupportPages.io suggest, generate and maintain articles in the background.' },
+];
+/** The invitation shown before a folder has chosen where its articles go,
+ * composed from the same catalogue the post-article reminders draw on so a user
+ * cannot be promised one thing at setup and another afterwards. Hosting is an
+ * offer here, never a requirement: saving articles locally needs no account. */
+const shortForm = (id) => {
+    const benefit = hostingBenefits.find(item => item.id === id);
+    const short = benefit && 'short' in benefit ? benefit.short : undefined;
+    if (!short)
+        throw new Error(`Hosting benefit ${id} has no short form for the setup invitation.`);
+    return short;
+};
+export const setupInvitation = () => [
+    `Linking a free SupportPages.io help centre also gives each article ${shortForm('public_url')}, ${shortForm('editor_review')} and ${shortForm('ai_answers')}.`,
+    `A free account ${shortForm('free_account')}.`,
+];
+/** The exact paragraph the agent shows after a saved local article: the benefit, then the offer. */
+export const hostingShowText = (invitation) => `${invitation.message} If you'd like, I can host it on a SupportPages.io help centre.`;
+/** Anonymous users have no context yet: every one of the first three local
+ * completions carries a benefit, then every third completion after that. */
+export const hostingReminderDue = (count) => count <= 3 || (count - 3) % 3 === 0;
+const stateSchema = reminderStateSchema(hostingInvitationSchema);
+/** Device-local preference and deduplication for a whole API origin: an anonymous
+ * folder has no help centre to key on, so every local folder on this computer shares it. */
+export class HostingReminders {
+    journal;
+    constructor(configDir = defaultConfigDir()) {
+        this.journal = new ReminderJournal(path.join(configDir, 'hosting-reminders'), stateSchema);
+    }
+    transaction(origin, operation) {
+        return this.journal.transaction([new URL(origin).origin, 'local'], operation);
+    }
+    preference(origin, enabled) {
+        return this.transaction(origin, state => {
+            if (enabled !== undefined)
+                state.enabled = enabled;
+            return { enabled: state.enabled, api_origin: origin, scope: 'local_folders_on_this_device' };
+        });
+    }
+    complete(input) {
+        return this.transaction(input.origin, state => {
+            if (!claimDelivery(state, input.articleId))
+                return;
+            if (!state.enabled || !hostingReminderDue(state.count))
+                return;
+            const benefit = selectBenefit(state, hostingBenefits);
+            const invitation = { id: benefit.id, message: benefit.message };
+            state.articles[input.articleId] = invitation;
+            return invitation;
+        });
+    }
+}
+//# sourceMappingURL=hosting-benefits.js.map

package/dist/hosting-benefits.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { Session, defaultConfigDir } from './session.js';
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pinSkills, startBackgroundUpdate } from './runtime.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { apiOrigin, defaultOrigin, developmentMode } from './api.js';
+import { createServer } from './server.js';
+import { fail, publicError } from './errors.js';
+import { configureTelemetry, reportError } from './telemetry.js';
+try {
+    const [major = 0, minor = 0] = process.versions.node.split('.').map(Number);
+    if (major < 22 || major === 22 && minor < 12) {
+        fail('missing_dependency', `SupportPages Writer needs Node.js 22.12 or later; this is ${process.version}. Install a newer Node.js and restart your coding agent.`);
+    }
+    const { values } = parseArgs({ options: { workspace: { type: 'string' }, 'api-url': { type: 'string' }, 'skills-dir': { type: 'string' }, 'token-file': { type: 'string' }, 'config-dir': { type: 'string' }, dev: { type: 'boolean' }, help: { type: 'boolean' }, doctor: { type: 'boolean' } } });
+    if (values.help) {
+        process.stdout.write('Usage: supportpages-mcp [--workspace /absolute/product/path] [--dev] [--api-url ORIGIN] [--skills-dir /path/to/engine] [--token-file /private/credential.json] [--doctor]\nUse --dev (or SUPPORTPAGES_DEV=true) for https://app.lvh.me:3443. Call supportpages_init in your agent to connect this project. Without --doctor, starts an MCP stdio server.\n');
+    }
+    else {
+        // Coding clients launch Node directly, without the wtfm/supportpages shell launchers.
+        process.env.PATH = path.dirname(process.execPath) + path.delimiter + (process.env.PATH ?? '');
+        const dev = values.dev ?? developmentMode(process.env.SUPPORTPAGES_DEV);
+        const origin = apiOrigin(values['api-url'] ?? process.env.SUPPORTPAGES_API_URL ?? defaultOrigin(dev), dev);
+        const installRoot = fileURLToPath(new URL('../', import.meta.url)).replace(/\/$/, '');
+        const configDir = path.resolve(values['config-dir'] ?? defaultConfigDir());
+        const telemetry = configureTelemetry({ configDir, origin, installRoot });
+        const skillsDir = await pinSkills(installRoot, path.resolve(values['skills-dir'] ?? process.env.RTFM_SKILLS_DIR ?? path.join(installRoot, 'engine')));
+        const session = new Session({ workspace: values.workspace ?? process.env.RTFM_WORKSPACE,
+            projectDir: process.env.CLAUDE_PROJECT_DIR, cwd: process.cwd(), origin, dev,
+            configDir,
+            tokenFile: values['token-file'] ?? process.env.SUPPORTPAGES_API_TOKEN_FILE, token: process.env.SUPPORTPAGES_API_TOKEN,
+            skillsDir });
+        if (values.doctor)
+            process.stdout.write(JSON.stringify(await (await session.bridge()).doctor(), null, 2) + '\n');
+        else {
+            await createServer(session).connect(new StdioServerTransport());
+            telemetry?.start();
+            startBackgroundUpdate(installRoot);
+        }
+    }
+}
+catch (error) {
+    reportError(error);
+    process.stderr.write(JSON.stringify(publicError(error)) + '\n');
+    process.exitCode = 1;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/local-inventory.d.ts

@@ -0,0 +1,22 @@
+import type { Bridge } from './bridge.js';
+/** Inspect current article files, without syncing, signing in or changing setup. */
+export declare function localArticleInventory(bridge: Bridge): Promise<{
+    status: "local";
+    source: "local";
+    articles: {
+        slug: string;
+        title: string;
+        artifact_dir: string;
+        article_path?: string;
+        export_path?: string;
+        local_article_id?: string;
+        run_id?: string;
+    }[];
+    next_cursor: null;
+    searched_directories: string[];
+    warnings: {
+        path: string;
+        message: string;
+    }[];
+    instructions: string;
+}>;

package/dist/local-inventory.js

@@ -0,0 +1,59 @@
+import path from 'node:path';
+import { z } from 'zod';
+import { publicError } from './errors.js';
+/** Inspect current article files, without syncing, signing in or changing setup. */
+export async function localArticleInventory(bridge) {
+    const { ws } = bridge;
+    const local = await bridge.local();
+    const roots = [...new Set([local?.export_dir, 'output/articles'].filter((value) => Boolean(value)))];
+    const saved = await bridge.localArticles();
+    const directories = new Map();
+    for (const root of roots) {
+        for (const entry of await ws.list(root)) {
+            if (entry.isDirectory())
+                directories.set(path.posix.join(root, entry.name), entry.name);
+        }
+    }
+    for (const item of saved)
+        directories.set(item.artifact_dir, item.slug);
+    const articles = new Map();
+    const warnings = [];
+    for (const [directory, slug] of directories) {
+        let title, articlePath, exportPath;
+        for (const filename of ['article.json', 'index.md']) {
+            const relative = path.posix.join(directory, filename);
+            try {
+                if (!await ws.exists(relative))
+                    continue;
+                if (filename === 'article.json') {
+                    const article = z.object({ title: z.string().trim().min(1) }).parse(await ws.json(relative));
+                    title = article.title;
+                    articlePath = await ws.resolve(relative);
+                }
+                else {
+                    const markdown = (await ws.read(relative)).toString('utf8');
+                    title ??= markdown.match(/^#\s+(.+)$/m)?.[1]?.trim() || slug;
+                    exportPath = await ws.resolve(relative);
+                }
+            }
+            catch (error) {
+                if (publicError(error).code === 'invalid_path')
+                    throw error;
+                warnings.push({ path: relative, message: 'Could not read this local article file.' });
+            }
+        }
+        if (!articlePath && !exportPath)
+            continue;
+        const state = saved.find(item => item.slug === slug);
+        const existing = articles.get(slug);
+        // The configured export is preferred; the source folder can supply its JSON.
+        articles.set(slug, { slug, title: title ?? slug, artifact_dir: directory,
+            ...(state ? { local_article_id: state.local_article_id, run_id: state.run_id } : {}), ...existing,
+            ...(existing?.article_path || !articlePath ? {} : { article_path: articlePath }),
+            ...(existing?.export_path || !exportPath ? {} : { export_path: exportPath }) });
+    }
+    return { status: 'local', source: 'local', articles: [...articles.values()].sort((a, b) => a.title.localeCompare(b.title)),
+        next_cursor: null, searched_directories: [...new Set([...roots, ...saved.map(item => item.artifact_dir)])], warnings,
+        instructions: 'Report the local articles and their file paths. An empty list means no local articles were found in the searched directories; it says nothing about hosted articles. Use these files, not git status, as the inventory. Do not request sign-in or start setup for this local listing. Only offer hosted access if the user explicitly asks for articles on SupportPages.io.' };
+}
+//# sourceMappingURL=local-inventory.js.map

package/dist/local-inventory.js.map

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