Skip to docs content
Browse documentation
On this page

Editing package source

Open a repo session on a saved package, edit files one at a time or with a patch, run the publish checks, then publish a new version.

To change an existing package, open a repo session. A session is a private workspace on the version that runs. You read and edit files in it one at a time, check the result, and publish it as a new package version. No git remote is involved: everything goes through the minion.repo capabilities.

How to edit a package

  1. Open a session and look around.
const { sessionId, files } = await minion.repo.openSession({ package: 'daily-digest' })
const { matches } = await minion.repo.search({ sessionId, query: 'cron' })
const src = await minion.repo.readFile({ sessionId, path: 'src/index.ts#L1-L60' })

repo.tree lists files with sizes. readFile takes #L10, #L10-L20 or a Markdown heading slug such as README.md#setup. Keep the sessionId: a later execute call resumes with repo.openSession({ sessionId }), and repo.listSessions() finds open sessions. Omitting sessionId always opens a new session, so two agents never share one by accident.

  1. Edit with repo.editFiles (write, replace, writeJson, delete, move; edits to the same path apply in order) or repo.applyPatch with a unified diff. Both are all or nothing and return a diff per file.
await minion.repo.editFiles({ sessionId, edits: [
	{ op: 'replace', path: 'src/index.ts', find: 'limit = 10', replace: 'limit = 25' },
] })
  1. Review and check. repo.status lists added, changed and deleted files, and repo.diff({ sessionId }) shows every change against the base. repo.restore({ sessionId, paths }) undoes some of them. repo.runChecks({ sessionId }) runs the publish checks (manifest, README.md, dependencies, bundling, TypeScript, job limits) without publishing anything.
  2. Publish. An owner or admin runs repo.publish({ sessionId }): it saves the files as a new version, publishes it and closes the session. Failing checks publish nothing and return the problems; fix them and publish again. Members can't publish, so they hand the sessionId to an owner or admin. See Package lifecycle .

A package can have up to 200 files, 256 KB per file and 2 MB in total.

Things to watch

  • The base can move. If the package has a version newer than your session's base (a save since you opened it, an unpublished draft, or versions published while it is locked), publishing fails with "Base moved". Call repo.rebase({ sessionId }). It moves your changes onto the latest version, or lists the files you both changed. For a conflict, read your version, repo.restore that path, rebase, and make the change again on the new base.
  • Sessions clean up. repo.discard({ sessionId }) throws one away. A session untouched for 7 days is discarded automatically.
  • Versions are kept. Each publish is a new numbered version, so a bad one doesn't destroy the previous one. Lock a package to a known good version with minion.packages.update({ name, changes: { pinnedVersion } }) (owners and admins).
  • Job and webhook source lives in the package. Change a job's schedule, export or code in the package and publish again.

Saving the whole package instead

For a brand new package, or when you already hold every file, send the complete file set to minion.packages.save. Pass all files, not a diff: any file you leave out isn't in the new version. minion.packages.get returns only the README, exports, jobs and versions, not the other source files. You can also browse any version's files in the app at /app/packages/<name>, and add ?v=<number> to see an older version.

await minion.packages.save({
	name: 'daily-digest',
	files: {
		'package.json': pkgJson,
		'README.md': readme,
		'src/index.ts': updatedSource,
	},
})

Related