@tinyviber/a2h 0.1.0

package/README.md

@@ -0,0 +1,229 @@
+# A2H — Agent to Human
+
+**Turn agent workspaces into human-readable, inspectable, actionable local web interfaces.**
+
+Agents are good at producing files, logs, diffs, reports, intermediate state, and machine-friendly metadata. Humans are not good at supervising all of that through a terminal or by opening folders one file at a time.
+
+A2H is the layer in between:
+
+```text
+Agent workspace
+      ↓
+scan + semantics
+      ↓
+presentation
+      ↓
+Human interface
+```
+
+It works with an ordinary repository out of the box, and agents can optionally describe richer semantics through a small `.a2h/manifest.json` protocol.
+
+A2H is **not** another agent runtime or workflow engine. It is the human-facing layer for reading, inspecting, comparing, judging, and acting on work produced by agents.
+
+## Quick start
+
+Requires Node.js 18+.
+
+```bash
+npx a2h render . --open
+```
+
+A2H scans the current workspace and starts a local viewer on `http://localhost:8420`.
+
+For live updates while an agent is working:
+
+```bash
+npx a2h render . --watch --open
+```
+
+No configuration is required.
+
+## Zero-config first
+
+On an ordinary repository, A2H infers a useful presentation from the files already there:
+
+- README and Markdown
+- code
+- diffs
+- logs
+- JSON / structured data
+- images
+- reports and generated artifacts
+
+File names, directory conventions, content type, and lightweight heuristics are used only as fallbacks. Existing repositories do not need to adopt an A2H-specific structure.
+
+## Explicit semantics for agents
+
+When a producer wants more control, it can write `.a2h/manifest.json` and tell A2H what the workspace means.
+
+Start from the current workspace automatically:
+
+```bash
+npx a2h init .
+```
+
+A small manifest can look like this:
+
+```json
+{
+  "a2h": 1,
+  "name": "Coding task",
+  "tasks": [
+    {
+      "id": "review",
+      "title": "Review implementation",
+      "status": "waiting-for-human",
+      "actions": ["approve"]
+    }
+  ],
+  "actions": [
+    {
+      "id": "approve",
+      "label": "Approve",
+      "kind": "approve",
+      "taskId": "review",
+      "sideEffect": "state"
+    }
+  ],
+  "items": [
+    {
+      "path": "review/summary.md",
+      "role": "review",
+      "taskId": "review",
+      "priority": 900
+    },
+    {
+      "path": "patches/change.diff",
+      "role": "implementation-diff",
+      "taskId": "review"
+    }
+  ]
+}
+```
+
+The important separation is:
+
+```text
+role         = what this artifact means
+content kind = how its bytes should be rendered
+```
+
+So a producer may invent roles such as `spec`, `evidence`, `decision`, `signal`, or `publish-candidate` without teaching the renderer new file types.
+
+When signals conflict, A2H prefers explicit semantics and falls back progressively to conventions and inference.
+
+## Tasks, runs, presentation blocks, and actions
+
+The protocol can describe more than files. A workspace can expose:
+
+- tasks and their status
+- agent / workflow runs
+- artifacts associated with a task or run
+- metrics, tables, timelines, comparisons, notices, and other presentation blocks
+- human-facing actions such as approve, reject, retry, or send back to an agent
+
+The built-in executor currently **simulates actions by default**. The UI says when an action is simulated. Real agent integrations are intended to sit behind provider / adapter boundaries rather than being hard-coded into A2H.
+
+## Examples
+
+Two example workspaces are included in the repository.
+
+### Radar
+
+A simulated daily agent workflow that ingests sources, clusters signals, writes publish candidates, and stops for human review.
+
+```bash
+npx a2h render examples/radar --open
+```
+
+See [`examples/radar`](examples/radar) and its [manifest](examples/radar/.a2h/manifest.json).
+
+### Coding task
+
+A workspace centered on a coding-agent task with a spec, implementation, tests, patch, screenshots, and review decisions.
+
+```bash
+npx a2h render examples/coding-task --open
+```
+
+See [`examples/coding-task`](examples/coding-task).
+
+## CLI
+
+```text
+a2h [render] [path] [options]
+a2h init [path]
+```
+
+Common options:
+
+```text
+-w, --watch       Watch the workspace and refresh on changes
+-p, --port <n>    Viewer port (default: 8420)
+-o, --open        Open the viewer in the default browser
+-f, --force       Overwrite an existing manifest when using init
+-v, --version     Print the version
+```
+
+Examples:
+
+```bash
+npx a2h render
+npx a2h render ../agent-workspace --watch
+npx a2h init .
+npx a2h render . --port 9000 --open
+```
+
+## Design principles
+
+A2H is deliberately local-first and content-first.
+
+The interface is designed for humans to:
+
+**read → inspect → compare → judge → act when necessary**
+
+The semantic layer is designed for machines to emit structured meaning without coupling themselves to a specific frontend.
+
+The zero-config path remains important: explicit metadata should improve a workspace, not become a requirement for using A2H.
+
+## Security model
+
+A2H treats the workspace as untrusted input.
+
+Workspace file reads go through a bounded capability that checks the scanner allowlist, sensitive-file classification, symlinks, and real-path containment. Raw workspace files are not exposed as arbitrary same-origin documents.
+
+Mutating browser requests go through a separate control-surface boundary. Actions must be declared, browser parameters are filtered against the declared schema, external effects require confirmation, and localhost mutations require a per-process session token.
+
+The server binds to `127.0.0.1` by default.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+npm run test:acceptance
+```
+
+Run the CLI from the repository:
+
+```bash
+node bin/a2h.js render examples/radar --open
+```
+
+Before publishing:
+
+```bash
+npm pack
+npm publish --dry-run
+```
+
+## Status
+
+A2H is early-stage. The protocol and presentation model are intentionally small and extensible, and real external agent providers are still evolving.
+
+If you are experimenting with coding agents, scheduled agents, research pipelines, or any workflow where machines produce more state than a human wants to inspect manually, A2H is meant to be a thin human interface over that work.
+
+## License
+
+MIT

package/bin/a2h.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+'use strict';
+
+// Thin entry point: loads the compiled CLI and hands off control.
+// Kept as plain JS so the shebang survives publishing regardless of
+// how the TypeScript build emits its output.
+require('../dist/cli/index.js').main(process.argv.slice(2));

package/dist/actions/engine.d.ts

@@ -0,0 +1,40 @@
+import type { ActionAuditEntry, ActionResult, ActionRequest, ActionView, RunView } from '../types';
+import type { ProviderRegistry } from '../providers/types';
+export type AuditEntry = ActionAuditEntry;
+export interface ActionEngineOptions {
+    rootDir: string;
+    registry: ProviderRegistry;
+    now?: () => Date;
+}
+export declare class ActionEngine {
+    private readonly rootDir;
+    private readonly registry;
+    private readonly now;
+    private runtimeRuns;
+    private taskStatus;
+    private audit;
+    private seq;
+    constructor(options: ActionEngineOptions);
+    /** Runs produced by actions during this session, newest first. */
+    getRuntimeRuns(): RunView[];
+    /** Task status overrides applied by executed actions. */
+    getTaskStatus(taskId: string): string | undefined;
+    getAuditTrail(): AuditEntry[];
+    /**
+     * Executes a declared action.
+     *
+     * @param declared the action registry as published to the client. Anything
+     *   not present here is rejected — this is the allowlist.
+     */
+    execute(request: ActionRequest, declared: ActionView[]): Promise<ActionResult>;
+    /**
+     * Records a refused or failed attempt and returns the result.
+     *
+     * Exactly one audit line is written per attempt — including the ones that
+     * never reached an executor. Attribution matters here: the trail is the
+     * record of what was asked for and what actually happened.
+     */
+    private fail;
+    private record;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/actions/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/actions/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAEhB,YAAY,EACZ,aAAa,EACb,UAAU,EACV,OAAO,EACR,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAkC3D,MAAM,MAAM,UAAU,GAAG,gBAAgB,CAAC;AAE1C,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IAEjC,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,GAAG,CAAK;gBAEJ,OAAO,EAAE,mBAAmB;IAMxC,kEAAkE;IAClE,cAAc,IAAI,OAAO,EAAE;IAI3B,yDAAyD;IACzD,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIjD,aAAa,IAAI,UAAU,EAAE;IAI7B;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IAuHpF;;;;;;OAMG;IACH,OAAO,CAAC,IAAI;IAoBZ,OAAO,CAAC,MAAM;CAIf"}

package/dist/actions/engine.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionEngine = void 0;
+const policy_1 = require("./policy");
+// ---------------------------------------------------------------------------
+// Action engine — the security boundary between the browser and anything with
+// an effect.
+//
+// Guarantees, in order of importance:
+//
+//   1. Only actions *declared in the workspace manifest* can be executed. The
+//      browser sends an id; it can never send a command.
+//   2. Values from the browser are filtered against the declared schema before
+//      an executor ever sees them: undeclared keys are dropped, and a value
+//      that is not legal for its declared type is refused. Nothing is
+//      interpolated into a shell or used as a path.
+//   3. An effect that reaches beyond A2H's own state requires an explicit
+//      second confirmation from the human. This is decided here, from two
+//      claims — the workspace's and the executor's — merged with the stricter
+//      winning. Neither is trusted on its own: the manifest is untrusted
+//      input, and it is the executor's declared policy that a workspace cannot
+//      talk down.
+//   4. Execution is delegated to a registered executor. The built-in executor
+//      only simulates state changes, so nothing dangerous can happen by
+//      default — but the protocol and the UI flow are fully exercised.
+//
+// The engine keeps an in-memory audit trail and in-memory run/status state. It
+// deliberately writes nothing to the workspace.
+// ---------------------------------------------------------------------------
+const MAX_PARAM_LENGTH = 2000;
+const MAX_PARAMS = 20;
+const MAX_RUNTIME_RUNS = 200;
+const MAX_AUDIT = 200;
+class ActionEngine {
+    rootDir;
+    registry;
+    now;
+    runtimeRuns = [];
+    taskStatus = new Map();
+    audit = [];
+    seq = 0;
+    constructor(options) {
+        this.rootDir = options.rootDir;
+        this.registry = options.registry;
+        this.now = options.now ?? (() => new Date());
+    }
+    /** Runs produced by actions during this session, newest first. */
+    getRuntimeRuns() {
+        return this.runtimeRuns;
+    }
+    /** Task status overrides applied by executed actions. */
+    getTaskStatus(taskId) {
+        return this.taskStatus.get(taskId);
+    }
+    getAuditTrail() {
+        return this.audit;
+    }
+    /**
+     * Executes a declared action.
+     *
+     * @param declared the action registry as published to the client. Anything
+     *   not present here is rejected — this is the allowlist.
+     */
+    async execute(request, declared) {
+        const action = declared.find((a) => a.id === request.id);
+        if (!action) {
+            return this.fail(request.id, 'unknown_action', 'That action is not declared by this workspace.');
+        }
+        if (!action.enabled) {
+            return this.fail(action.id, 'disabled', `"${action.label}" is currently disabled.`);
+        }
+        const declaredParams = action.params ?? [];
+        const outcome = buildParams(request.params, declaredParams);
+        if (outcome.invalid) {
+            return this.fail(action.id, 'invalid_params', `"${outcome.invalid.name}" ${outcome.invalid.reason}.`);
+        }
+        const params = outcome.params;
+        const missing = declaredParams
+            .filter((p) => p.required && !String(params[p.name] ?? '').trim())
+            .map((p) => p.label ?? p.name);
+        if (missing.length > 0) {
+            return this.fail(action.id, 'missing_params', `Missing required input: ${missing.join(', ')}.`);
+        }
+        // Who runs this, and what they say it will do. Asked before the
+        // confirmation check, because the answer is half of that decision.
+        const resolution = this.registry.resolve(action);
+        if (!resolution) {
+            return this.fail(action.id, 'no_executor', `No provider can execute "${action.kind}" actions in this workspace.`);
+        }
+        // The hard boundary, recomputed from both claims rather than read off the
+        // incoming view: the workspace may escalate the level, the executor may
+        // escalate it, and the merge takes the higher one. A forged ActionView
+        // therefore cannot de-escalate anything either.
+        const policy = (0, policy_1.strictestPolicy)((0, policy_1.policyFromHint)(action.sideEffect, action.confirm), resolution.policy);
+        if (policy.confirmation === 'required' && request.confirm !== true) {
+            return this.fail(action.id, 'confirmation_required', `"${action.label}" has a ${policy.effect} side effect and needs confirmation.`, resolution.executor.id, policy.effect);
+        }
+        this.seq += 1;
+        const runId = `run-${this.seq}-${slug(action.kind)}`;
+        try {
+            const outcome = await resolution.executor.execute(action, params, {
+                workspaceRoot: this.rootDir,
+                runId,
+                now: this.now(),
+            });
+            // Provenance is the registry's answer OR the executor's, never the
+            // executor's alone: a simulator that forgets to label its output, or a
+            // provider that claims a real effect it did not have, both end up
+            // reported as simulated rather than the reverse.
+            const simulated = resolution.simulated || outcome.simulated === true;
+            const run = outcome.run
+                ? {
+                    ...outcome.run,
+                    id: outcome.run.id ?? runId,
+                    taskId: action.taskId,
+                    simulated,
+                }
+                : undefined;
+            if (run) {
+                this.runtimeRuns.unshift(run);
+                if (this.runtimeRuns.length > MAX_RUNTIME_RUNS) {
+                    this.runtimeRuns.length = MAX_RUNTIME_RUNS;
+                }
+            }
+            if (action.taskId && outcome.taskStatus) {
+                this.taskStatus.set(action.taskId, outcome.taskStatus);
+            }
+            this.record({
+                at: this.now().toISOString(),
+                actionId: action.id,
+                kind: action.kind,
+                sideEffect: policy.effect,
+                ok: true,
+                simulated,
+                message: outcome.message,
+                executor: resolution.executor.id,
+            });
+            return {
+                ok: true,
+                actionId: action.id,
+                message: outcome.message,
+                simulated,
+                run,
+                task: action.taskId && outcome.taskStatus
+                    ? { id: action.taskId, status: outcome.taskStatus }
+                    : undefined,
+            };
+        }
+        catch (err) {
+            const message = `Executor "${resolution.executor.id}" failed: ${err.message}`;
+            return this.fail(action.id, 'executor_failed', message, resolution.executor.id, policy.effect);
+        }
+    }
+    /**
+     * Records a refused or failed attempt and returns the result.
+     *
+     * Exactly one audit line is written per attempt — including the ones that
+     * never reached an executor. Attribution matters here: the trail is the
+     * record of what was asked for and what actually happened.
+     */
+    fail(actionId, error, message, executor = 'none', sideEffect = 'none') {
+        this.record({
+            at: this.now().toISOString(),
+            actionId,
+            kind: 'n/a',
+            sideEffect,
+            ok: false,
+            simulated: false,
+            message,
+            executor,
+        });
+        return { ok: false, actionId, message, simulated: false, error };
+    }
+    record(entry) {
+        this.audit.unshift(entry);
+        if (this.audit.length > MAX_AUDIT)
+            this.audit.length = MAX_AUDIT;
+    }
+}
+exports.ActionEngine = ActionEngine;
+/**
+ * Untrusted browser input, filtered against the action's declared schema.
+ *
+ * The distinguishing property is what is *absent* from the result: a key the
+ * action never declared. An executor written against the spec therefore cannot
+ * be reached by `shell`, `cwd`, or anything else a hostile page invents — not
+ * because the executor remembers to ignore them, but because they never arrive.
+ *
+ * Values that are legal for their type are normalized (`boolean` becomes the
+ * string "true"/"false"), so an executor has one shape to handle.
+ */
+function buildParams(input, declared) {
+    const params = {};
+    if (typeof input !== 'object' || input === null || Array.isArray(input))
+        return { params };
+    const supplied = input;
+    for (const spec of declared.slice(0, MAX_PARAMS)) {
+        const raw = supplied[spec.name];
+        if (raw === undefined)
+            continue;
+        if (typeof raw !== 'string' && typeof raw !== 'number' && typeof raw !== 'boolean')
+            continue;
+        const value = String(raw).slice(0, MAX_PARAM_LENGTH);
+        if (spec.type === 'select') {
+            const options = spec.options ?? [];
+            // An out-of-range select is refused rather than passed through: a
+            // provider that branches on this value would otherwise be steerable.
+            if (options.length > 0 && !options.includes(value)) {
+                return { params, invalid: { name: spec.name, reason: `must be one of: ${options.join(', ')}` } };
+            }
+        }
+        if (spec.type === 'boolean') {
+            const normalized = value.trim().toLowerCase();
+            if (normalized !== 'true' && normalized !== 'false') {
+                return { params, invalid: { name: spec.name, reason: 'must be true or false' } };
+            }
+            params[spec.name] = normalized;
+            continue;
+        }
+        params[spec.name] = value;
+    }
+    return { params };
+}
+function slug(kind) {
+    return kind.replace(/[^a-z0-9]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'action';
+}
+//# sourceMappingURL=engine.js.map

package/dist/actions/engine.js.map

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

package/dist/actions/policy.d.ts

@@ -0,0 +1,8 @@
+import type { EffectPolicy, SideEffect } from '../types';
+/** The policy a workspace's own declaration amounts to. */
+export declare function policyFromHint(sideEffect?: SideEffect, confirm?: boolean): EffectPolicy;
+/** The stricter of two policies: the higher effect, and confirmation if either asks. */
+export declare function stricterPolicy(a: EffectPolicy, b: EffectPolicy): EffectPolicy;
+/** Folds a list of claims into the policy that governs the action. */
+export declare function strictestPolicy(...policies: EffectPolicy[]): EffectPolicy;
+//# sourceMappingURL=policy.d.ts.map

package/dist/actions/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/actions/policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAoCzD,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,UAAU,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,YAAY,CAKvF;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,YAAY,CAM7E;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,GAAG,QAAQ,EAAE,YAAY,EAAE,GAAG,YAAY,CAEzE"}

package/dist/actions/policy.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.policyFromHint = policyFromHint;
+exports.stricterPolicy = stricterPolicy;
+exports.strictestPolicy = strictestPolicy;
+// ---------------------------------------------------------------------------
+// Effect policy — the one place the confirmation boundary is computed.
+//
+// There are two statements about how dangerous an action is:
+//
+//   * the workspace's claim  — `sideEffect` + `confirm` in the manifest. The
+//     workspace is untrusted input, so this is a *hint*.
+//   * the provider's claim   — `ActionExecutor.policy()`. The provider is the
+//     code that will actually run, so this is *authoritative*.
+//
+// They are merged, and the stricter one wins, every time. A workspace can say
+// "this is worse than you think" and get a confirmation prompt; it can never
+// say "this is fine" and remove one. The old model let it: a manifest that
+// called a future `publish` action `sideEffect: "state"` decided its own
+// safety level, which is the wrong direction for untrusted input to point.
+//
+// The merge also normalizes one invariant: an effect that leaves this machine
+// always requires confirmation, whatever either side said. Spelling it here
+// rather than at the call site means there is no path that forgets it.
+// ---------------------------------------------------------------------------
+const RANK = { none: 0, state: 1, external: 2 };
+/**
+ * The invariant, applied to every policy that leaves this module: an effect
+ * that reaches outside this machine is always confirmed. Stated once here
+ * rather than at each call site, because there is no path that should skip it.
+ */
+function normalize(policy) {
+    return policy.effect === 'external' && policy.confirmation !== 'required'
+        ? { effect: 'external', confirmation: 'required' }
+        : policy;
+}
+/** The policy a workspace's own declaration amounts to. */
+function policyFromHint(sideEffect, confirm) {
+    return normalize({
+        effect: sideEffect ?? 'state',
+        confirmation: confirm ? 'required' : 'optional',
+    });
+}
+/** The stricter of two policies: the higher effect, and confirmation if either asks. */
+function stricterPolicy(a, b) {
+    return normalize({
+        effect: RANK[a.effect] >= RANK[b.effect] ? a.effect : b.effect,
+        confirmation: a.confirmation === 'required' || b.confirmation === 'required' ? 'required' : 'optional',
+    });
+}
+/** Folds a list of claims into the policy that governs the action. */
+function strictestPolicy(...policies) {
+    return policies.reduce(stricterPolicy, { effect: 'none', confirmation: 'optional' });
+}
+//# sourceMappingURL=policy.js.map

package/dist/actions/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/actions/policy.ts"],"names":[],"mappings":";;AAqCA,wCAKC;AAGD,wCAMC;AAGD,0CAEC;AAtDD,8EAA8E;AAC9E,uEAAuE;AACvE,EAAE;AACF,6DAA6D;AAC7D,EAAE;AACF,6EAA6E;AAC7E,yDAAyD;AACzD,8EAA8E;AAC9E,+DAA+D;AAC/D,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,2EAA2E;AAC3E,yEAAyE;AACzE,2EAA2E;AAC3E,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,uEAAuE;AACvE,8EAA8E;AAE9E,MAAM,IAAI,GAA+B,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;AAE5E;;;;GAIG;AACH,SAAS,SAAS,CAAC,MAAoB;IACrC,OAAO,MAAM,CAAC,MAAM,KAAK,UAAU,IAAI,MAAM,CAAC,YAAY,KAAK,UAAU;QACvE,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE;QAClD,CAAC,CAAC,MAAM,CAAC;AACb,CAAC;AAED,2DAA2D;AAC3D,SAAgB,cAAc,CAAC,UAAuB,EAAE,OAAiB;IACvE,OAAO,SAAS,CAAC;QACf,MAAM,EAAE,UAAU,IAAI,OAAO;QAC7B,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU;KAChD,CAAC,CAAC;AACL,CAAC;AAED,wFAAwF;AACxF,SAAgB,cAAc,CAAC,CAAe,EAAE,CAAe;IAC7D,OAAO,SAAS,CAAC;QACf,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM;QAC9D,YAAY,EACV,CAAC,CAAC,YAAY,KAAK,UAAU,IAAI,CAAC,CAAC,YAAY,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU;KAC3F,CAAC,CAAC;AACL,CAAC;AAED,sEAAsE;AACtE,SAAgB,eAAe,CAAC,GAAG,QAAwB;IACzD,OAAO,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC,CAAC;AACvF,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+export declare function main(argv: string[]): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAsBA,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAoBzC"}