From b2e319f620dee6e82b075e611f990dffdc6f8328 Mon Sep 17 00:00:00 2001
From: Turadg Aleahmad <turadg@agoric.com>
Date: Mon, 27 Nov 2023 14:23:28 -0800
Subject: [PATCH] feat: debug test image

---
 README.md                           | 11 +++++++--
 common.ts                           | 10 +++++++++
 debugTestImage.ts                   | 35 +++++++++++++++++++++++++++++
 upgrade-test-scripts/run_eval.sh    |  0
 upgrade-test-scripts/run_test.sh    |  0
 upgrade-test-scripts/run_use.sh     |  0
 upgrade-test-scripts/start_ag0.sh   |  0
 upgrade-test-scripts/start_agd.sh   |  0
 upgrade-test-scripts/start_to_to.sh |  0
 9 files changed, 54 insertions(+), 2 deletions(-)
 create mode 100755 debugTestImage.ts
 mode change 100644 => 100755 upgrade-test-scripts/run_eval.sh
 mode change 100644 => 100755 upgrade-test-scripts/run_test.sh
 mode change 100644 => 100755 upgrade-test-scripts/run_use.sh
 mode change 100644 => 100755 upgrade-test-scripts/start_ag0.sh
 mode change 100644 => 100755 upgrade-test-scripts/start_agd.sh
 mode change 100644 => 100755 upgrade-test-scripts/start_to_to.sh

diff --git a/README.md b/README.md
index 06a68743..3d562071 100644
--- a/README.md
+++ b/README.md
@@ -74,7 +74,15 @@ To run the tests for particular proposals,
 ./runTestImages.ts --match upgrade
 ```
 
-## Contributing
+## Debugging
+
+To get the local files into the container, use a [bind mount](https://docs.docker.com/storage/bind-mounts/). E.g.
+
+```
+docker run -it --entrypoint bash --mount type=bind,src=.,dst=/usr/src/a3p ghcr.io/agoric/agoric-3-proposals:use-upgrade-8
+```
+
+# Contributing
 
 To add a proposal, see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
@@ -102,7 +110,6 @@ docker run  ghrc.io/agoric/agoric-3-proposals:dev
 ## Future work
 
 - [ ] include a way to test soft patches that weren't proposals (e.g. PismoB)
-- [ ] documentation and tooling for debugging
 - [ ] separate console output for agd and the scripts (had been with tmux before but trouble, try Docker compose https://github.com/Agoric/agoric-sdk/discussions/8480#discussioncomment-7438329)
 - [ ] way to query capdata in one shot (not resorting to follow jsonlines hackery)
 - [ ] within each proposal, separate dirs for supporting files so images don't invalidate
diff --git a/common.ts b/common.ts
index deccc2d5..b50d454e 100644
--- a/common.ts
+++ b/common.ts
@@ -45,6 +45,16 @@ export function readProposals(): ProposalInfo[] {
   return proposalPaths.map(readInfo);
 }
 
+export const readOneProposal = (match: string) => {
+  const allProposals = readProposals();
+
+  const proposals = allProposals.filter(p => p.proposalName.includes(match));
+
+  assert(proposals.length > 0, 'no proposals match');
+  assert(proposals.length === 1, 'too many proposals match');
+  return proposals[0];
+};
+
 export function lastPassedProposal(proposals: ProposalInfo[]): ProposalInfo {
   // @ts-expect-error use es2023; findLast is available in Node 18
   const last = proposals.findLast(p => p.proposalIdentifier.match(/^\d/));
diff --git a/debugTestImage.ts b/debugTestImage.ts
new file mode 100755
index 00000000..69ef8f1b
--- /dev/null
+++ b/debugTestImage.ts
@@ -0,0 +1,35 @@
+#!/usr/bin/env tsx
+/**
+ * @file like runTestImages.ts, but for a single proposal,
+ * and leaves the chain running
+ */
+import { execSync } from 'node:child_process';
+import { parseArgs } from 'node:util';
+import { imageNameForProposal, readOneProposal } from './common';
+
+const options = {
+  match: { short: 'm', type: 'string' },
+} as const;
+const { values } = parseArgs({ options });
+
+const proposal = readOneProposal(values.match!);
+const { name } = imageNameForProposal(proposal, 'test');
+
+console.log(
+  `
+Starting chain of test image for proposal ${proposal.proposalName}
+
+To get an interactive shell in the container, use an IDE feature like "Attach Shell" or this command:'
+
+  docker exec -ti $(docker ps -q -f ancestor=${name}) bash
+
+And within that shell:
+  cd /usr/src/proposals/<PROPOSAL_PATH> && ./test.sh
+
+The 'proposals' path is mounted in the container so your edits will appear there.
+`,
+);
+
+// start the chain, with the repo mounted at /usr/src
+const cmd = `docker run --mount type=bind,src=./proposals,dst=/usr/src/proposals -it --entrypoint /usr/src/upgrade-test-scripts/start_agd.sh ${name}`;
+execSync(cmd, { stdio: 'inherit' });
diff --git a/upgrade-test-scripts/run_eval.sh b/upgrade-test-scripts/run_eval.sh
old mode 100644
new mode 100755
diff --git a/upgrade-test-scripts/run_test.sh b/upgrade-test-scripts/run_test.sh
old mode 100644
new mode 100755
diff --git a/upgrade-test-scripts/run_use.sh b/upgrade-test-scripts/run_use.sh
old mode 100644
new mode 100755
diff --git a/upgrade-test-scripts/start_ag0.sh b/upgrade-test-scripts/start_ag0.sh
old mode 100644
new mode 100755
diff --git a/upgrade-test-scripts/start_agd.sh b/upgrade-test-scripts/start_agd.sh
old mode 100644
new mode 100755
diff --git a/upgrade-test-scripts/start_to_to.sh b/upgrade-test-scripts/start_to_to.sh
old mode 100644
new mode 100755