@gitterm/opencode-cloud 0.0.0-stage → 0.1.4

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# @gitterm/opencode-cloud
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Move your local [OpenCode](https://opencode.ai) session to a [GitTerm](https://gitterm.dev)
+cloud workspace with one command, `/cloud`. Your conversation, commits, and (if you choose)
+uncommitted changes go with it. Your local files stay as they are.
+
+Formerly `@gitterm/opencode-plugin`. Want the agent to run commands remotely while the
+session stays local? Use [`@gitterm/opencode-sandbox`](../opencode-sandbox/README.md).
+
+## 1. Install
+
+Requires OpenCode 2.2.6 or newer.
+
+```sh
+opencode plugin add @gitterm/opencode-cloud
+```
+
+## 2. Sign in to GitTerm
+
+```sh
+npm install -g @gitterm/cli
+gitterm login
+```
+
+In GitTerm, add your model credentials and repository access first.
+
+## 3. Use it
+
+In a Git repository, stop the agent and finish or stop its background jobs, then type:
+
+```text
+/cloud
+```
+
+1. Choose whether to include uncommitted changes.
+2. Review what will be uploaded and approve it. The workspace is billed while it runs.
+3. Open the link to continue in the cloud.
+
+Run `/cloud` again later to reconnect to the same workspace. **Pause or delete the
+workspace in GitTerm when you are done.**
+
+## Settings
+
+All optional:
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "@gitterm/opencode-cloud",
+      "options": {
+        "provider": { "type": "e2b" },
+        "connections": ["github"],
+      },
+    },
+  ],
+}
+```
+
+| Option        | What it does                                                               |
+| ------------- | -------------------------------------------------------------------------- |
+| `provider`    | Cloud provider to use, for example `{ "type": "e2b" }`                     |
+| `connections` | Saved GitTerm connections, for example `"github"` for private repositories |
+| `name`        | Workspace name; defaults to the conversation title                         |
+| `persistent`  | Keep storage between restarts, where the provider allows                   |
+
+Self-hosting GitTerm? Sign in with `gitterm login --server https://gitterm.example.com`.
+`/cloud` talks to the OpenCode server that holds your session. It finds OpenCode's background
+service by itself. `opencode --standalone` uses a private server on a random port that `/cloud`
+can't reach; instead run `opencode serve --port 4096`, open it with
+`opencode --server http://127.0.0.1:4096`, and set `localServerUrl` to that address (and
+`localServerPassword` to its password).
+
+## Good to know
+
+- Only the current conversation moves. Running processes, ignored files (such as `.env`),
+  and your global OpenCode settings do not.
+- It is one way: later local edits are not sent, and cloud changes are not merged back.
+  Use Git to move work between them.
+- GitTerm must be able to clone your repository's `origin`.
+- The checkout and the conversation are each limited to 25 MiB. Submodules and merge
+  conflicts are not supported.
+- Common secret files are blocked, but this is not full secret scanning. Check the
+  upload before you approve it.

package/dist/handoff.d.ts

@@ -0,0 +1,43 @@
+import { type OpenCodeClient } from "@opencode/client";
+import { type GittermClient, type WorkspaceProviderSelection, type WorkspaceRuntimeAccess } from "@gitterm/sdk";
+export type HandoffOptions = {
+    serverUrl?: string;
+    token?: string;
+    provider?: WorkspaceProviderSelection;
+    persistent?: boolean;
+    name?: string;
+    connections?: string[];
+    localServerUrl?: string;
+    localServerPassword?: string;
+};
+export type HandoffRecord = {
+    attemptID: string;
+    sessionID: string;
+    phase: "creating" | "restoring" | "importing" | "ready" | "failed";
+    workspaceID?: string;
+    sourceDirectory: string;
+    head: string;
+    includeChanges: boolean;
+    sharedSessions: number;
+    createdAt: string;
+};
+type FormFields = Parameters<OpenCodeClient["session"]["form"]["create"]>[0]["fields"];
+export type HandoffDependencies = {
+    local: OpenCodeClient;
+    gitterm: GittermClient;
+    options: HandoffOptions;
+    signal: AbortSignal;
+    save(record: HandoffRecord): Promise<void>;
+    progress(text: string): Promise<void>;
+};
+export declare class HandoffCancelled extends Error {
+    constructor();
+}
+export declare function changePrompt(sharedCount: number): string;
+export declare function askForm(client: OpenCodeClient, sessionID: string, title: string, fields: FormFields, signal: AbortSignal): Promise<Record<string, string | number | boolean | readonly string[]>>;
+export declare function runtimeClient(runtime: WorkspaceRuntimeAccess): OpenCodeClient;
+export declare function runRemoteShell(remote: OpenCodeClient, directory: string, command: string, signal: AbortSignal): Promise<void>;
+export declare function importPayload(data: Awaited<ReturnType<OpenCodeClient["session"]["export"]>>, directory: string): Parameters<OpenCodeClient["session"]["import"]>[0];
+export declare function handoffSession(sessionID: string, deps: HandoffDependencies): Promise<HandoffRecord>;
+export declare function showConnection(local: OpenCodeClient, gitterm: GittermClient, record: HandoffRecord, signal: AbortSignal): Promise<void>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { Plugin } from "@opencode/plugin";
+export declare const GittermCloudPlugin: Plugin.Plugin;
+export default GittermCloudPlugin;