@apicircle/shared 1.0.1 → 1.0.3

package/LICENSE

@@ -1,110 +1,110 @@
-API Circle Studio License
-Custom Source-Available License, v1.0
-
-Copyright (c) 2026 Deva Prakash ("Licensor")
-
-The source code in this repository ("the Software") is made available for
-the purposes of transparency, security review, contribution, and personal
-evaluation. This is NOT an open-source license as defined by the Open
-Source Initiative.
-
-0. Definitions
-
-   "Commercial Use" means any use of the Software that is intended for
-   or directed toward commercial advantage or monetary compensation,
-   whether direct or indirect, including without limitation:
-
-   (a) using the Software to build, test, develop, deploy, or operate
-       any product, service, application, or system that is sold,
-       licensed, hosted, distributed, or otherwise made available to
-       any third party for a fee or other consideration;
-   (b) using the Software in the course of paid employment, paid
-       consulting, paid contracting, freelance work, or any other
-       revenue-generating activity, regardless of whether the Software
-       itself is sold or transferred;
-   (c) using the Software internally within a for-profit organization
-       beyond the Evaluation Period defined below;
-   (d) integrating the Software, or any portion of it, into any tool,
-       pipeline, automation, or workflow that supports the commercial
-       operations of any business;
-   (e) using the Software to provide a hosted, managed, or embedded
-       service of any kind to a third party, whether free or paid.
-
-   "Non-Commercial Use" means any use that is not Commercial Use,
-   including personal hobby projects, individual learning, academic
-   research, classroom instruction, and good-faith contribution to
-   this repository.
-
-   "Evaluation Period" means a single, continuous period of up to
-   thirty (30) days during which a for-profit organization may
-   internally evaluate the Software at no charge. After the Evaluation
-   Period expires, any further use of the Software by that organization
-   constitutes Commercial Use and requires a separate commercial
-   license from the Licensor.
-
-1. Permitted Use
-
-   You may, without charge:
-
-   (a) view, read, and study the source code of the Software;
-   (b) run the Software, in source or compiled form, for your own
-       Non-Commercial Use, or for Commercial Use solely within the
-       Evaluation Period;
-   (c) submit improvements to the Software back to this repository via
-       pull request, subject to Section 3 (Contributions).
-
-2. Prohibited Use
-
-   Without prior written permission from the Licensor, you may NOT:
-
-   (a) make any Commercial Use of the Software, in whole or in part,
-       except during the Evaluation Period as defined in Section 0;
-   (b) redistribute the Software, in source or compiled form, whether
-       modified or unmodified, to any third party;
-   (c) sublicense, sell, rent, lease, or otherwise transfer the
-       Software or any rights granted herein;
-   (d) remove, obscure, or alter any copyright, trademark, attribution,
-       or license notice contained in the Software;
-   (e) use the names "API Circle", "API Circle Studio", or any related
-       logos or trademarks, except as required for accurate attribution.
-
-3. Contributions
-
-   By submitting any contribution (including but not limited to code,
-   documentation, or assets) to this repository, you grant the Licensor
-   a perpetual, worldwide, irrevocable, royalty-free, sublicensable
-   license to use, modify, distribute, and relicense your contribution
-   under any terms, including the terms of this license or any future
-   version thereof.
-
-4. No Trademark License
-
-   This license does not grant permission to use the trade names,
-   trademarks, service marks, or product names of the Licensor, except
-   as required for reasonable and customary use in describing the
-   origin of the Software.
-
-5. Termination
-
-   The rights granted in Section 1 terminate automatically if you
-   breach any term of this license. Upon termination, you must cease
-   all use of the Software and destroy all copies in your possession.
-
-6. Disclaimer of Warranty
-
-   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
-   NON-INFRINGEMENT.
-
-7. Limitation of Liability
-
-   IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR
-   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
-   OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
-   OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-8. Commercial Licensing
-
-   For commercial licensing, redistribution, or any use not permitted
-   under Section 1, contact: apicircle365@gmail.com
+API Circle Studio License
+Custom Source-Available License, v1.0
+
+Copyright (c) 2026 Deva Prakash ("Licensor")
+
+The source code in this repository ("the Software") is made available for
+the purposes of transparency, security review, contribution, and personal
+evaluation. This is NOT an open-source license as defined by the Open
+Source Initiative.
+
+0. Definitions
+
+   "Commercial Use" means any use of the Software that is intended for
+   or directed toward commercial advantage or monetary compensation,
+   whether direct or indirect, including without limitation:
+
+   (a) using the Software to build, test, develop, deploy, or operate
+       any product, service, application, or system that is sold,
+       licensed, hosted, distributed, or otherwise made available to
+       any third party for a fee or other consideration;
+   (b) using the Software in the course of paid employment, paid
+       consulting, paid contracting, freelance work, or any other
+       revenue-generating activity, regardless of whether the Software
+       itself is sold or transferred;
+   (c) using the Software internally within a for-profit organization
+       beyond the Evaluation Period defined below;
+   (d) integrating the Software, or any portion of it, into any tool,
+       pipeline, automation, or workflow that supports the commercial
+       operations of any business;
+   (e) using the Software to provide a hosted, managed, or embedded
+       service of any kind to a third party, whether free or paid.
+
+   "Non-Commercial Use" means any use that is not Commercial Use,
+   including personal hobby projects, individual learning, academic
+   research, classroom instruction, and good-faith contribution to
+   this repository.
+
+   "Evaluation Period" means a single, continuous period of up to
+   thirty (30) days during which a for-profit organization may
+   internally evaluate the Software at no charge. After the Evaluation
+   Period expires, any further use of the Software by that organization
+   constitutes Commercial Use and requires a separate commercial
+   license from the Licensor.
+
+1. Permitted Use
+
+   You may, without charge:
+
+   (a) view, read, and study the source code of the Software;
+   (b) run the Software, in source or compiled form, for your own
+       Non-Commercial Use, or for Commercial Use solely within the
+       Evaluation Period;
+   (c) submit improvements to the Software back to this repository via
+       pull request, subject to Section 3 (Contributions).
+
+2. Prohibited Use
+
+   Without prior written permission from the Licensor, you may NOT:
+
+   (a) make any Commercial Use of the Software, in whole or in part,
+       except during the Evaluation Period as defined in Section 0;
+   (b) redistribute the Software, in source or compiled form, whether
+       modified or unmodified, to any third party;
+   (c) sublicense, sell, rent, lease, or otherwise transfer the
+       Software or any rights granted herein;
+   (d) remove, obscure, or alter any copyright, trademark, attribution,
+       or license notice contained in the Software;
+   (e) use the names "API Circle", "API Circle Studio", or any related
+       logos or trademarks, except as required for accurate attribution.
+
+3. Contributions
+
+   By submitting any contribution (including but not limited to code,
+   documentation, or assets) to this repository, you grant the Licensor
+   a perpetual, worldwide, irrevocable, royalty-free, sublicensable
+   license to use, modify, distribute, and relicense your contribution
+   under any terms, including the terms of this license or any future
+   version thereof.
+
+4. No Trademark License
+
+   This license does not grant permission to use the trade names,
+   trademarks, service marks, or product names of the Licensor, except
+   as required for reasonable and customary use in describing the
+   origin of the Software.
+
+5. Termination
+
+   The rights granted in Section 1 terminate automatically if you
+   breach any term of this license. Upon termination, you must cease
+   all use of the Software and destroy all copies in your possession.
+
+6. Disclaimer of Warranty
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
+   NON-INFRINGEMENT.
+
+7. Limitation of Liability
+
+   IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
+   OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
+   OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+8. Commercial Licensing
+
+   For commercial licensing, redistribution, or any use not permitted
+   under Section 1, contact: apicircle365@gmail.com

package/README.md

@@ -4,23 +4,122 @@
 
 <h1 align="center">@apicircle/shared</h1>
 
-Shared foundation for [API Circle Studio](https://github.com/apicircle/studio) — the TypeScript types, ID generation, validators, and encryption helpers every other `@apicircle/*` package builds on.
+<p align="center">
+  <strong>The TypeScript contract for everything API Circle Studio reads, writes, and ships.</strong><br />
+  One package, one source of truth — types, IDs, validators, crypto, and the MCP tool catalog.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@apicircle/shared"><img src="https://img.shields.io/npm/v/@apicircle/shared?color=cb3837&logo=npm" alt="npm version" /></a>
+  <img src="https://img.shields.io/badge/types-included-blue?logo=typescript" alt="TypeScript types included" />
+  <img src="https://img.shields.io/badge/node-%E2%89%A5%2020-brightgreen" alt="Node ≥ 20" />
+  <img src="https://img.shields.io/badge/zero%20runtime%20deps-yes-success" alt="Zero runtime dependencies" />
+</p>
+
+---
+
+## Why this package exists
+
+Every other `@apicircle/*` package — the request engine, the mock server, the
+MCP host, the CLI, the desktop app — agrees on **one workspace schema**.
+That schema lives here.
+
+If you are building a third-party tool that reads, writes, syncs, lints, or
+visualises an API Circle workspace, this is the only dependency you need to
+stay byte-for-byte compatible with Studio.
+
+> **Use this directly when** you are writing a custom MCP client, a workspace
+> linter, a Git pre-commit hook, a migration script, or any other tool that
+> needs to understand the Studio workspace format without pulling in the
+> full execution engine.
 
 ## Install
 
 ```bash
 npm install @apicircle/shared
+# pnpm add @apicircle/shared
+# yarn add @apicircle/shared
+```
+
+Ships dual ESM + CJS builds and full `.d.ts` types. Zero runtime dependencies.
+
+## What's in the box
+
+| Surface              | What you get                                                                                                                                                 |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Workspace schema** | `WorkspaceSynced` (the git-tracked document) and `WorkspaceLocal` (per-device state) — every entity type Studio knows about, fully typed.                    |
+| **Entity types**     | Requests, folders, environments, mock-server definitions, plans, assertions, releases, linked workspaces, global assets, history runs, secret-crypto blobs.  |
+| **`generateId()`**   | The only sanctioned way to mint entity IDs — collision-resistant, URL-safe, length-bounded.                                                                  |
+| **Validators**       | Lightweight shape checks for workspace documents and imported specs — handy when you're loading untrusted JSON.                                              |
+| **Crypto helpers**   | AES-GCM via WebCrypto for at-rest secret material. Browser-safe, no Node-only modules.                                                                       |
+| **MCP catalog**      | `MCP_TOOL_NAMES` — the canonical list of every tool the MCP server exposes, plus the `McpToolName` union type. Stay in lockstep with the server, by version. |
+| **Envelope types**   | Discriminated unions for MCP responses (`multiple-workspaces`, error envelopes, etc.) so your client gets exhaustive narrowing for free.                     |
+
+## A taste of it
+
+```ts
+import {
+  MCP_TOOL_NAMES,
+  generateId,
+  type McpToolName,
+  type WorkspaceSynced,
+  type Request,
+} from '@apicircle/shared';
+
+// Build a request the way Studio would — same ID shape, same schema.
+const req: Request = {
+  id: generateId(),
+  name: 'List Pets',
+  method: 'GET',
+  url: 'https://api.example.com/pets',
+  headers: [],
+  params: [],
+  auth: { type: 'none' },
+  bodies: {},
+  activeBody: 'none',
+};
+
+// Validate a workspace document loaded from disk / Git.
+const synced: WorkspaceSynced = JSON.parse(raw);
+
+// Iterate every MCP tool the server knows about — useful for building
+// custom MCP clients, dashboards, or documentation generators.
+for (const name of MCP_TOOL_NAMES) {
+  console.log(name); // 'workspace.list', 'request.create', 'mock.start', ...
+}
+
+function dispatch(name: McpToolName) {
+  // McpToolName is a string literal union, so the switch is exhaustive.
+}
 ```
 
-## What's inside
+## Where this fits in the ecosystem
+
+```
+@apicircle/shared              ◀── you are here (types + utilities)
+├── @apicircle/core            (request engine, auth, imports, applyMutation)
+├── @apicircle/mock-server-core (Hono mock-server runtime)
+├── @apicircle/mcp-server       (MCP stdio host + tool catalog)
+└── @apicircle/cli              (apicircle binary)
+```
+
+Most users will install `@apicircle/cli` or `@apicircle/mcp-server` and never
+touch this package directly. You only need `@apicircle/shared` when you're
+the one **building** something that talks to a Studio workspace.
+
+## Stability
+
+The workspace schema is the public contract API Circle Studio cares about most.
+Breaking changes are versioned per [semver](https://semver.org); the schema
+is exercised by **1,900+ unit and integration tests** across the wider Studio
+codebase, and every Studio release (desktop, web, CLI, MCP) pins the same
+`@apicircle/shared` version.
 
-- **Workspace types** — the canonical `WorkspaceSynced` / `WorkspaceLocal` schema and every entity type (requests, folders, environments, mock servers, plans, releases).
-- **`generateId()`** — collision-resistant ID generation; the only sanctioned way to mint entity IDs.
-- **Validators** — shape checks for workspace documents and imported specs.
-- **Encryption helpers** — AES-GCM via WebCrypto for at-rest secret material.
-- **MCP envelopes** — the request/response envelope types shared with `@apicircle/mcp-server`.
+## Learn more
 
-This package is mostly consumed indirectly through the other API Circle packages — install it directly when you are building tooling against the workspace format.
+- **Studio repo & docs**: <https://github.com/apicircle/studio>
+- **MCP tool reference**: <https://github.com/apicircle/studio/blob/main/docs/mcp-tools-reference.md>
+- **Architecture overview**: <https://github.com/apicircle/studio/blob/main/docs/architecture/platform.md>
 
 ## License
 

package/dist/index.cjs

@@ -81,7 +81,7 @@ function validateUrl(value) {
   const trimmed = value.trim();
   if (!trimmed) return fail("URL is required.");
   if (/^\s*\{\{\s*[^{}]+\s*\}\}/.test(trimmed)) return OK;
-  const probe = trimmed.replace(/\{\{[^{}]+\}\}/g, "placeholder");
+  const probe = trimmed.replace(/\{\{[^{}]+\}\}/g, "1");
   try {
     const u = new URL(probe);
     if (!/^https?:|^file:$/i.test(u.protocol)) {
@@ -403,6 +403,7 @@ var MCP_TOOL_NAMES = [
   "import.insomnia",
   "import.har",
   "generate.code",
+  "workspace.list",
   "workspace.read",
   "workspace.write",
   "request.create",