@immediately-run/sdk 0.46.0 → 0.48.0

package/dist/vcs.cjs.map

@@ -1 +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';\nimport { PROTOCOL_VCS, REQUEST_VCS_STATE, VCS_STATE } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\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(SCHEMES[PROTOCOL_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;AAChC,sBAA2D;AAC3D,6BAAwB;AA4CxB,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,+BAAQ,4BAAY,GAAG,QAAQ,CAAC,GAAG,CAAC;AACvE,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":[]}
+{"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';\nimport { PROTOCOL_VCS, REQUEST_VCS_STATE, VCS_STATE } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\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((c) => !!c && typeof (c as VcsChange).path === 'string' && typeof (c as VcsChange).status === 'string');\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 = 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) => 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 = { ok: true; data: unknown } | { ok: false; code: string; message: string };\n\nconst vcsRequest = async (method: string, arg: Record<string, unknown> = {}): Promise<void> => {\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_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;AAChC,sBAA2D;AAC3D,6BAAwB;AA4CxB,MAAM,QAAkB,EAAE,SAAS,CAAC,GAAG,QAAQ,MAAM,KAAK,CAAC,GAAG,aAAa,MAAM;AAEjF,MAAM,gBAAgB,CAAC,MACrB,MAAM,QAAQ,CAAC,KACf,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,OAAQ,EAAgB,SAAS,YAAY,OAAQ,EAAgB,WAAW,QAAQ;AAEhH,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,SAAS,IAAI,UAAU,OAAO,IAAI,WAAW,WAAY,IAAI,SAAuB;AAC1F,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,aAAsD,QAAQ,SAAS,QAAQ;AAGzG,MAAM,cAAc,MAAgB,QAAQ,IAAI;AAuBvD,MAAM,aAAa,OAAO,QAAgB,MAA+B,CAAC,MAAqB;AAC7F,QAAM,MAAO,UAAM,qCAAgB,+BAAQ,4BAAY,GAAG,QAAQ,CAAC,GAAG,CAAC;AACvE,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.js

@@ -4,9 +4,7 @@ import { protocolRequest } from "./sandboxUtils";
 import { PROTOCOL_VCS, REQUEST_VCS_STATE, VCS_STATE } from "./generated/protocol";
 import { SCHEMES } from "./protocolSchemes";
 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 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,

package/dist/vcs.js.map

@@ -1 +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';\nimport { PROTOCOL_VCS, REQUEST_VCS_STATE, VCS_STATE } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\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(SCHEMES[PROTOCOL_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;AAChC,SAAS,cAAc,mBAAmB,iBAAiB;AAC3D,SAAS,eAAe;AA4CxB,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,QAAQ,YAAY,GAAG,QAAQ,CAAC,GAAG,CAAC;AACvE,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":[]}
+{"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';\nimport { PROTOCOL_VCS, REQUEST_VCS_STATE, VCS_STATE } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\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((c) => !!c && typeof (c as VcsChange).path === 'string' && typeof (c as VcsChange).status === 'string');\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 = 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) => 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 = { ok: true; data: unknown } | { ok: false; code: string; message: string };\n\nconst vcsRequest = async (method: string, arg: Record<string, unknown> = {}): Promise<void> => {\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_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;AAChC,SAAS,cAAc,mBAAmB,iBAAiB;AAC3D,SAAS,eAAe;AA4CxB,MAAM,QAAkB,EAAE,SAAS,CAAC,GAAG,QAAQ,MAAM,KAAK,CAAC,GAAG,aAAa,MAAM;AAEjF,MAAM,gBAAgB,CAAC,MACrB,MAAM,QAAQ,CAAC,KACf,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,OAAQ,EAAgB,SAAS,YAAY,OAAQ,EAAgB,WAAW,QAAQ;AAEhH,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,SAAS,IAAI,UAAU,OAAO,IAAI,WAAW,WAAY,IAAI,SAAuB;AAC1F,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,aAAsD,QAAQ,SAAS,QAAQ;AAGzG,MAAM,cAAc,MAAgB,QAAQ,IAAI;AAuBvD,MAAM,aAAa,OAAO,QAAgB,MAA+B,CAAC,MAAqB;AAC7F,QAAM,MAAO,MAAM,gBAAgB,QAAQ,YAAY,GAAG,QAAQ,CAAC,GAAG,CAAC;AACvE,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.46.0";
+const SDK_VERSION = "0.48.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.46.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.48.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.46.0";
+declare const SDK_VERSION = "0.48.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.46.0";
+declare const SDK_VERSION = "0.48.0";
 
 export { SDK_VERSION };

package/dist/version.js

@@ -1,5 +1,5 @@
 import "./chunk-VHAA22YE.js";
-const SDK_VERSION = "0.46.0";
+const SDK_VERSION = "0.48.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.46.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.48.0';\n"],"mappings":";AAIO,MAAM,cAAc;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/sdk",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "description": "Runtime SDK for code executing inside an immediately.run sandbox.",
   "license": "MIT",
   "repository": "github:immediately-run/immediately-run-sdk",
@@ -29,12 +29,14 @@
     "prebuild": "node scripts/gen-version.mjs",
     "build": "tsup && node scripts/build-safecontent-deps.mjs && node scripts/copy-ambient-types.mjs",
     "test": "jest",
+    "format": "prettier --write \"src/**/*.{ts,tsx,js,mjs,json}\" \"test/**/*.{ts,mjs}\" \"scripts/**/*.mjs\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx,js,mjs,json}\" \"test/**/*.{ts,mjs}\" \"scripts/**/*.mjs\"",
     "check:circular": "node scripts/check-circular.mjs",
     "api:check": "node scripts/check-api-stability.mjs",
     "protocol:check": "node scripts/check-protocol-snapshot.mjs",
     "verify:codegen-parity": "node scripts/codegen-prototype/verify-drift.mjs --self-test && node scripts/codegen-prototype/verify-drift.mjs && node scripts/codegen-prototype/verify.streams.mjs --self-test && node scripts/codegen-prototype/verify.streams.mjs",
     "api:update": "node scripts/check-api-stability.mjs --update",
-    "verify": "npm run check:circular && npm run build && npm test && npm run test:safe-content && npm run test:metadata-e2e && npm run api:check && npm run compat:selftest && npm run compat:previous && npm run protocol:check && npm run protocol:selftest && npm run check:selfhost:selftest && npm run check:selfhost && npm run verify:codegen-parity",
+    "verify": "npm run format:check && npm run check:circular && npm run build && npm test && npm run test:safe-content && npm run test:metadata-e2e && npm run api:check && npm run compat:selftest && npm run compat:previous && npm run protocol:check && npm run protocol:selftest && npm run check:selfhost:selftest && npm run check:selfhost && npm run verify:codegen-parity",
     "docs": "typedoc --json docs/api.json && node scripts/gen-llms.mjs",
     "prepublishOnly": "npm run check:circular && npm run build && npm run api:check",
     "test:safe-content": "node scripts/build-safecontent-e2e.mjs && node --test test/safeContent.e2e.mjs",
@@ -43,7 +45,8 @@
     "compat:previous": "node scripts/check-previous-sdk-compat.mjs",
     "compat:selftest": "node scripts/check-previous-sdk-compat.mjs --self-test",
     "check:selfhost": "node scripts/build-selfhost.mjs .selfhost-check && node scripts/check-selfhost-resolvable.mjs --dir .selfhost-check",
-    "check:selfhost:selftest": "node scripts/check-selfhost-resolvable.mjs --self-test"
+    "check:selfhost:selftest": "node scripts/check-selfhost-resolvable.mjs --self-test",
+    "prepare": "git config core.hooksPath .githooks || true"
   },
   "peerDependencies": {
     "react": "^19.0.0",
@@ -56,6 +59,7 @@
   },
   "devDependencies": {
     "@immediately-run/mdx-plugins": "^0.1.0",
+    "@immediately-run/prettier-config": "0.1.0",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/jest": "^29.5.0",
@@ -70,6 +74,7 @@
     "mdast-util-mdx-jsx": "^3.2.0",
     "micromark-extension-gfm": "^3.0.0",
     "micromark-extension-mdx-jsx": "^3.0.2",
+    "prettier": "2.8.8",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "ts-jest": "^29.1.0",
@@ -77,5 +82,6 @@
     "tsup": "^8.0.0",
     "typedoc": "^0.27.0",
     "typescript": "^5.6.0"
-  }
+  },
+  "prettier": "@immediately-run/prettier-config"
 }