halfcycle 0.3.7

package/dist/device-signin.d.ts

@@ -0,0 +1,255 @@
+/**
+ * The BROWSER HANDOFF, client half — `npx halfcycle` signing a machine in (T-08,
+ * feature `connect-signup-and-credential`; **loopback added by T-25, #614**).
+ *
+ * The CLI mints a device code, opens a browser, and waits until a signed-in human
+ * approves or refuses. That direction — CLI mints, browser redeems — is the same as
+ * the board's enter-code flow.
+ *
+ * ---------------------------------------------------------------------------
+ * SINCE T-25 THERE ARE TWO WAYS THE ANSWER COMES BACK, and `signIn` below is where
+ * the choice is made:
+ *
+ *   LOOPBACK (the default) — the CLI listens on `127.0.0.1`, the page redirects the
+ *   browser back to it, and NO CODE IS SHOWN. `loopback-signin.ts` owns the listener.
+ *
+ *   DEVICE CODE (the fallback) — the code is printed, the human compares it with the
+ *   page, and this file polls. Unchanged, and the right answer whenever the browser
+ *   is not on this machine.
+ *
+ * The fallback is chosen from two MEASUREMENTS — a bind that failed, or a browser
+ * opener that failed — and never from reading the environment and guessing. See
+ * `signIn` and `openBrowser`.
+ *
+ * ---------------------------------------------------------------------------
+ * THE WIRE SHAPES ARE IMPORTED, NEVER RE-DECLARED. Every payload and every `status`
+ * value comes from `@halfcycle/events`, which is where this contract lives since
+ * this task (INV-003, INV-001 — `packages/events` is on the shippable allowlist).
+ * A hand-written `interface StartResponse` here would be a second home for a shape
+ * whose other end is a deployed service, and the two would agree until the first
+ * time one of them changed.
+ *
+ * The responses are PARSED, not cast. A cast asserts nothing: a plane that answered
+ * `{}` would satisfy `as DeviceAuthStartResponse` and produce a CLI that opened
+ * `undefined` in a browser and polled with an empty code for fifteen minutes.
+ *
+ * ---------------------------------------------------------------------------
+ * FOUR WAYS THIS ENDS, and each is a different sentence and a non-zero exit:
+ *
+ *   `declined`  — a human refused at the page. Nothing was created.
+ *   `expired`   — the code's window closed on CONTROL's clock before anyone acted.
+ *   `unknown`   — the server is not waiting on this code (never minted, or spent).
+ *   unreachable — the plane stopped answering mid-poll. This one is OURS to word,
+ *                 because control cannot send a sentence about a request it never
+ *                 received.
+ *
+ * The first three are control's own words, forwarded verbatim from
+ * `@halfcycle/events`, because they were written for exactly this reader and each
+ * already names what to do next. Re-wording them here would give the terminal and
+ * the confirmation page two different accounts of one event.
+ *
+ * ---------------------------------------------------------------------------
+ * THE EXPIRY IS THE SERVER'S. The poll runs until control answers a terminal state
+ * or until the local clock passes the `expiresAt` control declared, plus one poll
+ * interval of slack. The client never decides that a code has expired while control
+ * still considers it live — it keeps asking, and control's `expired` is what ends
+ * the wait. The local deadline exists only so an unreachable plane cannot make this
+ * loop unbounded; crossing it is reported as a TIMEOUT, in its own words, and never
+ * as "expired", which would be a claim about a server state nobody observed.
+ *
+ * INV-001: Node builtins, the global `fetch` (Node 20), and `@halfcycle/events`.
+ */
+import { type DeviceAuthStartResponse, type DevicePollApproved } from '@halfcycle/events';
+/**
+ * A sign-in that ended without a credential.
+ *
+ * `status` carries control's own discriminant when control produced one, and the
+ * local `'timed-out'` when the plane stopped answering. It is exposed so a caller
+ * can branch (`bin.ts` does not, today — it prints and exits — but a refusal a
+ * caller cannot tell apart is a refusal that gets retried in a loop by the next
+ * person who tries).
+ */
+export declare class SignInRefused extends Error {
+    readonly status: string;
+    constructor(status: string, message: string);
+}
+/** The local status for "the plane stopped answering". Not a control status. */
+export declare const SIGN_IN_TIMED_OUT = "timed-out";
+/**
+ * The sentence for a poll that outlived its local deadline without control ever
+ * answering. Distinct from `DEVICE_EXPIRED_MESSAGE` on purpose: that one is a fact
+ * control asserted, this one is a fact only the client observed, and telling a
+ * developer their code expired when what actually happened is that the server went
+ * away sends them to re-run instead of to check their connection.
+ */
+export declare const SIGN_IN_TIMEOUT_MESSAGE: string;
+/**
+ * The sentence for a non-interactive run with no credential in the environment.
+ *
+ * A CI job has no browser and nobody to look at a code, so minting one and waiting
+ * fifteen minutes for a human who does not exist is the worst available failure: it
+ * burns the job's time and then reports something that reads like a platform
+ * outage. It refuses immediately instead, and names the ONE thing a workflow can
+ * actually do.
+ */
+export declare const SIGN_IN_NON_INTERACTIVE_MESSAGE: string;
+/** Everything this module touches that a test may need to hold still. */
+export interface SignInDeps {
+    /** Where the CLI writes its narration. Defaults to stdout. */
+    write?: (text: string) => void;
+    /** Sleep between polls. Defaults to a real timer. */
+    sleep?: (ms: number) => Promise<void>;
+    /** The clock the local deadline is measured on. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * The platform command that opens a URL in the user's browser, as `{command, args}`.
+ *
+ * A PURE FUNCTION so the argv can be asserted on every platform from any platform —
+ * the alternative is a test that only ever checks the branch it happens to be
+ * running on, which on this repo's CI would mean the Windows and Linux arms were
+ * never looked at.
+ *
+ * NO SHELL, EVER. The URL is an argv element, so a value containing shell
+ * metacharacters is an odd URL and not a command. `start` on Windows is the one
+ * that would need a shell, so it is invoked through `cmd /c start ""` with an empty
+ * title argument — without that empty string, `start` treats a quoted URL as the
+ * window title and opens nothing.
+ */
+export declare function browserOpenCommand(os: string, url: string): {
+    command: string;
+    args: string[];
+};
+/**
+ * Is this URL safe to hand to the platform opener?
+ *
+ * The address comes off the wire, so it is a value a compromised or misconfigured
+ * plane controls. Only `http`/`https` are opened; anything else is printed instead.
+ * The opener takes argv rather than a shell string, so the exposure was bounded
+ * already — this closes the rest of it, where a `file://` URL would open a local
+ * document and a handler-scheme URL would launch whatever claims that scheme.
+ */
+export declare function isOpenableUrl(url: string): boolean;
+/** What was MEASURED when this run tried to open a browser. */
+export interface BrowserOpenAttempt {
+    /** A browser was launched. Nobody claims the human looked at it. */
+    opened: boolean;
+    /**
+     * Why not, in a clause that fits inside one sentence. Present iff `opened` is
+     * false, and it always names an OBSERVATION — an exit code, a spawn error, an
+     * explicit instruction — never an inference about the kind of machine this is.
+     */
+    reason?: string;
+}
+/**
+ * Open a browser, and MEASURE whether that worked.
+ *
+ * ---------------------------------------------------------------------------
+ * THIS FUNCTION IS ACCEPTANCE CRITERION 3. The loopback flow needs to know whether a
+ * browser actually came up, because that is half of what decides whether the sign-in
+ * can complete without a code — and the criterion says the decision must come from a
+ * measurement, not from sniffing the environment and guessing.
+ *
+ * **The previous version could not answer the question, and returned `true` as
+ * though it could.** It spawned `detached`, attached an empty `error` sink and
+ * returned `true` the instant `spawn` did not throw synchronously — but `spawn`
+ * reports a missing binary ASYNCHRONOUSLY, on the `error` event, and reports a
+ * non-zero exit later still. So `openBrowser('…')` on a box with no `xdg-open`
+ * returned `true`. That was harmless while the answer only chose between two
+ * printed sentences and the poll ran either way; it is not harmless now, because a
+ * wrong `true` here is a terminal that waits in silence for a browser that never
+ * opened.
+ *
+ * So the child is spawned ATTACHED and watched for whichever comes first:
+ *   - `error`      → could not run it at all (`ENOENT` — no `xdg-open` on PATH).
+ *   - `exit(≠0)`   → it ran and refused (`xdg-open` with no display).
+ *   - `exit(0)`    → handed off (macOS/Windows).
+ *   - still up after `BROWSER_OPEN_GRACE_MS` → it is the browser (Linux).
+ *
+ * On the last arm the child is `unref`'d, so a browser that outlives the install
+ * cannot hold this process open.
+ *
+ * ---------------------------------------------------------------------------
+ * `HALFCYCLE_NO_BROWSER` IS AN INSTRUCTION, NOT A HEURISTIC, and the distinction is
+ * exactly the one criterion 3 draws. It is the developer saying *do not take my
+ * browser over*; honouring it is not a guess about the machine, and the reason
+ * reported says so in those words. Nothing else in this flow reads the environment
+ * to decide which path to take.
+ */
+export declare function openBrowser(url: string, env?: NodeJS.ProcessEnv): Promise<BrowserOpenAttempt>;
+/** True iff this run has no human at the keyboard. */
+export declare function isNonInteractive(env?: NodeJS.ProcessEnv): boolean;
+/** `POST /auth/device/start` — mint a code. Throws `SignInRefused` on a refusal. */
+export declare function startDeviceAuth(serviceUrl: string): Promise<DeviceAuthStartResponse>;
+/**
+ * Poll until control answers a terminal state, or until the local deadline.
+ *
+ * A TRANSIENT NETWORK FAILURE IS NOT A REFUSAL. A dropped packet mid-poll gets
+ * another attempt at the next interval, because the developer is standing in front
+ * of a browser they have already signed into and the credential is waiting on the
+ * server. Only the deadline ends the loop — and it is reported as a timeout, in the
+ * client's own words, never as one of control's three refusals.
+ */
+export declare function pollForCredential(serviceUrl: string, started: DeviceAuthStartResponse, deps?: SignInDeps): Promise<DevicePollApproved>;
+/** What a completed sign-in yields. */
+export interface SignedIn {
+    accountId: string;
+    credential: string;
+    /** Control's issue-time expiry, UTC ISO-8601. Information, never a local gate. */
+    expiresAt: string;
+}
+/**
+ * The sentence for a loopback sign-in whose browser never came back.
+ *
+ * DISTINCT FROM `SIGN_IN_TIMEOUT_MESSAGE`, which is about a plane that stopped
+ * answering. Here the plane was fine and the terminal was waiting on a redirect from
+ * the browser — so the recovery is different, and it names the flow that does not
+ * need one.
+ */
+export declare const LOOPBACK_TIMEOUT_MESSAGE: string;
+/**
+ * The whole terminal experience — **loopback first, the device code as the fallback**
+ * (T-25, #614).
+ *
+ * ---------------------------------------------------------------------------
+ * THE TWO PATHS, AND HOW THE CHOICE BETWEEN THEM IS MADE.
+ *
+ *   LOOPBACK — bind `127.0.0.1:0`, put that port in the URL we open, and wait for
+ *   the confirmation page to send the browser back. **No code is displayed at all**
+ *   (criterion 1): there is nothing for the human to compare, so printing a code
+ *   would be printing a value with no use.
+ *
+ *   DEVICE CODE — print the code, open (or print) the page, and poll. Unchanged from
+ *   T-08, still tested, and still correct for every machine whose browser is not the
+ *   one this process can talk to: SSH, containers, remote dev boxes, Codespaces.
+ *
+ * **THE FALLBACK IS CHOSEN BY TWO MEASUREMENTS AND NOTHING ELSE** (criterion 3):
+ * `bindLoopback` tried to listen and reports the `EADDRINUSE`/`EACCES` it got, and
+ * `openBrowser` spawned the platform opener and reports its exit code or spawn error.
+ * Nothing here reads `SSH_CONNECTION`, `DISPLAY`, `SSH_TTY`, `TERM`, `container` or
+ * any other variable to infer what kind of machine this is — an inference that is
+ * wrong in both directions, since a container with a forwarded browser has no
+ * `DISPLAY` and works, and a kiosked desktop has one and does not. The single
+ * environment variable consulted, `HALFCYCLE_NO_BROWSER`, is the developer's own
+ * instruction not to open a browser, and it is honoured rather than interpreted.
+ *
+ * **ORDER MATTERS AND IS DELIBERATE.** The listener is bound BEFORE the code is
+ * minted, so a machine that cannot listen has burned no code by the time it falls
+ * back; and the code is minted once for both paths, so a fallback is never a second
+ * `POST /auth/device/start`.
+ *
+ * **THE FALLBACK OPENS THE UNDECORATED URL.** `started.verificationUrl` is what
+ * control composed; the loopback parameters are added only for the loopback attempt.
+ * Handing the page a port nothing is listening on would make it redirect the browser
+ * to a connection error after a successful approval — a page that looks broken for a
+ * sign-in that worked.
+ *
+ * WHAT IS PRINTED AND WHAT IS NOT, on the device-code path: the USER code is printed
+ * — it is a selector a human compares between two screens and yields nothing to
+ * whoever reads it, since only the device code can claim the credential. The DEVICE
+ * code and the credential are printed nowhere, ever, and appear in no URL.
+ */
+export declare function signIn(serviceUrl: string, deps?: SignInDeps & {
+    env?: NodeJS.ProcessEnv;
+}): Promise<SignedIn>;
+//# sourceMappingURL=device-signin.d.ts.map

package/dist/device-signin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-signin.d.ts","sourceRoot":"","sources":["../src/device-signin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAIH,OAAO,EAKL,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAG3B;;;;;;;;GAQG;AACH,qBAAa,aAAc,SAAQ,KAAK;aAEpB,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM;CAKlB;AAED,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,QAGV,CAAC;AAE3B;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B,QAGsC,CAAC;AAQnF,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,qDAAqD;IACrD,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAUD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,MAAM,GACV;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAIrC;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOlD;AAaD,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,MAAM,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,kBAAkB,CAAC,CAmE7B;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAG9E;AAED,oFAAoF;AACpF,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAsC1F;AAYD;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,uBAAuB,EAChC,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,kBAAkB,CAAC,CAmD7B;AAED,uCAAuC;AACvC,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,QAIF,CAAC;AAiEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAsB,MAAM,CAC1B,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,UAAU,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAO,GAClD,OAAO,CAAC,QAAQ,CAAC,CAmFnB"}

package/dist/engagement-credential.d.ts

@@ -0,0 +1,267 @@
+/**
+ * THE PER-ENGAGEMENT CREDENTIAL STORE — `~/.halfcycle/engagements/<id>/env`
+ * (T-09, feature `connect-signup-and-credential`).
+ *
+ * This is the credential that authenticates a REPOSITORY to the Halfcycle plane:
+ * the session token minted once on create, under the two names its two consumers
+ * read, plus the three origins and the engagement id. Until T-09 it lived in the
+ * client tree at `.env.local`, gitignored. It now lives OUTSIDE every repository,
+ * owner-only, keyed on the engagement.
+ *
+ * ---------------------------------------------------------------------------
+ * WHY OUT OF THE TREE AT ALL. Gitignoring a secret is a discipline; putting it
+ * where the repository cannot reach it is a structure. `.gitignore` is a tracked
+ * file a developer can edit, a `git add -f` overrides it, an editor's "commit all"
+ * has ignored it before, and a zip export carries the file regardless. Studio has
+ * never had this exposure because its layout put the per-engagement token at
+ * machine level from the start (`docs/features/mac-workspace-provider.md:27`),
+ * which is described there as making the moat *"structural, not disciplinary"*.
+ * This module adopts that layout for Connect. Nothing here is new design; it is
+ * one topology's answer applied to the other (INV-022 — Connect reaches it with a
+ * home directory and nothing else).
+ *
+ * ---------------------------------------------------------------------------
+ * IT IS AN ENV FILE AND NOT JSON, AND THAT IS FORCED — not a preference.
+ *
+ * Two consumers read this credential and both are POSIX `sh`:
+ *
+ *   - `.claude/hooks/guard-runner.sh` SOURCES it (`set -a; . "$f"; set +a`) so the
+ *     runner, which reads only `process.env`, receives its three variables. That is
+ *     the INV-001 seam: env loading lives in the hook wiring, never in the binary.
+ *   - `.halfcycle/mcp-headers.sh` READS one `KEY=` line out of it.
+ *
+ * Neither can parse JSON — there is no `jq` in this environment and `node` is not
+ * dependable on a desktop-launched session's PATH (the reason `mcp-headers.sh` is
+ * `sh` and not node in the first place). So the machine-level file is `KEY=value`
+ * lines, exactly as Studio's is, and the ONE field that must come out of the
+ * committed pin — the engagement id — is cut out of JSON with `sed`. See
+ * `engagementResolutionShell()` for that, and for why `tr -d '\n'` precedes it.
+ *
+ * ---------------------------------------------------------------------------
+ * THE SEVEN — NOW EIGHT (T-10) — KEYS ARE FOUR THINGS, AND THE COUNT DECIDES WHAT
+ * MAY BE COMMITTED. Four public origins (the fourth, `CONTROL_TELEMETRY_URL`,
+ * joined at T-10), the engagement id twice, and ONE token under two names —
+ * `HALFCYCLE_TOKEN` and `GUARD_SERVICE_TOKEN` are byte-identical, one credential
+ * under the two names its two consumers read. So six of the eight keys are not
+ * secret at all. **They still do not go into the committed pin.** An earlier draft
+ * of the feature spec counted six non-secret keys out of SEVEN, which would have
+ * sent `GUARD_SERVICE_TOKEN` to a tracked file — the exact outcome this work exists
+ * to prevent — and the safe reading is the one that keeps the credential's key set
+ * whole and in one place: everything the shells need is here, and the pin
+ * contributes only the id that names this directory. `CONTROL_TELEMETRY_URL`
+ * joining the non-secret count does not reopen that count: it is a fourth origin
+ * added after the draft that got the arithmetic wrong, not a recount of the same
+ * seven.
+ *
+ * ---------------------------------------------------------------------------
+ * OWNER-ONLY, AND WHAT THAT MEANS WHERE IT MEANS NOTHING (phase decision 6).
+ *
+ *   - macOS and Linux: the directory is created `0700` and the file written `0600`,
+ *     then `chmodSync`'d explicitly AFTER the write — `writeFileSync`'s `mode` is
+ *     honoured only when the file is CREATED, so a store that already existed at
+ *     `0644` would keep those bits forever, a permission bug with no symptom.
+ *   - Windows: POSIX mode bits are meaningless and `chmod` is a near no-op, so the
+ *     call is SKIPPED rather than issued-and-ignored. Nothing here reads as a
+ *     protection that is not there. What Windows does get is the part that matters
+ *     most and is platform-independent: the credential is in `%USERPROFILE%`, not
+ *     in the repository, so it cannot be committed, pushed or zipped with the
+ *     product. Per-user ACLs on `%USERPROFILE%` are the OS's own default and are
+ *     not something this installer sets or can honestly claim to have set. The two
+ *     generated consumers are POSIX `sh` and run under Git Bash / WSL there.
+ *
+ * The same posture, for the same reasons, as `account-credential.ts` — which is
+ * why `halfcycleHome()` is imported from it rather than re-derived.
+ *
+ * ---------------------------------------------------------------------------
+ * TWO HOMES FOR THIS PATH SHAPE ACROSS THE REPO, AND IT IS A PRESENT CONSTRAINT,
+ * NOT AN OVERSIGHT. `packages/mac-workspace-provider/src/registry.ts` has its own
+ * `engagementEnvPath()` for the identical path — Studio's writer. `packages/bundle`
+ * is shippable and its import allowlist is exactly `{packages/core, packages/events}`
+ * (INV-001), and the provider is hosted-only, so the two cannot share a function
+ * today. `packages/core` is the one package both may import and is where this
+ * belongs eventually; that is the same direction `GUARD_ENV_KEYS`'s docblock in
+ * `install.ts` records as #476, and it is deliberately not done mid-wave. What
+ * binds the two meanwhile is a test that reads the provider's source text off disk
+ * and asserts the shapes agree (`test/credential-out-of-repo.test.ts`) — an `fs`
+ * read, not an import, so there is no build edge and nothing crosses the moat.
+ *
+ * INV-001: Node builtins and this package's own modules only.
+ */
+/**
+ * The field the committed pin (`.halfcycle/bundle.json`) carries the engagement id
+ * under. Named once here because BOTH readers of it — `readEngagementCredential`'s
+ * TS caller and the generated POSIX `sed` — must agree on it, and the pin's writer
+ * (`writeBundlePin`) is in `install.ts`. A test installs, then runs the generated
+ * shell against the real written pin and compares its answer to
+ * `engagementEnvPath()`, so writer and both readers are asserted to agree rather
+ * than left to match by eye.
+ */
+export declare const PIN_ENGAGEMENT_ID_FIELD = "engagementId";
+/** `~/.halfcycle/engagements/<id>/` — this engagement's machine-level state dir. */
+export declare function engagementStateDir(engagementId: string, home?: string): string;
+/** `~/.halfcycle/engagements/<id>/env` — the owner-only per-engagement env file. */
+export declare function engagementEnvPath(engagementId: string, home?: string): string;
+/**
+ * The three variables the generated guard hook requires — **the bundle's one home
+ * for those names.** Anything in this package that needs to name them (the write
+ * set below, the installer's report in `bin.ts`) reads them from here rather than
+ * retyping them into a string.
+ *
+ * **This is the SECOND copy across the repo — a PRESENT constraint, not a permanent
+ * one (see #476).** The authoritative list is `packages/runner/src/config.ts`, the
+ * runner's sole `process.env` read site, and a shippable may not import the runner,
+ * which is wired as an external binary contract — so today the two cannot share a
+ * constant. **`packages/core` is the one package both shippables may import under
+ * INV-001**, so moving this constant there would remove the duplication rather than
+ * test around it; that is #476, deliberately not done mid-wave, because a
+ * shared-package change during an active wave is a class this repo has been burned
+ * by. Do not read the paragraph below as an argument that the duplication is fine.
+ *
+ * What binds the two copies meanwhile is **structural, not coincidental**:
+ * `readConfig()` is a conjunction over the exact required set, and AC1's assertion
+ * in `install-guard-config.test.ts` sits strictly downstream of it — it fires the
+ * REAL installed wrapper at a recording guard service and asserts the evaluation
+ * ARRIVES, through a wrapper that names no variable. So any element the bundle
+ * fails to write breaks the conjunction observably, and — the row that decides it —
+ * **the runner adding a fourth required variable is caught with the bundle knowing
+ * nothing about it**, which a name-to-name comparison cannot do: that would pass on
+ * two lists agreeing with each other and with nothing. The one gap is superset
+ * drift (the bundle writes a name the runner ignores), which is the harmless
+ * direction and is partly caught by the `.env.example` subset check.
+ *
+ * (Moved here from `install.ts` at T-09 with its reasoning intact: the write set it
+ * feeds moved out of the repository, and the names belong beside the file they are
+ * written into.)
+ */
+export declare const GUARD_ENV_KEYS: readonly ["GUARD_SERVICE_URL", "GUARD_SERVICE_TOKEN", "GUARD_ENGAGEMENT_ID"];
+/**
+ * The eight keys the engagement credential owns in the machine-level env file.
+ * These are the ONLY keys the reconcile adds or updates — see `reconcileEnvText`.
+ *
+ * `CONTROL_TELEMETRY_URL` JOINED THIS LIST AT T-10 (phase decision 13): without it
+ * no Connect engagement emitted telemetry, which is why `guard_results` was empty
+ * on prod. **It is written as `''` (never omitted) when the plane reports none** —
+ * `writeEngagementCredential` in `install.ts` keys this record on
+ * `EngagementEnvKey`, so a missing entry is a compile error rather than a silent
+ * gap, and `toCredential` there treats a blank value as absent. It is deliberately
+ * NOT in `CREDENTIAL_REQUIRED_KEYS` (`install.ts`) — that conjunction decides
+ * whether a checkout is treated as holding a credential at all, and putting an
+ * eighth, telemetry-only key into it would make every repository installed before
+ * this task (which has the other seven and not this one) read as credential-less
+ * on its next run and silently join a fresh one. See `DeviceCredential`'s docblock.
+ */
+export declare const ENGAGEMENT_ENV_KEYS: readonly ["HALFCYCLE_SERVICE_URL", "HALFCYCLE_MCP_URL", "HALFCYCLE_TOKEN", "HALFCYCLE_ENGAGEMENT_ID", "GUARD_SERVICE_URL", "GUARD_SERVICE_TOKEN", "GUARD_ENGAGEMENT_ID", "CONTROL_TELEMETRY_URL"];
+export type EngagementEnvKey = (typeof ENGAGEMENT_ENV_KEYS)[number];
+/**
+ * Parse `KEY=value` lines. **PARSES, NEVER SOURCES** — a credential store is not
+ * code, and `.` would execute whatever the file happens to contain. An optional
+ * leading `export ` is tolerated because the shells that source this file accept
+ * one, so a hand-edited store must read the same both ways, and one layer of
+ * matching quotes is stripped for the same reason (see the encoding note above).
+ *
+ * (The one exception is `guard-runner.sh`, which genuinely sources rather than
+ * parses: it must EXPORT the values into a child process, which is a thing only the
+ * shell can do. That file is generated by us, written `0600` outside every
+ * repository, and is Studio's adopted contract — a narrower surface than the
+ * developer-editable `.env.local` it replaces.)
+ */
+export declare function parseEnvText(raw: string): Record<string, string>;
+/**
+ * Reconcile our keys into an existing env-file body BY KEY.
+ *
+ * Every pre-existing line survives byte-for-byte: a `KEY=value` line whose key is
+ * one of ours is updated IN PLACE (so key order is preserved and no duplicate is
+ * introduced); one of ours that is absent is appended under the header; and any
+ * other line — comments, blanks, a key some other Halfcycle writer put here — is
+ * copied through untouched.
+ *
+ * **`export KEY=` counts as that key.** `parseEnvText` and the installer's legacy
+ * migration both tolerate the prefix, and this function did not — so an existing
+ * `export HALFCYCLE_TOKEN=old` was left alone and a bare `HALFCYCLE_TOKEN=new`
+ * appended below it. Last-assignment-wins meant nothing observably broke, which is
+ * why it survived: a superseded token simply stayed on disk, in the one feature
+ * whose whole subject is where a credential is allowed to be. The prefix is
+ * preserved on the rewritten line rather than normalised away, because "every
+ * pre-existing line survives" is the contract and `export` is the developer's.
+ *
+ * Values are written `shq`-quoted — see the encoding note above; the file is
+ * SOURCED by `guard-runner.sh`, so an unquoted value carrying a space executes
+ * its own remainder.
+ *
+ * **The non-destructiveness is not vestigial after the move out of the tree.** This
+ * path is Studio's too: `packages/mac-workspace-provider` writes
+ * `CONTROL_TELEMETRY_TOKEN` and `HALFCYCLE_GUARD_EVAL_LOG_DIR` into the same file for
+ * an engagement it manages. A whole-file overwrite here would silently delete them on
+ * any machine where both ever touch one engagement. Reconciling by key costs nothing
+ * and removes that whole class.
+ *
+ * **`CONTROL_TELEMETRY_URL` is deliberately NOT named alongside those two** — this
+ * said `CONTROL_TELEMETRY_*` (the whole family) until a T-10 follow-up correction.
+ * `CONTROL_TELEMETRY_URL` is one of OURS since T-10 (`ENGAGEMENT_ENV_KEYS` above), so
+ * it is reconciled the same as `HALFCYCLE_TOKEN` — updated in place by a Connect
+ * install, not preserved as a foreign writer's key. A Studio-written value for it is
+ * legitimately overwritten on the next Connect install; only `CONTROL_TELEMETRY_TOKEN`
+ * is still genuinely foreign.
+ */
+export declare function reconcileEnvText(existing: string | null, values: Record<string, string>, keys?: readonly string[]): string;
+/**
+ * Read this engagement's machine-level credential, or `null` when this machine
+ * holds none for it.
+ *
+ * A missing or unreadable file is `null`, never a throw: the commonest reason to
+ * have none is a fresh clone of an engaged repository, which is an ordinary state
+ * the caller reports in words rather than a fault.
+ */
+export declare function readEngagementEnv(engagementId: string, home?: string): Record<string, string> | null;
+/** What a write did, in the installer's report vocabulary. */
+export type EnvWriteOutcome = 'written' | 'skipped';
+/**
+ * Write this engagement's credential to the machine-level store, owner-only.
+ *
+ * Idempotent: identical content is `skipped`, so a re-install writes nothing here
+ * and the installer's *"a second install writes nothing but the bundle pin"*
+ * invariant survives the move out of the tree.
+ *
+ * The mode is re-applied on the skipped path too — a store that already existed at
+ * the wrong mode is exactly the case `writeFileSync`'s `mode` option cannot fix,
+ * and a re-install is the natural moment to repair it.
+ */
+export declare function writeEngagementEnv(engagementId: string, values: Record<string, string>, home?: string): EnvWriteOutcome;
+/**
+ * The shell function both generated consumers embed to find this file.
+ *
+ * **ONE authoring home for the resolution, two generated copies**, and that is the
+ * deliberate choice over a third installed script the other two would source: a
+ * shared script is one more file that can be missing, collide with a developer's
+ * own, or be lost by an export — and its absence would fail BOTH consumers at once,
+ * silently, which is the failure mode this whole feature is closing. Both copies
+ * come from this function, so there is nothing to keep in step by hand, and the
+ * path shape itself is composed from the same constants `engagementEnvPath()` uses.
+ *
+ * **Why `tr -d '\n'` before `sed`.** The pin is written pretty-printed
+ * (`JSON.stringify(pin, null, 2)`), so the key and its value are on one line today —
+ * but `sed` is line-oriented and a pin reformatted by any other tool would put them
+ * on two, at which point a line-wise match silently finds nothing and the developer
+ * gets "no credential" on a repository that has one. Flattening first makes the
+ * match independent of the file's line breaks. (This repo has paid twice for a
+ * pattern that wrapped across lines reading as absent.)
+ *
+ * **Why not `node`.** `mcp-headers.sh` is `sh` and not node precisely because a
+ * desktop-launched session's PATH typically has no version-manager `node`. Using it
+ * here would put that back.
+ *
+ * **IT SETS VARIABLES AND PRINTS NOTHING, and that is not a style choice.** The
+ * obvious form — print the path and let the caller take it with `$(…)` — puts the
+ * function in a SUBSHELL, so the `HALFCYCLE_ENV_PROBLEM` it sets on the failure
+ * path never reaches the caller. Measured: under `set -u` (which `mcp-headers.sh`
+ * runs with) the caller then dies on `HALFCYCLE_ENV_PROBLEM: unbound variable`
+ * instead of printing the reason it was carrying. So the function assigns
+ * `HALFCYCLE_ENV_FILE` / `HALFCYCLE_ENV_PROBLEM` / `HALFCYCLE_ENV_ENGAGEMENT` in
+ * the CURRENT shell and returns a status, and callers use `if halfcycle_env_file …`.
+ *
+ * `$HALFCYCLE_ENV_PROBLEM` names which step failed — `no-pin`, `no-id`, `no-home`,
+ * `no-credential` — so each caller says the true thing for its own surface instead
+ * of printing one sentence for four different situations.
+ */
+export declare function engagementResolutionShell(): string;
+//# sourceMappingURL=engagement-credential.d.ts.map

package/dist/engagement-credential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engagement-credential.d.ts","sourceRoot":"","sources":["../src/engagement-credential.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AAiBH;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAEtD,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7E;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,cAAc,8EAIjB,CAAC;AAEX;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB,mMAOtB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAmEpE;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,IAAI,GAAE,SAAS,MAAM,EAAwB,GAC5C,MAAM,CA8BR;AAMD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAM/B;AAED,8DAA8D;AAC9D,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,SAAS,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,IAAI,CAAC,EAAE,MAAM,GACZ,eAAe,CAkBjB;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CA0ClD"}

package/dist/identity.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Project identity — mint or read `.halfcycle/project.json`.
+ *
+ * A repository is not a machine. Two developers cloning one repository, or one
+ * developer with five git worktrees, are ONE project. The identity is committed
+ * (it arrives with the code) and carries the repository's root commit hash and
+ * remote — the most stable identifier a git repository has, identical across
+ * every clone, fork and worktree. The remote travels with it so a fork carrying
+ * an inherited identity can be detected rather than silently joining someone
+ * else's board. The per-device credential is NOT here, and since T-09 it is not
+ * anywhere in this repository — it lives at machine level, outside every checkout
+ * (`engagement-credential.ts`). See docs/features/client-install-surface.md
+ * (operator decision (au), whose committed-identity-versus-device-credential split
+ * survives; only the credential's location changed).
+ *
+ * INV-001: this file imports only Node builtins.
+ */
+/**
+ * The disambiguation note stamped into every `project.json` (W8-T-04, F-4).
+ *
+ * `projectId` sits in the same directory as `bundle.json`'s `engagementId`, and a
+ * cold session reading `.halfcycle/` top-down took `projectId` for the engagement
+ * id — it is a real uuid, so nothing about the VALUE flagged the mistake. The tool
+ * description already names the right file (`services/delivery/src/routes/mcp.ts`,
+ * #447), but that only reaches a session that calls the tool rather than reading
+ * the directory by hand, which is exactly what happened. This note is read
+ * whether or not the session ever calls a tool.
+ *
+ * It does NOT carry the engagement id itself — operator decision (au) keeps that
+ * out of the committed identity, and a comment in `create-engagement.ts` records
+ * that adding it here would re-open that decision. So the note can only say what
+ * this id is *not*, and where the right one lives; it cannot answer the question
+ * directly.
+ */
+export declare const PROJECT_IDENTITY_NOTE: string;
+/** The committed project identity: minted id plus the repo's root fingerprint. */
+export interface ProjectIdentity {
+    /** A minted, stable project id (uuid). Assigned once, at first install. */
+    projectId: string;
+    /**
+     * The repository's root (first) commit hash, or null when the tree is not a
+     * git repository / has no commits yet. Identical across every clone, fork and
+     * worktree; survives renames and remote changes.
+     */
+    rootCommit: string | null;
+    /** The `origin` remote URL, or null when there is no remote. */
+    remote: string | null;
+    /**
+     * A fixed disambiguation string, always `PROJECT_IDENTITY_NOTE` — see there.
+     * Present so a session reading this file directly (not through a tool
+     * description) sees the warning too. Reconciled on every install: if an
+     * install written before this field existed re-installs, the note is
+     * backfilled (`writeProjectIdentity` rewrites iff the serialized bytes
+     * differ) — `projectId`/`rootCommit`/`remote` are never touched by that.
+     */
+    note: string;
+}
+/** Read the repository's root commit hash (the first commit, reachable from HEAD). */
+export declare function readRootCommit(targetRepoRoot: string): string | null;
+/** Read the `origin` remote URL. */
+export declare function readRemote(targetRepoRoot: string): string | null;
+/**
+ * Return the existing committed identity if `.halfcycle/project.json` is present,
+ * otherwise mint a fresh one. Minting never overwrites the MINTED fields
+ * (`projectId`/`rootCommit`/`remote`): an existing identity's own values are
+ * returned verbatim so re-install and every clone share one project. `note` is
+ * the one exception — it is always stamped to the CURRENT `PROJECT_IDENTITY_NOTE`,
+ * on both the mint and the read path, so an install from before this field
+ * existed picks up the disambiguation text on its next install rather than
+ * staying silent forever.
+ */
+export declare function mintOrReadIdentity(targetRepoRoot: string): {
+    identity: ProjectIdentity;
+    minted: boolean;
+};
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,QAGF,CAAC;AAEjC,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gEAAgE;IAChE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;;;;OAOG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAgBD,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMpE;AAED,oCAAoC;AACpC,wBAAgB,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAmBzG"}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @halfcycle/bundle — public API.
+ *
+ * The bundle is the Halfcycle Method as an installable Claude Code plugin.
+ * It exports the install/wiring generator and the drift-check function.
+ * Method text (agents, commands, skills, scaffolding) is shipped as static
+ * files in the package; this module exports only the programmatic API.
+ *
+ * INV-001: imports only from @halfcycle/core, @halfcycle/events, or Node builtins.
+ */
+export { install, checkDrift, readBundlePin, ZONE_B_DIR } from './install.js';
+export type { InstallOptions, InstallResult, BundlePin, EngagementType, DeviceCredential } from './install.js';
+export { mintOrReadIdentity, readRootCommit, readRemote } from './identity.js';
+export type { ProjectIdentity } from './identity.js';
+export { createEngagement, CreateEngagementRefused } from './create-engagement.js';
+export type { CreatedEngagement } from './create-engagement.js';
+export { mintBoardEnterCode } from './mint-board-code.js';
+export type { MintedBoardCode } from './mint-board-code.js';
+export { mergeSettings } from './merge-settings.js';
+export type { ClaudeSettings, HookEntry, HookCommand } from './merge-settings.js';
+export { runBootstrapScan, scanLayers, mergeWithRecords, HALFCYCLE_STATE_FORMAT } from './scan.js';
+export type { HalfcycleStateFile, ScannedLayerEntry, ScannedLayerValue } from './scan.js';
+export * from './setup/index.js';
+export * from './build-record/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC9E,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,SAAS,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC/G,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC/E,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACnF,YAAY,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAyBhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnG,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAI1F,cAAc,kBAAkB,CAAC;AAKjC,cAAc,yBAAyB,CAAC"}