{"_id":"@21stgov/commons","_rev":"7-5a0e2a075dbf5be3db5ea61ed2eaee0c","name":"@21stgov/commons","dist-tags":{"latest":"0.6.0"},"versions":{"0.1.0":{"name":"@21stgov/commons","version":"0.1.0","keywords":["design-system","accessibility","government","civic-tech","cli","commons","21stgov"],"license":"MIT","_id":"@21stgov/commons@0.1.0","maintainers":[{"name":"sethcottle","email":"sethcottle@gmail.com"}],"homepage":"https://commonsui.com","bugs":{"url":"https://github.com/21stgov/commons/issues"},"bin":{"commons":"dist/index.js"},"dist":{"shasum":"627d1d30f3db11381d93d63d3cb7e9db556368b5","tarball":"https://registry.npmjs.org/@21stgov/commons/-/commons-0.1.0.tgz","fileCount":5,"integrity":"sha512-DUK1FcaUlfEw0NqSdJyiWx6+OT2brOL0fVYuy6UVVV4tnyJrnyinLon/7oeZ7W0QoEUfl60nmZ4bKsBJ4YlVcA==","signatures":[{"sig":"MEUCIQDJgkNBn5fYJYwE7BTa7wROpceJT+Tb2dSuUdehnS+Q7gIgYkgJHNs8pHmVXp1/2I3pNLXwvKBE3aGLCdeaxZim4yE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":166921},"type":"module","_from":"file:21stgov-commons-0.1.0.tgz","engines":{"node":">=22"},"private":false,"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"sethcottle","email":"sethcottle@gmail.com"},"_resolved":"/private/var/folders/cf/wl28lk8s19770tzrdlt63yvw0000gn/T/cfedb8e67fa81b5fba9b773fb8e913c6/21stgov-commons-0.1.0.tgz","_integrity":"sha512-DUK1FcaUlfEw0NqSdJyiWx6+OT2brOL0fVYuy6UVVV4tnyJrnyinLon/7oeZ7W0QoEUfl60nmZ4bKsBJ4YlVcA==","repository":{"url":"git+https://github.com/21stgov/commons.git","type":"git","directory":"packages/cli"},"_npmVersion":"11.16.0","description":"The Commons CLI — add accessible, government-ready components from the Commons design system registry.","directories":{},"_nodeVersion":"24.18.0","dependencies":{"zod":"^4.4.3","citty":"^0.2.2","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^4.1.10","typescript":"^5.9.3","@types/node":"^22.20.1"},"_npmOperationalInternal":{"tmp":"tmp/commons_0.1.0_1783994467772_0.5191281320669117","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@21stgov/commons","version":"0.2.0","keywords":["design-system","accessibility","government","civic-tech","cli","commons","21stgov"],"license":"MIT","_id":"@21stgov/commons@0.2.0","maintainers":[{"name":"sethcottle","email":"sethcottle@gmail.com"}],"homepage":"https://commonsui.com","bugs":{"url":"https://github.com/21stGov/commons/issues"},"bin":{"commons":"dist/index.js"},"dist":{"shasum":"bc00b39d89a97b00621938c93bac7ccdfb14c08f","tarball":"https://registry.npmjs.org/@21stgov/commons/-/commons-0.2.0.tgz","fileCount":8,"integrity":"sha512-uZLI4gWMEFrOpCMxzo1bTjIuNmmCGoAIg2o5+liP9tV0Z2g3a6I/8cFl9mi7fljVaQCVpsc+veFvX/h0vcN1oA==","signatures":[{"sig":"MEQCIHXHkdGeI68B5o3Wazkt3NHWQAxR07lDJlc+PaCaFn4iAiBztCRlK0YwvdhJJePHVSDlIRBKwzRfBPVIdrEDiCcq2Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@21stgov%2fcommons@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":213238},"type":"module","_from":"file:21stgov-commons-0.2.0.tgz","engines":{"node":">=22"},"exports":{"./registry":{"types":"./dist/registry/lib.d.ts","import":"./dist/registry/lib.js"},"./package.json":"./package.json"},"private":false,"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:28bf13d5-8b6a-4d01-ab57-83009d172299"}},"_resolved":"/tmp/9fbd1d0c4a4942b53e0679f089f275c0/21stgov-commons-0.2.0.tgz","_integrity":"sha512-uZLI4gWMEFrOpCMxzo1bTjIuNmmCGoAIg2o5+liP9tV0Z2g3a6I/8cFl9mi7fljVaQCVpsc+veFvX/h0vcN1oA==","repository":{"url":"git+https://github.com/21stGov/commons.git","type":"git","directory":"packages/cli"},"_npmVersion":"11.16.0","description":"The Commons CLI — add accessible, government-ready components from the Commons design system registry.","directories":{},"_nodeVersion":"24.18.0","dependencies":{"zod":"^4.4.3","citty":"^0.2.2","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^4.1.10","typescript":"^5.9.3","@types/node":"^22.20.1"},"_npmOperationalInternal":{"tmp":"tmp/commons_0.2.0_1784010187066_0.9759008061016254","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@21stgov/commons","version":"0.3.0","keywords":["design-system","accessibility","government","civic-tech","cli","commons","21stgov"],"license":"MIT","_id":"@21stgov/commons@0.3.0","maintainers":[{"name":"sethcottle","email":"sethcottle@gmail.com"}],"homepage":"https://commonsui.com","bugs":{"url":"https://github.com/21stGov/commons/issues"},"bin":{"commons":"dist/index.js"},"dist":{"shasum":"a4043542dc870013b349e22448fe6ac333161672","tarball":"https://registry.npmjs.org/@21stgov/commons/-/commons-0.3.0.tgz","fileCount":8,"integrity":"sha512-Yfgl7Lf8zGKTL2LwMTmLdeohIIjrRSqJBx84PxUpycN05AJZ70bOFw29zUw/NVSeYCycC3FTp8oT3mkDXnMi4A==","signatures":[{"sig":"MEYCIQCw1q6mKWZXisQ2xY2ytC46ivcgnDXzexMJRDw75944DwIhANRjVEQjeAvPLefjBL95las9xTHuCVzKTFE1zcBlwzCy","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@21stgov%2fcommons@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":215602},"type":"module","_from":"file:21stgov-commons-0.3.0.tgz","engines":{"node":">=22"},"exports":{"./registry":{"types":"./dist/registry/lib.d.ts","import":"./dist/registry/lib.js"},"./package.json":"./package.json"},"private":false,"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:28bf13d5-8b6a-4d01-ab57-83009d172299"}},"_resolved":"/tmp/8a08004cd81ca209fa524ebb98568182/21stgov-commons-0.3.0.tgz","_integrity":"sha512-Yfgl7Lf8zGKTL2LwMTmLdeohIIjrRSqJBx84PxUpycN05AJZ70bOFw29zUw/NVSeYCycC3FTp8oT3mkDXnMi4A==","repository":{"url":"git+https://github.com/21stGov/commons.git","type":"git","directory":"packages/cli"},"_npmVersion":"11.16.0","description":"The Commons CLI — add accessible, government-ready components from the Commons design system registry.","directories":{},"_nodeVersion":"24.18.0","dependencies":{"zod":"^4.4.3","citty":"^0.2.2","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^4.1.10","typescript":"^5.9.3","@types/node":"^22.20.1"},"_npmOperationalInternal":{"tmp":"tmp/commons_0.3.0_1784152221505_0.7958638014408213","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@21stgov/commons","version":"0.3.1","keywords":["design-system","accessibility","government","civic-tech","cli","commons","21stgov"],"license":"MIT","_id":"@21stgov/commons@0.3.1","maintainers":[{"name":"sethcottle","email":"sethcottle@gmail.com"}],"homepage":"https://commonsui.com","bugs":{"url":"https://github.com/21stGov/commons/issues"},"bin":{"commons":"dist/index.js"},"dist":{"shasum":"903aec2ac678cfa8959c57df1ddb19123cb8dfce","tarball":"https://registry.npmjs.org/@21stgov/commons/-/commons-0.3.1.tgz","fileCount":8,"integrity":"sha512-m5iPjiiXvX5gaM1taDGx20DBPI7Kg5Tl4nVOVJ3BVSioLicF70KGx+Cdjeqn5sWCdbLqfqj9BZSTb4D65Bnr3g==","signatures":[{"sig":"MEQCIA3o7aI2CHg31/m5e2ALB+15JD5k3wNXUDuA5cBn4PrZAiBw/YSXDk5B/QstddvQkFiyzClm6cxhdg9vcpb/BgbVqw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@21stgov%2fcommons@0.3.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":215602},"type":"module","_from":"file:21stgov-commons-0.3.1.tgz","engines":{"node":">=22"},"exports":{"./registry":{"types":"./dist/registry/lib.d.ts","import":"./dist/registry/lib.js"},"./package.json":"./package.json"},"private":false,"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:28bf13d5-8b6a-4d01-ab57-83009d172299"}},"_resolved":"/tmp/dece537a557285241c56bc72d2d37f08/21stgov-commons-0.3.1.tgz","_integrity":"sha512-m5iPjiiXvX5gaM1taDGx20DBPI7Kg5Tl4nVOVJ3BVSioLicF70KGx+Cdjeqn5sWCdbLqfqj9BZSTb4D65Bnr3g==","repository":{"url":"git+https://github.com/21stGov/commons.git","type":"git","directory":"packages/cli"},"_npmVersion":"11.16.0","description":"The Commons CLI — add accessible, government-ready components from the Commons design system registry.","directories":{},"_nodeVersion":"24.18.0","dependencies":{"zod":"^4.4.3","citty":"^0.2.2","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^4.1.10","typescript":"^5.9.3","@types/node":"^22.20.1"},"_npmOperationalInternal":{"tmp":"tmp/commons_0.3.1_1784157918679_0.2774440784793122","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@21stgov/commons","version":"0.4.0","keywords":["design-system","accessibility","government","civic-tech","cli","commons","21stgov"],"license":"MIT","_id":"@21stgov/commons@0.4.0","maintainers":[{"name":"sethcottle","email":"sethcottle@gmail.com"}],"homepage":"https://commonsui.com","bugs":{"url":"https://github.com/21stGov/commons/issues"},"bin":{"commons":"dist/index.js"},"dist":{"shasum":"a55a5fba57bdb2b17dac058f6846b9ff7d9e71a6","tarball":"https://registry.npmjs.org/@21stgov/commons/-/commons-0.4.0.tgz","fileCount":8,"integrity":"sha512-6RDU+icTuAYdLjsnGxb66+vsjphhLYhfrDHd1PnkAq2Hy11T2OZcv4uWtvJSTyCcu1H1EJ6EMLOCszgv26YczQ==","signatures":[{"sig":"MEUCIQCOL1FvLfa8YQswgNysIBmyV1cqzweKi9jgu+vu1rTPXwIgFF5y8Pp5XJqHVsRO8e4V89SAQD/HaRPGYrPVLtFnTDM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@21stgov%2fcommons@0.4.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":215602},"type":"module","_from":"file:21stgov-commons-0.4.0.tgz","engines":{"node":">=22"},"exports":{"./registry":{"types":"./dist/registry/lib.d.ts","import":"./dist/registry/lib.js"},"./package.json":"./package.json"},"private":false,"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:28bf13d5-8b6a-4d01-ab57-83009d172299"}},"_resolved":"/tmp/fbf0a443b39e16e41cac149815e3e891/21stgov-commons-0.4.0.tgz","_integrity":"sha512-6RDU+icTuAYdLjsnGxb66+vsjphhLYhfrDHd1PnkAq2Hy11T2OZcv4uWtvJSTyCcu1H1EJ6EMLOCszgv26YczQ==","repository":{"url":"git+https://github.com/21stGov/commons.git","type":"git","directory":"packages/cli"},"_npmVersion":"11.16.0","description":"The Commons CLI — add accessible, government-ready components from the Commons design system registry.","directories":{},"_nodeVersion":"24.18.0","dependencies":{"zod":"^4.4.3","citty":"^0.2.2","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^4.1.10","typescript":"^5.9.3","@types/node":"^22.20.1"},"_npmOperationalInternal":{"tmp":"tmp/commons_0.4.0_1784170192961_0.15725325551313452","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"name":"@21stgov/commons","version":"0.5.0","keywords":["design-system","accessibility","government","civic-tech","cli","commons","21stgov"],"license":"MIT","_id":"@21stgov/commons@0.5.0","maintainers":[{"name":"sethcottle","email":"sethcottle@gmail.com"}],"homepage":"https://commonsui.com","bugs":{"url":"https://github.com/21stGov/commons/issues"},"bin":{"commons":"dist/index.js"},"dist":{"shasum":"e2a0926a065cef39419a9ef21852cfc6ccd4e701","tarball":"https://registry.npmjs.org/@21stgov/commons/-/commons-0.5.0.tgz","fileCount":8,"integrity":"sha512-XLvm9i3YHmdmBVWagEzG3mvxOaA4Ex4rU2yJxFqDMCT1+/YiWZR5pUcyqf++WH/3zP+L5SO61XtnXpqYKZSyUg==","signatures":[{"sig":"MEUCIDt1KtdG6a19vFXhHL+9TRPZsk+0mSJ2Isz3QmP13PuuAiEA8t2+/VGf7tRSWRPXNj2iGy6it8gCN7IYUAaKum8ukbw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@21stgov%2fcommons@0.5.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":223256},"type":"module","_from":"file:21stgov-commons-0.5.0.tgz","engines":{"node":">=22"},"exports":{"./registry":{"types":"./dist/registry/lib.d.ts","import":"./dist/registry/lib.js"},"./package.json":"./package.json"},"private":false,"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:28bf13d5-8b6a-4d01-ab57-83009d172299"}},"_resolved":"/tmp/478a8d5d23b7cd51b4c40079896164db/21stgov-commons-0.5.0.tgz","_integrity":"sha512-XLvm9i3YHmdmBVWagEzG3mvxOaA4Ex4rU2yJxFqDMCT1+/YiWZR5pUcyqf++WH/3zP+L5SO61XtnXpqYKZSyUg==","repository":{"url":"git+https://github.com/21stGov/commons.git","type":"git","directory":"packages/cli"},"_npmVersion":"11.16.0","description":"The Commons CLI — add accessible, government-ready components from the Commons design system registry.","directories":{},"_nodeVersion":"24.18.0","dependencies":{"zod":"^4.4.3","citty":"^0.2.2","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^4.1.10","typescript":"^5.9.3","@types/node":"^22.20.1"},"_npmOperationalInternal":{"tmp":"tmp/commons_0.5.0_1784173735532_0.16092316131147366","host":"s3://npm-registry-packages-npm-production"}},"0.6.0":{"name":"@21stgov/commons","version":"0.6.0","description":"The Commons CLI — add accessible, government-ready components from the Commons design system registry.","type":"module","license":"MIT","private":false,"engines":{"node":">=22"},"bin":{"commons":"dist/index.js"},"exports":{"./registry":{"types":"./dist/registry/lib.d.ts","import":"./dist/registry/lib.js"},"./package.json":"./package.json"},"repository":{"type":"git","url":"git+https://github.com/21stGov/commons.git","directory":"packages/cli"},"homepage":"https://commonsui.com","bugs":{"url":"https://github.com/21stGov/commons/issues"},"publishConfig":{"access":"public"},"keywords":["design-system","accessibility","government","civic-tech","cli","commons","21stgov"],"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","citty":"^0.2.2","zod":"^4.4.3"},"devDependencies":{"@types/node":"^22.20.1","tsup":"^8.5.1","typescript":"^5.9.3","vitest":"^4.1.10"},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","typecheck":"tsc --noEmit"},"_id":"@21stgov/commons@0.6.0","_integrity":"sha512-0vkzU0pObOjKUmBmpKf4KyQcZRtAEKhyuX4phr90YvxlUtogbjD+UfxMA0yST0z2JX13qLk3tMsB9KTwPqkhUg==","_resolved":"/tmp/c685ea20eaa69edb2da6934becb52b93/21stgov-commons-0.6.0.tgz","_from":"file:21stgov-commons-0.6.0.tgz","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-0vkzU0pObOjKUmBmpKf4KyQcZRtAEKhyuX4phr90YvxlUtogbjD+UfxMA0yST0z2JX13qLk3tMsB9KTwPqkhUg==","shasum":"7a8bbc6245711adb384fc678d38178cabf4480e7","tarball":"https://registry.npmjs.org/@21stgov/commons/-/commons-0.6.0.tgz","fileCount":8,"unpackedSize":223256,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@21stgov%2fcommons@0.6.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIE1ZO7/1tElqvpD5cIR8X5xybVe7ypKpzPmhtqFyxotAAiAudG4IH4GE35JVM3xfBDgzVrSLncnDOIPI0zU5ZNT4XQ=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:28bf13d5-8b6a-4d01-ab57-83009d172299"}},"directories":{},"maintainers":[{"name":"sethcottle","email":"sethcottle@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/commons_0.6.0_1784255085641_0.715344224904044"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-14T02:01:07.555Z","modified":"2026-07-17T02:24:46.065Z","0.1.0":"2026-07-14T02:01:07.938Z","0.2.0":"2026-07-14T06:23:07.192Z","0.3.0":"2026-07-15T21:50:21.647Z","0.3.1":"2026-07-15T23:25:18.832Z","0.4.0":"2026-07-16T02:49:53.120Z","0.5.0":"2026-07-16T03:48:55.663Z","0.6.0":"2026-07-17T02:24:45.777Z"},"bugs":{"url":"https://github.com/21stGov/commons/issues"},"license":"MIT","homepage":"https://commonsui.com","keywords":["design-system","accessibility","government","civic-tech","cli","commons","21stgov"],"repository":{"type":"git","url":"git+https://github.com/21stGov/commons.git","directory":"packages/cli"},"description":"The Commons CLI — add accessible, government-ready components from the Commons design system registry.","maintainers":[{"name":"sethcottle","email":"sethcottle@gmail.com"}],"readme":"# @21stgov/commons\n\nThe Commons CLI. Adds accessible, government-ready components from the\n[Commons](https://commonsui.com) design system registry to your project —\nthe same way you would with shadcn, but tuned for U.S. local government\nneeds (WCAG 2.2 AA baseline, high-contrast theme layer, gov patterns).\n\n## Usage\n\n```sh\n# Set up Commons in your project (creates commons.json)\nnpx @21stgov/commons init --yes\n\n# Search the registry catalog\nnpx @21stgov/commons search date\n\n# Inspect one component's contract before installing\nnpx @21stgov/commons inspect button\n\n# Preview exactly what add would do, without writing anything\nnpx @21stgov/commons add button --dry-run\n\n# Add a component (and its registry dependencies) to your project\nnpx @21stgov/commons add button\n\n# Add several at once; replace locally changed files explicitly\nnpx @21stgov/commons add button alert banner --overwrite\n```\n\nEvery command accepts `--cwd <dir>` to operate on another project\ndirectory, and `--json` for the machine interface described below.\n\n## Machine interface (`--json`)\n\nBuilt for scripts, CI, and AI agents. With `--json`, every command prints\n**exactly one** JSON envelope to stdout; diagnostics go to stderr:\n\n```json\n{\n  \"$schema\": \"https://commonsui.com/schema/cli-output.v1.json\",\n  \"schemaVersion\": \"1\",\n  \"cli\": \"0.1.0\",\n  \"command\": \"add\",\n  \"ok\": true,\n  \"data\": {\n    \"registry\": \"https://commonsui.com/r\",\n    \"items\": [\"cn\", \"button\"],\n    \"files\": [{ \"path\": \"src/lib/cn.ts\", \"action\": \"write\", \"item\": \"cn\" }],\n    \"dependencies\": [\"clsx\", \"tailwind-merge\"],\n    \"packageManager\": \"pnpm\",\n    \"installCommand\": \"pnpm add clsx tailwind-merge\",\n    \"dryRun\": false,\n    \"written\": 2\n  }\n}\n```\n\nOn failure the envelope carries `\"ok\": false` and\n`\"error\": { \"code\": \"...\", \"message\": \"...\" }` instead of `data`. This\nholds even for argument/usage errors (missing arguments, unknown\nsubcommands): stdout gets the envelope (`\"command\": \"unknown\"` when no\nvalid subcommand could be resolved), help text and diagnostics go to\nstderr, exit code 1.\n\nStable exit codes:\n\n| Code | Meaning                                                             |\n| ---- | ------------------------------------------------------------------- |\n| 0    | Success                                                              |\n| 1    | User error or conflict (bad input, existing files, config problems)  |\n| 2    | Network or registry error (unreachable, 404, HTTP failure, bad JSON) |\n| 3    | Validation error (schema mismatch, integrity mismatch, unsafe paths) |\n\n## How `add` works\n\n1. Loads `commons.json` from `--cwd` (defaults to the current directory).\n2. Fetches each item from `{registry}/{name}.json` and resolves\n   `registryDependencies` recursively (cycle-safe, deduplicated,\n   dependencies installed first).\n3. Verifies sha256 `integrity` hashes when the item carries them\n   (mismatch, or a file missing from the integrity map → exit 3, nothing\n   written).\n4. Rejects unsafe file paths — absolute paths, `..` segments, drive\n   letters, UNC paths, Windows-reserved device names (`CON`, `NUL`,\n   `COM1`, …), segments with trailing dots or spaces, or anything\n   resolving outside the project root, including through symlinks\n   (exit 3, nothing written).\n5. Pre-flights every destination **before writing a single file**:\n   files that already match are skipped; files that differ are conflicts.\n   Any conflict without `--overwrite` aborts with exit 1 and zero writes,\n   as does any pair of files whose destinations collide case-insensitively.\n6. Writes files by type: `registry:ui` → `paths.ui`, `registry:lib` →\n   `paths.lib`, everything else → `paths.components` (basename only).\n7. Prints the dependency install command for your package manager\n   (detected from the lockfile; default pnpm). Pass `--install` to run it\n   for you (or accept the prompt the CLI offers on an interactive terminal).\n\n`--dry-run` performs steps 1–5 and reports the full plan without writing.\n\n## Configuration\n\n`commons init --yes` writes a `commons.json` in your project root:\n\n```json\n{\n  \"$schema\": \"https://commonsui.com/schema/commons.json\",\n  \"registry\": \"https://commonsui.com/r\",\n  \"paths\": {\n    \"ui\": \"src/components/ui\",\n    \"components\": \"src/components\",\n    \"lib\": \"src/lib\"\n  },\n  \"theme\": \"light\"\n}\n```\n\n- `registry` — base URL the CLI fetches `{name}.json` registry items and\n  the `index.json` catalog from. Point this at a private or\n  agency-specific registry if you run one.\n- `paths` — where component files land, by registry file type. Projects\n  without a `src` directory get `components/ui`, `components`, and `lib`.\n- `theme` — default theme layer (`light`, `dark`, or `high-contrast`).\n\n`init` refuses to overwrite an existing `commons.json` unless you pass\n`--force`.\n\n## MCP server (`commons mcp`)\n\n`commons mcp` runs a **local, read-only** MCP server over stdio, exposing\nthe registry to MCP clients (Claude Code, Cursor, VS Code, Codex):\n\n- `search_components` — search the catalog (same matching as `commons search`)\n- `get_component` — one component's full registry-item v1 JSON\n- `plan_install` — the exact `commons add --dry-run` plan; never writes\n- `get_setup` — registry URL, CSS import lines, tsconfig alias, init command\n\nEvery result carries `schemaVersion`, the CLI package version, and the\nregistry URL it was resolved against. The registry comes from\n`commons.json` in `--cwd` (default: the current directory), then the\n`COMMONS_REGISTRY` environment variable, then the public default.\nInstalling is still the local CLI's job — the server returns the exact\n`npx @21stgov/commons add <names>` command instead of writing files.\n\nConfigure a client with:\n\n```sh\nnpx @21stgov/commons mcp init                    # Claude Code -> .mcp.json\nnpx @21stgov/commons mcp init --client cursor    # -> .cursor/mcp.json\nnpx @21stgov/commons mcp init --client vscode    # -> .vscode/mcp.json\nnpx @21stgov/commons mcp init --client codex     # prints ~/.codex/config.toml snippet\n```\n\nExisting config files are merged, never clobbered; a differing `commons`\nentry is refused unless you pass `--force`.\n\n## Registry format\n\nItems are served as static JSON at `{registry}/{name}.json` and the\nsearchable catalog at `{registry}/index.json`. The item schema follows\nthe open shadcn registry format (MIT) — see `src/registry/schema.ts` —\nwith Commons additions: required inline `files[].content`, a first-class\n`high-contrast` group in `cssVars`, and optional `status`, `useWhen`,\n`avoidWhen`, `compatibility`, `accessibility`, `integrity`, and `version`\nmetadata. Unknown fields never fail validation (forward compatibility).\n\n## Development\n\n```sh\npnpm build      # tsup -> dist/index.js (ESM, shebang)\npnpm test       # vitest run\npnpm typecheck  # tsc --noEmit\n```\n\n## License\n\nMIT © 21st Gov\n","readmeFilename":"README.md"}