spfn 0.3.0-beta.4 → 0.3.0-beta.6

package/dist/index.d.ts

@@ -117,6 +117,1064 @@ interface SpfnConfig {
     deployment: DeploymentConfig;
 }
 
+type KitGate = 'kit-check' | 'typecheck' | 'test' | 'build' | 'db-status' | 'health';
+
+/**
+ * Turning a release's scaffold archive into a project on disk.
+ *
+ * The archive is one artifact and it is verified as one: the manifest declares
+ * an integrity for it, and nothing is expanded until the bytes that arrived
+ * match. That ordering is the whole safety property — a half-expanded archive
+ * that turns out to be wrong leaves files a later step has to guess about,
+ * while an archive rejected before expansion leaves the directory exactly as it
+ * was found.
+ *
+ * Two things the expansion will not do. It will not write outside the directory
+ * it was given, which `readTar` enforces by refusing the paths that could. And
+ * it will not overwrite a file that is already there: by the time the scaffold
+ * runs, activation has already written the licence file, and an archive that
+ * claims a path something else owns is a release bug, not a merge to resolve.
+ *
+ * The seed is the small, customer-owned part: the project's own name. It is
+ * written after expansion rather than baked into the archive so that one
+ * archive serves every project, and it is the only file this module edits
+ * rather than creates.
+ */
+
+/** What the manifest says about the release's scaffold. */
+interface KitScaffoldDescriptor {
+    recipeVersion: string;
+    artifact: string;
+    integrity: string;
+}
+interface ScaffoldMaterializerOptions {
+    artifacts: ArtifactPort;
+}
+/**
+ * The real `ScaffoldPort`: fetch, verify, expand, seed.
+ *
+ * `spfn create` is not shelled out to. A scaffold that came from a signed
+ * release has to be the *release's* scaffold, and a locally installed CLI
+ * generating its own approximation of one is how a project ends up subtly
+ * unlike the release it claims to be.
+ */
+declare class ArtifactScaffoldPort implements ScaffoldPort {
+    private readonly artifacts;
+    constructor(options: ScaffoldMaterializerOptions);
+    createBase(request: {
+        targetDir: string;
+        name: string;
+        scaffold?: KitScaffoldDescriptor;
+    }): Promise<void>;
+}
+
+/**
+ * Where a Kit's local credential lives, and the two-step dance that puts it
+ * there (unit 06 section 3.3).
+ *
+ * The credential is stored in the OS keychain under a service of its own,
+ * `superfunction.spfn.kit`, so it is never reachable through the env-secret
+ * path that `spfn secret` uses. What is committed to the repository is only
+ * enough to *find* the item again — kit ID, activation ID, client ID — never
+ * the value and never the expiry, which changes on every rotation and would
+ * make the committed file wrong minutes after it was written.
+ *
+ * The dance matters. A first activation has no activation ID yet, so the CLI
+ * generates the credential locally, writes it under a `pending` account, and
+ * only then calls activation. If the response is lost in the network the same
+ * pending value re-drives the same idempotent call, and a second slot is never
+ * consumed. Once the server answers, the item moves to its final account. If
+ * the license is refused, the pending item is deleted.
+ */
+
+interface KitCredentialRecord {
+    /** The opaque local credential the control plane issued or accepted. */
+    credential: string;
+    /** When registry access from this credential stops working. */
+    accessExpiresAt: string;
+    /** Server generation. A lower one than the server's is stale. */
+    generation: number;
+}
+interface KitCredentialIdentity {
+    kitId: string;
+    localClientId: string;
+    /** Present once the server has answered an activation. */
+    activationId?: string;
+    /** Present only while the first activation is still in flight. */
+    installationId?: string;
+}
+/** Identity of the item held while a first activation is in flight. */
+type PendingIdentity = Required<Pick<KitCredentialIdentity, 'kitId' | 'installationId' | 'localClientId'>>;
+/** Identity of the settled item, once the server has answered. */
+type SettledIdentity = Required<Pick<KitCredentialIdentity, 'kitId' | 'activationId' | 'localClientId'>>;
+interface KitCredentialStore {
+    readonly id: string;
+    isAvailable(): Promise<boolean>;
+    readPending(identity: PendingIdentity): Promise<KitCredentialRecord | null>;
+    savePending(identity: PendingIdentity, record: KitCredentialRecord): Promise<void>;
+    /** Move the pending item to its final account. Returns what was moved. */
+    promote(identity: Required<KitCredentialIdentity>, record?: KitCredentialRecord): Promise<KitCredentialRecord>;
+    read(identity: SettledIdentity): Promise<KitCredentialRecord | null>;
+    save(identity: SettledIdentity, record: KitCredentialRecord): Promise<void>;
+    remove(account: string): Promise<void>;
+}
+
+/** A public key the CLI is willing to trust, as base64 SPKI DER. */
+interface TrustedKey {
+    keyId: string;
+    publicKey: string;
+}
+
+/**
+ * The first thing `spfn kit install` does, and the only place a setup URL is
+ * turned into something the CLI will act on.
+ *
+ * Unit 06 section 3.1: the setup link is a public locator, not a secret. That
+ * cuts both ways — because it is public it may be shared, and because it is
+ * public it must carry nothing else, so a URL with a query or a fragment is
+ * refused before a single byte is fetched. The origin is an exact allowlist:
+ * a valid signature on a descriptor served from somewhere else does not make
+ * that somewhere else an official setup origin.
+ *
+ * Order matters here, and it is the order below: allowlist, fetch, signature,
+ * schema, self-consistency, freshness, payload digest, CLI compatibility. Each
+ * step may only trust what the steps above it have already established.
+ */
+
+/** Fetches one URL and returns the parsed JSON body, or the redirect target. */
+interface SetupFetchResult {
+    /** Set when the origin answered with a redirect. */
+    redirectTo?: string;
+    body?: unknown;
+}
+type SetupFetcher = (url: string) => Promise<SetupFetchResult>;
+
+/**
+ * Everything a Kit operation needs from the outside world, as one set of
+ * interfaces.
+ *
+ * The operations in `operations/` contain the order of the steps, the
+ * checkpoints and the refusals — the parts that are the same whatever is on the
+ * other end. The ports are the parts that are not: a control plane, a registry,
+ * a package manager, a database, Git, a cloud provider.
+ *
+ * The reason for the seam is not testability alone. It is that a Wave-1 install
+ * has to be provable *before* any of those services may be touched: with fake
+ * ports the whole sequence, including its failures and resumes, runs on a
+ * temporary directory and reaches nothing real.
+ *
+ * Two rules hold across every port:
+ *   - a port reports outcomes, it does not decide policy. `activate` says
+ *     `project-limit`; whether that is fatal is the operation's call;
+ *   - a secret crosses a port boundary only as a value the CLI immediately puts
+ *     into a keychain item or a child environment. No port writes one to disk.
+ */
+
+interface KitClock {
+    /** An ISO-8601 instant with second precision, matching the contract. */
+    now(): string;
+}
+/**
+ * Transport for the signed documents. Each call returns the *signed wrapper*,
+ * never a document the transport has already decided to trust — verification is
+ * the CLI's job and stays in one place.
+ */
+interface CatalogPort {
+    fetchSignedCatalog(url: string): Promise<unknown>;
+    fetchSignedManifest(url: string): Promise<unknown>;
+}
+interface ActivationRequest {
+    kitId: string;
+    installationId: string;
+    localClientId: string;
+    /** Read from a masked prompt or stdin, held in memory, never stored. */
+    licenseKey: string;
+    /** The client-generated credential already parked in the pending item. */
+    candidateCredential: string;
+}
+interface ActivationResult {
+    status: 'activated' | 'license-invalid' | 'license-revoked' | 'project-limit' | 'unavailable';
+    activationId?: string;
+    accessExpiresAt?: string;
+    generation?: number;
+    /** Secret-free detail for the report, e.g. how many slots are in use. */
+    detail?: Record<string, string | number | boolean | null>;
+}
+interface EntitlementResult {
+    entitled: boolean;
+    reason?: 'expired' | 'not-entitled' | 'revoked' | 'unavailable';
+}
+interface EntitlementRequest {
+    activationId: string;
+    kitId: string;
+    release: string;
+    /**
+     * The package whose availability answers the question, from the release
+     * that is being asked about.
+     *
+     * A generic CLI cannot know what a Kit ships as. Guessing it from the Kit
+     * id works only for Kits whose package happens to be named after them, and
+     * a wrong guess is answered by the registry as "not entitled" — a refusal
+     * the customer reads as a licence problem when nothing about the licence
+     * is wrong. The manifest names its packages, so the caller that holds the
+     * manifest says which one to ask about, and this stays a transport.
+     */
+    packageName?: string;
+}
+/**
+ * The answer to "please e-mail this activation a recovery challenge".
+ *
+ * `sent` whether or not the activation exists. The control plane answers the
+ * same way in both cases on purpose (unit 04 §6.1), so a caller who could tell
+ * the difference would be telling an attacker which public activation ids are
+ * real. The CLI carries that property forward rather than trying to be more
+ * helpful than the service it asked.
+ */
+interface RecoveryRequestResult {
+    status: 'sent' | 'unavailable';
+    detail?: Record<string, string | number | boolean | null>;
+}
+interface RecoveryCompletionResult {
+    status: 'recovered' | 'recovery-invalid' | 'license-revoked' | 'unavailable';
+    /** The activation the replacement credential now belongs to. */
+    activationId?: string;
+    /** The server's name for the client the replacement created. */
+    localClientId?: string;
+    accessExpiresAt?: string;
+    generation?: number;
+    detail?: Record<string, string | number | boolean | null>;
+}
+interface LicensePort {
+    activate(request: ActivationRequest): Promise<ActivationResult>;
+    entitlement(request: EntitlementRequest): Promise<EntitlementResult>;
+    /** Unit 06 §4.10 step 1: ask for a challenge at the address of record. */
+    requestRecovery(request: {
+        activationId: string;
+    }): Promise<RecoveryRequestResult>;
+    /**
+     * Unit 06 §4.10 steps 4–5.
+     *
+     * The replacement credential is generated by the CLI and sent, rather than
+     * minted by the server and returned: a secret the server mints can be lost
+     * in transit, and losing the one that replaces a lost one has no next step.
+     */
+    completeRecovery(request: {
+        recoveryId: string;
+        challenge: string;
+        replacementCredential: string;
+    }): Promise<RecoveryCompletionResult>;
+}
+interface RegistrySession {
+    status: 'ok' | 'credential-stale' | 'credential-invalid' | 'unavailable';
+    /** Short-lived bearer, handed only to a child environment. */
+    token?: string;
+    expiresInSeconds?: number;
+}
+interface RegistryPort {
+    /**
+     * `kitId` names the keychain item the credential lives in, so a port that
+     * rotates an expired credential can put the replacement back where the next
+     * command will look for it. A port that never rotates ignores it.
+     */
+    issueSession(request: {
+        kitId?: string;
+        activationId: string;
+        localClientId: string;
+        credential: string;
+        /**
+         * Set on a retry after the registry refused the last credential. The
+         * local record can look perfectly current while the server has already
+         * stopped honouring it, and re-presenting it would fail identically.
+         */
+        forceRotation?: boolean;
+    }): Promise<RegistrySession>;
+}
+interface PackageInstallResult {
+    ok: boolean;
+    exitCode: number;
+    /** Why it failed, in terms the operation can branch on. */
+    failure?: 'unauthorized' | 'network' | 'resolution' | 'other';
+}
+interface PackageManagerPort {
+    install(request: {
+        cwd: string;
+        frozen: boolean;
+        env: Record<string, string>;
+    }): Promise<PackageInstallResult>;
+}
+interface DatabaseStatus {
+    /** Whether a connection string is configured at all. */
+    configured: boolean;
+    reachable: boolean;
+    applied: string[];
+    pending: string[];
+}
+interface MigrationResult {
+    ok: boolean;
+    applied: string[];
+    pending: string[];
+    backupId?: string;
+    failure?: string;
+}
+interface DatabasePort {
+    status(request: {
+        cwd: string;
+    }): Promise<DatabaseStatus>;
+    migrate(request: {
+        cwd: string;
+        withBackup: boolean;
+    }): Promise<MigrationResult>;
+}
+interface GateResult {
+    ok: boolean;
+    /** A short secret-free summary; never raw command output. */
+    summary?: string;
+}
+interface GatePort {
+    run(gate: KitGate, request: {
+        cwd: string;
+    }): Promise<GateResult>;
+}
+interface GitPort {
+    init(request: {
+        cwd: string;
+    }): Promise<void>;
+    isClean(request: {
+        cwd: string;
+    }): Promise<boolean>;
+    commit(request: {
+        cwd: string;
+        message: string;
+    }): Promise<{
+        commit: string;
+    }>;
+    head(request: {
+        cwd: string;
+    }): Promise<string | null>;
+    /**
+     * Which of these paths the repository actually tracks.
+     *
+     * Asked because a file that exists is not the same as a file a clean clone
+     * will have. `.spfn/kit-lock.json` and `.spfn/license.json` are the two
+     * files a restore has nothing without (unit 06 §4.2, §5.1), and a scaffold
+     * whose `.gitignore` covers `.spfn/` produces a project that installs,
+     * builds, passes every gate and cannot be restored from its own repository.
+     */
+    trackedAmong(request: {
+        cwd: string;
+        paths: readonly string[];
+    }): Promise<string[]>;
+}
+interface ScaffoldPort {
+    /**
+     * The project's base, as the release publishes it.
+     *
+     * `scaffold` is what the signed manifest declared: which archive, and the
+     * integrity it has to match. It is passed in rather than looked up because
+     * a scaffold that came from anywhere but the release under installation is
+     * not this release's scaffold.
+     */
+    createBase(request: {
+        targetDir: string;
+        name: string;
+        scaffold?: KitScaffoldDescriptor;
+    }): Promise<void>;
+}
+interface ArtifactPort {
+    /** The bytes of one release artifact. Verified by digest before use. */
+    fetch(artifact: string): Promise<Uint8Array>;
+}
+/** Loads a module from the installed project graph, for tooling discovery. */
+type ProjectModuleLoader = (specifier: string, projectDir: string) => Promise<unknown>;
+interface KitAdapters {
+    clock: KitClock;
+    setupFetcher: SetupFetcher;
+    trustedKeys: readonly TrustedKey[];
+    catalog: CatalogPort;
+    license: LicensePort;
+    registry: RegistryPort;
+    credentials: KitCredentialStore;
+    packageManager: PackageManagerPort;
+    database: DatabasePort;
+    gates: GatePort;
+    git: GitPort;
+    scaffold: ScaffoldPort;
+    artifacts: ArtifactPort;
+    loadProjectModule: ProjectModuleLoader;
+    /** The running public CLI version, as the descriptor compares against. */
+    cliVersion: string;
+    controlPlaneUrl: string;
+    registryUrl: string;
+}
+
+/**
+ * Where a command gets its ports from.
+ *
+ * The live set — a real control-plane client, a real registry session, the real
+ * package manager — arrives with the work that connects `spfn kit` to the
+ * running service. Until then this build has no way to reach any of it, and it
+ * says so with a `CLI_`-prefixed code rather than pretending to be a Kit state:
+ * "this CLI cannot reach the control plane" is a fact about the CLI, not about
+ * the project's licence, lock or release.
+ *
+ * `setKitAdapterFactory` is the seam the tests drive the whole command surface
+ * through, with the fake world standing in for every external service.
+ */
+
+interface AdapterRequest {
+    projectDir: string;
+}
+type KitAdapterFactory = (request: AdapterRequest) => Promise<KitAdapters>;
+declare function setKitAdapterFactory(next: KitAdapterFactory | null): void;
+
+/**
+ * The one place `spfn kit` talks to a network, and the rules that hold there.
+ *
+ * Three of them are worth stating, because every client below depends on all
+ * three and none of them can be added later:
+ *
+ *   - a request body may hold a licence key or a local credential, so no error
+ *     raised here ever quotes one. What a failure is allowed to carry is the
+ *     method, the origin, the path and the status — never the body it sent and
+ *     never the body it got back;
+ *   - a response is a stranger's bytes. It is read with a ceiling on its size
+ *     and a deadline on its arrival, so an origin that answers slowly or
+ *     endlessly stops the command instead of hanging it;
+ *   - "the service said no" and "the service could not be reached" are
+ *     different answers. A transport failure becomes `CLI_...`, because it is a
+ *     fact about this machine's connection rather than about the licence.
+ */
+
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+interface KitHttpOptions {
+    /** Injected so tests reach a local fixture and nothing else. */
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+}
+
+/**
+ * The real control-plane client: signed documents over HTTP, licence
+ * activation, and keeping this machine's local credential alive.
+ *
+ * Everything here is a translation layer and nothing here is a decision. The
+ * service answers in its own vocabulary — `LICENSE_REVOKED`,
+ * `PROJECT_LIMIT_REACHED`, `LOCAL_CREDENTIAL_STALE` — and the operations branch
+ * on the CLI's, so one table below maps one to the other. Where the two
+ * vocabularies do not line up the server's own code travels on in `detail`,
+ * because a report that says only "unavailable" when the server said
+ * `RATE_LIMITED` has thrown away the one fact that would have explained it.
+ *
+ * What this client never does is decide that a document is trustworthy. It
+ * returns the signed wrapper exactly as it arrived; the signature check lives
+ * in one place, and that place is not the transport.
+ */
+
+interface ControlPlaneOptions extends KitHttpOptions {
+    /** Origin the licence routes are served from, e.g. `https://…`. */
+    baseUrl: string;
+}
+/** Signed catalogs and manifests, fetched and handed on unopened. */
+declare class HttpCatalogPort implements CatalogPort {
+    private readonly http;
+    constructor(http?: KitHttpOptions);
+    fetchSignedCatalog(url: string): Promise<unknown>;
+    fetchSignedManifest(url: string): Promise<unknown>;
+    private fetchDocument;
+}
+/**
+ * Answers "does this licence still cover that release".
+ *
+ * The control plane has no endpoint for the question — entitlement is enforced
+ * where it is used, by the registry refusing to serve a version — so the live
+ * client answers it by asking the registry. The probe is injected rather than
+ * built in, because the licence client has no business knowing which package a
+ * Kit ships as.
+ */
+type EntitlementProbe = (request: EntitlementRequest) => Promise<EntitlementResult>;
+declare class HttpLicensePort implements LicensePort {
+    private readonly baseUrl;
+    private readonly http;
+    private readonly probe;
+    constructor(options: ControlPlaneOptions, probe?: EntitlementProbe | null);
+    activate(request: ActivationRequest): Promise<ActivationResult>;
+    entitlement(request: EntitlementRequest): Promise<EntitlementResult>;
+    requestRecovery(request: {
+        activationId: string;
+    }): Promise<RecoveryRequestResult>;
+    completeRecovery(request: {
+        recoveryId: string;
+        challenge: string;
+        replacementCredential: string;
+    }): Promise<RecoveryCompletionResult>;
+}
+/**
+ * The bearer the package manager installs with, and the rotation that keeps one
+ * available.
+ *
+ * There is no separate "session" to issue for a local install: the control
+ * plane accepts the machine's own local credential at the registry for as long
+ * as its access window is open, and issues a *new* credential when it is not.
+ * So this port's real job is the second half — notice a window about to close,
+ * rotate before it does, and put the replacement in the keychain in the same
+ * step, so a rotation that is not recorded can never have happened.
+ */
+declare class HttpRegistryPort implements RegistryPort {
+    private readonly baseUrl;
+    private readonly http;
+    private readonly credentials;
+    private readonly now;
+    constructor(options: ControlPlaneOptions & {
+        credentials: KitCredentialStore;
+        now: () => string;
+    });
+    issueSession(request: {
+        kitId?: string;
+        activationId: string;
+        localClientId: string;
+        credential: string;
+        forceRotation?: boolean;
+    }): Promise<RegistrySession>;
+    private rotate;
+}
+
+/**
+ * The private registry, reached through the licence proxy.
+ *
+ * The proxy is the place entitlement is actually enforced: it answers with the
+ * versions this activation may have and rewrites every tarball link to its own
+ * public origin, so "which releases do I have" is a question with a real answer
+ * even though the licence service has no endpoint for it.
+ *
+ * Integrity is checked twice on purpose, and the two checks catch different
+ * things. The first compares the version's `integrity` against the digest the
+ * *signed manifest* pinned: it catches a registry that serves a different
+ * package than the release was built from, and it happens before a byte is
+ * downloaded. The second hashes the bytes that actually arrived: it catches a
+ * tarball that was replaced in transit or in storage. Passing the first says
+ * the registry agrees with the manifest; only the second says the file on this
+ * disk is the file the manifest described.
+ */
+
+interface RegistryProxyOptions extends KitHttpOptions {
+    /** Public registry base, e.g. `https://…/npm/`. Trailing slash optional. */
+    registryUrl: string;
+}
+interface RegistryVersion {
+    version: string;
+    integrity: string;
+    tarball: string;
+}
+/**
+ * What one metadata request produced.
+ *
+ * `status` separates the three answers that need different handling: the
+ * package was served, the credential was refused, or the proxy could not say.
+ * "Not entitled" and "no such package" are one answer (`not-found`) because the
+ * proxy deliberately makes them indistinguishable.
+ */
+interface RegistryMetadataResult {
+    status: 'ok' | 'not-found' | 'credential-rejected' | 'unavailable';
+    versions: RegistryVersion[];
+    detail?: string;
+}
+declare class KitRegistryProxyClient {
+    private readonly registryUrl;
+    private readonly http;
+    constructor(options: RegistryProxyOptions);
+    /** The entitled versions of one package, as the proxy reports them. */
+    metadata(packageName: string, credential: string): Promise<RegistryMetadataResult>;
+    /**
+     * The bytes of one exact version, proven against the manifest's digest.
+     *
+     * The tarball link comes from the proxy's own answer and is checked to stay
+     * on the registry origin: a rewritten link that points somewhere else is
+     * how an entitled request gets turned into a download from a stranger.
+     */
+    fetchExact(request: {
+        packageName: string;
+        version: string;
+        integrity: string;
+        credential: string;
+    }): Promise<Uint8Array>;
+    private download;
+}
+/** Produces the bearer a release artifact is fetched with, or null. */
+type ArtifactCredentialResolver = () => Promise<string | null>;
+/**
+ * Release artifacts — managed files, agent packs, scaffold archives — fetched
+ * from the release store the catalog lives in.
+ *
+ * An artifact is paid content, so the store authenticates it exactly as the npm
+ * proxy does: the same bearer, the same refusal codes. That makes a refusal
+ * here a statement about *this machine's credential* rather than about the
+ * file, and the two send an agent to completely different next steps — only
+ * one of them is `spfn kit recover`.
+ *
+ * The setup descriptor, the catalog and the manifests stay public and are
+ * fetched without a bearer. They are locators and promises about a release;
+ * nothing anyone paid for is inside them.
+ *
+ * No digest is checked here, and that is not an omission: the caller holds the
+ * digest the *signed manifest* declared, and checking it anywhere else would
+ * mean a second place that decides what "correct bytes" means.
+ */
+declare class HttpArtifactPort implements ArtifactPort {
+    private readonly resolveBase;
+    private readonly http;
+    private readonly credential;
+    /**
+     * `baseUrl` may be a function because the release store is only known once
+     * the operation has a catalog URL — which is a fact about the release being
+     * installed, not about the machine installing it.
+     */
+    constructor(options: KitHttpOptions & {
+        baseUrl: string | (() => string);
+        credential?: ArtifactCredentialResolver;
+    });
+    fetch(artifact: string): Promise<Uint8Array>;
+}
+
+/**
+ * Proving the exact graph before installing it.
+ *
+ * A frozen install is only as exact as the registry it pulls from. The lockfile
+ * pins versions, the manifest pins digests, and between them sits a proxy that
+ * could serve a different tarball under the same name — so every package the
+ * signed manifest names is fetched through the proxy and checked against the
+ * manifest's own integrity *before* the package manager is allowed to run.
+ *
+ * This is a decorator rather than a package manager: what actually installs is
+ * still pnpm, npm or whatever the project uses. The verification wraps it,
+ * because "which packages must be exact" is a release fact and "how do I put
+ * them on disk" is not.
+ *
+ * The manifest is not passed in. It is read from the operation context the
+ * running operation already wrote, and re-verified against the trusted keys
+ * here — a manifest trusted because a caller handed it over is a manifest
+ * trusted for the wrong reason.
+ */
+
+interface RegistryVerifyingPackageManagerOptions {
+    catalog: CatalogPort;
+    trustedKeys: readonly TrustedKey[];
+    registry: KitRegistryProxyClient;
+    /** What performs the install once the graph is proven. */
+    delegate: PackageManagerPort;
+    /** Package names to skip, e.g. ones the private registry does not carry. */
+    skip?: (name: string) => boolean;
+}
+declare class RegistryVerifyingPackageManager implements PackageManagerPort {
+    private readonly options;
+    constructor(options: RegistryVerifyingPackageManagerOptions);
+    install(request: {
+        cwd: string;
+        frozen: boolean;
+        env: Record<string, string>;
+    }): Promise<PackageInstallResult>;
+    private verifyGraph;
+}
+
+/**
+ * Assembling the half of the Kit world that lives on the network.
+ *
+ * Six ports of the ten are remote or artifact-shaped — catalog, licence,
+ * registry, artifacts, scaffold and the verification in front of the package
+ * manager — and this builds all six from three addresses. The other four
+ * (package manager, database, gates, Git) are local process work and are handed
+ * in, because how a project runs its own tests is not something a control-plane
+ * client should have an opinion about.
+ *
+ * The addresses are resolved per project, in one order and no other: what the
+ * checkout already recorded when it was activated, then what the environment
+ * overrides for a staging or local run, then the published defaults. A checkout
+ * activated against one control plane must not silently start talking to
+ * another because a shell variable was left set.
+ */
+
+/** Where a Kit's services live when nothing says otherwise. */
+declare const DEFAULT_CONTROL_PLANE_URL = "https://start.superfunction.xyz";
+declare const DEFAULT_REGISTRY_URL = "https://packages.superfunction.xyz/npm/";
+/** Environment overrides, for a staging control plane or a local server. */
+declare const CONTROL_PLANE_URL_ENV = "SPFN_KIT_CONTROL_PLANE_URL";
+declare const REGISTRY_URL_ENV = "SPFN_KIT_REGISTRY_URL";
+interface KitEndpoints {
+    controlPlaneUrl: string;
+    registryUrl: string;
+    /** Where the addresses came from, for the status report. */
+    source: 'checkout' | 'environment' | 'default';
+}
+declare function resolveKitEndpoints(projectDir: string, env?: NodeJS.ProcessEnv): KitEndpoints;
+interface KitRemotePortsOptions extends KitHttpOptions {
+    projectDir: string;
+    endpoints: KitEndpoints;
+    credentials: KitCredentialStore;
+    trustedKeys: readonly TrustedKey[];
+    now: () => string;
+    /** What actually installs, once the graph has been proven exact. */
+    packageManager: PackageManagerPort;
+    /** Packages the private registry does not serve, e.g. public ones. */
+    skipVerification?: (name: string) => boolean;
+}
+interface KitRemotePorts {
+    /** Fetches the setup descriptor, one allowlist-checked hop at a time. */
+    setupFetcher: SetupFetcher;
+    catalog: HttpCatalogPort;
+    license: HttpLicensePort;
+    registry: HttpRegistryPort;
+    artifacts: HttpArtifactPort;
+    scaffold: ArtifactScaffoldPort;
+    packageManager: RegistryVerifyingPackageManager;
+    /** Exposed so a caller can ask the registry a question directly. */
+    registryClient: KitRegistryProxyClient;
+}
+declare function createKitRemotePorts(options: KitRemotePortsOptions): KitRemotePorts;
+/**
+ * A last-resort guess at the package a Kit ships as.
+ *
+ * Only for a caller with no manifest in hand. The convention it encodes —
+ * one scoped package named after the Kit — is not true of every Kit:
+ * `campaign-landing` ships as `@superfunction/landing-kit`, and asking the
+ * registry about `@superfunction/campaign-landing` gets a 404 that reads as
+ * "your licence does not cover this release". Anything that holds a manifest
+ * passes `packageName` instead of relying on this.
+ */
+declare function kitPackageName(kitId: string): string;
+
+interface RunRequest {
+    file: string;
+    args: string[];
+    cwd: string;
+    /** Secret-free variables the child needs beyond the passthrough set. */
+    extraEnv?: Record<string, string>;
+    /** The one secret a child may receive, and only through its environment. */
+    registryToken?: string;
+    /** Parent variable names this child may also read. Never secrets. */
+    passthrough?: readonly string[];
+    timeoutMs?: number;
+}
+interface RunResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    /** True when the binary was not there at all, rather than exiting badly. */
+    missing: boolean;
+}
+type CommandRunner = (request: RunRequest) => Promise<RunResult>;
+
+/**
+ * The package manager, actually run.
+ *
+ * "Frozen" is the whole point of this port. A Kit release pins an exact graph
+ * in a lockfile, and an install that quietly resolves something newer has
+ * produced a project the release never described — so the frozen flag is
+ * passed through to pnpm as `--frozen-lockfile`, and a lockfile that no longer
+ * matches `package.json` fails the install rather than being rewritten.
+ *
+ * The registry session never becomes an argument and never becomes a file. It
+ * reaches the child as npm configuration in that child's own environment,
+ * addressed to the registry it is good for — so the token is in the process's
+ * own memory and in no argument list, no `.npmrc` and no log. The committed
+ * `.npmrc` only maps the release's scopes to the registry, which is public.
+ *
+ * Why a failure is classified at all: unit 06 lets exactly one failure be
+ * retried with a fresh session, and only one. Everything else would fail
+ * identically the second time, so telling "the registry refused us" apart from
+ * "this graph cannot be resolved" is what keeps the retry meaningful instead of
+ * doubling every genuine failure.
+ */
+
+interface PnpmPackageManagerOptions {
+    /** Registry the install resolves against. Public URL, never a secret. */
+    registryUrl?: string;
+    /**
+     * Secret-free variables the install needs, e.g. `npm_config_userconfig`
+     * pointed at an empty file so a machine's own `~/.npmrc` cannot redirect a
+     * scope somewhere the release never named. The operation's own environment
+     * takes precedence over anything here.
+     */
+    extraEnv?: Record<string, string>;
+    /** A store outside the user's own, for a run that must not touch it. */
+    storeDir?: string;
+    /** Refuse to run a dependency's install scripts. */
+    ignoreScripts?: boolean;
+    /** Treat the project as standalone, whatever it happens to sit inside. */
+    ignoreWorkspace?: boolean;
+    timeoutMs?: number;
+    /** Injected so tests drive the classification without spawning pnpm. */
+    run?: CommandRunner;
+    /** The binary to run. `pnpm` unless a test or a project says otherwise. */
+    binary?: string;
+}
+declare class PnpmPackageManagerPort implements PackageManagerPort {
+    private readonly options;
+    constructor(options?: PnpmPackageManagerOptions);
+    install(request: {
+        cwd: string;
+        frozen: boolean;
+        env: Record<string, string>;
+    }): Promise<PackageInstallResult>;
+    /**
+     * The arguments, with the registry among them and the session not.
+     *
+     * A registry URL is a public locator, so it is safe on a command line; the
+     * bearer that opens it is not, and travels in the environment instead.
+     */
+    private argumentsFor;
+}
+
+/**
+ * The project's database, asked through the project's own CLI.
+ *
+ * The asking is done by a child process rather than in this one, and that is
+ * the design rather than an accident. Reading a project's migration state
+ * means loading that project's environment, and loading it in *this* process
+ * would pull the project's secrets — a connection string with a password in it
+ * — into the memory of a command that has no use for them and prints reports
+ * for a living. A child loads them, answers one question, and exits.
+ *
+ * The question is asked in the machine-readable form `spfn db status --json`
+ * exists for. Nothing here parses prose: a human summary is written to change
+ * when it reads better, and a port that depended on its wording would break
+ * quietly the first time someone improved it.
+ */
+
+interface SpfnDatabaseOptions {
+    /** How to run this CLI. Defaults to the binary this build ships with. */
+    command?: {
+        file: string;
+        args: string[];
+    };
+    timeoutMs?: number;
+    run?: CommandRunner;
+}
+declare class SpfnDatabasePort implements DatabasePort {
+    private readonly options;
+    constructor(options?: SpfnDatabaseOptions);
+    status(request: {
+        cwd: string;
+    }): Promise<DatabaseStatus>;
+    /**
+     * Apply what is waiting, then look again.
+     *
+     * The second look is not belt and braces: `spfn db migrate` reports what it
+     * attempted, and this port has to report what is *true afterwards*. A
+     * migration that exits 0 having applied three of four is a failure, and
+     * only re-reading the status says so.
+     */
+    migrate(request: {
+        cwd: string;
+        withBackup: boolean;
+    }): Promise<MigrationResult>;
+    private report;
+    private run;
+}
+
+/**
+ * The release's gates, run where the release lives.
+ *
+ * A gate is the release's own claim that the project it just produced works:
+ * it typechecks, its tests pass, it builds. So each one runs the project's own
+ * script wherever the project has one, and falls back to the obvious command
+ * only where there is an obvious one. A gate a project has no way to run is a
+ * failure with a reason, not a silent pass — "we could not check" and "we
+ * checked and it is fine" are different claims, and only one of them may let
+ * an install commit.
+ *
+ * `db-status` is not a command at all. It is the database port's own answer,
+ * asked again, because a gate that shelled out to a second implementation of
+ * the same question could disagree with the migration step it follows.
+ *
+ * `health` never reaches here: it is a deployment gate, and the operation
+ * filters it out before local gates run.
+ */
+
+interface CommandGateOptions {
+    /** Answers the `db-status` gate. The same port the migration step used. */
+    database: DatabasePort;
+    packageManagerBinary?: string;
+    timeoutMs?: number;
+    run?: CommandRunner;
+}
+declare class CommandGatePort implements GatePort {
+    private readonly options;
+    constructor(options: CommandGateOptions);
+    run(gate: KitGate, request: {
+        cwd: string;
+    }): Promise<GateResult>;
+    private commandFor;
+}
+
+/**
+ * Git, in the narrow shape unit 06 asks for: start a repository, say whether
+ * it is clean, make one commit, name the current one.
+ *
+ * Deliberately nothing else. No remote is added, nothing is pushed, no branch
+ * is renamed and no history is rewritten — a Kit install finishes at a
+ * verified local repository, and a port that could push would make that
+ * boundary a matter of trust rather than of capability.
+ *
+ * The identity question is handled the way it should be: the user's own
+ * `user.name` and `user.email` are used whenever Git can find them, and a
+ * fallback is supplied *for one command* only when it cannot. Writing an
+ * identity into the repository's config would change a setting the person
+ * owns; passing it with `-c` changes nothing that outlives the commit.
+ */
+
+interface SystemGitOptions {
+    binary?: string;
+    timeoutMs?: number;
+    run?: CommandRunner;
+}
+declare class SystemGitPort implements GitPort {
+    private readonly options;
+    constructor(options?: SystemGitOptions);
+    /** Start a repository, or leave the one that is already there alone. */
+    init(request: {
+        cwd: string;
+    }): Promise<void>;
+    /**
+     * Whether the worktree has nothing uncommitted.
+     *
+     * A Git call that fails is *not* reported as clean. An update refuses to
+     * start on a dirty worktree, and answering "clean" because the question
+     * could not be asked would turn a missing answer into permission.
+     */
+    isClean(request: {
+        cwd: string;
+    }): Promise<boolean>;
+    /**
+     * Commit whatever the operation produced, or report the commit already
+     * there when it produced nothing to record.
+     *
+     * "Nothing to commit" is not a failure. A resume reaches this after the
+     * previous run committed, and an operation whose whole effect was ignored
+     * by `.gitignore` reaches it too — in neither case is refusing with a raw
+     * error the right answer, and the second case is caught where it belongs,
+     * by the check that the committed state is actually tracked.
+     */
+    commit(request: {
+        cwd: string;
+        message: string;
+    }): Promise<{
+        commit: string;
+    }>;
+    trackedAmong(request: {
+        cwd: string;
+        paths: readonly string[];
+    }): Promise<string[]>;
+    /** The current commit, or null in a repository that has none yet. */
+    head(request: {
+        cwd: string;
+    }): Promise<string | null>;
+    /**
+     * `-c user.name=… -c user.email=…`, but only when Git has neither.
+     *
+     * `--no-verify` above and this together mean a commit works on a machine
+     * that has never been set up, without either one changing what the machine
+     * does for anything else.
+     */
+    private identityArguments;
+    private git;
+}
+
+/**
+ * The four ports that are local process work, assembled.
+ *
+ * Everything a Kit operation does on this machine rather than over the network
+ * ends up here: installing the graph, applying migrations, running the
+ * release's gates and making the first commit. They are built together because
+ * two of them depend on a third — the `db-status` gate has to be the same
+ * database port the migration step used, or a gate could contradict the step
+ * it follows.
+ */
+
+interface KitLocalPortsOptions {
+    packageManager?: PnpmPackageManagerOptions;
+    database?: SpfnDatabaseOptions;
+    git?: SystemGitOptions;
+    gateTimeoutMs?: number;
+}
+interface KitLocalPorts {
+    packageManager: PackageManagerPort;
+    database: DatabasePort;
+    gates: GatePort;
+    git: GitPort;
+    loadProjectModule: ProjectModuleLoader;
+}
+declare function createKitLocalPorts(options?: KitLocalPortsOptions): KitLocalPorts;
+
+/**
+ * All ten ports, for a real run.
+ *
+ * This is the join: the six that reach the network or a release artifact, and
+ * the four that run something on this machine. Nothing here decides policy —
+ * every refusal, every retry and every checkpoint still lives in the
+ * operations. What this file decides is only *which* implementation answers,
+ * and it makes three choices worth naming:
+ *
+ *   - the credential store is the real keychain, under the Kit's own service.
+ *     A Kit credential is never reachable through the env-secret path, and the
+ *     separation is a constructor argument rather than a convention;
+ *   - the trusted keys are the ones built into this build. Nothing about a
+ *     project can widen them;
+ *   - the addresses come from the checkout first. A project activated against
+ *     one control plane keeps talking to that one.
+ *
+ * `spfn kit status` and `spfn kit check` reach this too, and must not be
+ * stopped by it: they are read-only and have to work on a machine with no
+ * keychain and no network. So nothing here connects, opens or checks anything
+ * at construction time — every port is inert until an operation calls it.
+ */
+
+interface LiveKitAdapterOptions extends KitLocalPortsOptions {
+    /** Overridden by tests and by an integration run against a fixture. */
+    endpoints?: KitEndpoints;
+    fetchImpl?: (input: string, init?: RequestInit) => Promise<Response>;
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * The adapters `spfn kit` uses when nothing has replaced them.
+ *
+ * An ISO instant with second precision, not milliseconds: the contract's
+ * timestamps are second-precision, and an operation ID derived from a
+ * millisecond clock would not match the pattern the journal is checked against.
+ */
+declare function createLiveKitAdapters(request: AdapterRequest, options?: LiveKitAdapterOptions): KitAdapters;
+
+/**
+ * The public keys this CLI will accept a signed Kit document from.
+ *
+ * The list is built in rather than fetched, and that is the point: a trust root
+ * that arrives over the network is not a trust root, because whoever can serve
+ * the document can serve the key that vouches for it. Keys change by shipping a
+ * new CLI, which is a thing customers can see happen.
+ *
+ * The list is empty in this build. The release signing key is not published
+ * yet, so every signed document fails verification, and that is the correct
+ * behaviour for a CLI that has no way to tell a real release from a forged one
+ * — it fails closed, with `KIT_MANIFEST_INVALID`, rather than installing
+ * whatever it was handed.
+ *
+ * `SPFN_KIT_TRUSTED_KEYS` exists for the runs that legitimately verify against
+ * a key that is not the published one: an integration against a staging
+ * control plane, or a release rehearsal. It *replaces* the built-in list rather
+ * than adding to it, so a stray variable can only ever narrow what this CLI
+ * trusts down to keys the person running it chose.
+ */
+
+/** Keys shipped with this build. Empty until the signing key is published. */
+declare const BUILT_IN_TRUSTED_KEYS: readonly TrustedKey[];
+declare const TRUSTED_KEYS_ENV = "SPFN_KIT_TRUSTED_KEYS";
+/**
+ * The keys to verify with, and where they came from.
+ *
+ * A malformed override is rejected outright rather than partially honoured: a
+ * trust list that silently dropped the entry someone meant to add would verify
+ * with whatever was left, which is the one outcome worth avoiding here.
+ */
+declare function resolveTrustedKeys(env?: NodeJS.ProcessEnv): readonly TrustedKey[];
+
 declare function run(): Promise<void>;
 
-export { type CustomDomains, type DeploymentConfig, type EnvironmentVariables, type PackageManager, type Region, type SpfnConfig, run };
+export { BUILT_IN_TRUSTED_KEYS, CONTROL_PLANE_URL_ENV, CommandGatePort, type CustomDomains, DEFAULT_CONTROL_PLANE_URL, DEFAULT_REGISTRY_URL, type DeploymentConfig, type EnvironmentVariables, type KitAdapterFactory, type KitAdapters, type KitEndpoints, type KitLocalPorts, type KitLocalPortsOptions, type KitRemotePorts, type KitRemotePortsOptions, type LiveKitAdapterOptions, type PackageManager, PnpmPackageManagerPort, REGISTRY_URL_ENV, type Region, type SpfnConfig, SpfnDatabasePort, SystemGitPort, TRUSTED_KEYS_ENV, createKitLocalPorts, createKitRemotePorts, createLiveKitAdapters, kitPackageName, resolveKitEndpoints, resolveTrustedKeys, run, setKitAdapterFactory };