@super-hands/import

Imports your repository's design system into Superhands from a checkout you already have.

Installing a GitHub App is an organisation-level permission, and the people who most want a component library — designers — routinely do not have it. They can read the repository perfectly well; it is on their laptop. This is the way in that does not need an administrator.

Usage

Press Import from a local checkout in Superhands (on Components, or during setup). It gives you the whole line, already filled in. Run it from the root of the repository:

SUPERHANDS_IMPORT_GRANT="<the grant>" SUPERHANDS_ORIGIN="https://app.superhands.ai" npx -y @super-hands/import@latest

Copy it from Superhands rather than typing it from here — the grant is short-lived, single-use, and authorizes one import for one team. It is read from the environment rather than an argument because argv is world-readable through ps on a shared machine.

Both variables are required. SUPERHANDS_ORIGIN is not defaulted on purpose: it names the deployment the import publishes to, and a client that guessed would send a self-hosted or preview import somewhere else without saying so.

@latest matters. npx caches by version spec, so a bare @super-hands/import can rerun a build from months ago — which Superhands will then refuse as an incompatible client, for a reason you cannot see from here.

What it does

It exports the committed HEAD of your repository into a scratch directory, runs Superhands' extractor over that, and uploads the resulting design-system summary: components, tokens, patterns, screens, and the source of the component modules it found.

What it does not do

• It does not upload your repository. What goes is the extracted summary described above — not an archive, not the working tree, not .git.
• It does not run any of your code. No install, no build, no test, no package script. git is invoked with fixed arguments and never through a shell.
• It does not read uncommitted work. Everything after the export reads the scratch directory, so staged changes, half-edited files and an uncommitted .env are excluded by not being in the commit — not by a filter that has to be kept correct.
• It installs nothing on your machine, and holds no credential beyond the grant you gave it.

Verifying it before you run it

This package carries no npm provenance attestation, and that is worth saying rather than leaving to be assumed: npm mints those from a CI identity and refuses them for a private source repository, which Superhands' is. What you get instead is that the published code is short, readable and unminified.

It is generated from lib/local-import-client-entry.ts in the Superhands repository. If you would rather read it before running it:

npm pack @super-hands/import && tar -xzf super-hands-import-*.tgz

If your coding agent is running this for you and its permission system asks before it does, that is the correct instinct — this program uploads source. A one-time approval is all it needs.