build: initial OSS commit

Hello world from Replica!

Author: nshki

.github/assets/replica-readme-banner.png

@@ -0,0 +1,23 @@
+version: 2
+updates:
+  - package-ecosystem: bundler
+    directory: "/hub"
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+  - package-ecosystem: npm
+    directories:
+      - "/hub"
+      - "/actions/build"
+      - "/starter"
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7

.github/dependabot.yml

@@ -0,0 +1,114 @@
+import { randomUUID } from "node:crypto"
+
+// Allow the 8 KiB Controls query plus the underlying prototype route.
+export const MAX_RELOAD_ADDRESS_LENGTH = 16_384
+
+export function agentCommands() {
+  let pending = null
+  const queue = []
+  const history = []
+
+  function stage(command, name) {
+    command.trace.push({ stage: name, elapsedMs: Date.now() - command.queuedAt })
+  }
+  function diagnostic(command) {
+    return {
+      id: command.id,
+      type: command.type,
+      rendererId: command.rendererId ?? null,
+      outcome: command.outcome ?? "pending",
+      stages: command.trace.map((entry) => ({ ...entry })),
+    }
+  }
+
+  function startNext() {
+    if (pending || !queue.length) return
+    const command = queue.shift()
+    const timer = setTimeout(() => {
+      pending = null
+      command.outcome = "timeout"
+      command.reject(
+        new Error(
+          `The live canvas did not respond. Request ${command.id}; last stage: ${command.trace.at(-1).stage}. Keep its panel open and try again.`,
+        ),
+      )
+      startNext()
+    }, command.timeoutMs)
+    command.timer = timer
+    pending = command
+  }
+
+  return {
+    invoke(type, input = {}, timeoutMs = 5_000) {
+      return new Promise((resolve, reject) => {
+        const command = {
+          id: randomUUID(),
+          type,
+          input,
+          timeoutMs,
+          resolve,
+          reject,
+          queuedAt: Date.now(),
+          trace: [],
+        }
+        stage(command, "queued")
+        history.push(command)
+        if (history.length > 20) history.shift()
+        queue.push(command)
+        startNext()
+      })
+    },
+    next(rendererId) {
+      if (
+        rendererId !== undefined &&
+        (typeof rendererId !== "string" || !/^[a-zA-Z0-9-]{1,64}$/.test(rendererId))
+      )
+        throw new Error("Invalid canvas renderer ID.")
+      if (!pending || pending.sent) return null
+      pending.sent = true
+      pending.rendererId = rendererId
+      stage(pending, "delivered")
+      return { id: pending.id, type: pending.type, input: pending.input }
+    },
+    progress({ id, stage: name }, rendererId) {
+      if (!pending || pending.id !== id || pending.rendererId !== rendererId)
+        throw new Error("No matching canvas action is pending for this renderer.")
+      const stages = ["handler started", "status collected"]
+      if (!stages.includes(name)) throw new Error("Invalid canvas action stage.")
+      if (!pending.trace.some((entry) => entry.stage === name)) stage(pending, name)
+    },
+    diagnostics() {
+      return { requests: history.map(diagnostic) }
+    },
+    complete(result, rendererId) {
+      if (!pending || result?.id !== pending.id || typeof result.ok !== "boolean") {
+        throw new Error("No matching canvas action is pending.")
+      }
+      if (pending.rendererId !== rendererId)
+        throw new Error("This canvas action belongs to another renderer.")
+      const { resolve, reject, timer } = pending
+      stage(pending, "reply received")
+      pending.outcome = result.ok ? "completed" : "failed"
+      clearTimeout(timer)
+      pending = null
+      if (result.ok) resolve(result.value)
+      else
+        reject(new Error(typeof result.error === "string" ? result.error : "Canvas action failed."))
+      startNext()
+    },
+    close() {
+      const error = new Error("The canvas was closed or changed during this action.")
+      if (pending) {
+        pending.outcome = "cancelled"
+        clearTimeout(pending.timer)
+        pending.reject(error)
+        pending = null
+      }
+      for (const command of queue) {
+        command.outcome = "cancelled"
+        command.reject(error)
+      }
+      queue.length = 0
+    },
+  }
+}

.github/extensions/replica-prototype/README.md

@@ -0,0 +1,106 @@
+import assert from "node:assert/strict"
+import { it } from "node:test"
+
+import { agentCommands } from "./index.mjs"
+
+it("delivers queued actions in order and matches each response ID", async () => {
+  const commands = agentCommands()
+  const result = commands.invoke("inspect")
+  const command = commands.next()
+  assert.equal(command.type, "inspect")
+  assert.equal(commands.next(), null)
+  const following = commands.invoke("click")
+  assert.equal(commands.next(), null)
+  assert.throws(() => commands.complete({ id: "wrong", ok: true }), /No matching/)
+  commands.complete({ id: command.id, ok: true, value: { addressDraft: "/draft" } })
+  assert.deepEqual(await result, { addressDraft: "/draft" })
+  const click = commands.next()
+  assert.equal(click.type, "click")
+  commands.complete({ id: click.id, ok: true, value: { clicked: true } })
+  assert.deepEqual(await following, { clicked: true })
+})
+
+it("rejects failed actions and cancels pending and queued work when the panel closes", async () => {
+  const commands = agentCommands()
+  const failed = commands.invoke("click")
+  const command = commands.next()
+  commands.complete({ id: command.id, ok: false, error: "Target hidden." })
+  await assert.rejects(failed, /Target hidden/)
+  const pending = commands.invoke("inspect")
+  const queued = commands.invoke("controls-status")
+  const cancelQueued = assert.rejects(queued, /closed or changed/)
+  commands.close()
+  await assert.rejects(pending, /closed or changed/)
+  await cancelQueued
+  assert.equal(commands.next(), null)
+})
+
+it("allows a bounded readiness wait beyond the ordinary transport timeout", async (t) => {
+  t.mock.timers.enable({ apis: ["setTimeout"] })
+  const commands = agentCommands()
+  const result = commands.invoke("controls-status", { timeoutMs: 10000 }, 15000)
+  const command = commands.next()
+  t.mock.timers.tick(6000)
+  commands.complete({ id: command.id, ok: true, value: { status: "ready" } })
+  assert.deepEqual(await result, { status: "ready" })
+  const timeout = assert.rejects(
+    commands.invoke("controls-status", { timeoutMs: 10000 }, 15000),
+    /did not respond/,
+  )
+  t.mock.timers.tick(15000)
+  await timeout
+})
+
+it("traces the owning renderer, rejects competing replies and reports the last stage on timeout", async (t) => {
+  t.mock.timers.enable({ apis: ["setTimeout", "Date"] })
+  const commands = agentCommands()
+  const failure = assert.rejects(
+    commands.invoke("controls-status", {}, 5000),
+    /last stage: handler started/,
+  )
+  const command = commands.next("native-renderer")
+  assert.equal(commands.next("browser-renderer"), null)
+  assert.throws(
+    () => commands.progress({ id: command.id, stage: "status collected" }, "browser-renderer"),
+    /No matching/,
+  )
+  commands.progress({ id: command.id, stage: "handler started" }, "native-renderer")
+  assert.throws(
+    () => commands.complete({ id: command.id, ok: true }, "browser-renderer"),
+    /another renderer/,
+  )
+  t.mock.timers.tick(5000)
+  await failure
+  assert.deepEqual(commands.diagnostics().requests[0], {
+    id: command.id,
+    type: "controls-status",
+    rendererId: "native-renderer",
+    outcome: "timeout",
+    stages: [
+      { stage: "queued", elapsedMs: 0 },
+      { stage: "delivered", elapsedMs: 0 },
+      { stage: "handler started", elapsedMs: 0 },
+    ],
+  })
+
+  it("bounds diagnostic history and excludes request inputs and reply values", async () => {
+    const commands = agentCommands()
+    for (let index = 0; index < 25; index++) {
+      const result = commands.invoke("inspect", { value: "PRIVATE_INPUT" })
+      const command = commands.next("renderer")
+      commands.complete({ id: command.id, ok: true, value: "PRIVATE_REPLY" }, "renderer")
+      await result
+    }
+    const diagnostics = commands.diagnostics()
+    assert.equal(diagnostics.requests.length, 20)
+    assert.ok(!JSON.stringify(diagnostics).includes("PRIVATE"))
+    commands.close()
+    const result = commands.invoke("controls-status")
+    const command = commands.next("reloaded-renderer")
+    commands.complete(
+      { id: command.id, ok: true, value: { status: "pending" } },
+      "reloaded-renderer",
+    )
+    assert.deepEqual(await result, { status: "pending" })
+  })
+})