@loopstack/git-examples 0.1.1 → 0.1.2

package/README.md

@@ -38,6 +38,42 @@ npm install @loopstack/git-examples
 import { GitExamplesModule } from '@loopstack/git-examples';
 ```
 
+## Required app-module configuration
+
+Both examples invoke git tools that execute on a **remote agent**, so the workspace needs a connected `sandbox` environment. `GitExamplesModule` declares the slot via `RemoteClientModule.forFeature(...)`, but the consumer must register at least one matching environment in their root module via `RemoteClientModule.forRoot(...)`:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { GitExamplesModule } from '@loopstack/git-examples';
+import { LoopstackModule } from '@loopstack/loopstack-module';
+import { RemoteClientModule } from '@loopstack/remote-client';
+
+@Module({
+  imports: [
+    LoopstackModule.forRoot(),
+    RemoteClientModule.forRoot({
+      environments: {
+        available: [
+          {
+            type: 'sandbox',
+            name: 'Local Remote Server',
+            connectionUrl: process.env.SANDBOX_URL ?? 'http://localhost:3080',
+            agentUrl: process.env.SANDBOX_AGENT_URL ?? 'http://localhost:3001',
+            local: true,
+          },
+        ],
+      },
+    }),
+    GitExamplesModule,
+  ],
+})
+export class AppModule {}
+```
+
+The `type: 'sandbox'` must match the slot type declared by `GitExamplesModule`. The simplest remote agent option is `@loopstack/remote-server` on `localhost:3001`.
+
+`GitExamplesModule` re-imports `GitModule.forFeature()` and `GitHubIntegrationModule`, which transitively brings in the global `OAuthModule` and the GitHub OAuth provider — no additional OAuth wiring required in your AppModule. You just need to set the GitHub OAuth client env vars (see [Environment](#environment) below).
+
 ## Environment
 
 The repo-sync example requires GitHub OAuth credentials:

package/dist/workflows/github-repo-sync/github-repo-sync-example.workflow.d.ts

@@ -12,7 +12,7 @@ type ConnectResult = z.infer<typeof ConnectResultSchema>;
 export declare class GithubRepoSyncExampleWorkflow extends BaseWorkflow {
     private readonly connectGitHubWorkflow;
     constructor(connectGitHubWorkflow: ConnectGitHubWorkflow);
-    connect(_state: Record<string, unknown>): Promise<void>;
+    connect(): Promise<void>;
     connectComplete(_state: Record<string, unknown>, input: TransitionInput<ConnectResult>): Promise<void>;
 }
 export {};

package/dist/workflows/github-repo-sync/github-repo-sync-example.workflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"github-repo-sync-example.workflow.d.ts","sourceRoot":"","sources":["../../../src/workflows/github-repo-sync/github-repo-sync-example.workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAA0C,MAAM,mBAAmB,CAAC;AACzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAEtE,QAAA,MAAM,mBAAmB;;;;;mBAGvB,CAAC;AACH,KAAK,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEzD,qBAKa,6BAA8B,SAAQ,YAAY;IACjD,OAAO,CAAC,QAAQ,CAAC,qBAAqB;gBAArB,qBAAqB,EAAE,qBAAqB;IAKnE,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAavC,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,eAAe,CAAC,aAAa,CAAC;CAa7F"}
+{"version":3,"file":"github-repo-sync-example.workflow.d.ts","sourceRoot":"","sources":["../../../src/workflows/github-repo-sync/github-repo-sync-example.workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAA0C,MAAM,mBAAmB,CAAC;AACzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAEtE,QAAA,MAAM,mBAAmB;;;;;mBAGvB,CAAC;AACH,KAAK,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEzD,qBAKa,6BAA8B,SAAQ,YAAY;IACjD,OAAO,CAAC,QAAQ,CAAC,qBAAqB;gBAArB,qBAAqB,EAAE,qBAAqB;IAKnE,OAAO;IAaP,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,eAAe,CAAC,aAAa,CAAC;CAa7F"}

package/dist/workflows/github-repo-sync/github-repo-sync-example.workflow.js

@@ -23,7 +23,7 @@ let GithubRepoSyncExampleWorkflow = class GithubRepoSyncExampleWorkflow extends
         super();
         this.connectGitHubWorkflow = connectGitHubWorkflow;
     }
-    async connect(_state) {
+    async connect() {
         await this.connectGitHubWorkflow.run({}, { callback: { transition: 'connectComplete' }, show: 'inline', label: 'Connecting to GitHub...' });
     }
     async connectComplete(_state, input) {
@@ -43,7 +43,7 @@ exports.GithubRepoSyncExampleWorkflow = GithubRepoSyncExampleWorkflow;
 __decorate([
     (0, common_1.Transition)({ to: 'connecting' }),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object]),
+    __metadata("design:paramtypes", []),
     __metadata("design:returntype", Promise)
 ], GithubRepoSyncExampleWorkflow.prototype, "connect", null);
 __decorate([

package/dist/workflows/github-repo-sync/github-repo-sync-example.workflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"github-repo-sync-example.workflow.js","sourceRoot":"","sources":["../../../src/workflows/github-repo-sync/github-repo-sync-example.workflow.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,6BAAwB;AACxB,8CAAyF;AAEzF,sEAAsE;AAEtE,MAAM,mBAAmB,GAAG,OAAC,CAAC,KAAK,CAAC;IAClC,OAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE,EAAE,CAAC;IAC/C,OAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,OAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;CACzC,CAAC,CAAC;AAQI,IAAM,6BAA6B,GAAnC,MAAM,6BAA8B,SAAQ,qBAAY;IAChC;IAA7B,YAA6B,qBAA4C;QACvE,KAAK,EAAE,CAAC;QADmB,0BAAqB,GAArB,qBAAqB,CAAuB;IAEzE,CAAC;IAGK,AAAN,KAAK,CAAC,OAAO,CAAC,MAA+B;QAC3C,MAAM,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAClC,EAAE,EACF,EAAE,QAAQ,EAAE,EAAE,UAAU,EAAE,iBAAiB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,yBAAyB,EAAE,CAClG,CAAC;IACJ,CAAC;IAQK,AAAN,KAAK,CAAC,eAAe,CAAC,MAA+B,EAAE,KAAqC;QAC1F,IAAI,WAAW,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YAC9B,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,yBAAgB,EAAE;gBAC9C,QAAQ,EAAE,0CAA0C;aACrD,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,yBAAgB,EAAE;YAC9C,QAAQ,EAAE,2CAA2C,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI;SAC5F,CAAC,CAAC;QACH,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,EAAwC,CAAC,CAAC;IACvG,CAAC;CACF,CAAA;AAhCY,sEAA6B;AAMlC;IADL,IAAA,mBAAU,EAAC,EAAE,EAAE,EAAE,YAAY,EAAE,CAAC;;;;4DAMhC;AAQK;IANL,IAAA,mBAAU,EAAC;QACV,IAAI,EAAE,YAAY;QAClB,EAAE,EAAE,KAAK;QACT,IAAI,EAAE,IAAI;QACV,MAAM,EAAE,mBAAmB;KAC5B,CAAC;;;;oEAaD;wCA/BU,6BAA6B;IALzC,IAAA,iBAAQ,EAAC;QACR,KAAK,EAAE,gCAAgC;QACvC,WAAW,EACT,+LAA+L;KAClM,CAAC;qCAEoD,0CAAqB;GAD9D,6BAA6B,CAgCzC"}
+{"version":3,"file":"github-repo-sync-example.workflow.js","sourceRoot":"","sources":["../../../src/workflows/github-repo-sync/github-repo-sync-example.workflow.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,6BAAwB;AACxB,8CAAyF;AAEzF,sEAAsE;AAEtE,MAAM,mBAAmB,GAAG,OAAC,CAAC,KAAK,CAAC;IAClC,OAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE,EAAE,CAAC;IAC/C,OAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,OAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;CACzC,CAAC,CAAC;AAQI,IAAM,6BAA6B,GAAnC,MAAM,6BAA8B,SAAQ,qBAAY;IAChC;IAA7B,YAA6B,qBAA4C;QACvE,KAAK,EAAE,CAAC;QADmB,0BAAqB,GAArB,qBAAqB,CAAuB;IAEzE,CAAC;IAGK,AAAN,KAAK,CAAC,OAAO;QACX,MAAM,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAClC,EAAE,EACF,EAAE,QAAQ,EAAE,EAAE,UAAU,EAAE,iBAAiB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,yBAAyB,EAAE,CAClG,CAAC;IACJ,CAAC;IAQK,AAAN,KAAK,CAAC,eAAe,CAAC,MAA+B,EAAE,KAAqC;QAC1F,IAAI,WAAW,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YAC9B,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,yBAAgB,EAAE;gBAC9C,QAAQ,EAAE,0CAA0C;aACrD,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,yBAAgB,EAAE;YAC9C,QAAQ,EAAE,2CAA2C,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI;SAC5F,CAAC,CAAC;QACH,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,EAAwC,CAAC,CAAC;IACvG,CAAC;CACF,CAAA;AAhCY,sEAA6B;AAMlC;IADL,IAAA,mBAAU,EAAC,EAAE,EAAE,EAAE,YAAY,EAAE,CAAC;;;;4DAMhC;AAQK;IANL,IAAA,mBAAU,EAAC;QACV,IAAI,EAAE,YAAY;QAClB,EAAE,EAAE,KAAK;QACT,IAAI,EAAE,IAAI;QACV,MAAM,EAAE,mBAAmB;KAC5B,CAAC;;;;oEAaD;wCA/BU,6BAA6B;IALzC,IAAA,iBAAQ,EAAC;QACR,KAAK,EAAE,gCAAgC;QACvC,WAAW,EACT,+LAA+L;KAClM,CAAC;qCAEoD,0CAAqB;GAD9D,6BAA6B,CAgCzC"}

package/package.json

@@ -9,7 +9,7 @@
     "github",
     "workflow"
   ],
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "MIT",
   "author": {
     "name": "Jakob Klippel",
@@ -33,7 +33,7 @@
     "@loopstack/common": "*",
     "@loopstack/git-module": "*",
     "@loopstack/github-integration": "*",
-    "@nestjs/common": "^11.1.19",
+    "@nestjs/common": "^12.0.1",
     "zod": "^4.3.6"
   },
   "files": [

package/src/workflows/git-commit-flow/__tests__/git-commit-flow-example.spec.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import { GitModule } from '@loopstack/git-module';
+import { RemoteClientModule } from '@loopstack/remote-client';
+import { replay, runWorkflow } from '@loopstack/testing';
+import { GitExamplesModule } from '../../../git-examples.module';
+import { GitCommitFlowExampleWorkflow } from '../git-commit-flow-example.workflow';
+
+/**
+ * A scripted multi-tool pipeline with no LLM. The git and write tools are HTTP-backed (they
+ * talk to a remote workspace), so the whole flow runs against the tool boundary: each tool's
+ * response is replayed in call order, and the workflow's own state threading and document
+ * rendering run for real. Envelopes match each tool's `resultSchema`.
+ *
+ * `RemoteClientModule.forRoot()` establishes the global remote-client services the git tools
+ * depend on; the tools' actual network calls are replaced by the replay script.
+ */
+describe('GitCommitFlowExampleWorkflow', () => {
+  it('writes a file, then stages, commits, and reads back the log', async () => {
+    const run = await runWorkflow(GitCommitFlowExampleWorkflow, undefined, {
+      imports: [
+        RemoteClientModule.forRoot(),
+        GitModule.forFeature(),
+        RemoteClientModule.forFeature({ slots: [{ id: 'sandbox', type: 'sandbox', title: 'Sandbox' }] }),
+        GitExamplesModule,
+      ],
+      replay: replay({
+        version: 3,
+        recordings: [
+          { tool: 'write', envelope: { data: { success: true, path: 'tmp/example.txt' } } },
+          {
+            tool: 'git_status',
+            envelope: {
+              data: { branch: 'main', staged: [], modified: [], untracked: ['tmp/example.txt'], deleted: [] },
+            },
+          },
+          { tool: 'git_add', envelope: { data: { success: true } } },
+          { tool: 'git_commit', envelope: { data: { hash: 'abc123', message: 'chore: example commit' } } },
+          {
+            tool: 'git_log',
+            envelope: {
+              data: {
+                commits: [
+                  {
+                    hash: 'abc123',
+                    shortHash: 'abc123',
+                    message: 'chore: example commit',
+                    author: 'Test',
+                    date: '2026-01-01',
+                  },
+                ],
+              },
+            },
+          },
+        ],
+      }),
+    });
+
+    expect(run.error).toBeUndefined();
+    expect(run.status).toBe('completed');
+    expect(run.path).toEqual(['writeTestFile', 'checkStatus', 'stageAll', 'commit', 'readBack']);
+
+    const texts = run.documents.map((d) => (d.content as { text?: string }).text ?? '');
+    expect(texts.some((t) => t.includes('"branch": "main"'))).toBe(true);
+    expect(texts.some((t) => t.includes('chore: example commit'))).toBe(true);
+  });
+});

package/src/workflows/github-repo-sync/github-repo-sync-example.workflow.ts

@@ -20,7 +20,7 @@ export class GithubRepoSyncExampleWorkflow extends BaseWorkflow {
   }
 
   @Transition({ to: 'connecting' })
-  async connect(_state: Record<string, unknown>) {
+  async connect() {
     await this.connectGitHubWorkflow.run(
       {},
       { callback: { transition: 'connectComplete' }, show: 'inline', label: 'Connecting to GitHub...' },