@skrr-ai/cli 0.1.42 → 0.1.44

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/firstPartyHarness.d.ts

@@ -24,25 +24,40 @@
  *      phase, once every peer accepts the new one;
  *   4. regenerate `first-party-harness.json`
  *      (`node --import tsx scripts/emit-first-party-harness-json.mjs`);
- *   5. ship the data migration, which is generic over `aliases`.
+ *   5. ship the data migration, which is generic over `aliases` and
+ *      `formerSpellings`;
+ *   6. at that rename's contract, move the spelling from `aliases` to the front
+ *      of `formerSpellings`.
  *
  * No identifier, file, env var name or workflow input moves.
  *
- * ── Three spellings, kept apart on purpose ────────────────────────────────
- *
- * `provider`     CANONICAL. What the platform stores, returns and renders.
- * `aliases`      ACCEPTED on every ingress until contract, and normalised to
- *                canonical at the edge. Nothing new is ever written with one.
- * `wireProvider` What the server and a daemon say to EACH OTHER — the
- *                capability a daemon advertises, `daemon:<p>:request|response`,
- *                the `provider` of a session RPC. It moves after the flip and
- *                BEFORE contract, because a daemon on a user's machine may be
- *                any version and the server cannot tell which one sent a
- *                request: only a released daemon that already advertises the
- *                canonical capability lets the old one age out of the fleet.
- *
- * The old code treated those three as one string, which is why no single
- * change could rename it safely. See
+ * ── Four fields, kept apart on purpose ────────────────────────────────────
+ *
+ * `provider`        CANONICAL. What the platform stores, returns and renders.
+ * `aliases`         ACCEPTED on every ingress during a rename's window, and
+ *                   normalised to canonical at the edge. Nothing new is ever
+ *                   written with one. Empty between renames.
+ * `formerSpellings` RETIRED. Accepted on NO ingress: no HTTP body, enum, Mongo
+ *                   filter, capability, wire event, CLI flag or trust table
+ *                   admits one. Recognised only where an ARTIFACT that predates
+ *                   the rename is read — a binary already installed, a checkout
+ *                   directory already on disk, a release already published
+ *                   under its prefix, a row or config key already written.
+ *                   Those exist whatever the platform accepts, and dropping a
+ *                   spelling from this list does not make them go away. Read it
+ *                   through `firstPartyHarnessArtifactSpellings`, never as an
+ *                   ingress check.
+ * `wireProvider`    What the server and a daemon say to EACH OTHER — the
+ *                   capability a daemon advertises,
+ *                   `daemon:<p>:request|response`, the `provider` of a session
+ *                   RPC. It moves after the flip and BEFORE contract, because a
+ *                   daemon on a user's machine may be any version and the
+ *                   server cannot tell which one sent a request: only a
+ *                   released daemon that already advertises the canonical
+ *                   capability lets the old one age out of the fleet.
+ *
+ * The old code treated these as one string, which is why no single change could
+ * rename it safely. See
  * `docs/architecture/skrr-code-identifier-rename-2026-09-13.md`.
  *
  * ── Constraints on this file ──────────────────────────────────────────────
@@ -61,24 +76,28 @@ export interface FirstPartyHarnessIdentity {
     readonly provider: string;
     /** Older spellings still ACCEPTED on every ingress, newest first. */
     readonly aliases: readonly string[];
+    /**
+     * Retired spellings, newest first: accepted on NO ingress, recognised only in
+     * artifacts that predate their retirement (see the file header).
+     */
+    readonly formerSpellings: readonly string[];
     /** The spelling daemons and the server exchange on the wire. */
     readonly wireProvider: string;
 }
 /**
  * THE identity — the only literal product name in the codebase.
  *
- * Phase: WIRE MOVED. `skrr-code` is canonical — stored, returned, rendered — and
- * it is now also what the server and a daemon say to each other. `sky-code` is
- * still accepted on every ingress, so a daemon released before this change
- * (which advertises and answers on `sky-code`) keeps working against a server
- * that speaks `skrr-code`, and the reverse. Contract (OSK-8663) empties
- * `aliases` once no connected daemon still advertises the old capability.
+ * Phase: CONTRACTED (OSK-8663). `skrr-code` is the only spelling any ingress
+ * accepts and the only one on the wire. `sky-code` is retired: nothing admits
+ * it, and it is still recognised where a binary, a checkout, a published
+ * release or a stored value written before the rename is looked for.
  */
 declare const IDENTITY: {
     readonly displayName: "skrr Code";
     readonly command: "skrr code";
     readonly provider: "skrr-code";
-    readonly aliases: readonly ["sky-code"];
+    readonly aliases: readonly [];
+    readonly formerSpellings: readonly ["sky-code"];
     readonly wireProvider: "skrr-code";
 };
 /** The canonical slug, as a literal type. */
@@ -92,8 +111,26 @@ export type FirstPartyHarnessCapabilityName = `${FirstPartyHarnessProvider}_sess
 export declare const FIRST_PARTY_HARNESS: FirstPartyHarnessIdentity;
 /** The canonical slug with its literal type, for `as const` tuples and keyed tables. */
 export declare const FIRST_PARTY_HARNESS_PROVIDER: FirstPartyHarnessCanonicalProvider;
-/** Every spelling, canonical first. The order is the resolution order. */
+/**
+ * Every ACCEPTED spelling, canonical first — what an ingress admits. The order
+ * is the resolution order.
+ */
 export declare function firstPartyHarnessSpellings(): readonly string[];
+/**
+ * Every spelling an ARTIFACT that already exists may carry, canonical first:
+ * the accepted spellings, then every former one.
+ *
+ * For code that LOOKS FOR what an earlier release left behind — an installed
+ * binary, a checkout directory, an immutable published release, a stored value
+ * or config key — and for the tooling that must keep recognising those
+ * (ignore lists, the identity ratchet). A machine that never ran a post-rename
+ * client still has its engine under the old name, and it must still be found.
+ *
+ * Never an ingress check: a former spelling is not accepted anywhere, and a
+ * reader that admitted one here would silently reopen what contract closed. Use
+ * `firstPartyHarnessSpellings` / `isFirstPartyHarnessProvider` for that.
+ */
+export declare function firstPartyHarnessArtifactSpellings(): readonly string[];
 /** True for the canonical provider or any alias (case- and whitespace-insensitive). */
 export declare function isFirstPartyHarnessProvider(value: unknown): boolean;
 /**
@@ -102,6 +139,24 @@ export declare function isFirstPartyHarnessProvider(value: unknown): boolean;
  * caller's own normalisation still owns case and shape for other providers).
  */
 export declare function canonicalHarnessProvider<T>(value: T): T | string;
+/**
+ * The canonical provider for a value read back from an ARTIFACT that may predate
+ * a rename — any artifact spelling (canonical, alias or FORMER) becomes the
+ * provider; every other value is returned unchanged.
+ *
+ * For values nobody migrates and nobody can refuse: a harness row's stored
+ * display NAME (the operator migration rewrites `provider`, never `name`), a
+ * daemon's config file, a harness session binding on a user's machine. Read raw
+ * after contract, each would name an unknown provider — a label that renders the
+ * retired name again, a local session silently running another backend, a live
+ * resume context reset as new — with no error anywhere.
+ *
+ * NEVER for anything a peer, a client or an operator SENDS, and never for a
+ * trust, dispatch or admission decision: a former spelling is accepted on no
+ * ingress, and canonicalising one here would reopen what contract closed. Use
+ * `canonicalHarnessProvider` for those.
+ */
+export declare function canonicalArtifactHarnessProvider<T>(value: T): T | string;
 /**
  * Every spelling a stored row for this provider may carry, canonical first —
  * for a Mongo `$in` filter while rows written before a flip still exist. Any
@@ -138,7 +193,16 @@ export declare function isFirstPartyHarnessEnvironment(value: unknown): boolean;
 export declare function canonicalExecutionEnvironment<T>(value: T): T | string;
 /** Binary file name. `platform` is a `process.platform` value; only `win32` differs. */
 export declare function firstPartyHarnessBinaryName(provider?: string, platform?: string): string;
-/** Every binary file name, canonical first — the lookup order. */
+/**
+ * Every binary file name an install may carry, canonical first — the lookup
+ * order, and the names an install links to the canonical binary.
+ *
+ * Built from the ARTIFACT spellings, former ones included: binaries are
+ * artifacts. An engine installed before a rename is still on disk under its old
+ * name, and a platform CLI or daemon built before it still looks for that name,
+ * so resolvers try it and installers leave a link at it. Neither makes the
+ * spelling acceptable on any ingress.
+ */
 export declare function firstPartyHarnessBinaryNames(platform?: string): readonly string[];
 /**
  * The engine home directory name under the skrr config root.
@@ -149,7 +213,8 @@ export declare function firstPartyHarnessBinaryNames(platform?: string): readonl
  * the managed `AGENTS.md` from `<home>`. Deriving it from the provider would, on
  * a fresh install after a provider rename, create a second directory the engine
  * never reads — managed instructions would stop applying with no error. It moves
- * when the engine's namespace moves, and not before.
+ * when the engine's namespace moves, and not before; it did in OSK-8674, and
+ * `migrateFirstPartyHarnessHome` moves a home under a legacy name onto it.
  */
 export declare function firstPartyHarnessHomeDirname(): string;
 /** Signed release manifest file name. */
@@ -161,23 +226,33 @@ export declare function firstPartyHarnessManifestFile(provider?: string): string
 export declare const FIRST_PARTY_HARNESS_FEED_ORIGIN = "https://updates.oversky.ai";
 /** Object-key prefix for one spelling's feed, e.g. `skrr-code/`. */
 export declare function firstPartyHarnessFeedPrefix(provider?: string): string;
-/** Every feed prefix, canonical first. Publishing writes all of them. */
+/**
+ * Every feed prefix a publish WRITES, canonical first: the accepted spellings.
+ *
+ * A former spelling's prefix still holds every release published under it, and
+ * those stay served — their artifact URLs are inside signed manifests — but
+ * nothing new is written there, so its channel pointers stop moving at contract.
+ */
 export declare function firstPartyHarnessFeedPrefixes(): readonly string[];
 /** Object-key prefix the fork stages unsigned builds under, e.g. `skrr-code-staging/`. */
 export declare function firstPartyHarnessStagingPrefix(provider?: string): string;
 /** Default feed base URL for one spelling. */
 export declare function firstPartyHarnessDefaultFeedBase(provider?: string): string;
 export interface FirstPartyHarnessEnvName {
-    /** Brand-neutral name. Set this one. */
+    /** Brand-neutral name — the only one the platform reads. */
     readonly name: string;
-    /** Older names still read, in precedence order, until contract. */
-    readonly legacy: readonly string[];
 }
 /**
- * Every environment variable the platform reads for the first-party harness,
- * by purpose. The neutral name wins; a legacy name is read only when the neutral
- * one is unset or blank, because a variable set in an ECS task definition, a
- * user's shell or a LaunchAgent does not change when the code does.
+ * Every environment variable the PLATFORM reads for the first-party harness, by
+ * purpose, under one brand-neutral name each — so a product rename never renames
+ * one.
+ *
+ * The product-named variables these replaced were read second until contract
+ * (OSK-8663) and are not read at all now. The ENGINE's own variables are a
+ * different namespace (`FIRST_PARTY_HARNESS_ENGINE.env`): the fork reads them,
+ * so a platform reader that must agree with the engine consults the engine's
+ * names explicitly (`readFirstPartyHarnessEngineEnv`) — the engine home is the
+ * one case (`home` below).
  */
 export declare const FIRST_PARTY_HARNESS_ENV: Readonly<{
     /** Absolute path to an engine binary, overriding resolution. */
@@ -192,7 +267,13 @@ export declare const FIRST_PARTY_HARNESS_ENV: Readonly<{
     devKeys: FirstPartyHarnessEnvName;
     /** Engine version the desktop build bundles. */
     bundleVersion: FirstPartyHarnessEnvName;
-    /** Engine home override (the engine reads its own name too — see ENGINE env below). */
+    /**
+     * Engine home override. The engine reads only its own variable, under every
+     * name it has had (`readFirstPartyHarnessEngineEnv(env, 'home')`), so a reader
+     * that resolves the home the engine will use reads those second, and a
+     * launcher hands the engine the resolved path under every one of them
+     * (`firstPartyHarnessEngineEnvEntries`).
+     */
     home: FirstPartyHarnessEnvName;
     /** Engine version baked into the cloud-coding image. */
     cloudCodingVersion: FirstPartyHarnessEnvName;
@@ -213,43 +294,87 @@ export interface FirstPartyHarnessEnvReading {
     readonly value: string | undefined;
     /** The variable that supplied `value`. */
     readonly name: string | undefined;
-    /** True when the value came from a legacy name — worth telling the operator. */
-    readonly legacy: boolean;
 }
-/** Every name for one purpose, neutral first — for spawn-env forwarding and sanitisers. */
-export declare function firstPartyHarnessEnvNames(key: FirstPartyHarnessEnvKey): readonly string[];
-/** Read one purpose's variable: neutral name first, legacy names after. */
+/** Read one purpose's variable. A blank value counts as unset. */
 export declare function readFirstPartyHarnessEnv(env: Readonly<Record<string, string | undefined>>, key: FirstPartyHarnessEnvKey): FirstPartyHarnessEnvReading;
+/**
+ * Every variable the engine reads, by purpose, as the suffix after the app
+ * name's prefix (`skrr-code` → `SKRR_CODE_<suffix>`). The fork names all of its
+ * own variables this way, so the names follow the namespace rather than being
+ * written out once per spelling.
+ */
+declare const ENGINE_ENV_SUFFIXES: Readonly<{
+    serverPassword: "SERVER_PASSWORD";
+    serverUsername: "SERVER_USERNAME";
+    home: "HOME";
+    config: "CONFIG";
+    appName: "APP_NAME";
+    scriptName: "SCRIPT_NAME";
+    allowUpstreamEgress: "ALLOW_UPSTREAM_EGRESS";
+    compatOpencode: "COMPAT_OPENCODE";
+    noCompatPrompts: "NO_COMPAT_PROMPTS";
+}>;
+export type FirstPartyHarnessEngineEnvKey = keyof typeof ENGINE_ENV_SUFFIXES;
 /**
  * Names the ENGINE itself defines and reads. The platform sets or reads them
  * across the daemon↔engine boundary, so they are recorded here as values rather
- * than scattered as literals — but they are the fork's to change, and moving
- * one is a two-sided change (contract §6). Not part of this identity's rename.
+ * than scattered as literals. They are the fork's names, and moving one is a
+ * two-sided change: the engine reads the new name first and every legacy name
+ * second, and while engine and platform releases can arrive in either order the
+ * platform SETS every name and READS new-then-legacy (contract §6, OSK-8674).
  */
 export declare const FIRST_PARTY_HARNESS_ENGINE: Readonly<{
     /**
      * The engine's state namespace: XDG dirs, project marker, config basename, and
      * the engine home under the skrr root (`firstPartyHarnessHomeDirname`).
      */
-    appName: "sky-code";
+    appName: string;
     /**
-     * Earlier `appName`s whose home directory `migrateFirstPartyHarnessHome` moves
-     * onto the current one. Empty until the engine's namespace is renamed.
+     * Earlier `appName`s, newest first. `migrateFirstPartyHarnessHome` moves a home
+     * under one of them onto the current name and leaves a symlink; readers of
+     * engine state look under them after the current name.
      */
     legacyAppNames: readonly string[];
     /** Project-local configuration directory inside a user's repository. */
-    projectDirectory: ".sky-code";
-    /** Environment variables the engine reads. */
-    env: Readonly<{
-        serverPassword: "SKY_CODE_SERVER_PASSWORD";
-        serverUsername: "SKY_CODE_SERVER_USERNAME";
-        home: "SKY_CODE_HOME";
-        config: "SKY_CODE_CONFIG";
-        appName: "SKY_CODE_APP_NAME";
-        scriptName: "SKY_CODE_SCRIPT_NAME";
-        allowUpstreamEgress: "SKY_CODE_ALLOW_UPSTREAM_EGRESS";
-        compatOpencode: "SKY_CODE_COMPAT_OPENCODE";
-        noCompatPrompts: "SKY_CODE_NO_COMPAT_PROMPTS";
-    }>;
+    projectDirectory: `.${string}`;
+    /**
+     * Earlier project directories, newest first. The engine still reads them and
+     * the platform never rewrites a user's repository to move one, so a reader
+     * looks here after `projectDirectory`, and a writer adopts an existing file
+     * here rather than creating a second one beside it.
+     */
+    legacyProjectDirectories: readonly string[];
+    /**
+     * Environment variables the engine reads, under the CURRENT namespace. The
+     * engine also reads each one under every legacy namespace, second — use
+     * `readFirstPartyHarnessEngineEnv` to read one the way the engine does and
+     * `firstPartyHarnessEngineEnvEntries` to set one every engine build honours.
+     */
+    env: Readonly<Record<"appName" | "serverPassword" | "serverUsername" | "home" | "config" | "scriptName" | "allowUpstreamEgress" | "compatOpencode" | "noCompatPrompts", string>>;
 }>;
+/**
+ * Every name the engine reads for one purpose, current namespace first — the
+ * engine's own lookup order.
+ */
+export declare function firstPartyHarnessEngineEnvNames(key: FirstPartyHarnessEngineEnvKey): readonly string[];
+/**
+ * Read one engine variable the way the engine reads it: the current name, then
+ * every legacy name. A blank value counts as unset.
+ */
+export declare function readFirstPartyHarnessEngineEnv(env: Readonly<Record<string, string | undefined>>, key: FirstPartyHarnessEngineEnvKey): FirstPartyHarnessEnvReading;
+/**
+ * One engine variable set under EVERY name the engine has read, for a process
+ * that spawns the engine. An engine binary is installed on its own schedule, so
+ * a launcher cannot know whether the one it starts reads the current name or a
+ * legacy one; setting both means either build receives the value.
+ */
+export declare function firstPartyHarnessEngineEnvEntries(key: FirstPartyHarnessEngineEnvKey, value: string): Record<string, string>;
+/** Every engine project directory, current first — the engine's read order. */
+export declare function firstPartyHarnessEngineProjectDirectories(): readonly string[];
+/**
+ * Every engine home directory name under a config root, current first: where an
+ * engine home may exist on disk. `firstPartyHarnessHomeDirname` is the one the
+ * platform writes.
+ */
+export declare function firstPartyHarnessEngineHomeDirnames(): readonly string[];
 export {};