@try-works/dsh-tool-mode 0.0.0-stage → 0.5.45

package/node_modules/@try-works/tool-mode-contracts/lib/meta.js

@@ -0,0 +1,64 @@
+/**
+ * The shared result envelope every Tool Mode tool returns (DECL-03).
+ *
+ * The envelope is what makes a result self-describing: a caller can tell which
+ * contract and version produced it, which implementation actually ran, where it
+ * ran, and whether the host attached any warnings. The host stamps the
+ * authoritative provenance fields; an implementation cannot forge another
+ * package's identity.
+ *
+ * DECL-04 is the reason `warnings` exists but a universal `confidence` does not:
+ * a successful call means a valid result was produced, not that it is correct,
+ * and a fabricated confidence number would claim more than the model supplied.
+ *
+ * @module @try-works/tool-mode-contracts/meta
+ */
+/** The JSON Schema for {@link ToolMeta}, used to validate every result. */
+export const TOOL_META_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: [
+        'contract', 'contractVersion', 'implementationId', 'extension',
+        'extensionVersion', 'activationGeneration', 'executionLocation',
+        'receiptId', 'warnings',
+    ],
+    properties: {
+        contract: { type: 'string', minLength: 1 },
+        contractVersion: { type: 'string', pattern: '^\\d+\\.\\d+\\.\\d+$' },
+        implementationId: { type: 'string', minLength: 1 },
+        extension: { type: 'string', minLength: 1 },
+        extensionVersion: { type: 'string', pattern: '^\\d+\\.\\d+\\.\\d+' },
+        activationGeneration: { type: 'integer', minimum: 0 },
+        executionLocation: { type: 'string', enum: ['host', 'device', 'team-server', 'remote'] },
+        receiptId: { type: 'string', minLength: 1 },
+        warnings: { type: 'array', items: { type: 'string' } },
+        confidence: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['kind', 'source'],
+            properties: {
+                kind: { type: 'string', enum: ['vendor-reported', 'calibrated', 'ranking-logits', 'unavailable'] },
+                source: { type: 'string', minLength: 1 },
+            },
+        },
+    },
+};
+/**
+ * Attach a `meta` property to a result schema.
+ *
+ * Contracts declare their own payload; the envelope is identical everywhere, so
+ * it is composed here rather than retyped in each contract — retyping it is how
+ * the shapes drift apart.
+ * @param payload - the contract's payload schema properties.
+ * @param requiredPayload - payload property names that are required.
+ * @returns a closed object schema containing the payload plus `meta`.
+ */
+export function withMeta(payload, requiredPayload = []) {
+    return {
+        type: 'object',
+        additionalProperties: false,
+        required: [...requiredPayload, 'meta'],
+        properties: { ...payload, meta: TOOL_META_SCHEMA },
+    };
+}
+//# sourceMappingURL=meta.js.map

package/node_modules/@try-works/tool-mode-contracts/lib/registry.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Contract definitions and their runtime validation.
+ *
+ * A contract is the tool's public identity: stable name, version, input and
+ * output schema, semantics, limits and policy metadata (DECL-01). It is
+ * deliberately model-free — implementations bind to it, it does not know about
+ * them — which is what lets two models serve one `stt_transcribe` instead of
+ * producing a duplicate tool each (BASE-02).
+ *
+ * Milestone A is explicit that "a copied schema with no runtime validation is not
+ * completion", so this module validates both directions: the contract DEFINITION
+ * is checked when registered, and every RESULT is checked against the declared
+ * output schema before it reaches a caller.
+ *
+ * @module @try-works/tool-mode-contracts/registry
+ */
+import { TOOL_META_SCHEMA } from './meta.ts';
+/** One tool contract: the authored-once public identity (DECL-01). */
+export interface ToolContract {
+    /** Contract identity, e.g. `stt.transcribe`. Never a model name. */
+    readonly contract: string;
+    /** Semantic version, independent of any host release number. */
+    readonly version: string;
+    /** The tool name callers see, e.g. `stt_transcribe`. */
+    readonly toolName: string;
+    /** Concise description, used verbatim for DSH registration. */
+    readonly description: string;
+    /** Input schema as JSON Schema. The object root is closed. */
+    readonly inputSchema: Record<string, unknown>;
+    /** Output schema as JSON Schema, including the `meta` envelope. */
+    readonly outputSchema: Record<string, unknown>;
+    /** Declared semantics a caller must be able to rely on. */
+    readonly semantics: Readonly<Record<string, string | number | boolean>>;
+    /** Admitted resource limits, in the units the schema declares. */
+    readonly limits: Readonly<Record<string, number>>;
+    /** Unsupported cases the caller should be told about. */
+    readonly unsupported: readonly string[];
+    /** Worked examples the author ships with the contract (DECL-01). */
+    readonly examples?: readonly ContractExample[];
+    /** Policy metadata beyond limits (DECL-01). */
+    readonly policy?: ContractPolicy;
+}
+/** One worked example: a representative input and its output payload. */
+export interface ContractExample {
+    readonly input: Record<string, unknown>;
+    readonly output: Record<string, unknown>;
+}
+/** Explicit policy metadata for a contract (DECL-01). */
+export interface ContractPolicy {
+    readonly recording: 'required' | 'optional';
+    readonly remote: 'allowed' | 'local-only';
+}
+/** A contract that failed validation, with every reason. */
+export declare class ContractError extends Error {
+    readonly name = "ContractError";
+    /** The individual violations, in declaration order. */
+    readonly violations: readonly string[];
+    constructor(subject: string, violations: readonly string[]);
+}
+/** A value that did not satisfy a declared schema. */
+export declare class ContractViolationError extends Error {
+    readonly name = "ContractViolationError";
+    readonly violations: readonly string[];
+    constructor(subject: string, violations: readonly string[]);
+}
+/**
+ * Validate a contract definition.
+ *
+ * This is deliberately strict about the identity fields: a contract whose
+ * `toolName` is not a legal tool name, or whose version is not semver, would
+ * register a tool that callers cannot address consistently.
+ * @param contract - the definition to check.
+ * @throws ContractError listing every violation.
+ */
+export declare function assertValidContract(contract: ToolContract): void;
+/**
+ * Validate caller arguments against the contract's input schema.
+ * @param contract - the contract to check against.
+ * @param args - the candidate arguments.
+ * @throws ContractViolationError listing every violation.
+ */
+export declare function assertValidInput(contract: ToolContract, args: unknown): void;
+/**
+ * Validate a result against the contract's output schema.
+ *
+ * This runs before the value reaches a caller, so a violation surfaces as a
+ * tool failure rather than as malformed data downstream (AT-11).
+ * @param contract - the contract to check against.
+ * @param value - the candidate result.
+ * @throws ContractViolationError listing every violation.
+ */
+export declare function assertValidOutput(contract: ToolContract, value: unknown): void;
+/** The meta envelope's own schema, exported for contract authors. */
+export { TOOL_META_SCHEMA };
+/**
+ * Compile an arbitrary JSON Schema once, for a host that serves manifest-declared
+ * tool schemas rather than registered contracts.
+ *
+ * Compiling at REGISTRATION (in the host's try/catch) means a malformed schema
+ * fails when the tool is registered, not on the first caller's event-loop tick —
+ * and it is never re-compiled per call, which a per-call text-keyed cache could
+ * not guarantee.
+ * @param schema - the JSON Schema to compile.
+ * @throws ContractError when the schema does not compile.
+ * @returns a validator whose violations are rendered by {@link assertAgainstSchema}.
+ */
+export declare function compileSchema(schema: Readonly<Record<string, unknown>>): (value: unknown) => readonly string[];
+/**
+ * Validate an arbitrary value against a compiled declared schema.
+ *
+ * The full-schema counterpart of {@link assertValidInput}/{@link assertValidOutput}:
+ * the projected advertisement the DSH registry validates is deliberately LOOSER
+ * (union members become `json`, unsupported keywords are dropped), so without this
+ * the dropped keywords are enforced nowhere for manifest-declared tools.
+ * @param subject - the tool or schema name used in the violation message.
+ * @param validate - the compiled validator, from {@link compileSchema}.
+ * @param value - the candidate value.
+ * @throws ContractViolationError listing every violation.
+ */
+export declare function assertAgainstSchema(subject: string, validate: (value: unknown) => readonly string[], value: unknown): void;
+//# sourceMappingURL=registry.d.ts.map

package/node_modules/@try-works/tool-mode-contracts/lib/registry.d.ts.map

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

package/node_modules/@try-works/tool-mode-contracts/lib/registry.js

@@ -0,0 +1,246 @@
+/**
+ * Contract definitions and their runtime validation.
+ *
+ * A contract is the tool's public identity: stable name, version, input and
+ * output schema, semantics, limits and policy metadata (DECL-01). It is
+ * deliberately model-free — implementations bind to it, it does not know about
+ * them — which is what lets two models serve one `stt_transcribe` instead of
+ * producing a duplicate tool each (BASE-02).
+ *
+ * Milestone A is explicit that "a copied schema with no runtime validation is not
+ * completion", so this module validates both directions: the contract DEFINITION
+ * is checked when registered, and every RESULT is checked against the declared
+ * output schema before it reaches a caller.
+ *
+ * @module @try-works/tool-mode-contracts/registry
+ */
+// The explicit `.js` suffix is REQUIRED for packed installs: plain Node ESM does
+// not apply extension resolution to package subpaths, and the workspace's tsx
+// loader masks that (the round-67 packed-orchestration run caught exactly this
+// failure). extension-needle's validation.ts uses the same spelling.
+import Ajv2020 from 'ajv/dist/2020.js';
+import { TOOL_META_SCHEMA } from "./meta.js";
+/** A contract that failed validation, with every reason. */
+export class ContractError extends Error {
+    name = 'ContractError';
+    /** The individual violations, in declaration order. */
+    violations;
+    constructor(subject, violations) {
+        super(`${subject} is not a valid contract: ${violations.join('; ')}`);
+        this.violations = violations;
+    }
+}
+/** A value that did not satisfy a declared schema. */
+export class ContractViolationError extends Error {
+    name = 'ContractViolationError';
+    violations;
+    constructor(subject, violations) {
+        super(`value violates the ${subject} schema: ${violations.join('; ')}`);
+        this.violations = violations;
+    }
+}
+/**
+ * The validator, on the 2020-12 dialect.
+ *
+ * 2020-12 rather than draft-07 because extension-declared schemas ship as
+ * 2020-12 documents (`$schema`, `$id`, `$defs` — the extension-needle package's
+ * tools-plan/structured-extract schemas are the concrete case): a draft-07
+ * compiler cannot resolve `#/$defs/...` references, so those real packages
+ * could not be activated in the host. `strict: false` for the same reason as
+ * before — contract schemas annotate keywords Ajv's strict mode rejects when
+ * they are merely descriptive, and a strict-mode THROW on an annotation would
+ * refuse a schema that validates fine. A schema that does not COMPILE (an
+ * unresolvable `$ref`, a structurally broken keyword) still throws at
+ * registration, so a bad schema refuses loudly rather than being accepted.
+ * `allowUnionTypes` admits `type: ["number", "null"]`-style unions, which the
+ * shipped needle schemas use for nullable fields. `allErrors` keeps the
+ * violation report listing every problem rather than the first.
+ */
+function createAjv() {
+    return new Ajv2020({ allErrors: true, strict: false, allowUnionTypes: true });
+}
+const ajv = createAjv();
+const outputValidators = new Map();
+const inputValidators = new Map();
+/**
+ * Validators for $id-bearing schemas, keyed by the id itself.
+ *
+ * Ajv registers a compiled schema under its `$id`, and compiling the same id a
+ * second time THROWS "already exists" — which would make re-activating an
+ * extension (or two tools sharing one declared schema file) fail on the second
+ * compile. Identical content re-compiles to the same validator; DIFFERENT
+ * content under one id is a refusal, because two schemas sharing an id is
+ * exactly the drift a caller must never silently inherit.
+ */
+const compiledById = new Map();
+/** Compile a schema, tolerating a repeat compile of identical $id content. */
+function compileTracked(schema) {
+    const id = typeof schema.$id === 'string' ? schema.$id : undefined;
+    if (id === undefined)
+        return ajv.compile(schema);
+    const serialized = JSON.stringify(schema);
+    const cached = compiledById.get(id);
+    if (cached !== undefined) {
+        if (cached.serialized !== serialized) {
+            throw new ContractError('declared-schema', [`a schema with $id ${JSON.stringify(id)} was already compiled from different content; two different schemas must not share an id`]);
+        }
+        return cached.validate;
+    }
+    const validate = ajv.compile(schema);
+    compiledById.set(id, { serialized, validate });
+    return validate;
+}
+/** Render Ajv errors as stable, deduplicated strings. */
+function renderErrors(errors) {
+    const seen = new Set();
+    const out = [];
+    for (const error of errors ?? []) {
+        const path = error.instancePath === '' ? '(root)' : error.instancePath;
+        const line = `${path} ${error.message ?? 'is invalid'}`;
+        if (!seen.has(line)) {
+            seen.add(line);
+            out.push(line);
+        }
+    }
+    return out;
+}
+/**
+ * Validate a contract definition.
+ *
+ * This is deliberately strict about the identity fields: a contract whose
+ * `toolName` is not a legal tool name, or whose version is not semver, would
+ * register a tool that callers cannot address consistently.
+ * @param contract - the definition to check.
+ * @throws ContractError listing every violation.
+ */
+export function assertValidContract(contract) {
+    const violations = [];
+    if (!/^[a-z][a-z0-9_]*$/.test(contract.toolName)) {
+        violations.push(`toolName ${JSON.stringify(contract.toolName)} must be lower snake_case`);
+    }
+    if (!/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/.test(contract.contract)) {
+        violations.push(`contract ${JSON.stringify(contract.contract)} must be a dotted lower-case identity `
+            + '(for example "stt.transcribe" or "text.language_detect")');
+    }
+    if (!/^\d+\.\d+\.\d+$/.test(contract.version)) {
+        violations.push(`version ${JSON.stringify(contract.version)} must be semantic (x.y.z)`);
+    }
+    if (contract.description.trim().length < 10) {
+        violations.push('description must be a real sentence, not a placeholder');
+    }
+    const input = contract.inputSchema;
+    if (input.type !== 'object') {
+        violations.push('inputSchema root must be an object (clients require an object argument)');
+    }
+    const output = contract.outputSchema;
+    if (output.type !== 'object') {
+        violations.push('outputSchema root must be an object for broad client compatibility (DECL-02)');
+    }
+    else if (output.properties?.meta === undefined) {
+        violations.push('outputSchema must include the shared `meta` envelope (DECL-03)');
+    }
+    // DECL-02: an unconstrained open object is not an adequate leaf-tool contract.
+    if (output.additionalProperties !== false) {
+        violations.push('outputSchema must be closed (additionalProperties: false), not a generic open object (DECL-02)');
+    }
+    if (contract.unsupported.length === 0) {
+        violations.push('unsupported must name at least one case; an empty list claims universal support');
+    }
+    if (violations.length > 0)
+        throw new ContractError(contract.contract, violations);
+    // Schemas must be compilable, or the contract is unenforceable.
+    try {
+        inputValidators.set(contract.contract, compileTracked(contract.inputSchema));
+    }
+    catch (error) {
+        throw new ContractError(contract.contract, [`inputSchema does not compile: ${message(error)}`]);
+    }
+    try {
+        outputValidators.set(contract.contract, compileTracked(contract.outputSchema));
+    }
+    catch (error) {
+        throw new ContractError(contract.contract, [`outputSchema does not compile: ${message(error)}`]);
+    }
+}
+/**
+ * Validate caller arguments against the contract's input schema.
+ * @param contract - the contract to check against.
+ * @param args - the candidate arguments.
+ * @throws ContractViolationError listing every violation.
+ */
+export function assertValidInput(contract, args) {
+    const validate = inputValidators.get(contract.contract);
+    if (validate === undefined) {
+        throw new ContractError(contract.contract, ['input was validated before the contract was registered']);
+    }
+    if (!validate(args))
+        throw new ContractViolationError(contract.contract, renderErrors(validate.errors));
+}
+/**
+ * Validate a result against the contract's output schema.
+ *
+ * This runs before the value reaches a caller, so a violation surfaces as a
+ * tool failure rather than as malformed data downstream (AT-11).
+ * @param contract - the contract to check against.
+ * @param value - the candidate result.
+ * @throws ContractViolationError listing every violation.
+ */
+export function assertValidOutput(contract, value) {
+    const validate = outputValidators.get(contract.contract);
+    if (validate === undefined) {
+        throw new ContractError(contract.contract, ['result was validated before the contract was registered']);
+    }
+    if (!validate(value))
+        throw new ContractViolationError(contract.contract, renderErrors(validate.errors));
+}
+/** The meta envelope's own schema, exported for contract authors. */
+export { TOOL_META_SCHEMA };
+/**
+ * Compile an arbitrary JSON Schema once, for a host that serves manifest-declared
+ * tool schemas rather than registered contracts.
+ *
+ * Compiling at REGISTRATION (in the host's try/catch) means a malformed schema
+ * fails when the tool is registered, not on the first caller's event-loop tick —
+ * and it is never re-compiled per call, which a per-call text-keyed cache could
+ * not guarantee.
+ * @param schema - the JSON Schema to compile.
+ * @throws ContractError when the schema does not compile.
+ * @returns a validator whose violations are rendered by {@link assertAgainstSchema}.
+ */
+export function compileSchema(schema) {
+    let validate;
+    try {
+        validate = compileTracked(schema);
+    }
+    catch (error) {
+        throw new ContractError('declared-schema', [`schema does not compile: ${message(error)}`]);
+    }
+    return value => (validate(value) ? [] : renderErrors(validate.errors));
+}
+/**
+ * Validate an arbitrary value against a compiled declared schema.
+ *
+ * The full-schema counterpart of {@link assertValidInput}/{@link assertValidOutput}:
+ * the projected advertisement the DSH registry validates is deliberately LOOSER
+ * (union members become `json`, unsupported keywords are dropped), so without this
+ * the dropped keywords are enforced nowhere for manifest-declared tools.
+ * @param subject - the tool or schema name used in the violation message.
+ * @param validate - the compiled validator, from {@link compileSchema}.
+ * @param value - the candidate value.
+ * @throws ContractViolationError listing every violation.
+ */
+export function assertAgainstSchema(subject, validate, value) {
+    const violations = validate(value);
+    if (violations.length > 0)
+        throw new ContractViolationError(subject, violations);
+}
+/** Best-effort message from an arbitrary thrown value. */
+function message(error) {
+    try {
+        return error instanceof Error ? error.message : String(error);
+    }
+    catch {
+        return '<unrenderable>';
+    }
+}
+//# sourceMappingURL=registry.js.map

package/node_modules/@try-works/tool-mode-contracts/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@try-works/tool-mode-contracts",
+  "version": "0.1.1",
+  "description": "Model-free standard tool contracts for Tool Mode: identities, schemas, semantics and runtime validation",
+  "license": "Apache-2.0",
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/try-works/tool-mode.git",
+    "directory": "packages/tool-mode-contracts"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": { "types": "./lib/index.d.ts", "default": "./lib/index.js" },
+    "./package.json": "./package.json"
+  },
+  "files": ["lib/**/*.js", "lib/**/*.d.ts", "lib/**/*.d.ts.map", "README.md"],
+  "dependencies": {
+    "ajv": "^8.20.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "tsx --test tests/*.test.ts",
+    "prepack": "tsc -p tsconfig.build.json",
+    "prepare": "tsc -p tsconfig.build.json"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}
+

package/node_modules/@try-works/tool-mode-extension-sdk/bin/dsh-tool-mode.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * The `dsh-tool-mode` executable (EXT-31).
+ *
+ * A thin shim: it wires real process streams into the tested CLI and translates
+ * the returned code into an exit status. All the logic lives in the library, so
+ * every path — including the refusals — is exercised by tests rather than only by
+ * running the binary by hand.
+ */
+
+import { runToolModeCli } from '../lib/cli.js'
+
+const code = await runToolModeCli(
+  process.argv.slice(2),
+  {
+    out: line => process.stdout.write(`${line}\n`),
+    err: line => process.stderr.write(`${line}\n`),
+  },
+)
+process.exitCode = code

package/node_modules/@try-works/tool-mode-extension-sdk/lib/cli.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The operator command family (EXT-31).
+ *
+ * EXT-31 is explicit that these are REQUIRED NEW FUNCTIONALITY, not existing npm
+ * or DSH commands, and that offline edits must hold exclusive store ownership. So
+ * every mutating command takes the store lock, and the CLI refuses rather than
+ * racing a running host.
+ *
+ * The entry point takes argv and an output sink instead of reading `process`
+ * directly. A CLI that can only be exercised by spawning a child process is a CLI
+ * whose failure paths are tested by hand or not at all, and the failure paths here
+ * are the security-relevant ones.
+ *
+ * The management surface is deliberately NOT the inference surface: EXT-31 forbids
+ * exposing the management channel on the MCP tool surface by default, and nothing
+ * in this module registers a tool.
+ *
+ * @module @try-works/tool-mode-extension-sdk/cli
+ */
+import { type ContributionRegistrar } from './install/lifecycle.ts';
+/** Where the CLI writes. Injected so a test can capture output. */
+export interface CliIo {
+    /** Write one line of normal output. */
+    out(line: string): void;
+    /** Write one line of error output. */
+    err(line: string): void;
+}
+/** Options resolved from argv. */
+export interface CliOptions {
+    /** The extension store root. */
+    readonly store: string;
+    /** The profile to act on. */
+    readonly profile: string;
+    /** Positional arguments after the command. */
+    readonly positional: readonly string[];
+    /** `--flag` names and their values. */
+    readonly flags: Readonly<Record<string, string | true>>;
+}
+/** What the CLI needs from the environment to act. */
+export interface CliDependencies {
+    /** A registrar for activation. Without one, activation is refused rather than faked. */
+    readonly registrar?: ContributionRegistrar;
+    /** Parse and install from a specifier; injected so the CLI owns no network stack. */
+    readonly install?: (spec: string, integrity: string | undefined, store: string) => Promise<string>;
+    /**
+     * The recipes authoring runner, forwarded to by the `recipes` namespace
+     * (RCP-08). When absent, the SDK resolves `@try-works/tool-mode-recipes/cli`
+     * lazily at invocation time; when that also fails, the command answers a
+     * PRECISE refusal — the SDK never duplicates recipe semantics and never
+     * depends on the recipes package at import time.
+     */
+    readonly recipeCliRunner?: {
+        runRecipeCli(argv: readonly string[], io: CliIo): Promise<number>;
+    };
+    /** Override the lazy resolver (tests); returns the runner or undefined. */
+    readonly resolveRecipeCli?: () => Promise<{
+        runRecipeCli(argv: readonly string[], io: CliIo): Promise<number>;
+    } | undefined>;
+}
+/**
+ * Parse argv into options.
+ *
+ * Anything unrecognised is REFUSED rather than ignored: a mistyped flag that is
+ * silently dropped turns `--deactivate` into a command the operator did not ask
+ * for, which on `uninstall` is the difference between previewing and removing.
+ * @param argv - arguments after the executable name.
+ * @returns the parsed options.
+ * @throws ManagementError when a flag is unknown or a value is missing.
+ */
+export declare function parseArgs(argv: readonly string[]): CliOptions;
+/**
+ * Run one command.
+ *
+ * @param argv - arguments after the executable name.
+ * @param io - output sinks.
+ * @param dependencies - the registrar and installer to act with.
+ * @returns the process exit code.
+ */
+export declare function runToolModeCli(argv: readonly string[], io: CliIo, dependencies?: CliDependencies): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/node_modules/@try-works/tool-mode-extension-sdk/lib/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AAIvF,mEAAmE;AACnE,MAAM,WAAW,KAAK;IACpB,uCAAuC;IACvC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,sCAAsC;IACtC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB;AAED,kCAAkC;AAClC,MAAM,WAAW,UAAU;IACzB,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAA;CACxD;AAED,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,wFAAwF;IACxF,QAAQ,CAAC,SAAS,CAAC,EAAE,qBAAqB,CAAA;IAC1C,qFAAqF;IACrF,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAClG;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE;QAAE,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;KAAE,CAAA;IAChG,2EAA2E;IAC3E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC;QAAE,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;KAAE,GAAG,SAAS,CAAC,CAAA;CAC7H;AA4ED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CA4C7D;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,YAAY,GAAE,eAAoB,GACjC,OAAO,CAAC,MAAM,CAAC,CA8DjB"}