@immediately-run/sdk 0.26.0 → 0.27.0

package/README.md

@@ -65,6 +65,14 @@ single request:
 The installed npm package also ships `.d.ts` carrying the same JSDoc, so your
 editor/agent tooling can read the typed API inline without any network access.
 
+## Verify (the CI/deploy gate)
+
+`npm run verify` runs this repo's full CI gate in one command —
+`check:circular` → `test` → `build` → `api:check` (the additive-only API-stability
+check against the committed snapshot). Run it before pushing; it is the same set of
+checks CI enforces, so a local green equals a green CI. (Ways of working §4: the local
+verify gate must equal the deploy gate — one `npm run verify` per repo.)
+
 ## License
 
 [MIT](./LICENSE)

package/dist/index.cjs

@@ -38,6 +38,7 @@ __reExport(index_exports, require("./netFetch"), module.exports);
 __reExport(index_exports, require("./secrets"), module.exports);
 __reExport(index_exports, require("./llm"), module.exports);
 __reExport(index_exports, require("./diagnostics"), module.exports);
+__reExport(index_exports, require("./vcs"), module.exports);
 __reExport(index_exports, require("./onFsChange"), module.exports);
 __reExport(index_exports, require("./fs"), module.exports);
 __reExport(index_exports, require("./debug"), module.exports);
@@ -73,6 +74,7 @@ __reExport(index_exports, require("./sandboxTypes"), module.exports);
   ...require("./secrets"),
   ...require("./llm"),
   ...require("./diagnostics"),
+  ...require("./vcs"),
   ...require("./onFsChange"),
   ...require("./fs"),
   ...require("./debug"),

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":";;;;;;;;;;;;;;;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAIA,0BAAc,uCAJd;AAKA,0BAAc,oCALd;AAMA,0BAAc,gCANd;AAOA,0BAAc,oBAPd;AAQA,0BAAc,mBARd;AASA,0BAAc,oBATd;AAUA,0BAAc,4BAVd;AAWA,0BAAc,qBAXd;AAYA,0BAAc,yBAZd;AAaA,0BAAc,qBAbd;AAcA,0BAAc,qBAdd;AAeA,0BAAc,yBAfd;AAgBA,0BAAc,sBAhBd;AAiBA,0BAAc,kBAjBd;AAkBA,0BAAc,kBAlBd;AAmBA,0BAAc,uBAnBd;AAoBA,0BAAc,sBApBd;AAqBA,0BAAc,kBArBd;AAsBA,0BAAc,0BAtBd;AAuBA,0BAAc,yBAvBd;AAwBA,0BAAc,iBAxBd;AAyBA,0BAAc,oBAzBd;AA0BA,0BAAc,oBA1Bd;AA2BA,0BAAc,sBA3Bd;AA4BA,0BAAc,wBA5Bd;AA6BA,0BAAc,oBA7Bd;AA8BA,0BAAc,sBA9Bd;AA+BA,0BAAc,6BA/Bd;AAgCA,0BAAc,2BAhCd;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":";;;;;;;;;;;;;;;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAIA,0BAAc,uCAJd;AAKA,0BAAc,oCALd;AAMA,0BAAc,gCANd;AAOA,0BAAc,oBAPd;AAQA,0BAAc,mBARd;AASA,0BAAc,oBATd;AAUA,0BAAc,4BAVd;AAWA,0BAAc,qBAXd;AAYA,0BAAc,yBAZd;AAaA,0BAAc,qBAbd;AAcA,0BAAc,qBAdd;AAeA,0BAAc,yBAfd;AAgBA,0BAAc,sBAhBd;AAiBA,0BAAc,kBAjBd;AAkBA,0BAAc,kBAlBd;AAmBA,0BAAc,uBAnBd;AAoBA,0BAAc,sBApBd;AAqBA,0BAAc,kBArBd;AAsBA,0BAAc,0BAtBd;AAuBA,0BAAc,kBAvBd;AAwBA,0BAAc,yBAxBd;AAyBA,0BAAc,iBAzBd;AA0BA,0BAAc,oBA1Bd;AA2BA,0BAAc,oBA3Bd;AA4BA,0BAAc,sBA5Bd;AA6BA,0BAAc,wBA7Bd;AA8BA,0BAAc,oBA9Bd;AA+BA,0BAAc,sBA/Bd;AAgCA,0BAAc,6BAhCd;AAiCA,0BAAc,2BAjCd;","names":[]}

package/dist/index.d.cts

@@ -21,6 +21,7 @@ export { HostFetchInit, HostFetchResponse, HostFetchStreamEvent, HostFetchStream
 export { SecretError, SecretGrant, SecretHints, SecretQuery, SecretType, SecretView, getSecrets, onSecretsChange, requestAddSecret, requestSecret, revokeSecret, useSecrets } from './secrets.cjs';
 export { ChatDelta, ChatFeatures, ChatMessage, ChatProviderInfo, ChatRequest, ChatResult, ChatRole, ChatStopReason, ContentPart, ToolDef, chat, describeChat, onChatProviderChange, useChatProvider } from './llm.cjs';
 export { BuildError, ConsoleEntry, ConsoleLevel, Diagnostics, DiagnosticsProvenance, getDiagnostics, onDiagnosticsChange, useDiagnostics } from './diagnostics.cjs';
+export { VcsActionError, VcsBranch, VcsChange, VcsPR, VcsState, getVcsState, onVcsStateChange, refreshDiff, refreshPRs, resetWorkingTree, useVcsState } from './vcs.cjs';
 export { FsChange, getFsChange, onFsChange, useFsChange } from './onFsChange.cjs';
 export { DirEntry, FileStat, FsError, MountFs, SandboxFsPort, fsAvailable, mimeTypeFor, openAppFs, openFs, sandboxFs } from './fs.cjs';
 export { DebugLevel, debug, isDebugEnabled, log, useDebugEnabled } from './debug.cjs';

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export { HostFetchInit, HostFetchResponse, HostFetchStreamEvent, HostFetchStream
 export { SecretError, SecretGrant, SecretHints, SecretQuery, SecretType, SecretView, getSecrets, onSecretsChange, requestAddSecret, requestSecret, revokeSecret, useSecrets } from './secrets.js';
 export { ChatDelta, ChatFeatures, ChatMessage, ChatProviderInfo, ChatRequest, ChatResult, ChatRole, ChatStopReason, ContentPart, ToolDef, chat, describeChat, onChatProviderChange, useChatProvider } from './llm.js';
 export { BuildError, ConsoleEntry, ConsoleLevel, Diagnostics, DiagnosticsProvenance, getDiagnostics, onDiagnosticsChange, useDiagnostics } from './diagnostics.js';
+export { VcsActionError, VcsBranch, VcsChange, VcsPR, VcsState, getVcsState, onVcsStateChange, refreshDiff, refreshPRs, resetWorkingTree, useVcsState } from './vcs.js';
 export { FsChange, getFsChange, onFsChange, useFsChange } from './onFsChange.js';
 export { DirEntry, FileStat, FsError, MountFs, SandboxFsPort, fsAvailable, mimeTypeFor, openAppFs, openFs, sandboxFs } from './fs.js';
 export { DebugLevel, debug, isDebugEnabled, log, useDebugEnabled } from './debug.js';

package/dist/index.js

@@ -21,6 +21,7 @@ export * from "./netFetch";
 export * from "./secrets";
 export * from "./llm";
 export * from "./diagnostics";
+export * from "./vcs";
 export * from "./onFsChange";
 export * from "./fs";
 export * from "./debug";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":"AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":"AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}

package/dist/vcs.cjs

@@ -0,0 +1,74 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var vcs_exports = {};
+__export(vcs_exports, {
+  getVcsState: () => getVcsState,
+  onVcsStateChange: () => onVcsStateChange,
+  refreshDiff: () => refreshDiff,
+  refreshPRs: () => refreshPRs,
+  resetWorkingTree: () => resetWorkingTree,
+  useVcsState: () => useVcsState
+});
+module.exports = __toCommonJS(vcs_exports);
+var import_pushChannel = require("./pushChannel");
+var import_sandboxUtils = require("./sandboxUtils");
+const EMPTY = { changes: [], branch: null, prs: [], diffLoading: false };
+const isChangeArray = (v) => Array.isArray(v) && v.every(
+  (c) => !!c && typeof c.path === "string" && typeof c.status === "string"
+);
+const channel = (0, import_pushChannel.createPushChannel)({
+  pushType: "vcs-state",
+  requestType: "request-vcs-state",
+  initial: EMPTY,
+  parse: (msg) => {
+    if (!isChangeArray(msg.changes)) return void 0;
+    const branch = msg.branch && typeof msg.branch === "object" ? msg.branch : null;
+    const prs = Array.isArray(msg.prs) ? msg.prs : [];
+    return {
+      changes: msg.changes,
+      branch,
+      prs,
+      diffLoading: msg.diffLoading === true
+    };
+  }
+});
+const getVcsState = () => channel.get();
+const onVcsStateChange = (listener) => channel.onChange(listener);
+const useVcsState = () => channel.use();
+const vcsRequest = async (method, arg = {}) => {
+  const res = await (0, import_sandboxUtils.protocolRequest)("vcs", method, [arg]);
+  if (!res || res.ok !== true) {
+    const err = new Error(res?.message ?? `vcs ${method} failed`);
+    err.code = res?.code ?? "unknown";
+    throw err;
+  }
+};
+const refreshDiff = () => vcsRequest("refreshDiff");
+const refreshPRs = () => vcsRequest("refreshPRs");
+const resetWorkingTree = () => vcsRequest("reset", { confirm: true });
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getVcsState,
+  onVcsStateChange,
+  refreshDiff,
+  refreshPRs,
+  resetWorkingTree,
+  useVcsState
+});
+//# sourceMappingURL=vcs.cjs.map

package/dist/vcs.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/vcs.ts"],"sourcesContent":["// The `vcs:read` / `vcs:reset` source-control surface — app-facing wrappers\n// (UI_AS_APPS_SPEC §5.3 Recipe A read channel + §8.4 Recipe B actions;\n// migrate-sidebars-to-apps Phase 05; roadmap R3-52).\n//\n// A first-party contribute panel (the `panel.contribute` app, Phase 06) reads the\n// live source-control state the native `SourceControlPanel` shows — the working-tree\n// diff summary, the branch lineage, and the open-PR list — and can trigger a\n// refresh/reset. The host derives all of it from authenticated GitHub calls +\n// the COW layers; NONE of the underlying `DiffResult` / `FileSystem` / OAuth token\n// ever crosses the boundary (§8.10) — the wire carries only the plain-JSON\n// {@link VcsState} the host projects.\n//\n// Read side: a Recipe-A push channel, the same get/onChange/use trio as\n// `editorContext` / `diagnostics`. Inert until the host wires the channel\n// (site-main `channelBridge`); an app without `vcs:read` simply sees the empty\n// initial. Action side: `protocol-vcs` requests gated host-side — `refreshDiff` /\n// `refreshPRs` by `vcs:read`, `resetWorkingTree` by first-party-only `vcs:reset`.\nimport { createPushChannel } from './pushChannel';\nimport { protocolRequest } from './sandboxUtils';\n\n/** One changed path in the working tree (vs. the loaded ref). `status` mirrors the\n *  host `DiffResult` change kinds; `path` is repo-relative. Contents are NOT\n *  carried — the native panel showed path + status, and a per-file content diff is\n *  a deferred follow-up (plan step 6). */\nexport interface VcsChange {\n  path: string;\n  status: 'created' | 'modified' | 'deleted';\n}\n\n/** The branch the working tree sits on and the upstream it diverged from\n *  (host `BranchInfo`, §15.1). `null` until the user is on a immediately.run-created\n *  branch. `upstreamPushable` is `null` while push access is still being probed. */\nexport interface VcsBranch {\n  name: string;\n  parentRepo: string;\n  parentRef: string;\n  parentCommitSha: string;\n  upstreamPushable: boolean | null;\n}\n\n/** One pull request open from the current branch (host `BranchPR`). */\nexport interface VcsPR {\n  number: number;\n  url: string;\n  title: string;\n  state: 'open' | 'closed' | 'merged';\n  draft: boolean;\n}\n\n/** The whole source-control snapshot the host projects to a `vcs:read` frame.\n *  Plain JSON — never a `DiffResult` / `FileSystem` / `Journal`. */\nexport interface VcsState {\n  changes: VcsChange[];\n  branch: VcsBranch | null;\n  prs: VcsPR[];\n  /** True while the host is recomputing the diff — the panel shows a spinner\n   *  without a separate request (plan gotcha). */\n  diffLoading: boolean;\n}\n\n/** Value before the host answers — also the value when the app may not read the\n *  channel (no `vcs:read`): an empty, branch-less snapshot. */\nconst EMPTY: VcsState = { changes: [], branch: null, prs: [], diffLoading: false };\n\nconst isChangeArray = (v: unknown): v is VcsChange[] =>\n  Array.isArray(v) &&\n  v.every(\n    (c) =>\n      !!c &&\n      typeof (c as VcsChange).path === 'string' &&\n      typeof (c as VcsChange).status === 'string',\n  );\n\nconst channel = createPushChannel<VcsState>({\n  pushType: 'vcs-state',\n  requestType: 'request-vcs-state',\n  initial: EMPTY,\n  parse: (msg) => {\n    // Require a well-formed `changes` array; tolerate an absent branch/prs. A\n    // malformed push is ignored (returns undefined) so the last good state stands.\n    if (!isChangeArray(msg.changes)) return undefined;\n    const branch =\n      msg.branch && typeof msg.branch === 'object' ? (msg.branch as VcsBranch) : null;\n    const prs = Array.isArray(msg.prs) ? (msg.prs as VcsPR[]) : [];\n    return {\n      changes: msg.changes,\n      branch,\n      prs,\n      diffLoading: msg.diffLoading === true,\n    };\n  },\n});\n\n/** One-off read of the current source-control state. Returns the empty snapshot\n *  until the host answers (or if the app lacks `vcs:read`). Use\n *  {@link onVcsStateChange} / {@link useVcsState} to react to live updates. */\nexport const getVcsState = (): VcsState => channel.get();\n\n/** Subscribe to source-control changes. Invoked immediately with the current\n *  value, then on every host push (diff refresh, PR poll, branch change). Returns\n *  an unsubscribe. */\nexport const onVcsStateChange = (listener: (state: VcsState) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook: the current source-control state, re-rendering on every change. */\nexport const useVcsState = (): VcsState => channel.use();\n\n// ---------------------------------------------------------------------------\n// Actions (Recipe B, §8.4). The app NAMES an intent and the HOST performs it —\n// the COW/journal stays in the kernel (§2/§4). `refreshDiff`/`refreshPRs` only\n// cause a host-side recompute + a fresh push (gated `vcs:read`, no new authority);\n// `resetWorkingTree` DISCARDS the user's unsaved work, gated by the first-party-only\n// `vcs:reset` — a fork can never hold it. The arm-then-confirm UX stays in the app;\n// the authority is gated host-side (§8.9), and the host requires `confirm:true` as\n// belt-and-braces (T22).\n// ---------------------------------------------------------------------------\n\n/** An error from a `vcs` action, carrying a machine-readable `.code`. */\nexport interface VcsActionError extends Error {\n  code:\n    | 'forbidden' // the frame lacks the required capability (`vcs:read` / `vcs:reset`)\n    | 'invalid-params' // reset called without `confirm: true`\n    | 'no-target' // there is no host contribute session (not in edit mode)\n    | 'unknown';\n}\n\ntype VcsResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\nconst vcsRequest = async (method: string, arg: Record<string, unknown> = {}): Promise<void> => {\n  const res = (await protocolRequest('vcs', method, [arg])) as VcsResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `vcs ${method} failed`) as VcsActionError;\n    err.code = (res?.code as VcsActionError['code']) ?? 'unknown';\n    throw err;\n  }\n};\n\n/** Ask the host to recompute the working-tree diff and push a fresh {@link VcsState}.\n *  Gated `vcs:read`. Rejects with a {@link VcsActionError} (`.code`). */\nexport const refreshDiff = (): Promise<void> => vcsRequest('refreshDiff');\n\n/** Ask the host to re-poll the open PRs and push a fresh {@link VcsState}. Gated\n *  `vcs:read`. Rejects with a {@link VcsActionError} (`.code`). */\nexport const refreshPRs = (): Promise<void> => vcsRequest('refreshPRs');\n\n/** Ask the host to DISCARD the working tree (COW writable wipe + journal clear) —\n *  irreversible. First-party-only (`vcs:reset`); a fork/preview is refused at the\n *  gate. Requires `confirm: true` (host belt-and-braces). Rejects with a\n *  {@link VcsActionError} (`.code`). */\nexport const resetWorkingTree = (): Promise<void> => vcsRequest('reset', { confirm: true });\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAiBA,yBAAkC;AAClC,0BAAgC;AA4ChC,MAAM,QAAkB,EAAE,SAAS,CAAC,GAAG,QAAQ,MAAM,KAAK,CAAC,GAAG,aAAa,MAAM;AAEjF,MAAM,gBAAgB,CAAC,MACrB,MAAM,QAAQ,CAAC,KACf,EAAE;AAAA,EACA,CAAC,MACC,CAAC,CAAC,KACF,OAAQ,EAAgB,SAAS,YACjC,OAAQ,EAAgB,WAAW;AACvC;AAEF,MAAM,cAAU,sCAA4B;AAAA,EAC1C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAQ;AAGd,QAAI,CAAC,cAAc,IAAI,OAAO,EAAG,QAAO;AACxC,UAAM,SACJ,IAAI,UAAU,OAAO,IAAI,WAAW,WAAY,IAAI,SAAuB;AAC7E,UAAM,MAAM,MAAM,QAAQ,IAAI,GAAG,IAAK,IAAI,MAAkB,CAAC;AAC7D,WAAO;AAAA,MACL,SAAS,IAAI;AAAA,MACb;AAAA,MACA;AAAA,MACA,aAAa,IAAI,gBAAgB;AAAA,IACnC;AAAA,EACF;AACF,CAAC;AAKM,MAAM,cAAc,MAAgB,QAAQ,IAAI;AAKhD,MAAM,mBAAmB,CAAC,aAC/B,QAAQ,SAAS,QAAQ;AAGpB,MAAM,cAAc,MAAgB,QAAQ,IAAI;AAyBvD,MAAM,aAAa,OAAO,QAAgB,MAA+B,CAAC,MAAqB;AAC7F,QAAM,MAAO,UAAM,qCAAgB,OAAO,QAAQ,CAAC,GAAG,CAAC;AACvD,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,OAAO,MAAM,SAAS;AAC5D,QAAI,OAAQ,KAAK,QAAmC;AACpD,UAAM;AAAA,EACR;AACF;AAIO,MAAM,cAAc,MAAqB,WAAW,aAAa;AAIjE,MAAM,aAAa,MAAqB,WAAW,YAAY;AAM/D,MAAM,mBAAmB,MAAqB,WAAW,SAAS,EAAE,SAAS,KAAK,CAAC;","names":[]}

package/dist/vcs.d.cts

@@ -0,0 +1,63 @@
+/** One changed path in the working tree (vs. the loaded ref). `status` mirrors the
+ *  host `DiffResult` change kinds; `path` is repo-relative. Contents are NOT
+ *  carried — the native panel showed path + status, and a per-file content diff is
+ *  a deferred follow-up (plan step 6). */
+interface VcsChange {
+    path: string;
+    status: 'created' | 'modified' | 'deleted';
+}
+/** The branch the working tree sits on and the upstream it diverged from
+ *  (host `BranchInfo`, §15.1). `null` until the user is on a immediately.run-created
+ *  branch. `upstreamPushable` is `null` while push access is still being probed. */
+interface VcsBranch {
+    name: string;
+    parentRepo: string;
+    parentRef: string;
+    parentCommitSha: string;
+    upstreamPushable: boolean | null;
+}
+/** One pull request open from the current branch (host `BranchPR`). */
+interface VcsPR {
+    number: number;
+    url: string;
+    title: string;
+    state: 'open' | 'closed' | 'merged';
+    draft: boolean;
+}
+/** The whole source-control snapshot the host projects to a `vcs:read` frame.
+ *  Plain JSON — never a `DiffResult` / `FileSystem` / `Journal`. */
+interface VcsState {
+    changes: VcsChange[];
+    branch: VcsBranch | null;
+    prs: VcsPR[];
+    /** True while the host is recomputing the diff — the panel shows a spinner
+     *  without a separate request (plan gotcha). */
+    diffLoading: boolean;
+}
+/** One-off read of the current source-control state. Returns the empty snapshot
+ *  until the host answers (or if the app lacks `vcs:read`). Use
+ *  {@link onVcsStateChange} / {@link useVcsState} to react to live updates. */
+declare const getVcsState: () => VcsState;
+/** Subscribe to source-control changes. Invoked immediately with the current
+ *  value, then on every host push (diff refresh, PR poll, branch change). Returns
+ *  an unsubscribe. */
+declare const onVcsStateChange: (listener: (state: VcsState) => void) => (() => void);
+/** React hook: the current source-control state, re-rendering on every change. */
+declare const useVcsState: () => VcsState;
+/** An error from a `vcs` action, carrying a machine-readable `.code`. */
+interface VcsActionError extends Error {
+    code: 'forbidden' | 'invalid-params' | 'no-target' | 'unknown';
+}
+/** Ask the host to recompute the working-tree diff and push a fresh {@link VcsState}.
+ *  Gated `vcs:read`. Rejects with a {@link VcsActionError} (`.code`). */
+declare const refreshDiff: () => Promise<void>;
+/** Ask the host to re-poll the open PRs and push a fresh {@link VcsState}. Gated
+ *  `vcs:read`. Rejects with a {@link VcsActionError} (`.code`). */
+declare const refreshPRs: () => Promise<void>;
+/** Ask the host to DISCARD the working tree (COW writable wipe + journal clear) —
+ *  irreversible. First-party-only (`vcs:reset`); a fork/preview is refused at the
+ *  gate. Requires `confirm: true` (host belt-and-braces). Rejects with a
+ *  {@link VcsActionError} (`.code`). */
+declare const resetWorkingTree: () => Promise<void>;
+
+export { type VcsActionError, type VcsBranch, type VcsChange, type VcsPR, type VcsState, getVcsState, onVcsStateChange, refreshDiff, refreshPRs, resetWorkingTree, useVcsState };

package/dist/vcs.d.ts

@@ -0,0 +1,63 @@
+/** One changed path in the working tree (vs. the loaded ref). `status` mirrors the
+ *  host `DiffResult` change kinds; `path` is repo-relative. Contents are NOT
+ *  carried — the native panel showed path + status, and a per-file content diff is
+ *  a deferred follow-up (plan step 6). */
+interface VcsChange {
+    path: string;
+    status: 'created' | 'modified' | 'deleted';
+}
+/** The branch the working tree sits on and the upstream it diverged from
+ *  (host `BranchInfo`, §15.1). `null` until the user is on a immediately.run-created
+ *  branch. `upstreamPushable` is `null` while push access is still being probed. */
+interface VcsBranch {
+    name: string;
+    parentRepo: string;
+    parentRef: string;
+    parentCommitSha: string;
+    upstreamPushable: boolean | null;
+}
+/** One pull request open from the current branch (host `BranchPR`). */
+interface VcsPR {
+    number: number;
+    url: string;
+    title: string;
+    state: 'open' | 'closed' | 'merged';
+    draft: boolean;
+}
+/** The whole source-control snapshot the host projects to a `vcs:read` frame.
+ *  Plain JSON — never a `DiffResult` / `FileSystem` / `Journal`. */
+interface VcsState {
+    changes: VcsChange[];
+    branch: VcsBranch | null;
+    prs: VcsPR[];
+    /** True while the host is recomputing the diff — the panel shows a spinner
+     *  without a separate request (plan gotcha). */
+    diffLoading: boolean;
+}
+/** One-off read of the current source-control state. Returns the empty snapshot
+ *  until the host answers (or if the app lacks `vcs:read`). Use
+ *  {@link onVcsStateChange} / {@link useVcsState} to react to live updates. */
+declare const getVcsState: () => VcsState;
+/** Subscribe to source-control changes. Invoked immediately with the current
+ *  value, then on every host push (diff refresh, PR poll, branch change). Returns
+ *  an unsubscribe. */
+declare const onVcsStateChange: (listener: (state: VcsState) => void) => (() => void);
+/** React hook: the current source-control state, re-rendering on every change. */
+declare const useVcsState: () => VcsState;
+/** An error from a `vcs` action, carrying a machine-readable `.code`. */
+interface VcsActionError extends Error {
+    code: 'forbidden' | 'invalid-params' | 'no-target' | 'unknown';
+}
+/** Ask the host to recompute the working-tree diff and push a fresh {@link VcsState}.
+ *  Gated `vcs:read`. Rejects with a {@link VcsActionError} (`.code`). */
+declare const refreshDiff: () => Promise<void>;
+/** Ask the host to re-poll the open PRs and push a fresh {@link VcsState}. Gated
+ *  `vcs:read`. Rejects with a {@link VcsActionError} (`.code`). */
+declare const refreshPRs: () => Promise<void>;
+/** Ask the host to DISCARD the working tree (COW writable wipe + journal clear) —
+ *  irreversible. First-party-only (`vcs:reset`); a fork/preview is refused at the
+ *  gate. Requires `confirm: true` (host belt-and-braces). Rejects with a
+ *  {@link VcsActionError} (`.code`). */
+declare const resetWorkingTree: () => Promise<void>;
+
+export { type VcsActionError, type VcsBranch, type VcsChange, type VcsPR, type VcsState, getVcsState, onVcsStateChange, refreshDiff, refreshPRs, resetWorkingTree, useVcsState };

package/dist/vcs.js

@@ -0,0 +1,45 @@
+import { createPushChannel } from "./pushChannel";
+import { protocolRequest } from "./sandboxUtils";
+const EMPTY = { changes: [], branch: null, prs: [], diffLoading: false };
+const isChangeArray = (v) => Array.isArray(v) && v.every(
+  (c) => !!c && typeof c.path === "string" && typeof c.status === "string"
+);
+const channel = createPushChannel({
+  pushType: "vcs-state",
+  requestType: "request-vcs-state",
+  initial: EMPTY,
+  parse: (msg) => {
+    if (!isChangeArray(msg.changes)) return void 0;
+    const branch = msg.branch && typeof msg.branch === "object" ? msg.branch : null;
+    const prs = Array.isArray(msg.prs) ? msg.prs : [];
+    return {
+      changes: msg.changes,
+      branch,
+      prs,
+      diffLoading: msg.diffLoading === true
+    };
+  }
+});
+const getVcsState = () => channel.get();
+const onVcsStateChange = (listener) => channel.onChange(listener);
+const useVcsState = () => channel.use();
+const vcsRequest = async (method, arg = {}) => {
+  const res = await protocolRequest("vcs", method, [arg]);
+  if (!res || res.ok !== true) {
+    const err = new Error(res?.message ?? `vcs ${method} failed`);
+    err.code = res?.code ?? "unknown";
+    throw err;
+  }
+};
+const refreshDiff = () => vcsRequest("refreshDiff");
+const refreshPRs = () => vcsRequest("refreshPRs");
+const resetWorkingTree = () => vcsRequest("reset", { confirm: true });
+export {
+  getVcsState,
+  onVcsStateChange,
+  refreshDiff,
+  refreshPRs,
+  resetWorkingTree,
+  useVcsState
+};
+//# sourceMappingURL=vcs.js.map

package/dist/vcs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/vcs.ts"],"sourcesContent":["// The `vcs:read` / `vcs:reset` source-control surface — app-facing wrappers\n// (UI_AS_APPS_SPEC §5.3 Recipe A read channel + §8.4 Recipe B actions;\n// migrate-sidebars-to-apps Phase 05; roadmap R3-52).\n//\n// A first-party contribute panel (the `panel.contribute` app, Phase 06) reads the\n// live source-control state the native `SourceControlPanel` shows — the working-tree\n// diff summary, the branch lineage, and the open-PR list — and can trigger a\n// refresh/reset. The host derives all of it from authenticated GitHub calls +\n// the COW layers; NONE of the underlying `DiffResult` / `FileSystem` / OAuth token\n// ever crosses the boundary (§8.10) — the wire carries only the plain-JSON\n// {@link VcsState} the host projects.\n//\n// Read side: a Recipe-A push channel, the same get/onChange/use trio as\n// `editorContext` / `diagnostics`. Inert until the host wires the channel\n// (site-main `channelBridge`); an app without `vcs:read` simply sees the empty\n// initial. Action side: `protocol-vcs` requests gated host-side — `refreshDiff` /\n// `refreshPRs` by `vcs:read`, `resetWorkingTree` by first-party-only `vcs:reset`.\nimport { createPushChannel } from './pushChannel';\nimport { protocolRequest } from './sandboxUtils';\n\n/** One changed path in the working tree (vs. the loaded ref). `status` mirrors the\n *  host `DiffResult` change kinds; `path` is repo-relative. Contents are NOT\n *  carried — the native panel showed path + status, and a per-file content diff is\n *  a deferred follow-up (plan step 6). */\nexport interface VcsChange {\n  path: string;\n  status: 'created' | 'modified' | 'deleted';\n}\n\n/** The branch the working tree sits on and the upstream it diverged from\n *  (host `BranchInfo`, §15.1). `null` until the user is on a immediately.run-created\n *  branch. `upstreamPushable` is `null` while push access is still being probed. */\nexport interface VcsBranch {\n  name: string;\n  parentRepo: string;\n  parentRef: string;\n  parentCommitSha: string;\n  upstreamPushable: boolean | null;\n}\n\n/** One pull request open from the current branch (host `BranchPR`). */\nexport interface VcsPR {\n  number: number;\n  url: string;\n  title: string;\n  state: 'open' | 'closed' | 'merged';\n  draft: boolean;\n}\n\n/** The whole source-control snapshot the host projects to a `vcs:read` frame.\n *  Plain JSON — never a `DiffResult` / `FileSystem` / `Journal`. */\nexport interface VcsState {\n  changes: VcsChange[];\n  branch: VcsBranch | null;\n  prs: VcsPR[];\n  /** True while the host is recomputing the diff — the panel shows a spinner\n   *  without a separate request (plan gotcha). */\n  diffLoading: boolean;\n}\n\n/** Value before the host answers — also the value when the app may not read the\n *  channel (no `vcs:read`): an empty, branch-less snapshot. */\nconst EMPTY: VcsState = { changes: [], branch: null, prs: [], diffLoading: false };\n\nconst isChangeArray = (v: unknown): v is VcsChange[] =>\n  Array.isArray(v) &&\n  v.every(\n    (c) =>\n      !!c &&\n      typeof (c as VcsChange).path === 'string' &&\n      typeof (c as VcsChange).status === 'string',\n  );\n\nconst channel = createPushChannel<VcsState>({\n  pushType: 'vcs-state',\n  requestType: 'request-vcs-state',\n  initial: EMPTY,\n  parse: (msg) => {\n    // Require a well-formed `changes` array; tolerate an absent branch/prs. A\n    // malformed push is ignored (returns undefined) so the last good state stands.\n    if (!isChangeArray(msg.changes)) return undefined;\n    const branch =\n      msg.branch && typeof msg.branch === 'object' ? (msg.branch as VcsBranch) : null;\n    const prs = Array.isArray(msg.prs) ? (msg.prs as VcsPR[]) : [];\n    return {\n      changes: msg.changes,\n      branch,\n      prs,\n      diffLoading: msg.diffLoading === true,\n    };\n  },\n});\n\n/** One-off read of the current source-control state. Returns the empty snapshot\n *  until the host answers (or if the app lacks `vcs:read`). Use\n *  {@link onVcsStateChange} / {@link useVcsState} to react to live updates. */\nexport const getVcsState = (): VcsState => channel.get();\n\n/** Subscribe to source-control changes. Invoked immediately with the current\n *  value, then on every host push (diff refresh, PR poll, branch change). Returns\n *  an unsubscribe. */\nexport const onVcsStateChange = (listener: (state: VcsState) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook: the current source-control state, re-rendering on every change. */\nexport const useVcsState = (): VcsState => channel.use();\n\n// ---------------------------------------------------------------------------\n// Actions (Recipe B, §8.4). The app NAMES an intent and the HOST performs it —\n// the COW/journal stays in the kernel (§2/§4). `refreshDiff`/`refreshPRs` only\n// cause a host-side recompute + a fresh push (gated `vcs:read`, no new authority);\n// `resetWorkingTree` DISCARDS the user's unsaved work, gated by the first-party-only\n// `vcs:reset` — a fork can never hold it. The arm-then-confirm UX stays in the app;\n// the authority is gated host-side (§8.9), and the host requires `confirm:true` as\n// belt-and-braces (T22).\n// ---------------------------------------------------------------------------\n\n/** An error from a `vcs` action, carrying a machine-readable `.code`. */\nexport interface VcsActionError extends Error {\n  code:\n    | 'forbidden' // the frame lacks the required capability (`vcs:read` / `vcs:reset`)\n    | 'invalid-params' // reset called without `confirm: true`\n    | 'no-target' // there is no host contribute session (not in edit mode)\n    | 'unknown';\n}\n\ntype VcsResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\nconst vcsRequest = async (method: string, arg: Record<string, unknown> = {}): Promise<void> => {\n  const res = (await protocolRequest('vcs', method, [arg])) as VcsResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `vcs ${method} failed`) as VcsActionError;\n    err.code = (res?.code as VcsActionError['code']) ?? 'unknown';\n    throw err;\n  }\n};\n\n/** Ask the host to recompute the working-tree diff and push a fresh {@link VcsState}.\n *  Gated `vcs:read`. Rejects with a {@link VcsActionError} (`.code`). */\nexport const refreshDiff = (): Promise<void> => vcsRequest('refreshDiff');\n\n/** Ask the host to re-poll the open PRs and push a fresh {@link VcsState}. Gated\n *  `vcs:read`. Rejects with a {@link VcsActionError} (`.code`). */\nexport const refreshPRs = (): Promise<void> => vcsRequest('refreshPRs');\n\n/** Ask the host to DISCARD the working tree (COW writable wipe + journal clear) —\n *  irreversible. First-party-only (`vcs:reset`); a fork/preview is refused at the\n *  gate. Requires `confirm: true` (host belt-and-braces). Rejects with a\n *  {@link VcsActionError} (`.code`). */\nexport const resetWorkingTree = (): Promise<void> => vcsRequest('reset', { confirm: true });\n"],"mappings":"AAiBA,SAAS,yBAAyB;AAClC,SAAS,uBAAuB;AA4ChC,MAAM,QAAkB,EAAE,SAAS,CAAC,GAAG,QAAQ,MAAM,KAAK,CAAC,GAAG,aAAa,MAAM;AAEjF,MAAM,gBAAgB,CAAC,MACrB,MAAM,QAAQ,CAAC,KACf,EAAE;AAAA,EACA,CAAC,MACC,CAAC,CAAC,KACF,OAAQ,EAAgB,SAAS,YACjC,OAAQ,EAAgB,WAAW;AACvC;AAEF,MAAM,UAAU,kBAA4B;AAAA,EAC1C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAQ;AAGd,QAAI,CAAC,cAAc,IAAI,OAAO,EAAG,QAAO;AACxC,UAAM,SACJ,IAAI,UAAU,OAAO,IAAI,WAAW,WAAY,IAAI,SAAuB;AAC7E,UAAM,MAAM,MAAM,QAAQ,IAAI,GAAG,IAAK,IAAI,MAAkB,CAAC;AAC7D,WAAO;AAAA,MACL,SAAS,IAAI;AAAA,MACb;AAAA,MACA;AAAA,MACA,aAAa,IAAI,gBAAgB;AAAA,IACnC;AAAA,EACF;AACF,CAAC;AAKM,MAAM,cAAc,MAAgB,QAAQ,IAAI;AAKhD,MAAM,mBAAmB,CAAC,aAC/B,QAAQ,SAAS,QAAQ;AAGpB,MAAM,cAAc,MAAgB,QAAQ,IAAI;AAyBvD,MAAM,aAAa,OAAO,QAAgB,MAA+B,CAAC,MAAqB;AAC7F,QAAM,MAAO,MAAM,gBAAgB,OAAO,QAAQ,CAAC,GAAG,CAAC;AACvD,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,OAAO,MAAM,SAAS;AAC5D,QAAI,OAAQ,KAAK,QAAmC;AACpD,UAAM;AAAA,EACR;AACF;AAIO,MAAM,cAAc,MAAqB,WAAW,aAAa;AAIjE,MAAM,aAAa,MAAqB,WAAW,YAAY;AAM/D,MAAM,mBAAmB,MAAqB,WAAW,SAAS,EAAE,SAAS,KAAK,CAAC;","names":[]}

package/dist/version.cjs

@@ -21,7 +21,7 @@ __export(version_exports, {
   SDK_VERSION: () => SDK_VERSION
 });
 module.exports = __toCommonJS(version_exports);
-const SDK_VERSION = "0.26.0";
+const SDK_VERSION = "0.27.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SDK_VERSION

package/dist/version.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.26.0';\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAIO,MAAM,cAAc;","names":[]}
+{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.27.0';\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAIO,MAAM,cAAc;","names":[]}

package/dist/version.d.cts

@@ -1,4 +1,4 @@
 /** This SDK's package version, baked from package.json at build (SP2-6). */
-declare const SDK_VERSION = "0.26.0";
+declare const SDK_VERSION = "0.27.0";
 
 export { SDK_VERSION };

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 /** This SDK's package version, baked from package.json at build (SP2-6). */
-declare const SDK_VERSION = "0.26.0";
+declare const SDK_VERSION = "0.27.0";
 
 export { SDK_VERSION };

package/dist/version.js

@@ -1,4 +1,4 @@
-const SDK_VERSION = "0.26.0";
+const SDK_VERSION = "0.27.0";
 export {
   SDK_VERSION
 };

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.26.0';\n"],"mappings":"AAIO,MAAM,cAAc;","names":[]}
+{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.27.0';\n"],"mappings":"AAIO,MAAM,cAAc;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/sdk",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Runtime SDK for code executing inside an immediately.run sandbox.",
   "license": "MIT",
   "repository": "github:immediately-run/immediately-run-sdk",
@@ -32,6 +32,7 @@
     "check:circular": "node scripts/check-circular.mjs",
     "api:check": "node scripts/check-api-stability.mjs",
     "api:update": "node scripts/check-api-stability.mjs --update",
+    "verify": "npm run check:circular && npm test && npm run build && npm run api:check",
     "docs": "typedoc --json docs/api.json && node scripts/gen-llms.mjs",
     "prepublishOnly": "npm run check:circular && npm run build && npm run api:check"
   },